DeepgramTTS

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:147

Deepgram TTS provider for real-time streaming text-to-speech via native WebSocket.

Remarks

This provider connects directly to Deepgram’s TTS WebSocket API without the @deepgram/sdk. Text chunks are sent incrementally and audio chunks are emitted as they arrive, enabling low-latency speech output.

The lifecycle is:

1. Construct with DeepgramTTSConfig
2. Call initialize() to validate configuration
3. Call connect() to open the WebSocket connection
4. Call sendText() to stream text for synthesis
5. Call finalize() to flush remaining audio
6. Call disconnect() to close the WebSocket
7. Call dispose() to release all resources

Audio flow: Text chunks -> WebSocket -> Deepgram -> Audio chunks -> onAudio callback

Example

import { DeepgramTTS } from 'composite-voice';

const tts = new DeepgramTTS({
  apiKey: 'dg-xxxxxxxxxxxx',
  voice: 'aura-2-thalia-en',
  sampleRate: 24000,
  outputFormat: 'linear16',
});

await tts.initialize();
await tts.connect();

tts.onAudio((chunk) => {
  // Process audio chunk (e.g., feed to AudioPlayer)
});

tts.sendText('Hello, world!');
await tts.finalize();
await tts.disconnect();

See

• LiveTTSProvider - The base class this provider extends.
• DeepgramTTSConfig - Configuration options for this provider.

Extends

• LiveTTSProvider

Constructors

Constructor

new DeepgramTTS(config, logger?): DeepgramTTS;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:165

Creates a new DeepgramTTS provider instance.

Parameters

Returns

DeepgramTTS

Overrides

LiveTTSProvider.constructor

Properties

Accessors

isProxyMode

Get Signature

get protected isProxyMode(): boolean;

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

Whether the provider is in proxy mode.

Returns

boolean

true when proxyUrl is set.

Inherited from

LiveTTSProvider.isProxyMode

Methods

assertAuth()

protected assertAuth(): void;

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

Validate that auth is configured (either apiKey or proxyUrl).

Returns

void

Remarks

Call this in onInitialize() for any provider that requires external authentication. Native providers (NativeSTT, NativeTTS) and in-browser providers (WebLLM) should NOT call this method.

Throws

ProviderInitializationError Thrown when neither apiKey nor proxyUrl is set.

Inherited from

LiveTTSProvider.assertAuth

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

LiveTTSProvider.assertReady

clearBuffer()

clearBuffer(): void;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:480

Clears the Deepgram TTS audio buffer.

Returns

void

Remarks

Sends a { "type": "Clear" } JSON message. This immediately discards any buffered text and audio that has not yet been sent to the client. Useful for interrupting speech when the user starts talking (barge-in).

If not connected, the call is silently ignored with a warning log.

connect()

connect(): Promise<void>;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:242

Connects to the Deepgram WebSocket for real-time TTS streaming.

Returns

Promise<void>

Remarks

Establishes a native WebSocket connection with the configured model, encoding, and sample rate as query parameters. The connection emits audio chunks as Deepgram processes incoming text.

In direct mode, auth is sent via WebSocket subprotocol ["token", apiKey]. In proxy mode, no auth is sent — the proxy injects the real key.

This method is idempotent — calling it when already connected is a no-op.

Throws

ProviderConnectionError if the connection fails or times out.

Overrides

LiveTTSProvider.connect

disconnect()

disconnect(): Promise<void>;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:503

Disconnects from the Deepgram WebSocket.

Returns

Promise<void>

Remarks

Sends a Flush then Close message for graceful server-side cleanup. Waits for the WebSocket to close (with a 1-second timeout).

Throws

Rethrows any error that occurs during disconnection.

Overrides

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

LiveTTSProvider.dispose

emitAudio()

protected emitAudio(chunk): void;

Defined in: src/providers/base/BaseTTSProvider.ts:190

Emit a synthesized audio chunk to the registered callback.

Parameters

Returns

void

Remarks

Subclasses call this method for each chunk of audio produced during synthesis. If no callback has been registered the chunk is silently dropped.

Inherited from

LiveTTSProvider.emitAudio

emitMetadata()

protected emitMetadata(metadata): void;

Defined in: src/providers/base/BaseTTSProvider.ts:206

Emit audio metadata to the registered callback.

Parameters

Returns

void

Remarks

Typically called once at the start of synthesis when the provider knows the output format. If no callback has been registered the metadata is silently dropped.

Inherited from

LiveTTSProvider.emitMetadata

finalize()

finalize(): Promise<void>;

Defined in: src/providers/base/LiveTTSProvider.ts:165

Finalize synthesis — flush remaining audio.

Returns

Promise<void>

Remarks

Called after all text has been sent via processChunk. Delegates to finalizeSocket, which subclasses implement to flush the WebSocket connection.

Inherited from

LiveTTSProvider.finalize

finalizeSocket()

protected finalizeSocket(): Promise<void>;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:439

Finalizes the current synthesis session by flushing remaining audio.

Returns

Promise<void>

Remarks

Sends a { "type": "Flush" } JSON message to ensure all buffered text has been processed and all resulting audio has been emitted. Waits for the Flushed event or a 1-second timeout before resolving.

Called by the base class’s LiveTTSProvider.finalize method.

Throws

Rethrows any error that occurs during finalization.

Overrides

LiveTTSProvider.finalizeSocket

getConfig()

getConfig(): TTSProviderConfig;

Defined in: src/providers/base/BaseTTSProvider.ts:217

Get a shallow copy of the current TTS configuration.

Returns

TTSProviderConfig

A new TTSProviderConfig object.

Inherited from

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

LiveTTSProvider.initialize

isAudioReady()

isAudioReady(chunk): boolean;

Defined in: src/providers/base/BaseTTSProvider.ts:145

Is this audio chunk ready for playback?

Parameters

Returns

boolean

true when the chunk has valid audio data.

Remarks

The orchestrator calls this to validate audio chunks before passing them to the audio player. The default implementation checks that the chunk has non-zero data.

Inherited from

LiveTTSProvider.isAudioReady

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

LiveTTSProvider.isReady

isWebSocketConnected()

isWebSocketConnected(): boolean;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:558

Checks whether the WebSocket connection to Deepgram is currently active.

Returns

boolean

true if the WebSocket is connected, false otherwise.

onAudio()

onAudio(callback): void;

Defined in: src/providers/base/BaseTTSProvider.ts:161

Register a callback to receive synthesized audio chunks.

Parameters

Returns

void

Remarks

All TTS providers — regardless of transport — deliver audio through this callback. CompositeVoice registers it during pipeline setup so that audio data flows into the AudioPlayer.

Inherited from

LiveTTSProvider.onAudio

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

LiveTTSProvider.onConfigUpdate

onDispose()

protected onDispose(): Promise<void>;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:197

Disposes the provider, disconnecting from the WebSocket and releasing resources.

Returns

Promise<void>

Overrides

LiveTTSProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:180

Validate configuration — no SDK import required.

Returns

Promise<void>

Throws

ProviderInitializationError if neither apiKey nor proxyUrl is configured.

Overrides

LiveTTSProvider.onInitialize

onMetadata()

onMetadata(callback): void;

Defined in: src/providers/base/BaseTTSProvider.ts:176

Register a callback to receive audio metadata.

Parameters

Returns

void

Remarks

Metadata (sample rate, encoding, channels, etc.) helps the AudioPlayer configure playback correctly. Providers may emit metadata once at the start of synthesis but are not required to.

Inherited from

LiveTTSProvider.onMetadata

processChunk()

processChunk(text): void;

Defined in: src/providers/base/LiveTTSProvider.ts:141

Process a text chunk by sending it over the WebSocket for synthesis.

Parameters

Returns

void

Remarks

Legacy alias for sendText. Delegates to sendTextToSocket.

Inherited from

LiveTTSProvider.processChunk

resolveApiKey()

protected resolveApiKey(): string;

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

Resolve the API key for this provider.

Returns

string

The configured API key, or 'proxy' in proxy mode.

Remarks

Returns 'proxy' in proxy mode so that SDK clients (which require a non-empty API key string) can be instantiated without the real key.

Inherited from

LiveTTSProvider.resolveApiKey

resolveAuthHeader()

protected resolveAuthHeader(defaultAuthType?): string | undefined;

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

Resolve Authorization header value for the configured auth type.

Parameters

Returns

string | undefined

The Authorization header value, or undefined in proxy mode.

Remarks

Returns the header value for REST or server-side WebSocket connections:

• 'token' → 'Token <apiKey>'
• 'bearer' → 'Bearer <apiKey>'

Returns undefined in proxy mode.

Inherited from

LiveTTSProvider.resolveAuthHeader

resolveBaseUrl()

protected resolveBaseUrl(defaultUrl?): string | undefined;

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

Resolve the base URL for this provider.

Parameters

Returns

string | undefined

The resolved URL, or undefined when all sources are unset.

Remarks

Priority: proxyUrl > endpoint > defaultUrl.

For WebSocket providers (this.type === 'websocket'), the proxy URL’s http(s) scheme is automatically converted to ws(s).

When no URL is configured and defaultUrl is undefined, the return value is undefined — this lets SDK-based providers (Anthropic, OpenAI) fall back to their own built-in defaults.

Inherited from

LiveTTSProvider.resolveBaseUrl

resolveWsProtocols()

protected resolveWsProtocols(defaultAuthType?): string[] | undefined;

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

Resolve WebSocket subprotocol for authentication.

Parameters

Returns

string[] | undefined

Subprotocol array for new WebSocket(url, protocols), or undefined.

Remarks

Returns the subprotocol array for direct mode based on authType:

• 'token' → ['token', apiKey] (Deepgram default)
• 'bearer' → ['bearer', apiKey] (OAuth/Bearer tokens)

Returns undefined in proxy mode (no client-side auth needed).

Inherited from

LiveTTSProvider.resolveWsProtocols

sendText()

sendText(chunk): void;

Defined in: src/providers/base/LiveTTSProvider.ts:129

Send a text chunk for real-time synthesis.

Parameters

Returns

void

Remarks

This is the public method required by the ILiveTTSProvider interface. It delegates to sendTextToSocket, which subclasses implement to forward text over the WebSocket connection.

Inherited from

LiveTTSProvider.sendText

sendTextToSocket()

protected sendTextToSocket(text): void;

Defined in: src/providers/tts/deepgram/DeepgramTTS.ts:414

Sends a text chunk to Deepgram for real-time synthesis.

Parameters

Returns

void

Remarks

Sends a { "type": "Speak", "text": "..." } JSON message over the WebSocket. Deepgram processes the text incrementally and emits audio chunks. If not connected, the call is silently ignored with a warning log.

Called by the base class’s LiveTTSProvider.sendText method.

Overrides

LiveTTSProvider.sendTextToSocket

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

LiveTTSProvider.updateConfig