AudioInputProvider

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

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

Remarks

An AudioInputProvider captures audio from a source (e.g. microphone, file buffer, network stream) and delivers it as AudioChunk objects via the onAudio callback. It is the first stage of the 5-role pipeline:

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

Providers implementing this interface must set roles to include 'input'. Multi-role providers (e.g. NativeSTT) may also include 'stt' when the underlying API handles both capture and transcription internally.

Lifecycle: initialize() -> start() -> audio flows via onAudio -> pause() / resume() -> stop() -> dispose()

Example

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

class MyMicrophoneInput implements AudioInputProvider {
  readonly type = 'websocket';
  readonly roles = ['input'] as const;
  private callback?: (chunk: AudioChunk) => void;
  private active = false;

  async initialize() { /* request permissions */ }
  async dispose() { /* release resources */ }
  isReady() { return true; }

  start() { this.active = true; /* begin capture */ }
  stop() { this.active = false; /* end capture */ }
  pause() { /* pause capture */ }
  resume() { /* resume capture */ }
  isActive() { return this.active; }

  onAudio(callback: (chunk: AudioChunk) => void) {
    this.callback = callback;
  }

  getMetadata(): AudioMetadata {
    return { sampleRate: 16000, encoding: 'linear16', channels: 1, bitDepth: 16 };
  }
}

See

• BaseProvider for lifecycle methods
• AudioChunk for the audio data type
• AudioMetadata for the metadata type
• AudioOutputProvider for the corresponding output role

Extends

• BaseProvider

Extended by

• AttachableInputProvider

Properties

Methods

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

getMetadata()

getMetadata(): AudioMetadata;

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

Get the audio format metadata for the captured audio.

Returns

AudioMetadata

AudioMetadata describing the audio format

Remarks

Returns metadata describing the format of audio chunks this provider will emit. Used by the pipeline to auto-configure the STT provider’s encoding, sample rate, and channel settings.

See

AudioMetadata for the metadata type

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

isActive()

isActive(): boolean;

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

Check whether the input source is actively capturing audio.

Returns

boolean

true when audio is being captured (between start() and stop(), and not paused)

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

onAudio()

onAudio(callback): void;

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

Register a callback to receive captured audio chunks.

Parameters

Returns

void

Remarks

The provider calls this callback with each chunk of captured audio. Must be called before start.

pause()

pause(): void;

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

Temporarily pause audio capture without releasing the source.

Returns

void

Remarks

Used by the turn-taking system to mute capture during TTS playback. Resume with resume.

resume()

resume(): void;

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

Resume audio capture after a pause.

Returns

void

See

pause

start()

start(): void;

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

Start capturing audio from the input source.

Returns

void

Remarks

After calling start(), the provider begins delivering audio chunks via the callback registered with onAudio. Must be called after initialize.

stop()

stop(): void;

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

Stop capturing audio and release the input source.

Returns

void

Remarks

Stops audio delivery. The provider can be restarted with start.

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

stopCapture()?

optional stopCapture(): void;

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

Stop capturing audio, explicitly, without touching playback.

Returns

void

Remarks

The pipeline calls this instead of stop whenever it means “stop listening” — so a provider that fills both roles never has to infer intent from its own state. Inferring it is unsafe: a barge-in raised while the agent is still thinking has no audio playing to distinguish it from a stop-listening, and guessing wrong leaves the agent deaf for the rest of the session.

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