FallbackSTT

Defined in: src/providers/stt/fallback/FallbackSTT.ts:142

A meta STT provider that chains multiple live STT providers with automatic failover.

Remarks

FallbackSTT implements the LiveSTTProvider interface itself, so it drops into the providers array anywhere a single STT provider would go. Providers are tried in the order given:

• Initialization: all providers are initialized concurrently. Providers that fail to initialize are marked dead; the first healthy provider becomes active. Initialization only fails if every provider fails.
• Connection: connect() tries the active provider first. On a connection error or timeout (FallbackSTTOptions.connectTimeout) it advances to the next healthy provider. It throws only when the whole chain is exhausted.
• Mid-session: when the active provider reports a streaming error (an error transcription result, or a throwing sendAudio()), the chain disconnects it, connects the next provider, and replays audio buffered during the swap. Transcription results from providers that were failed away from are discarded.

A failed provider stays dead until FallbackSTT.resetToPrimary is called — during a vendor outage there is no point repeatedly retrying the primary within the same session.

Every swap invokes the callbacks registered via FallbackSTT.onFallback. CompositeVoice registers one automatically and re-emits the swap as a 'provider.fallback' event.

Constraints:

• All chained providers must be live (type: 'websocket') — REST STT providers don’t participate in the streaming audio path.
• All chained providers must cover only the 'stt' role. Multi-role providers (e.g. NativeSTT, which manages its own microphone) own their audio path and cannot be swapped mid-session.

Example

import { CompositeVoice, FallbackSTT, DeepgramSTT, AssemblyAISTT } from 'composite-voice';

const agent = new CompositeVoice({
  providers: [
    new FallbackSTT([
      new DeepgramSTT({ proxyUrl: '/api/proxy/deepgram' }),
      new AssemblyAISTT({ proxyUrl: '/api/proxy/assemblyai' }),
    ]),
    new AnthropicLLM({ model: 'claude-haiku-4-5' }),
    new DeepgramTTS({ proxyUrl: '/api/proxy/deepgram' }),
  ],
});

agent.on('provider.fallback', ({ from, to, reason }) => {
  console.warn(`STT failed over from ${from} to ${to} (${reason})`);
});

See

• ProviderFallbackInfo for the failover notification payload
• FallbackSTTOptions for configuration options

Implements

• LiveSTTProvider
• FallbackCapableProvider

Constructors

Constructor

new FallbackSTT(providers, options?): FallbackSTT;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:208

Create a fallback chain over the given STT providers.

Parameters

Returns

FallbackSTT

Throws

ConfigurationError If the array is empty, contains a REST provider, or contains a multi-role provider.

Properties

Accessors

activeProvider

Get Signature

get activeProvider(): STTProvider;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:250

The provider currently receiving audio and producing transcriptions.

Returns

STTProvider

config

Get Signature

get config(): STTProviderConfig;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:243

The currently active provider’s configuration.

Returns

STTProviderConfig

Implementation of

LiveSTTProvider.config

Methods

connect()

connect(): Promise<void>;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:400

Connect the active provider, advancing down the chain on failure.

Returns

Promise<void>

Throws

The last provider’s connection error when every remaining provider in the chain fails to connect.

Implementation of

LiveSTTProvider.connect

disconnect()

disconnect(): Promise<void>;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:443

Disconnect from the streaming transcription service.

Returns

Promise<void>

Remarks

Closes the WebSocket connection. Can be reconnected by calling LiveSTTProvider.connect | connect again.

Implementation of

LiveSTTProvider.disconnect

dispose()

dispose(): Promise<void>;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:373

Clean up resources and dispose of the provider.

Returns

Promise<void>

Remarks

Called by CompositeVoice during agent shutdown. The provider should close any open connections, clear buffers, and release resources.

Implementation of

LiveSTTProvider.dispose

initialize()

initialize(): Promise<void>;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:330

Initialize the provider and allocate any required resources.

Returns

Promise<void>

Remarks

Called by CompositeVoice during agent startup. The provider should be ready to process requests after this method resolves.

Throws

Error if initialization fails (e.g., invalid API key, network error)

Implementation of

LiveSTTProvider.initialize

isFinal()

isFinal(result): boolean;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:469

Check whether a transcription result is final (committed text).

Parameters

Returns

boolean

true when the result is a committed, final transcript.

Implementation of

LiveSTTProvider.isFinal

isInterim()

isInterim(result): boolean;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:465

Check whether a transcription result is interim (not yet finalised).

Parameters

Returns

boolean

true when the result is a partial, non-committed transcript.

Implementation of

LiveSTTProvider.isInterim

isPreflight()

isPreflight(result): boolean;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:461

Check whether a transcription result is a preflight (speculative) signal.

Parameters

Returns

boolean

true when the result is a speculative early signal used by the eager LLM pipeline.

Implementation of

LiveSTTProvider.isPreflight

isReady()

isReady(): boolean;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:388

Check if the provider is initialized and ready to process requests.

Returns

boolean

true if the provider has been initialized and is operational

Implementation of

LiveSTTProvider.isReady

isUtteranceComplete()

isUtteranceComplete(result): boolean;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:457

Check whether a transcription result signals an utterance-complete event.

Parameters

Returns

boolean

true when the result indicates the user has finished speaking.

Implementation of

LiveSTTProvider.isUtteranceComplete

onFallback()

onFallback(callback): void | () => void;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:274

Register a callback invoked whenever the chain fails over to another provider.

Parameters

Returns

void | () => void

Remarks

CompositeVoice registers one automatically and re-emits each swap as a 'provider.fallback' SDK event, so most applications subscribe there instead. Multiple callbacks may be registered.

Implementation of

FallbackCapableProvider.onFallback

onTranscription()

onTranscription(callback): void;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:451

Register a callback for transcription results.

Parameters

Returns

void

Remarks

The provider calls this callback with transcription results as they arrive over the WebSocket connection. Must be called before LiveSTTProvider.connect | connect.

Implementation of

LiveSTTProvider.onTranscription

resetToPrimary()

resetToPrimary(): void;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:320

Clear all dead-provider markers and make the first provider active again.

Returns

void

Remarks

Call this between sessions (while not connected) to probe whether the primary has recovered from its outage. The chain never does this automatically — within a session, retrying a failed vendor would risk flapping.

Throws

InvalidStateError If called while a streaming session is active.

sendAudio()

sendAudio(chunk): void;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:420

Send an audio chunk for real-time transcription.

Parameters

Returns

void

Remarks

CompositeVoice calls this method with audio data captured from the microphone. The chunk is sent to the transcription service over the established connection.

Implementation of

LiveSTTProvider.sendAudio

setReconnectHeaderSource()

setReconnectHeaderSource(source): () => void;

Defined in: src/providers/stt/fallback/FallbackSTT.ts:299

Register a source for the cached audio container header.

Parameters

Returns

An unsubscribe function that clears this source if it is still the registered one. CompositeVoice calls it on initialize failure and dispose so a shared chain cannot retain a disposed agent’s cache.

(): void;

Returns

void

Remarks

When the input stream uses a container format (WebM/OGG/WAV), a provider that connects mid-stream needs the container header before any audio frames or it cannot demux them. The SDK re-injects the header from its AudioHeaderCache on every reconnect it drives itself; this hook lets the chain do the same for its internal failover reconnects. CompositeVoice wires this automatically.

Implementation of

FallbackCapableProvider.setReconnectHeaderSource