Skip to main content

Class: FallbackTTSProxy

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

A TextToSpeechProvider that wraps an ordered chain of TTS providers and implements automatic failover.

Retry Chain Logic​

Identical to FallbackSTTProxy: providers are tried left-to-right, the first successful synthesis result is returned, and provider_fallback events are emitted on each intermediate failure.

Voice Listing​

Voice listing is delegated to the first provider in the chain that exposes a listAvailableVoices() method. If no provider supports this, an empty array is returned. This is a best-effort approach — the voice list may not reflect the provider that actually handles synthesis if the primary fails.

See​

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

Example​

const proxy = new FallbackTTSProxy([elevenlabsProvider, openaiTtsProvider], emitter);
const audio = await proxy.synthesize('Hello world');
// If ElevenLabs fails, OpenAI TTS is tried automatically.

Implements​

Constructors​

Constructor​

new FallbackTTSProxy(chain, emitter): FallbackTTSProxy

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

Creates a new FallbackTTSProxy wrapping the given provider chain.

Parameters​

chain​

TextToSpeechProvider[]

Ordered list of TTS providers to try.

emitter​

EventEmitter

EventEmitter on which provider_fallback events are published.

Returns​

FallbackTTSProxy

Example​

const proxy = new FallbackTTSProxy(
  [elevenlabsProvider, openaiTtsProvider],
  resolver,
);

Properties​

displayName​

readonly displayName: string

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

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

Implementation of​

TextToSpeechProvider.displayName

id​

readonly id: string

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

Unique identifier derived from the first provider in the chain. Falls back to 'fallback-tts' for empty chains.

Implementation of​

TextToSpeechProvider.id

supportsStreaming​

readonly supportsStreaming: boolean

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

Whether the proxy supports streaming. Only reflects the first provider's capability — see FallbackSTTProxy.supportsStreaming for rationale.

Implementation of​

TextToSpeechProvider.supportsStreaming

Methods​

getProviderName()​

getProviderName(): string

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

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

Returns​

string

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

Example​

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

Implementation of​

TextToSpeechProvider.getProviderName

listAvailableVoices()​

listAvailableVoices(): Promise<SpeechVoice[]>

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

Returns the voice list from the first provider in the chain that supports listAvailableVoices().

Iterates through the chain looking for any provider that implements this optional method. Returns an empty array when no provider supports voice listing. This is a best-effort approach — if the primary provider fails during synthesis and a fallback provider handles it, the returned voice list may not match the provider that actually produced the audio.

Returns​

Promise<SpeechVoice[]>

A promise resolving to an array of available voices, or an empty array if no provider in the chain supports voice listing.

Example​

const voices = await proxy.listAvailableVoices();
// voices from the first provider that implements the method

Implementation of​

TextToSpeechProvider.listAvailableVoices

synthesize()​

synthesize(text, options?): Promise<SpeechSynthesisResult>

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

Attempt synthesis 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​

text​

string

The text to synthesize into speech.

options?​

SpeechSynthesisOptions

Optional synthesis settings (voice, speed, format, etc.).

Returns​

Promise<SpeechSynthesisResult>

The synthesis 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.synthesize('Hello world', { voice: 'nova' });

Implementation of​

TextToSpeechProvider.synthesize