Class FallbackAdapter

FallbackAdapter is a TTS wrapper that provides automatic failover between multiple TTS providers.

When the primary TTS fails, it automatically switches to the next available provider in the list. Failed providers are monitored in the background and restored when they recover.

Features:

  • Automatic failover to backup TTS providers on failure
  • Background health checks to restore recovered providers
  • Automatic audio resampling when TTS providers have different sample rates
  • Support for both streaming and non-streaming TTS providers

Example

import { FallbackAdapter } from '@livekit/agents';
import { TTS as OpenAITTS } from '@livekit/agents-plugin-openai';
import { TTS as ElevenLabsTTS } from '@livekit/agents-plugin-elevenlabs';

const fallbackTTS = new FallbackAdapter({
  ttsInstances: [
    new OpenAITTS(),      // Primary
    new ElevenLabsTTS(),  // Fallback
  ],
  maxRetryPerTTS: 2,      // Retry each TTS twice before moving to next
  recoveryDelayMs: 1000,  // Check recovery every 1 second
});

Hierarchy (view full)

Constructors

constructor

Properties

label maxRetryPerTTS recoveryDelayMs ttsInstances

Accessors

capabilities model numChannels provider sampleRate status

Methods

close getStreamingInstance markUnAvailable stream synthesize

Constructors

constructor

Properties

label

label: string = ...

Readonly maxRetryPerTTS

maxRetryPerTTS: number

Number of retries per TTS instance before falling back to the next one.

Readonly recoveryDelayMs

recoveryDelayMs: number

Delay in milliseconds before attempting to recover a failed TTS instance.

Readonly ttsInstances

ttsInstances: tts.TTS[]

The list of TTS instances used for fallback (in priority order).

Accessors

capabilities

model

  • get model(): string

  • Get the model name/identifier for this TTS instance.

    Returns string

    The model name if available, "unknown" otherwise.

    Remarks

    Plugins should override this property to provide their model information.

numChannels

  • get numChannels(): number

  • Returns the channel count of audio frames returned by this TTS

    Returns number

provider

  • get provider(): string

  • Get the provider name for this TTS instance.

    Returns string

    The provider name if available, "unknown" otherwise.

    Remarks

    Plugins should override this property to provide their provider information.

sampleRate

  • get sampleRate(): number

  • Returns the sample rate of audio frames returned by this TTS

    Returns number

status

Methods

close

  • close(): Promise<void>

  • Close the FallbackAdapter and all underlying TTS instances. This cancels any ongoing recovery tasks and cleans up resources.

    Returns Promise<void>

getStreamingInstance

markUnAvailable

stream

synthesize

Settings

Member Visibility

Theme

On This Page

constructorlabelmaxRetryPerTTSrecoveryDelayMsttsInstancescapabilitiesmodelnumChannelsprovidersampleRatestatusclosegetStreamingInstancemarkUnAvailablestreamsynthesize