Learn how to send messages while streaming audio, ensuring uninterrupted communication.

Streaming

KeepAlive serves as a crucial mechanism for maintaining an uninterrupted connection with Deepgram’s servers, allowing you to optimize your audio streaming experience while minimizing costs.

What is theKeepAlive message?

A common situation is needing to keep a connection open without constantly sending audio. Normally, you’d have to send data all the time, even silence, which wastes resources and increases costs since Deepgram charges for all audio, whether it’s speech or silence. KeepAlive solves this by allowing you to pause the connection and resume later, avoiding extra costs for transcribing silence.

Benefits

  • Cost Efficiency: KeepAlive enables you to optimize costs by pausing the connection during periods of silence, eliminating the need to transcribe unnecessary audio data.
  • Connection Maintenance: By sending periodic KeepAlive messages, you can ensure that the WebSocket connection remains open, preventing timeouts and maintaining communication with Deepgram’s servers.
  • Flexibility: KeepAlive offers flexibility in managing your streaming sessions. You can temporarily halt the transmission of audio data while keeping the connection active, resuming data streaming when needed without re-establishing the connection.

Sending KeepAlive

To send the KeepAlive message, you need to send the following JSON message to the server:

JSON
1{
2 "type": "KeepAlive"
3}

Because Deepgram’s streaming connection is set to time out after 10 seconds of inactivity, it’s essential to periodically send KeepAlive messages to maintain the connection and prevent it from closing prematurely.

If no audio data is sent within a 10-second window, the connection will close, triggering a NET-0001 error. Using KeepAlive extends the connection by another 10 seconds. To avoid this error and keep the connection open, continue sending KeepAlive messages 3-5 seconds before the 10 second timeout window expires until you are ready to resume sending audio.

Be sure to send the KeepAlive message as a text WebSocket message. Sending it as a binary message may result in incorrect handling and could lead to connection issues.

KeepAlive Confirmation

You will not receive a response back from the server.

Language Specific Implementations

Following are code examples to help you get started.

Sending a KeepAlive message in JSON Format

These snippets demonstrate how to construct a JSON message containing the KeepAlive type and send it over the WebSocket connection in each respective language.

1const WebSocket = require("ws");
2
3// Assuming 'headers' is already defined for authorization
4const ws = new WebSocket("wss://api.deepgram.com/v1/listen", { headers });
5
6// Assuming 'ws' is the WebSocket connection object
7const keepAliveMsg = JSON.stringify({ type: "KeepAlive" });
8ws.send(keepAliveMsg);

Streaming Examples

Here are more complete examples that make a streaming request and use KeepAlive. Try running these examples to see how KeepAlive is sent periodically.

1const WebSocket = require("ws");
2
3const authToken = "DEEPGRAM_API_KEY"; // Replace 'DEEPGRAM_API_KEY' with your actual authorization token
4const headers = {
5 Authorization: `Token ${authToken}`,
6};
7
8// Initialize WebSocket connection
9const ws = new WebSocket("wss://api.deepgram.com/v1/listen", { headers });
10
11// Handle WebSocket connection open event
12ws.on("open", function open() {
13 console.log("WebSocket connection established.");
14
15 // Send audio data (replace this with your audio streaming logic)
16 // Example: Read audio from a microphone and send it over the WebSocket
17 // For demonstration purposes, we're just sending a KeepAlive message
18
19 setInterval(() => {
20 const keepAliveMsg = JSON.stringify({ type: "KeepAlive" });
21 ws.send(keepAliveMsg);
22 console.log("Sent KeepAlive message");
23 }, 3000); // Sending KeepAlive messages every 3 seconds
24});
25
26// Handle WebSocket message event
27ws.on("message", function incoming(data) {
28 console.log("Received:", data);
29 // Handle received data (transcription results, errors, etc.)
30});
31
32// Handle WebSocket close event
33ws.on("close", function close() {
34 console.log("WebSocket connection closed.");
35});
36
37// Handle WebSocket error event
38ws.on("error", function error(err) {
39 console.error("WebSocket error:", err.message);
40});
41
42// Gracefully close the WebSocket connection when done
43function closeWebSocket() {
44 const closeMsg = JSON.stringify({ type: "CloseStream" });
45 ws.send(closeMsg);
46}
47
48// Call closeWebSocket function when you're finished streaming audio
49// For example, when user stops recording or when the application exits
50// closeWebSocket();

Deepgram SDKs

Deepgram’s SDKs make it easier to build with Deepgram in your preferred language. To learn more about getting started with the SDKs, visit Deepgram’s SDKs documentation.

1const { createClient, LiveTranscriptionEvents } = require("@deepgram/sdk");
2
3const live = async () => {
4 const deepgram = createClient("DEEPGRAM_API_KEY");
5 let connection;
6 let keepAlive;
7
8 const setupDeepgram = () => {
9 connection = deepgram.listen.live({
10 model: "nova-3",
11 utterance_end_ms: 1500,
12 interim_results: true,
13 });
14
15 if (keepAlive) clearInterval(keepAlive);
16 keepAlive = setInterval(() => {
17 console.log("KeepAlive sent.");
18 connection.keepAlive();
19 }, 3000); // Sending KeepAlive messages every 3 seconds
20
21 connection.on(LiveTranscriptionEvents.Open, () => {
22 console.log("Connection opened.");
23 });
24
25 connection.on(LiveTranscriptionEvents.Close, () => {
26 console.log("Connection closed.");
27 clearInterval(keepAlive);
28 });
29
30 connection.on(LiveTranscriptionEvents.Metadata, (data) => {
31 console.log(data);
32 });
33
34 connection.on(LiveTranscriptionEvents.Transcript, (data) => {
35 console.log(data.channel);
36 });
37
38 connection.on(LiveTranscriptionEvents.UtteranceEnd, (data) => {
39 console.log(data);
40 });
41
42 connection.on(LiveTranscriptionEvents.SpeechStarted, (data) => {
43 console.log(data);
44 });
45
46 connection.on(LiveTranscriptionEvents.Error, (err) => {
47 console.error(err);
48 });
49 };
50
51 setupDeepgram();
52};
53
54live();

Word Timings

Word timings for transcription results returned from a stream are based on the audio sent, not the lifetime of the websocket. If you send KeepAlive messages without sending audio payloads for a period of time, then resume sending audio payloads, the timestamps for transcription results will pick up where they left off when you paused sending audio payloads.

Here is an example timeline demonstrating the behavior:

EventWall TimeWord Timing Range on Results Response
Websocket opened, begin sending audio payloads0 seconds0 seconds
Results received5 seconds0-5 seconds
Results received10 seconds5-10 seconds
Pause sending audio payloads, while sending KeepAlive messages10 secondsn/a
Resume sending audio payloads30 secondsn/a
Results received35 seconds10-15 seconds

Built with