Class FallbackAdapter

Agent Fallback Adapter for TTS. Manages multiple TTS instances, providing automatic fallback between 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

_wrappedTts capabilities markup model numChannels provider sampleRate status

Methods

close getStreamingInstance markUnAvailable prewarm releaseIdleConnections 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

_wrappedTts

capabilities

markup

model

  • get model(): string

  • The model of the instance that serves next (see nextInstance). Spans and metrics read this, so a failover shows the model expected to answer rather than the adapter; the instance that actually served is stamped per request by the stream.

    Returns string

numChannels

  • get numChannels(): number

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

    Returns number

provider

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

prewarm

  • prewarm(): void

  • Open the provider connection ahead of the first synthesis, so it does not pay for the handshake. Best effort and non-blocking. Called by the framework when an agent starts or resumes. Providers without a persistent connection need not override this.

    Returns void

releaseIdleConnections

stream

synthesize

Settings

Member Visibility

Theme

On This Page

constructorlabelmaxRetryPerTTSrecoveryDelayMsttsInstances_wrappedTtscapabilitiesmarkupmodelnumChannelsprovidersampleRatestatusclosegetStreamingInstancemarkUnAvailableprewarmreleaseIdleConnectionsstreamsynthesize