DeepgramSTT

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:277

Deepgram real-time STT provider using native WebSocket (no SDK required).

Remarks

DeepgramSTT extends LiveSTTProvider and connects to Deepgram’s V1 WebSocket streaming transcription API directly. It supports:

• Real-time interim and final transcription results
• Multi-segment utterance buffering (accumulates is_final segments until speech_final to deliver a complete utterance)
• Proxy mode via DeepgramSTTConfig.proxyUrl (recommended for production so the API key stays server-side)
• All V1 query parameters (model, language, punctuate, smart_format, etc.)
• Keep-alive and finalize (flush) methods

Transport: Native WebSocket (no @deepgram/sdk required)

Browser support: All modern browsers (Chrome, Firefox, Safari, Edge).

Auth in browser: Direct mode uses WebSocket subprotocol ["token", apiKey]; proxy mode omits auth (the proxy injects the key via HTTP headers).

Data flow:

Microphone -> AudioCapture -> sendAudio(chunk) -> Deepgram WebSocket
                                                      |
CompositeVoice <- onTranscription(result) <----------+

Example

import { DeepgramSTT } from 'composite-voice';

const stt = new DeepgramSTT({
  proxyUrl: 'http://localhost:3001/api/proxy/deepgram',
  language: 'en-US',
  interimResults: true,
  options: {
    model: 'nova-3',
    smartFormat: true,
    punctuation: true,
  },
});

await stt.initialize();

stt.onTranscription((result) => {
  if (result.isFinal && result.speechFinal) {
    console.log('Complete utterance:', result.text);
  }
});

await stt.connect();
// ... send audio chunks via stt.sendAudio(chunk) ...
stt.sendFinalize(); // flush pending audio
await stt.disconnect();

See

• LiveSTTProvider for the base WebSocket STT class
• DeepgramSTTConfig for configuration options
• DeepgramTranscriptionOptions for transcription parameters

Extends

• LiveSTTProvider

Constructors

Constructor

new DeepgramSTT(config, logger?): DeepgramSTT;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:332

Create a new DeepgramSTT provider.

Parameters

Returns

DeepgramSTT

Example

const stt = new DeepgramSTT({
  apiKey: 'dg_abc123...',
  options: { model: 'nova-3' },
});

Overrides

LiveSTTProvider.constructor

Properties

Methods

assertReady()

protected assertReady(): void;

Defined in: src/providers/base/BaseProvider.ts:255

Guard that throws if the provider has not been initialized.

Returns

void

Remarks

Call at the start of any method that requires the provider to be ready.

Throws

Error Thrown with a descriptive message when initialized is false.

Inherited from

LiveSTTProvider.assertReady

connect()

connect(): Promise<void>;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:491

Open a WebSocket connection to Deepgram for real-time transcription.

Returns

Promise<void>

Remarks

Builds the connection URL with all query parameters, creates a native WebSocket, and waits for the open event before resolving.

In direct mode, auth is sent via WebSocket subprotocol ["token", apiKey] (the standard Deepgram browser auth mechanism). In proxy mode, no auth is sent — the proxy injects the real API key via HTTP headers.

Throws

ProviderConnectionError Thrown when the provider is not initialized, or the connection times out / errors.

Overrides

LiveSTTProvider.connect

disconnect()

disconnect(): Promise<void>;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:848

Gracefully close the Deepgram WebSocket connection.

Returns

Promise<void>

Remarks

Sends a CloseStream control message for graceful server-side cleanup, then closes the WebSocket. Waits up to 1 second for the close event before force-resolving. Resets the utterance buffer and internal state.

Throws

Re-throws any unexpected error during disconnection.

Overrides

LiveSTTProvider.disconnect

dispose()

dispose(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:154

Clean up resources and dispose of the provider.

Returns

Promise<void>

Remarks

Delegates to the subclass hook onDispose and resets the initialized flag. If the provider is not initialized, the call is a no-op.

Throws

Re-throws any error raised by onDispose.

Inherited from

LiveSTTProvider.dispose

emitTranscription()

protected emitTranscription(result): void;

Defined in: src/providers/base/BaseSTTProvider.ts:113

Emit a transcription result to the registered callback.

Parameters

Returns

void

Remarks

Subclasses call this method whenever transcribed text is available. If no callback has been registered via onTranscription, the result is logged as a warning and dropped.

Inherited from

LiveSTTProvider.emitTranscription

getConfig()

getConfig(): STTProviderConfig;

Defined in: src/providers/base/BaseSTTProvider.ts:132

Get a shallow copy of the current STT configuration.

Returns

STTProviderConfig

A new STTProviderConfig object.

Inherited from

LiveSTTProvider.getConfig

initialize()

initialize(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:127

Initialize the provider, making it ready for use.

Returns

Promise<void>

Remarks

Calls the subclass hook onInitialize. If the provider has already been initialized the call is a no-op.

Throws

ProviderInitializationError Thrown when onInitialize rejects. The original error is wrapped with the provider class name for diagnostics.

Inherited from

LiveSTTProvider.initialize

isReady()

isReady(): boolean;

Defined in: src/providers/base/BaseProvider.ts:178

Check whether the provider has been initialized and is ready.

Returns

boolean

true when initialize has completed successfully and dispose has not yet been called.

Inherited from

LiveSTTProvider.isReady

isWebSocketConnected()

isWebSocketConnected(): boolean;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:903

Check whether the Deepgram WebSocket connection is currently open.

Returns

boolean

true when connected and ready to receive audio.

onConfigUpdate()

protected onConfigUpdate(_config): void;

Defined in: src/providers/base/BaseProvider.ts:242

Hook called after updateConfig merges new values.

Parameters

Returns

void

Remarks

The default implementation is a no-op. Override in subclasses to react to runtime configuration changes (e.g. reconnect with a new API key).

Inherited from

LiveSTTProvider.onConfigUpdate

onDispose()

protected onDispose(): Promise<void>;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:368

Disconnect the WebSocket (if connected) and release resources.

Returns

Promise<void>

Overrides

LiveSTTProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:347

Validate configuration — no SDK import required.

Returns

Promise<void>

Throws

ProviderInitializationError Thrown when neither apiKey nor proxyUrl is configured.

Overrides

LiveSTTProvider.onInitialize

onTranscription()

onTranscription(callback): void;

Defined in: src/providers/base/BaseSTTProvider.ts:98

Register a callback to receive transcription results.

Parameters

Returns

void

Remarks

All STT providers — regardless of transport — deliver text through this callback. CompositeVoice registers it during pipeline setup so that transcription results flow into the conversation manager and, ultimately, the LLM provider.

Inherited from

LiveSTTProvider.onTranscription

sendAudio()

sendAudio(chunk): void;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:781

Send a raw audio chunk to Deepgram for real-time transcription.

Parameters

Returns

void

Remarks

Sends the audio data as a binary WebSocket frame. If the connection is not open, the chunk is silently dropped and a warning is logged.

Overrides

LiveSTTProvider.sendAudio

sendFinalize()

sendFinalize(): void;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:824

Send a finalize signal to flush any pending audio and force a final transcription result from Deepgram.

Returns

void

Remarks

Sends { "type": "Finalize" } JSON message. This tells Deepgram to process any buffered audio and return a final result. Useful before disconnecting or when you need an immediate result.

sendKeepAlive()

sendKeepAlive(): void;

Defined in: src/providers/stt/deepgram/DeepgramSTT.ts:801

Send a keep-alive signal to prevent the WebSocket from timing out.

Returns

void

Remarks

Sends { "type": "KeepAlive" } JSON message. Useful for long pauses where no audio is being sent but the connection should remain open.

updateConfig()

updateConfig(config): void;

Defined in: src/providers/base/BaseProvider.ts:201

Merge partial configuration updates into the current config.

Parameters

Returns

void

Remarks

After merging, the subclass hook onConfigUpdate is called so providers can react to changed values at runtime.

Inherited from

LiveSTTProvider.updateConfig