Skip to main content

Class: FallbackSTTProxy

Defined in: packages/agentos/src/speech/FallbackProxy.ts:89

A SpeechToTextProvider that wraps an ordered chain of STT providers and implements automatic failover.

Retry Chain Logic​

Providers are tried left-to-right (index 0 first, then 1, etc.). The first successful transcription result is returned immediately. When a provider throws:

  • If it is NOT the last provider: The error is caught, a provider_fallback event is emitted on the shared EventEmitter, and the next provider is tried. Errors are caught per-provider so that a single API outage doesn't block the entire pipeline.

  • If it IS the last provider: The error is re-thrown to the caller, since there are no more fallbacks to try.

  • If the chain is empty: An Error('No providers in fallback chain') is thrown immediately.

Why Errors are Caught Per-Provider​

Each provider in the chain operates independently. A Deepgram API key expiration should not prevent OpenAI Whisper from transcribing the same audio. Catching errors per-provider ensures maximum availability at the cost of slightly increased latency when early providers fail.

See​

ProviderFallbackEvent for the event payload shape See SpeechProviderResolver.resolveSTT() for how this proxy is created.

Example​

const proxy = new FallbackSTTProxy([whisperProvider, deepgramProvider], emitter);
const result = await proxy.transcribe(audio);
// If whisperProvider fails, deepgramProvider is tried automatically.

Implements​

Constructors​

Constructor​

new FallbackSTTProxy(chain, emitter): FallbackSTTProxy

Defined in: packages/agentos/src/speech/FallbackProxy.ts:127

Creates a new FallbackSTTProxy wrapping the given provider chain.

Parameters​

chain​

SpeechToTextProvider[]

Ordered list of STT providers to try. Must contain at least one entry for transcribe() to succeed, though an empty chain is allowed at construction time (it will always throw on transcribe).

emitter​

EventEmitter

EventEmitter on which provider_fallback events are published. Typically the SpeechProviderResolver instance.

Returns​

FallbackSTTProxy

Example​

const proxy = new FallbackSTTProxy(
  [primaryProvider, fallbackProvider],
  resolver, // extends EventEmitter
);

Properties​

displayName​

readonly displayName: string

Defined in: packages/agentos/src/speech/FallbackProxy.ts:100

Human-readable name showing the full chain for debugging and logging. Format: "Fallback STT (provider1 -> provider2 -> ...)".

Implementation of​

SpeechToTextProvider.displayName

id​

readonly id: string

Defined in: packages/agentos/src/speech/FallbackProxy.ts:94

Unique identifier derived from the first provider in the chain. Falls back to 'fallback-stt' for empty chains to avoid undefined access.

Implementation of​

SpeechToTextProvider.id

supportsStreaming​

readonly supportsStreaming: boolean

Defined in: packages/agentos/src/speech/FallbackProxy.ts:108

Whether the proxy supports streaming. Only true when the first (primary) provider supports streaming — fallback providers' streaming capabilities are not considered because mid-stream provider switching is not supported.

Implementation of​

SpeechToTextProvider.supportsStreaming

Methods​

getProviderName()​

getProviderName(): string

Defined in: packages/agentos/src/speech/FallbackProxy.ts:203

Returns the human-readable name of the primary (first) provider in the chain.

Returns​

string

The provider name string, or 'fallback' if the chain is empty.

Example​

proxy.getProviderName(); // 'OpenAI Whisper' (from the first chain entry)

Implementation of​

SpeechToTextProvider.getProviderName

transcribe()​

transcribe(audio, options?): Promise<SpeechTranscriptionResult>

Defined in: packages/agentos/src/speech/FallbackProxy.ts:159

Attempt transcription using each provider in the chain in order.

Emits a provider_fallback event (typed as ProviderFallbackEvent) whenever a non-final provider throws. Re-throws the last provider's error when the entire chain is exhausted.

Parameters​

audio​

SpeechAudioInput

The audio input to transcribe.

options?​

SpeechTranscriptionOptions

Optional transcription settings (language, model, etc.).

Returns​

Promise<SpeechTranscriptionResult>

The transcription result from the first provider that succeeds.

Throws​

'No providers in fallback chain' when the chain is empty.

Throws​

The last provider's error when all providers in the chain fail.

Example​

const result = await proxy.transcribe(
  { data: wavBuffer, mimeType: 'audio/wav' },
  { language: 'en-US' },
);

Implementation of​

SpeechToTextProvider.transcribe