Streaming

Transcribe Live Streaming Audio

Deepgram provides its customers with real-time, streaming transcription via its streaming endpoints. These endpoints are high-performance, full-duplex services running over the tried-and-true WebSocket protocol, which makes integration with customer pipelines simple due to the wide array of client libraries available.

To use this endpoint, connect to wss://api.deepgram.com/v1/listen. TLS encryption will protect your connection and data. We support a minimum of TLS 1.2.

All audio data is sent to the streaming endpoint as binary-type WebSocket messages containing payloads that are the raw audio data. Because the protocol is full-duplex, you can stream in real-time and still receive transcription responses while uploading data.

When you are finished, send a JSON message to the server: { 'type': 'CloseStream' }. The server will interpret it as a shutdown command, which means it will finish processing whatever data is still has cached, send the response to the client, send a summary metadata object, and then terminate the WebSocket connection.

To learn more about working with real-time streaming data and results, see Get Started with Streaming Audio.

Deepgram does not store transcriptions. Make sure to save output or return transcriptions to a callback URL for custom processing.

Query Params

Responses

Response Schema

{
  "metadata": {
    "transaction_key": "string",
    "request_id": "uuid",
    "sha256": "string",
    "created": "string",
    "duration": 0,
    "channels": 0,
    "models": [
      "string"
    ],
  },
  "channel": [
    {
      "alternatives": [
        {
          "transcript": "string",
          "confidence": 0,
          "words": [
            {
              "word": "string",
              "start": 0,
              "end": 0,
              "confidence": 0
            }
          ]
        }
      ],
      "search": [
        {
          "query": "string",
          "hits": [
            {
              "confidence": 0,
              "start": 0,
              "end": 0,
              "snippet": "string"
            }
          ]
        }
      ]
    }
  ],
  "channel_index": [
    0,
    0
  ],
  "duration": 0.0,
  "start": 0.0,
  "is_final": boolean,
  "speech_final": boolean
}

Stream KeepAlive

By default, the Deepgram streaming connection will time out with a NET-0001 error code if no audio is sent by the client for 12 seconds. (See Error Handling below for more information.)

To keep the websocket open without sending audio data, send the following JSON string:

{ 'type': 'KeepAlive' }

This will keep the streaming connection open for an additional 12 seconds. If no audio or additional KeepAlive messages are sent within the 12 second window, the streaming connection will close with a NET-0001. To avoid this error and keep the connection open, continue sending KeepAlive messages 3-5 seconds before the 12 second timeout window expires until you are ready to resume sending audio.

Close Stream

To gracefully close a streaming connection, send the following JSON string:

{ 'type': 'CloseStream' }

This tells Deepgram that no more audio will be sent. Deepgram will close the connection once all audio has finished processing.

Error Handling

If Deepgram encounters an error during real-time streaming, we will return a WebSocket Close frame (WebSocket Protocol specification, section 5.5.1]).

The body of the Close frame will indicate the reason for closing using one of the specification’s pre-defined status codes followed by a UTF-8-encoded payload that represents the reason for the error. Current codes and payloads in use include:

To learn about debugging WebSocket errors, see Troubleshooting WebSocket DATA and NET Errors When Live Streaming Audio.

After sending a Close message, the endpoint considers the WebSocket connection closed and will close the underlying TCP connection.