In real-time audio processing, there are scenarios where you may need to force the server to close. Deepgram supports a CloseStream message to handle such situations. This message will send a shutdown command to the server instructing it to finish processing any cached data, send the response to the client, send a summary metadata object, and then terminate the WebSocket connection.

What is the CloseStream Message

The CloseStream message is a JSON command that you send to the Deepgram server, instructing it close the connection. This is particularly useful in scenarios where you need to immediately shutdown the websocket connection and process and return all data to the client.

Using the CloseStream Message

Sending CloseStream

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

{ 
  "type": "CloseStream" 
}

Close Stream Confirmation

Upon receiving the CloseStream message, the server will process all remaining audio data and return the following:

{
    "type": "Metadata",
    "transaction_key": "deprecated",
    "request_id": "8c8ebea9-dbec-45fa-a035-e4632cb05b5f",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "created": "2024-08-29T22:37:55.202Z",
    "duration": 0.0,
    "channels": 0
}

Language-Specific Implementations

const WebSocket = require("ws");

// Assuming 'headers' is already defined for authorization
const ws = new WebSocket("wss://api.deepgram.com/v1/listen", { headers });

ws.on('open', function open() {
  // Construct CloseStream message
  const closeStreamMsg = JSON.stringify({ type: "CloseStream" });
  
  // Send CloseStream message
  ws.send(closeStreamMsg);
});

import json
import websocket

# Assuming 'headers' is already defined for authorization
ws = websocket.create_connection("wss://api.deepgram.com/v1/listen", header=headers)

# Construct CloseStream message
closestream_msg = json.dumps({"type": "CloseStream"})

# Send CloseStream message
ws.send(closestream_msg)

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "github.com/gorilla/websocket"
)

func main() {
    // Define headers for authorization
    headers := http.Header{}
    headers.Add("Authorization", "Bearer YOUR_API_KEY") // Replace with your actual API key

    // Connect to the WebSocket server
    conn, _, err := websocket.DefaultDialer.Dial("wss://api.deepgram.com/v1/listen", headers)
    if err != nil {
        log.Fatal("Error connecting to WebSocket:", err)
    }
    defer conn.Close()

    // Construct CloseStream message
    closeStreamMsg := map[string]string{"type": "CloseStream"}
    jsonMsg, err := json.Marshal(closeStreamMsg)
    if err != nil {
        log.Fatal("Error encoding JSON:", err)
    }

    // Send CloseStream message
    err = conn.WriteMessage(websocket.TextMessage, jsonMsg)
    if err != nil {
        log.Fatal("Error sending CloseStream message:", err)
    }
}

using System;
using System.Net.WebSockets;
using System.Text;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Set up the WebSocket URL and headers
        Uri uri = new Uri("wss://api.deepgram.com/v1/listen");
        string apiKey = "YOUR_API_KEY"; // Replace with your actual API key

        // Create a new client WebSocket instance
        using (ClientWebSocket ws = new ClientWebSocket())
        {
            // Set the authorization header
            ws.Options.SetRequestHeader("Authorization", "Token " + apiKey);

            try
            {
                // Connect to the WebSocket server
                await ws.ConnectAsync(uri, CancellationToken.None);

                // Construct the CloseStream message
                string closeStreamMsg = "{\"type\": \"CloseStream\"}";

                // Convert the CloseStream message to a byte array
                byte[] finalizeBytes = Encoding.UTF8.GetBytes(closeStreamMsg);

                // Send the CloseStream message asynchronously
                await ws.SendAsync(new ArraySegment<byte>(finalizeBytes), WebSocketMessageType.Text, true, CancellationToken.None);
            }
            catch (WebSocketException ex)
            {
                Console.WriteLine("WebSocket error: " + ex.Message);
            }
            catch (Exception ex)
            {
                Console.WriteLine("General error: " + ex.Message);
            }
        }
    }
}

Conclusion

In summary, when dealing with real-time audio processing, there are situations where it may be necessary to forcibly close the server connection. Deepgram provides the CloseStream message to facilitate this process. By sending this message, the server is instructed to complete processing any buffered data, return the final response along with summary metadata, and then gracefully terminate the WebSocket connection. This ensures a controlled shutdown, preserving the integrity of the data and the overall process.