FallbackTTS

The FallbackTTS class provides automatic failover between multiple TTS providers for improved reliability. When one provider fails after exhausting its retries, it automatically switches to the next provider in the list.

Features

• Automatic failover: Seamlessly switches between providers when failures occur
• Text buffering: Retains text chunks during failures and replays them to the next provider
• Circular rotation: Cycles through providers indefinitely until speech synthesis succeeds
• Zero configuration: Works with any TTS implementation
• Cancellation support: Properly forwards cancel() calls to the active provider

Usage

import { FallbackTTS } from '@micdrop/server'
import { ElevenLabsTTS } from '@micdrop/elevenlabs'
import { CartesiaTTS } from '@micdrop/cartesia'

// Create a fallback TTS with multiple providers
const tts = new FallbackTTS({
  factories: [
    // Primary provider: ElevenLabs with low retry count
    () =>
      new ElevenLabsTTS({
        apiKey: process.env.ELEVENLABS_API_KEY || '',
        voiceId: process.env.ELEVENLABS_VOICE_ID || '',
        maxRetry: 2, // Fail faster to switch to backup
      }),
    // Backup provider: Cartesia
    () =>
      new CartesiaTTS({
        apiKey: process.env.CARTESIA_API_KEY || '',
        modelId: 'sonic-turbo',
        voiceId: process.env.CARTESIA_VOICE_ID || '',
        maxRetry: 3,
      }),
  ],
})

// Use with MicdropServer
const server = new MicdropServer(socket, {
  tts,
  // ... other options
})

Options

Option	Type	Description
factories	Array<() => TTS>	Array of factory functions that create TTS instances

How It Works

1. Initialization: Starts with the first provider in the list
2. Normal operation: Forwards all text to the current provider and emits audio chunks
3. On failure: When a provider emits the Failed event:
   • Destroys the current provider
   • Moves to the next provider (wraps around to first if at end)
   • Replays buffered text chunks to the new provider
4. Logging: Inherits logger configuration and applies it to child providers