AudioOutputProvider

Defined in: src/core/types/providers.ts:1587

Audio output provider interface for the 'output' pipeline role.

Remarks

An AudioOutputProvider receives synthesized audio from the TTS stage and plays it through a destination (e.g. speakers, file, null sink). It is the last stage of the 5-role pipeline:

[AudioInputProvider] -> InputQueue -> [STT] -> [LLM] -> [TTS] -> OutputQueue -> [AudioOutputProvider]
                                                                                 ^^^^^^^^^^^^^^^^^^^

Providers implementing this interface must set roles to include 'output'. Multi-role providers (e.g. NativeTTS) may also include 'tts' when the underlying API handles both synthesis and playback internally.

Lifecycle: initialize() -> configure(metadata) -> enqueue(chunk) (repeated) -> flush() -> stop() -> dispose()

Example

import type { AudioOutputProvider, AudioChunk, AudioMetadata } from 'composite-voice';

class MySpeakerOutput implements AudioOutputProvider {
  readonly type = 'websocket';
  readonly roles = ['output'] as const;

  async initialize() { /* set up AudioContext */ }
  async dispose() { /* close AudioContext */ }
  isReady() { return true; }

  configure(metadata: AudioMetadata) { /* configure playback format */ }
  enqueue(chunk: AudioChunk) { /* buffer chunk for playback */ }
  async flush() { /* wait for all queued audio to finish playing */ }
  stop() { /* stop playback immediately */ }
  pause() { /* pause playback */ }
  resume() { /* resume playback */ }
  isPlaying() { return false; }

  onPlaybackStart(callback: () => void) { /* ... */ }
  onPlaybackEnd(callback: () => void) { /* ... */ }
  onPlaybackError(callback: (error: Error) => void) { /* ... */ }
}

See

• BaseProvider for lifecycle methods
• AudioChunk for the audio data type
• AudioMetadata for the metadata type
• AudioInputProvider for the corresponding input role

Extends

• BaseProvider

Properties

Methods

configure()

configure(metadata): void;

Defined in: src/core/types/providers.ts:1600

Configure the output with the audio format metadata from the TTS provider.

Parameters

Returns

void

Remarks

Called when the TTS provider emits metadata describing the format of incoming audio chunks. The output provider uses this to configure its playback pipeline (e.g. AudioContext sample rate).

See

AudioMetadata

dispose()

dispose(): Promise<void>;

Defined in: src/core/types/providers.ts:226

Clean up resources and dispose of the provider.

Returns

Promise<void>

Remarks

Called by CompositeVoice during agent shutdown. The provider should close any open connections, clear buffers, and release resources.

Inherited from

BaseProvider.dispose

enqueue()

enqueue(chunk): void;

Defined in: src/core/types/providers.ts:1613

Enqueue an audio chunk for playback.

Parameters

Returns

void

Remarks

Called for each audio chunk received from the TTS provider (via the output queue). Chunks are played in the order they are enqueued.

See

AudioChunk

flush()

flush(): Promise<void>;

Defined in: src/core/types/providers.ts:1622

Wait for all enqueued audio to finish playing.

Returns

Promise<void>

Remarks

Called after the TTS provider signals that all text has been synthesized. Resolves when the last enqueued chunk has finished playing.

initialize()

initialize(): Promise<void>;

Defined in: src/core/types/providers.ts:217

Initialize the provider and allocate any required resources.

Returns

Promise<void>

Remarks

Called by CompositeVoice during agent startup. The provider should be ready to process requests after this method resolves.

Throws

Error if initialization fails (e.g., invalid API key, network error)

Inherited from

BaseProvider.initialize

isPlaying()

isPlaying(): boolean;

Defined in: src/core/types/providers.ts:1673

Check whether audio is currently playing.

Returns

boolean

true when audio is actively being played

isReady()

isReady(): boolean;

Defined in: src/core/types/providers.ts:233

Check if the provider is initialized and ready to process requests.

Returns

boolean

true if the provider has been initialized and is operational

Inherited from

BaseProvider.isReady

onPlaybackEnd()

onPlaybackEnd(callback): void;

Defined in: src/core/types/providers.ts:1698

Register a callback invoked when all audio has finished playing.

Parameters

Returns

void

Remarks

Single-slot and claimed by CompositeVoice — see onPlaybackStart.

onPlaybackError()

onPlaybackError(callback): void;

Defined in: src/core/types/providers.ts:1709

Register a callback invoked when a playback error occurs.

Parameters

Returns

void

Remarks

Single-slot and claimed by CompositeVoice — see onPlaybackStart.

onPlaybackStart()

onPlaybackStart(callback): void;

Defined in: src/core/types/providers.ts:1687

Register a callback invoked when audio playback begins.

Parameters

Returns

void

Remarks

These slots hold a single callback each, and CompositeVoice claims all three when the provider is used in a pipeline — that is where the audio.playback.* events and the per-turn playback metrics come from. Applications should subscribe to those events on the agent instead of registering here, which would replace the pipeline’s handler.

pause()

pause(): void;

Defined in: src/core/types/providers.ts:1659

Temporarily pause playback.

Returns

void

Remarks

Playback can be resumed with resume.

resume()

resume(): void;

Defined in: src/core/types/providers.ts:1666

Resume playback after a pause.

Returns

void

See

pause

stop()

stop(): void;

Defined in: src/core/types/providers.ts:1634

Stop playback immediately and clear any buffered audio.

Returns

void

Remarks

Duplex providers cover both 'input' and 'output', so a bare stop() is ambiguous — implement stopPlayback and stopCapture to say which side is meant.

stopPlayback()?

optional stopPlayback(): void;

Defined in: src/core/types/providers.ts:1651

Stop playback, explicitly, without touching capture.

Returns

void

Remarks

The pipeline calls this instead of stop for barge-in. Capture must keep running: barge-in fires precisely because the user started talking, and that speech has to reach STT.

Barge-in is also raised while the agent is merely thinking — the LLM is still generating and no audio exists yet — so a duplex provider cannot tell barge-in from stop-listening by looking at its own playback state.

Optional. Providers that only cover 'output' can omit it — stop() is already unambiguous for them.