Getting Started

In this guide, you’ll learn how to automatically transcribe live streaming audio in real time using Deepgram’s SDKs, which are supported for use with the Deepgram API. (If you prefer not to use a Deepgram SDK, jump to the section Non-SDK Code Examples.)

SDKs

To transcribe audio from an audio stream using one of Deepgram’s SDKs, follow these steps.

Install the SDK

Open your terminal, navigate to the location on your drive where you want to create your project, and install the Deepgram SDK.

$
# Install the Deepgram JS SDK
>
# https://github.com/deepgram/deepgram-js-sdk
>
>
npm install @deepgram/sdk

Add Dependencies

$
# Install cross-fetch: Platform-agnostic Fetch API with typescript support, a simple interface, and optional polyfill.
>
# Install dotenv to protect your api key
>
>
npm install cross-fetch dotenv

Transcribe Audio from a Remote Stream

The following code shows how to transcribe audio from a remote audio stream. If you would like to learn how to stream audio from a microphone, check out our Live Audio Starter Apps or specific examples in the readme of each of the Deepgram SDKs.

1
// Example filename: index.js
2
3
const { createClient, LiveTranscriptionEvents } = require("@deepgram/sdk");
4
const fetch = require("cross-fetch");
5
const dotenv = require("dotenv");
6
dotenv.config();
7
8
// URL for the realtime streaming audio you would like to transcribe
9
const url = "http://stream.live.vc.bbcmedia.co.uk/bbc_world_service";
10
11
const live = async () => {
12
  // STEP 1: Create a Deepgram client using the API key
13
  const deepgram = createClient(process.env.DEEPGRAM_API_KEY);
14
15
  // STEP 2: Create a live transcription connection
16
  const connection = deepgram.listen.live({
17
    model: "nova-3",
18
    language: "en-US",
19
    smart_format: true,
20
  });
21
22
  // STEP 3: Listen for events from the live transcription connection
23
  connection.on(LiveTranscriptionEvents.Open, () => {
24
    connection.on(LiveTranscriptionEvents.Close, () => {
25
      console.log("Connection closed.");
26
    });
27
28
    connection.on(LiveTranscriptionEvents.Transcript, (data) => {
29
      console.log(data.channel.alternatives[0].transcript);
30
    });
31
32
    connection.on(LiveTranscriptionEvents.Metadata, (data) => {
33
      console.log(data);
34
    });
35
36
    connection.on(LiveTranscriptionEvents.Error, (err) => {
37
      console.error(err);
38
    });
39
40
    // STEP 4: Fetch the audio stream and send it to the live transcription connection
41
    fetch(url)
42
      .then((r) => r.body)
43
      .then((res) => {
44
        res.on("readable", () => {
45
          connection.send(res.read());
46
        });
47
      });
48
  });
49
};
50
51
live();

Non-SDK Code Examples

If you would like to try out making a Deepgram speech-to-text request in a specific language (but not using Deepgram’s SDKs), we offer a library of code-samples in this Github repo. However, we recommend first trying out our SDKs.

Results

In order to see the results from Deepgram, you must run the application. Run your application from the terminal. Your transcripts will appear in your shell.

1
# Run your application using the file you created in the previous step
2
# Example: node index.js
3
4
node YOUR_PROJECT_NAME.js

Analyze the Response

The responses that are returned will look similar to this:

1
{
2
  "type": "Results",
3
  "channel_index": [
4
    0,
5
    1
6
  ],
7
  "duration": 1.98,
8
  "start": 5.99,
9
  "is_final": true,
10
  "speech_final": true,
11
  "channel": {
12
    "alternatives": [
13
      {
14
        "transcript": "Tell me more about this.",
15
        "confidence": 0.99964225,
16
        "words": [
17
          {
18
            "word": "tell",
19
            "start": 6.0699997,
20
            "end": 6.3499994,
21
            "confidence": 0.99782443,
22
            "punctuated_word": "Tell"
23
          },
24
          {
25
            "word": "me",
26
            "start": 6.3499994,
27
            "end": 6.6299996,
28
            "confidence": 0.9998324,
29
            "punctuated_word": "me"
30
          },
31
          {
32
            "word": "more",
33
            "start": 6.6299996,
34
            "end": 6.79,
35
            "confidence": 0.9995466,
36
            "punctuated_word": "more"
37
          },
38
          {
39
            "word": "about",
40
            "start": 6.79,
41
            "end": 7.0299997,
42
            "confidence": 0.99984455,
43
            "punctuated_word": "about"
44
          },
45
          {
46
            "word": "this",
47
            "start": 7.0299997,
48
            "end": 7.2699995,
49
            "confidence": 0.99964225,
50
            "punctuated_word": "this"
51
          }
52
        ]
53
      }
54
    ]
55
  },
56
  "metadata": {
57
    "request_id": "52cc0efe-fa77-4aa7-b79c-0dda09de2f14",
58
    "model_info": {
59
      "name": "2-general-nova",
60
      "version": "2024-01-18.26916",
61
      "arch": "nova-2"
62
    },
63
    "model_uuid": "c0d1a568-ce81-4fea-97e7-bd45cb1fdf3c"
64
  },
65
  "from_finalize": false
66
}

In this default response, we see:

• transcript: the transcript for the audio segment being processed.

• confidence: a floating point value between 0 and 1 that indicates overall transcript reliability. Larger values indicate higher confidence.

• words: an object containing each word in the transcript, along with its start time and end time (in seconds) from the beginning of the audio stream, and a confidence value.

  • Because we passed the smart_format: true option to the transcription.prerecorded method, each word object also includes its punctuated_word value, which contains the transformed word after punctuation and capitalization are applied.

• speech_final: tells us this segment of speech naturally ended at this point. By default, Deepgram live streaming looks for any deviation in the natural flow of speech and returns a finalized response at these places. To learn more about this feature, see Endpointing.

• is_final: If this says false, it is indicating that Deepgram will continue waiting to see if more data will improve its predictions. Deepgram live streaming can return a series of interim transcripts followed by a final transcript. To learn more, see Interim Results.

If your scenario requires you to keep the connection alive even while data is not being sent to Deepgram, you can send periodic KeepAlive messages to essentially “pause” the connection without closing it. To learn more, see KeepAlive.

What’s Next?

Now that you’ve gotten transcripts for streaming audio, enhance your knowledge by exploring the following areas. You can also check out our Live Streaming API Reference for a list of all possible parameters.

Try the Starter Apps

• Clone and run one of our Live Audio Starter App repositories to see a full application with a frontend UI and a backend server streaming audio to Deepgram.

Read the Feature Guides

Deepgram’s features help you to customize your transcripts.

• Language: Learn how to transcribe audio in other languages.
• Feature Overview: Review the list of features available for streaming speech-to-text. Then, dive into individual guides for more details.

Tips and tricks

• End of speech detection - Learn how to pinpoint end of speech post-speaking more effectively.
• Using interim results - Learn how to use preliminary results provided during the streaming process which can help with speech detection.
• Measuring streaming latency - Learn how to measure latency in real-time streaming of audio.

Add Your Audio

• Ready to connect Deepgram to your own audio source? Start by reviewing how to determine your audio format and format your API request accordingly.
• Then, check out our Live Streaming Starter Kit. It’s the perfect “102” introduction to integrating your own audio.

Explore Use Cases

• Learn about the different ways you can use Deepgram products to help you meet your business objectives. Explore Deepgram’s use cases.

Transcribe Pre-recorded Audio

• Now that you know how to transcribe streaming audio, check out how you can use Deepgram to transcribe pre-recorded audio. To learn more, see Getting Started with Pre-recorded Audio.