Class FallbackSTTProxy

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

Methods

transcribe getProviderName

Properties

id displayName supportsStreaming

Constructors

constructor

  • new FallbackSTTProxy(chain, emitter): FallbackSTTProxy

  • 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<DefaultEventMap>

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

    Returns FallbackSTTProxy

    Example

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

Methods

transcribe

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

  • 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

    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' },
    );

getProviderName

  • getProviderName(): string

  • 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)

Properties

Readonly id

id: string

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

Readonly displayName

displayName: string

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

Readonly supportsStreaming

supportsStreaming: boolean

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.

Settings

Member Visibility

Theme

On This Page

constructortranscribegetProviderNameiddisplayNamesupportsStreaming