Live Streaming Audio Transcription

Declaring a Deepgram Websocket

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

# Configure the DeepgramClientOptions to enable KeepAlive for maintaining the WebSocket connection (only if necessary to your scenario)
config = DeepgramClientOptions(
    options={"keepalive": "true"}
)

# Create a websocket connection using the DEEPGRAM_API_KEY from environment variables
deepgram = DeepgramClient(API_KEY, config)

# Use the listen.live class to create the websocket connection
dg_connection = deepgram.listen.websocket.v("1") 

# Configure the DeepgramClientOptions to enable KeepAlive for maintaining the WebSocket connection (only if necessary to your scenario)
config = DeepgramClientOptions(
    options={"keepalive": "true"}
)

# Create a websocket connection using the DEEPGRAM_API_KEY from environment variables
deepgram = DeepgramClient(API_KEY, config)

# Use the listen.live class to create the websocket connection
dg_connection = deepgram.listen.asyncwebsocket.v("1") 

📘

This SDK supports both the Threaded and Async/Await Clients as described in the Threaded and Async IO Task Support section. The code blocks contain a tab for Threaded and Async to show examples for websocket versus asyncwebsocket, respectively. The difference between Threaded and Async is subtle.

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.

📘

Read more about KeepAlive in this comprehensive guide

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.

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

# Create a websocket connection using the DEEPGRAM_API_KEY from environment variables
dg_connection = deepgram.listen.asyncwebsocket.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.

def on_message(self, result, **kwargs):
  sentence = result.channel.alternatives[0].transcript
  if len(sentence) == 0:
    return
  print(f"Transcription: {sentence}")

dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)

async def on_message(self, result, **kwargs):
  sentence = result.channel.alternatives[0].transcript
  if len(sentence) == 0:
    return
  print(f"Transcription: {sentence}")

dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)

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

def on_error(self, error, **kwargs):
  print(f"Error: {error}")

dg_connection.on(LiveTranscriptionEvents.Error, on_error)

async def on_error(self, error, **kwargs):
  print(f"Error: {error}")

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.

options = LiveOptions(
  punctuate=True,
  interim_results=False,
  language='en-GB'
)

dg_connection.start(options)

options = LiveOptions(
  punctuate=True,
  interim_results=False,
  language='en-GB'
)

await 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.

dg_connection.send(SOME_STREAMING_DATA)

await 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).

def on_message(self, result, **kwargs):
  sentence = result.channel.alternatives[0].transcript
  if len(sentence) == 0:
    return
  print(f"Transcription: {sentence}")

dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)

async def on_message(self, result, **kwargs):
  sentence = result.channel.alternatives[0].transcript
  if len(sentence) == 0:
    return
  print(f"Transcription: {sentence}")

dg_connection.on(LiveTranscriptionEvents.Transcript, on_message)

Closing the Connection

The finish function closes the Websocket connection to Deepgram.

dg_connection.finish()

await 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