ElevenLabsTTS

Defined in: src/providers/tts/elevenlabs/ElevenLabsTTS.ts:243

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

Remarks

This provider establishes a WebSocket connection to the ElevenLabs streaming TTS API (or a proxy server). Text chunks are sent as JSON messages and audio is received either as base64-encoded JSON or raw binary data. The provider uses the ElevenLabs stream-input protocol with BOS (Beginning of Stream) and EOS (End of Stream) messages.

The lifecycle is:

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

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

Example

import { ElevenLabsTTS } from 'composite-voice';

const tts = new ElevenLabsTTS({
  apiKey: 'el-xxxxxxxxxxxx',
  voiceId: '21m00Tcm4TlvDq8ikWAM',
  modelId: 'eleven_turbo_v2_5',
  outputFormat: 'pcm_24000',
});

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

tts.onAudio((chunk) => {
  // Process audio chunk
});

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

See

• LiveTTSProvider - The base class this provider extends.
• ElevenLabsTTSConfig - Configuration options for this provider.
• WebSocketManager - The WebSocket manager used for connection handling.

Extends

• LiveTTSProvider

Constructors

Constructor

new ElevenLabsTTS(config, logger?): ElevenLabsTTS;

Defined in: src/providers/tts/elevenlabs/ElevenLabsTTS.ts:263

Creates a new ElevenLabsTTS provider instance.

Parameters

Returns

ElevenLabsTTS

Example

const tts = new ElevenLabsTTS({
  apiKey: 'el-xxxxxxxxxxxx',
  voiceId: '21m00Tcm4TlvDq8ikWAM',
});

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

connect()

connect(): Promise<void>;

Defined in: src/providers/tts/elevenlabs/ElevenLabsTTS.ts:352

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

Returns

Promise<void>

Remarks

Establishes a WebSocket connection and sends the BOS (Beginning of Stream) message, which includes voice settings (stability and similarity boost) and the API key (when not using a proxy). Auto-reconnect is disabled for TTS sessions since each session is typically short-lived.

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

Throws

ProviderConnectionError if the WebSocket connection fails.

Overrides

LiveTTSProvider.connect

disconnect()

disconnect(): Promise<void>;

Defined in: src/providers/tts/elevenlabs/ElevenLabsTTS.ts:623

Disconnects from the ElevenLabs WebSocket.

Returns

Promise<void>

Remarks

Gracefully closes the WebSocket connection and releases the WebSocketManager instance.

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/elevenlabs/ElevenLabsTTS.ts:565

Finalizes the current synthesis session by sending the EOS (End of Stream) message.

Returns

Promise<void>

Remarks

Sends an empty text message with flush: true to signal the end of input and trigger generation of any remaining buffered audio. Waits up to 2 seconds for final audio to arrive before resolving.

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/elevenlabs/ElevenLabsTTS.ts:649

Checks whether the WebSocket connection to ElevenLabs 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/elevenlabs/ElevenLabsTTS.ts:308

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/elevenlabs/ElevenLabsTTS.ts:282

Validates configuration and prepares the provider for connection.

Returns

Promise<void>

Throws

ProviderInitializationError if neither apiKey nor proxyUrl is configured.

Throws

ProviderInitializationError if voiceId is not provided.

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(chunk): void;

Defined in: src/providers/tts/elevenlabs/ElevenLabsTTS.ts:537

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

Parameters

Returns

void

Remarks

The text is wrapped in a JSON message with try_trigger_generation: true, which instructs ElevenLabs to begin generating audio as soon as enough text has been buffered. If not connected, the call is silently ignored with a warning log.

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