ElevenLabsSTT

Defined in: src/providers/stt/elevenlabs/ElevenLabsSTT.ts:317

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

Remarks

This provider establishes a WebSocket connection to the ElevenLabs Scribe V2 real-time STT API (or a proxy server). Audio chunks are base64-encoded and sent as JSON input_audio_chunk messages. Transcription results are received as partial_transcript and committed_transcript messages.

The lifecycle is:

1. Construct with ElevenLabsSTTConfig
2. Call initialize() to validate configuration and build the WebSocket URL
3. Call connect() to open the WebSocket and wait for session_started
4. Call sendAudio() to stream audio chunks for transcription
5. Call disconnect() to close the WebSocket
6. Call dispose() to release all resources

Audio flow: Microphone -> AudioCapture -> sendAudio(chunk) -> WebSocket -> Scribe V2

Example

import { ElevenLabsSTT } from 'composite-voice';

const stt = new ElevenLabsSTT({
  proxyUrl: 'http://localhost:3001/api/proxy/elevenlabs',
  model: 'scribe_v2_realtime',
  commitStrategy: 'vad',
  audioFormat: 'pcm_16000',
});

await stt.initialize();
await stt.connect();

stt.onTranscription((result) => {
  if (result.isFinal) {
    console.log('Final:', result.text);
  } else {
    console.log('Partial:', result.text);
  }
});

// Stream audio chunks from microphone...
stt.sendAudio(audioChunk);

await stt.disconnect();

See

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

Extends

• LiveSTTProvider

Constructors

Constructor

new ElevenLabsSTT(config, logger?): ElevenLabsSTT;

Defined in: src/providers/stt/elevenlabs/ElevenLabsSTT.ts:331

Creates a new ElevenLabsSTT provider instance.

Parameters

Returns

ElevenLabsSTT

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/elevenlabs/ElevenLabsSTT.ts:479

Opens a WebSocket connection and waits for the session_started message.

Returns

Promise<void>

Remarks

Establishes a WebSocket connection to the ElevenLabs real-time STT endpoint (or proxy). The connect promise does not resolve until the server sends a session_started message, ensuring the session is fully initialized before audio streaming begins.

Auto-reconnect is disabled because each STT session is stateful and cannot be resumed after disconnection.

Throws

ProviderConnectionError if the connection fails or times out.

Overrides

LiveSTTProvider.connect

disconnect()

disconnect(): Promise<void>;

Defined in: src/providers/stt/elevenlabs/ElevenLabsSTT.ts:770

Disconnects from the ElevenLabs WebSocket.

Returns

Promise<void>

Remarks

Sends a final commit message to flush any buffered audio, waits briefly for remaining transcription results, then gracefully closes the WebSocket connection and releases the WebSocketManager instance.

Throws

Rethrows any error that occurs 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/elevenlabs/ElevenLabsSTT.ts:828

Checks whether the WebSocket connection to ElevenLabs is currently active.

Returns

boolean

true if the WebSocket is connected, false otherwise.

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/elevenlabs/ElevenLabsSTT.ts:376

Disposes the provider, disconnecting and releasing resources.

Returns

Promise<void>

Overrides

LiveSTTProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

Defined in: src/providers/stt/elevenlabs/ElevenLabsSTT.ts:346

Validates configuration and builds the WebSocket URL with query parameters.

Logs a debug warning if none of apiKey, token, or proxyUrl is configured.

Returns

Promise<void>

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/elevenlabs/ElevenLabsSTT.ts:671

Sends a raw audio chunk to ElevenLabs for real-time transcription.

Parameters

Returns

void

Remarks

The audio ArrayBuffer is base64-encoded and sent as an input_audio_chunk JSON message. The previous_text context field is included only on the first audio chunk (when configured), to provide transcription context without sending it repeatedly.

Overrides

LiveSTTProvider.sendAudio

sendCommit()

sendCommit(): void;

Defined in: src/providers/stt/elevenlabs/ElevenLabsSTT.ts:732

Manually commits the current audio buffer, finalizing any partial transcript.

Returns

void

Remarks

This method is only meaningful when commitStrategy is 'manual'. In manual mode, the server buffers incoming audio and emits partial_transcript messages but does not finalize (commit) the transcript until instructed. Calling sendCommit() sends an empty input_audio_chunk with commit: true, telling the server to produce a committed_transcript for the buffered audio.

When commitStrategy is 'vad', this method is a no-op because the server automatically commits based on silence detection.

Example

const stt = new ElevenLabsSTT({
  proxyUrl: 'http://localhost:3001/api/proxy/elevenlabs',
  commitStrategy: 'manual',
});

// After streaming audio, manually commit to get final transcript:
stt.sendCommit();

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