Finalize
Streaming:Nova
Use the Finalize message to flush the WebSocket stream. This forces the server to immediately process any unprocessed audio data and return the final transcription results.
Purpose
Section titled “Purpose”In real-time audio processing, there are scenarios where you may need to force the server to process (or flush) all unprocessed audio data immediately. Deepgram supports a Finalize message to handle such situations, ensuring that interim results are treated as final.
Example Payloads
Section titled “Example Payloads”To send the Finalize message, you need to send the following JSON message to the server:
{
"type": "Finalize"
}You can optionally specify a channel field to finalize a specific channel. If the channel field is omitted, all channels in the audio will be finalized. Note that channel indexing starts at 0, so to finalize only the first channel you need to send:
{
"type": "Finalize",
"channel": 0
}Upon receiving the Finalize message, the server will process all remaining audio data and return the final results. You may receive a response with the from_finalize attribute set to true, indicating that the finalization process is complete. This response typically occurs when there is a noticeable amount of audio buffered in the server.
If you specified a channel to be finalized, use the response’s channel_index field to check which channel was finalized.
{
"from_finalize": true
}Language-Specific Implementations
Section titled “Language-Specific Implementations”Below are code examples to help you get started using Finalize.
Sending a Finalize message in JSON Format
Section titled “Sending a Finalize message in JSON Format”These snippets demonstrate how to construct a JSON message containing the “Finalize” type and send it over the WebSocket connection in each respective language.
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 Finalize message
const finalizeMsg = JSON.stringify({ type: "Finalize" });
// Send Finalize message
ws.send(finalizeMsg);
});Streaming Examples
Section titled “Streaming Examples”Here are more complete examples that make a streaming request and use Finalize. Try running these examples to see how Finalize can be sent to Deepgram, forcing the API to process all unprocessed audio data and immediately return the results.
const WebSocket = require("ws");
const axios = require("axios");
const { PassThrough } = require("stream");
const apiKey = "YOUR_DEEPGRAM_API_KEY";
const headers = {
Authorization: `Token ${apiKey}`,
};
// Initialize WebSocket connection
const ws = new WebSocket("wss://api.deepgram.com/v1/listen", { headers });
ws.on("open", async function open() {
console.log("WebSocket connection established.");
try {
// Fetch the audio stream from the remote URL
const response = await axios({
method: "get",
url: "http://stream.live.vc.bbcmedia.co.uk/bbc_world_service",
responseType: "stream",
});
const passThrough = new PassThrough();
response.data.pipe(passThrough);
passThrough.on("data", (chunk) => {
ws.send(chunk);
});
passThrough.on("end", () => {
console.log("Audio stream ended.");
finalizeWebSocket();
});
passThrough.on("error", (err) => {
console.error("Stream error:", err.message);
});
// Send Finalize message after 10 seconds
setTimeout(() => {
finalizeWebSocket();
}, 10000);
} catch (error) {
console.error("Error fetching audio stream:", error.message);
}
});
// Handle WebSocket message event
ws.on("message", function incoming(data) {
let response = JSON.parse(data);
if (response.type === "Results") {
console.log("Transcript: ", response.channel.alternatives[0].transcript);
}
});
// Handle WebSocket close event
ws.on("close", function close() {
console.log("WebSocket connection closed.");
});
// Handle WebSocket error event
ws.on("error", function error(err) {
console.error("WebSocket error:", err.message);
});
// Send Finalize message to WebSocket
function finalizeWebSocket() {
const finalizeMsg = JSON.stringify({ type: "Finalize" });
ws.send(finalizeMsg);
console.log("Finalize message sent.");
}
// Gracefully close the WebSocket connection when done
function closeWebSocket() {
const closeMsg = JSON.stringify({ type: "CloseStream" });
ws.send(closeMsg);
ws.close();
}
// Close WebSocket when process is terminated
process.on("SIGINT", () => {
closeWebSocket();
process.exit();
});