Live Streaming Audio Transcription

Declaring a Deepgram Websocket

The Deepgram Live Clients allows you to obtain Real-Time Transcription through the Websocket Streaming interface.

1
# Configure the DeepgramClientOptions to enable KeepAlive for maintaining the WebSocket connection (only if necessary to your scenario)
2
config = DeepgramClientOptions(
3
    options={"keepalive": "true"}
4
)
5
6
# Create a websocket connection using the DEEPGRAM_API_KEY from environment variables
7
deepgram = DeepgramClient(API_KEY, config)
8
9
# Use the listen.live class to create the websocket connection
10
dg_connection = deepgram.listen.websocket.v("1") 

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. By setting "keepalive": "true" in the DeepgramClientOptions object, you enable KeepAlive to maintain the WebSocket connection, ensuring a more stable and persistent connection with Deepgram’s servers.

Parameters

Additional options can be provided for streaming transcriptions when the websocket start() function is called. They are provided by declaring a LiveOptions object. Each of these parameters maps to a feature in the Deepgram API. Reference the features documentation to learn the appropriate features for your request.

Declaring a Deepgram Websocket

The listen package declares a websocket object to the Deepgram API.

1
# Create a websocket connection using the DEEPGRAM_API_KEY from environment variables
2
dg_connection = deepgram.listen.websocket.v("1")

Events and Callbacks

The following events are fired by the live transcription object:

Listening to Events

Use the on function to listen for events fired by the websocket object.

Listen for any transcripts to be received and receive a callback to your declared function called on_message.

1
def on_message(self, result, **kwargs):
2
  sentence = result.channel.alternatives[0].transcript
3
  if len(sentence) == 0:
4
    return
5
  print(f"Transcription: {sentence}")
6
7
dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)

Listen for any errors/exceptions and receive a callback to your declared function called on_error

1
def on_error(self, error, **kwargs):
2
  print(f"Error: {error}")
3
4
dg_connection.on(LiveTranscriptionEvents.Error, on_error)

Connecting Your Websocket

After you have declared your callbacks, declare the LiveOptions or the transcription parameters you want to use for your websocket connection. These options are passed into the start() function, which will subsequently connect the websocket to the Deepgram API.

1
options = LiveOptions(
2
  punctuate=True,
3
  interim_results=False,
4
  language='en-GB'
5
)
6
7
dg_connection.start(options)

Functions

The Deepgram websocket class provides several functions to simplify using the Deepgram API. The most notable ones are send and finish.

Sending Audio Stream Bytes

The send function sends raw audio data to the Deepgram API.

1
dg_connection.send(SOME_STREAMING_DATA)

When transcription results are available, you will receive those messages via the callback function previously mentioned (as seen below).

1
def on_message(self, result, **kwargs):
2
  sentence = result.channel.alternatives[0].transcript
3
  if len(sentence) == 0:
4
    return
5
  print(f"Transcription: {sentence}")
6
7
dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)

Closing the Connection

The finish function closes the Websocket connection to Deepgram.

1
dg_connection.finish()

Where To Find Additional Examples

The SDK repository has a good collection of live audio transcription examples. The README contains links to them. Each example below attempts to provide different options for transcribing an audio source.

Some Examples:

• Threaded Client using a Microphone - examples/speech-to-text/websocket/microphone
• Threaded Client from an HTTP Endpoint - examples/speech-to-text/websocket/http

If the Async Client suits your use case better:

• Async Client using a Microphone - examples/speech-to-text/websocket/async_microphone
• Async Client from an HTTP Endpoint - examples/speech-to-text/websocket/async_http