WebRTCInput

Browser audio input provider that extracts PCM from a WebRTC track.

Defined in: src/providers/input/WebRTCInput.ts:223

Browser audio input provider that extracts PCM from a WebRTC track.

Remarks

WebRTCInput converts a remote WebRTC audio source into linear16 PCM AudioChunk objects at a configurable target sample rate. The application owns the RTCPeerConnection (or SFU SDK) and provides the source via config or setTrack() / setStream(), which may be called at any time — including while capture is active — to swap sources live (e.g. when the active speaker changes in an SFU room).

Extraction mirrors AudioCapture: an AudioWorkletNode is preferred (off-main-thread processing), falling back to the deprecated ScriptProcessorNode where worklets are unavailable. Float32 samples are downsampled to the target rate when necessary and converted to 16-bit PCM.

pause()/resume() gate emission without tearing down the graph; stop() disconnects all nodes and closes the AudioContext (the source track itself is left untouched — the app owns it). The provider uses type: 'rest' because it holds no provider-managed network connection; the WebRTC transport belongs to the application.

Data-flow diagram:

MediaStreamTrack ──setTrack()──> WebRTCInput
                                      |
                    AudioContext(targetSampleRate)
                                      |
             MediaStreamSource -> Worklet | ScriptProcessor
                                      |
                  Float32 -> downsample -> floatTo16BitPCM
                                      |
                       active && !paused ? emit : drop
                                      |
                                      v
                             onAudio(AudioChunk)

Example

import { CompositeVoice, WebRTCInput, DeepgramSTT, AnthropicLLM, DeepgramTTS, WebRTCOutput } from 'composite-voice';

const input = new WebRTCInput();
const output = new WebRTCOutput();

const voice = new CompositeVoice({
  providers: [
    input,
    new DeepgramSTT({ apiKey: '...' }),
    new AnthropicLLM({ apiKey: '...', model: 'claude-haiku-4-5' }),
    new DeepgramTTS({ apiKey: '...' }),
    output,
  ],
});

await voice.initialize();

const pc = new RTCPeerConnection();
pc.ontrack = (e) => input.setTrack(e.track);      // remote audio -> pipeline
pc.addTrack(output.getTrack(), output.getStream()); // pipeline -> remote peer

await voice.startListening();

See

WebRTCInputConfig for configuration options
WebRTCOutput for the corresponding output provider
AudioInputProvider for the interface contract

Implements

AudioInputProvider

Constructors

Constructor

new WebRTCInput(config?): WebRTCInput;

Defined in: src/providers/input/WebRTCInput.ts:304

Creates a new WebRTCInput instance.

Parameters

Parameter	Type	Description
`config`	`WebRTCInputConfig`	Optional configuration. See WebRTCInputConfig.

Returns

WebRTCInput

Remarks

Construction is side-effect free: no browser APIs are touched until start(). A source may be supplied here or attached later with setTrack() / setStream().

Example

const input = new WebRTCInput({ targetSampleRate: 16000, debug: true });

Properties

Property	Modifier	Type	Default value	Description	Defined in
`roles`	`readonly`	readonly `ProviderRole`[]	`undefined`	Pipeline roles covered by this provider. Remarks `WebRTCInput` is a single-role provider covering only the `'input'` slot. It requires a separate STT provider for the `'stt'` role.	src/providers/input/WebRTCInput.ts:241
`type`	`readonly`	`ProviderType`	`'rest'`	Communication type for this provider. Remarks `'rest'` — the provider does not manage a persistent network connection. The WebRTC peer connection is owned by the application; this provider only processes a local `MediaStreamTrack`.	src/providers/input/WebRTCInput.ts:232

Methods

attach()

attach(source): void;

Defined in: src/providers/input/WebRTCInput.ts:503

Attach a source track or stream — dispatching alias for setTrack() / setStream().

Parameters

Parameter	Type	Description
`source`	`MediaStream` \| `MediaStreamTrack`	The remote `MediaStreamTrack` or `MediaStream` to consume.

Returns

void

Remarks

Implements the AttachableInputProvider contract so a remote WebRTC source can be passed straight to CompositeVoice.startListening(trackOrStream).

dispose()

dispose(): Promise<void>;

Defined in: src/providers/input/WebRTCInput.ts:353

Dispose of the provider and release all resources.

Returns

Promise<void>

Remarks

Stops capture (tearing down the audio graph), clears the callback and configured source references, and resets the sequence counter. The source track itself is not stopped — the application owns it. The instance may be re-initialized after disposal.

Implementation of

AudioInputProvider.dispose

getMetadata()

getMetadata(): AudioMetadata;

Defined in: src/providers/input/WebRTCInput.ts:480

Get the audio format metadata for the emitted audio.

Returns

AudioMetadata

The AudioMetadata describing the emitted audio format.

Remarks

WebRTCInput always emits mono linear16 PCM at the configured targetSampleRate. Used by the pipeline to auto-configure the downstream STT provider via configureSTTFromMetadata().

Implementation of

AudioInputProvider.getMetadata

initialize()

initialize(): Promise<void>;

Defined in: src/providers/input/WebRTCInput.ts:325

Initialize the provider, verifying the environment supports Web Audio.

Returns

Promise<void>

Remarks

Throws if AudioContext is unavailable (e.g. Node.js without a DOM) — WebRTCInput is a browser-only provider. The processing graph itself is built lazily on start(). If already initialized, this is a no-op.

Throws

ProviderInitializationError when the Web Audio API is not available in the current environment.

Implementation of

AudioInputProvider.initialize

isActive()

isActive(): boolean;

Defined in: src/providers/input/WebRTCInput.ts:450

Check whether the provider is actively emitting audio.

Returns

boolean

true when started and not paused.

Implementation of

AudioInputProvider.isActive

isReady()

isReady(): boolean;

Defined in: src/providers/input/WebRTCInput.ts:375

Check whether the provider has been initialized.

Returns

boolean

true when initialize has completed and dispose has not yet been called.

Implementation of

AudioInputProvider.isReady

onAudio()

onAudio(callback): void;

Defined in: src/providers/input/WebRTCInput.ts:465

Parameters

Parameter	Type	Description
`callback`	(`chunk`) => `void`	Function invoked with each AudioChunk while the provider is active and not paused.

Returns

void

Remarks

Only one callback can be registered at a time; subsequent calls replace the previous callback. Must be called before start() so no audio is missed.

Implementation of

AudioInputProvider.onAudio

pause()

pause(): void;

Defined in: src/providers/input/WebRTCInput.ts:426

Temporarily pause audio emission without tearing down the graph.

Returns

void

Remarks

While paused, incoming audio is silently dropped. Used by the turn-taking system to mute capture during TTS playback. Resume with resume().

Implementation of

AudioInputProvider.pause

resume()

resume(): void;

Defined in: src/providers/input/WebRTCInput.ts:438

Resume audio emission after a pause.

Returns

void

See

pause

Implementation of

AudioInputProvider.resume

setStream()

setStream(stream): void;

Defined in: src/providers/input/WebRTCInput.ts:548

Set or swap the source media stream.

Parameters

Parameter	Type	Description
`stream`	`MediaStream`	The remote `MediaStream` to consume.

Returns

void

Remarks

May be called before or after start(). When called while active, the processing graph is rewired to the new stream live. Replaces any previously configured track or stream.

setTrack()

setTrack(track): void;

Defined in: src/providers/input/WebRTCInput.ts:530

Set or swap the source audio track.

Parameters

Parameter	Type	Description
`track`	`MediaStreamTrack`	The remote audio `MediaStreamTrack` to consume.

Returns

void

Remarks

May be called before or after start(). When called while active, the processing graph is rewired to the new track without interrupting the pipeline — useful when the active speaker changes in an SFU room or a reconnect produces a fresh track. Replaces any previously configured track or stream.

Example

pc.ontrack = (event) => {
  if (event.track.kind === 'audio') input.setTrack(event.track);
};

start()

start(): void;

Defined in: src/providers/input/WebRTCInput.ts:395

Start capturing audio from the configured WebRTC source.

Returns

void

Remarks

Builds the processing graph (AudioContext, source node, worklet or script-processor) if a source is available. If no source has been set yet, the provider becomes active and the graph is built as soon as setTrack() or setStream() supplies one.

Graph construction is asynchronous (worklet module loading); errors are logged rather than thrown since this method is synchronous per the AudioInputProvider contract.

Implementation of

AudioInputProvider.start

stop()

stop(): void;

Defined in: src/providers/input/WebRTCInput.ts:411

Stop capturing audio and tear down the processing graph.

Returns

void

Remarks

Disconnects all audio nodes and closes the AudioContext. The source track/stream is left untouched (the application owns it) and remains configured, so the provider can be restarted with start().

Implementation of

AudioInputProvider.stop