Skip to main content

Class: FallbackAudioProxy

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:108

An IAudioGenerator that wraps an ordered chain of audio providers and implements automatic failover for every operation.

Retry chain logic​

Providers are tried left-to-right (index 0 first). The first provider that succeeds returns immediately. When a provider throws:

  • If it is NOT the last provider: an audio:generate:fallback event is emitted and the next provider is tried.
  • If it IS the last provider: an AggregateError containing every collected error is thrown.
  • If the chain is empty: an Error('No providers in audio fallback chain') is thrown immediately.

For generateMusic, providers whose IAudioGenerator.supports returns false for 'music' are silently skipped. For generateSFX, providers that don't support 'sfx' (or lack the method entirely) are skipped.

Implements​

Constructors​

Constructor​

new FallbackAudioProxy(chain, emitter): FallbackAudioProxy

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:134

Creates a new FallbackAudioProxy wrapping the given provider chain.

Parameters​

chain​

IAudioGenerator[]

Ordered list of audio providers to try. Must contain at least one entry for operations to succeed (an empty chain always throws).

emitter​

EventEmitter

EventEmitter on which audio:generate:fallback events are published so callers can observe the failover path.

Returns​

FallbackAudioProxy

Example​

const proxy = new FallbackAudioProxy(
  [sunoProvider, stableAudioProvider],
  new EventEmitter(),
);

Properties​

defaultModelId?​

readonly optional defaultModelId: string

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:116

Default model from the first provider, if set.

Implementation of​

IAudioGenerator.defaultModelId

isInitialized​

readonly isInitialized: boolean = true

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:113

Always true — the proxy is ready as soon as it is constructed.

Implementation of​

IAudioGenerator.isInitialized

providerId​

readonly providerId: string

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:110

Identifier derived from the first provider in the chain.

Implementation of​

IAudioGenerator.providerId

Methods​

generateMusic()​

generateMusic(request): Promise<AudioResult>

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:185

Generate music from a text prompt, falling back through the provider chain on failure.

Providers whose IAudioGenerator.supports returns false for 'music' are silently skipped.

Parameters​

request​

MusicGenerateRequest

The generation request forwarded to each provider.

Returns​

Promise<AudioResult>

The result from the first provider that succeeds.

Throws​

When every provider in the chain fails.

Throws​

When the chain is empty.

Implementation of​

IAudioGenerator.generateMusic

generateSFX()​

generateSFX(request): Promise<AudioResult>

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:215

Generate a sound effect from a text prompt, falling back through providers that support SFX.

Providers whose IAudioGenerator.supports returns false for 'sfx' or that lack the generateSFX method are silently skipped.

Parameters​

request​

SFXGenerateRequest

The SFX request forwarded to each capable provider.

Returns​

Promise<AudioResult>

The result from the first provider that succeeds.

Throws​

When every provider fails or does not support SFX.

Implementation of​

IAudioGenerator.generateSFX

initialize()​

initialize(_config): Promise<void>

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:150

No-op initialisation — individual providers in the chain should already be initialised before being passed to the proxy.

Parameters​

_config​

Record<string, unknown>

Returns​

Promise<void>

Implementation of​

IAudioGenerator.initialize

shutdown()​

shutdown(): Promise<void>

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:239

Shuts down all providers in the chain. Errors are caught per-provider so a single provider's failure does not prevent the others from cleaning up.

Returns​

Promise<void>

Implementation of​

IAudioGenerator.shutdown

supports()​

supports(capability): boolean

Defined in: packages/agentos/src/io/media/audio/FallbackAudioProxy.ts:165

Returns true if at least one provider in the chain supports the given capability.

Parameters​

capability​

The capability to query ('music' or 'sfx').

"music" | "sfx"

Returns​

boolean

Implementation of​

IAudioGenerator.supports