@ottervoice/runtime-web

Documentation

---

Documentation / @ottervoice/runtime-web

@ottervoice/runtime-web

Browser runtime adapter for OtterVoice, with microphone capture, VAD metering, barge-in pre-roll, and audio playback.

Install

npm install @ottervoice/core @ottervoice/runtime-web

Usage

import { createWebRuntime } from '@ottervoice/runtime-web';

const runtime = createWebRuntime();

The default runtime uses getUserMedia, MediaRecorder, AudioContext, and HTMLAudioElement. These browser primitives can be injected for tests or non-standard hosts.

Links

Documentation · Web example · GitHub

License

MIT

Classes

WebAudioInput

Defined in: runtime-web/src/audio-input.ts:109

Microphone capture via getUserMedia + MediaRecorder timeslices. Suitable for near-real-time ASR; streaming PCM (AudioWorklet) is a future enhancement.

When an AudioContext is available, WebAudioInput.onVolume reports RMS levels for rule-based turn detection.

Platform primitives are injected; createWebRuntime supplies the browser globals by default.

Implements

• AudioInputAdapter

Constructors

Constructor

new WebAudioInput(options): WebAudioInput;

Defined in: runtime-web/src/audio-input.ts:128

Parameters

Parameter	Type
options	WebAudioInputOptions

Returns

WebAudioInput

Methods

onChunk()

onChunk(cb): () => void;

Defined in: runtime-web/src/audio-input.ts:350

Subscribe to encoded / PCM chunks.

Parameters

Parameter	Type
cb	(chunk) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onChunk

onError()

onError(cb): () => void;

Defined in: runtime-web/src/audio-input.ts:360

Subscribe to capture failures.

Parameters

Parameter	Type
cb	(error) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onError

onVolume()

onVolume(cb): () => void;

Defined in: runtime-web/src/audio-input.ts:355

Subscribe to normalized volume levels in 0..1 for VAD.

Parameters

Parameter	Type
cb	(level) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onVolume

pause()

pause(): Promise<void>;

Defined in: runtime-web/src/audio-input.ts:296

Pause capture without tearing down permission / hardware (optional).

Returns

Promise<void>

Implementation of

AudioInputAdapter.pause

requestPermission()

requestPermission(): Promise<boolean>;

Defined in: runtime-web/src/audio-input.ts:138

Prompt for mic permission; false should surface as a session error.

Returns

Promise<boolean>

Implementation of

AudioInputAdapter.requestPermission

resume()

resume(): Promise<void>;

Defined in: runtime-web/src/audio-input.ts:300

Resume after pause.

Returns

Promise<void>

Implementation of

AudioInputAdapter.resume

resumeCapture()

resumeCapture(options?): Promise<void>;

Defined in: runtime-web/src/audio-input.ts:313

Resume encoded chunk capture after suspendCapture. Runtimes with a barge-in pre-roll buffer may include it when includePreRoll is true.

Parameters

Parameter	Type	Description
options	{ includePreRoll?: boolean; }	-
options.includePreRoll?	boolean	Flush retained pre-roll into the next chunks.

Returns

Promise<void>

Implementation of

AudioInputAdapter.resumeCapture

start()

start(options?): Promise<void>;

Defined in: runtime-web/src/audio-input.ts:148

Begin capture.

Parameters

Parameter	Type	Description
options	AudioInputOptions	Preferred rate / encoding hints the runtime may honor.

Returns

Promise<void>

Implementation of

AudioInputAdapter.start

stop()

stop(): Promise<void>;

Defined in: runtime-web/src/audio-input.ts:272

Stop capture and release resources tied to the current start.

Returns

Promise<void>

Implementation of

AudioInputAdapter.stop

suspendCapture()

suspendCapture(): Promise<void>;

Defined in: runtime-web/src/audio-input.ts:304

Suspend encoded chunk delivery while leaving volume/VAD monitoring active. A runtime may retain a bounded barge-in pre-roll internally.

Returns

Promise<void>

Implementation of

AudioInputAdapter.suspendCapture

---

WebAudioOutput

Defined in: runtime-web/src/audio-output.ts:96

Playback via an HTMLAudioElement. audioUrl plays directly; an audioBuffer is wrapped in an object URL (which requires createObjectURL).

Implements

• AudioOutputAdapter

Constructors

Constructor

new WebAudioOutput(options): WebAudioOutput;

Defined in: runtime-web/src/audio-output.ts:114

Parameters

Parameter	Type
options	WebAudioOutputOptions

Returns

WebAudioOutput

Methods

onEnd()

onEnd(cb): () => void;

Defined in: runtime-web/src/audio-output.ts:541

Subscribe to playback end (natural finish or stop).

Parameters

Parameter	Type
cb	() => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onEnd

onError()

onError(cb): () => void;

Defined in: runtime-web/src/audio-output.ts:546

Subscribe to playback failures.

Parameters

Parameter	Type
cb	(error) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onError

onStart()

onStart(cb): () => void;

Defined in: runtime-web/src/audio-output.ts:531

Subscribe to playback start.

Parameters

Parameter	Type
cb	() => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onStart

onVolume()

onVolume(cb): () => void;

Defined in: runtime-web/src/audio-output.ts:536

Subscribe to normalized RMS of the assistant audio currently being played (used as an acoustic echo reference for barge-in).

Parameters

Parameter	Type
cb	(level, at?) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onVolume

pause()

pause(): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:350

Pause playback without discarding the current utterance (optional).

Returns

Promise<void>

Implementation of

AudioOutputAdapter.pause

play()

play(input): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:131

Play a complete encoded buffer or URL.

Parameters

Parameter	Type	Description
input	AudioPlaybackInput	URL and/or in-memory bytes plus optional MIME / volume.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.play

resume()

resume(): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:365

Resume after AudioOutputAdapter.pause.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.resume

startPcmStream()

startPcmStream(options): Promise<AudioOutputStream>;

Defined in: runtime-web/src/audio-output.ts:219

Begin incremental raw-PCM playback for low-latency speech streaming.

Parameters

Parameter	Type	Description
options	PcmAudioStreamOptions	Encoding, sample rate, and channel layout for subsequent writes.

Returns

Promise<AudioOutputStream>

An AudioOutputStream that must be close()d.

Implementation of

AudioOutputAdapter.startPcmStream

stop()

stop(): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:388

Stop current playback and cancel any open PCM stream.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.stop

unlock()

unlock(): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:116

Prime browser autoplay permission from a direct user gesture.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.unlock

Interfaces

AnalyserNodeLike

Defined in: runtime-web/src/audio-input.ts:56

Minimal AnalyserNode surface for time-domain RMS metering.

Properties

Property	Type	Description	Defined in
fftSize	number	FFT size controlling analyser resolution.	runtime-web/src/audio-input.ts:58
frequencyBinCount	number	Number of bins available from AnalyserNodeLike.getByteTimeDomainData.	runtime-web/src/audio-input.ts:60

Methods

getByteTimeDomainData()

getByteTimeDomainData(array): void;

Defined in: runtime-web/src/audio-input.ts:62

Fill array with uint8 time-domain samples.

Parameters

Parameter	Type
array	Uint8Array

Returns

void

---

AudioContextLike

Defined in: runtime-web/src/audio-input.ts:66

Minimal AudioContext surface for mic metering (not full Web Audio).

Methods

close()

close(): Promise<void>;

Defined in: runtime-web/src/audio-input.ts:69

Returns

Promise<void>

createAnalyser()

createAnalyser(): AnalyserNodeLike;

Defined in: runtime-web/src/audio-input.ts:68

Returns

AnalyserNodeLike

createMediaStreamSource()

createMediaStreamSource(stream): {
  connect: void;
};

Defined in: runtime-web/src/audio-input.ts:67

Parameters

Parameter	Type
stream	MediaStreamLike

Returns

{
  connect: void;
}

Name	Type	Defined in
connect()	(node) => void	runtime-web/src/audio-input.ts:67

---

AudioElementLike

Defined in: runtime-web/src/audio-output.ts:15

Minimal HTMLAudioElement / Audio surface for one-shot encoded playback. Injected via WebAudioOutputOptions.createAudio.

Properties

Property	Type	Description	Defined in
src	string	Object URL or remote URL to play.	runtime-web/src/audio-output.ts:17
volume	number	Playback gain in [0, 1].	runtime-web/src/audio-output.ts:19

Methods

addEventListener()

addEventListener(type, listener): void;

Defined in: runtime-web/src/audio-output.ts:22

Parameters

Parameter	Type
type	string
listener	() => void

Returns

void

pause()

pause(): void;

Defined in: runtime-web/src/audio-output.ts:21

Returns

void

play()

play(): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:20

Returns

Promise<void>

---

AudioEnvelope

Defined in: runtime-web/src/audio-conversion.ts:22

Short RMS timeline of decoded assistant audio. Produced by measureBrowserAudioEnvelope and used as a playback reference for echo-aware barge-in.

Properties

Property	Type	Description	Defined in
frameMs	number	Duration of each frame in milliseconds.	runtime-web/src/audio-conversion.ts:26
levels	number[]	Per-frame RMS levels in roughly [0, 1].	runtime-web/src/audio-conversion.ts:24

---

BlobLike

Defined in: runtime-web/src/audio-input.ts:22

Minimal Blob surface for MediaRecorder dataavailable payloads.

Properties

Property	Type	Description	Defined in
size	number	Byte length of the blob.	runtime-web/src/audio-input.ts:24

Methods

arrayBuffer()

arrayBuffer(): Promise<ArrayBuffer>;

Defined in: runtime-web/src/audio-input.ts:26

Copy blob contents into an ArrayBuffer.

Returns

Promise<ArrayBuffer>

---

MediaRecorderLike

Defined in: runtime-web/src/audio-input.ts:33

Minimal MediaRecorder surface for chunked mic encoding. Injected via WebAudioInputOptions.mediaRecorder / browser global.

Methods

addEventListener()

addEventListener(type, listener): void;

Defined in: runtime-web/src/audio-input.ts:43

Subscribe to recorder events (e.g. dataavailable, error, stop).

Parameters

Parameter	Type
type	string
listener	(event) => void

Returns

void

pause()

pause(): void;

Defined in: runtime-web/src/audio-input.ts:39

Pause encoding without ending the recording.

Returns

void

resume()

resume(): void;

Defined in: runtime-web/src/audio-input.ts:41

Resume after MediaRecorderLike.pause.

Returns

void

start()

start(timeslice?): void;

Defined in: runtime-web/src/audio-input.ts:35

Begin encoding; optional timeslice (ms) for periodic dataavailable events.

Parameters

Parameter	Type
timeslice?	number

Returns

void

stop()

stop(): void;

Defined in: runtime-web/src/audio-input.ts:37

Stop encoding and release the recorder.

Returns

void

---

MediaStreamLike

Defined in: runtime-web/src/audio-input.ts:16

Minimal MediaStream surface used by WebAudioInput.

Methods

getTracks()

getTracks(): MediaTrackLike[];

Defined in: runtime-web/src/audio-input.ts:18

Tracks belonging to the stream (mic, etc.).

Returns

MediaTrackLike[]

---

MediaTrackLike

Defined in: runtime-web/src/audio-input.ts:10

Minimal MediaStreamTrack surface used to stop capture.

Methods

stop()

stop(): void;

Defined in: runtime-web/src/audio-input.ts:12

End this track (releases the microphone).

Returns

void

---

PcmAudioBufferLike

Defined in: runtime-web/src/audio-output.ts:26

Minimal AudioBuffer surface for scheduling PCM frames.

Methods

getChannelData()

getChannelData(channel): Float32Array;

Defined in: runtime-web/src/audio-output.ts:28

Mutable float samples for one channel.

Parameters

Parameter	Type
channel	number

Returns

Float32Array

---

PcmAudioBufferSourceLike

Defined in: runtime-web/src/audio-output.ts:32

Minimal AudioBufferSourceNode surface for gapless PCM streaming.

Properties

Property	Type	Description	Defined in
buffer	| PcmAudioBufferLike | null	Buffer to play, or null before assignment.	runtime-web/src/audio-output.ts:34

Methods

addEventListener()

addEventListener(type, listener): void;

Defined in: runtime-web/src/audio-output.ts:38

Parameters

Parameter	Type
type	"ended"
listener	() => void

Returns

void

connect()

connect(destination): unknown;

Defined in: runtime-web/src/audio-output.ts:35

Parameters

Parameter	Type
destination	unknown

Returns

unknown

start()

start(when?): void;

Defined in: runtime-web/src/audio-output.ts:36

Parameters

Parameter	Type
when?	number

Returns

void

stop()

stop(): void;

Defined in: runtime-web/src/audio-output.ts:37

Returns

void

---

PcmAudioContextLike

Defined in: runtime-web/src/audio-output.ts:45

Minimal Web Audio context used for incremental PCM playback and echo reference. Distinct from the mic-metering context shim on WebAudioInput.

Properties

Property	Type	Description	Defined in
currentTime	number	AudioContext clock in seconds.	runtime-web/src/audio-output.ts:47
destination	unknown	Default output destination.	runtime-web/src/audio-output.ts:49

Methods

createBuffer()

createBuffer(
   numberOfChannels,
   length,
   sampleRate): PcmAudioBufferLike;

Defined in: runtime-web/src/audio-output.ts:52

Parameters

Parameter	Type
numberOfChannels	number
length	number
sampleRate	number

Returns

PcmAudioBufferLike

createBufferSource()

createBufferSource(): PcmAudioBufferSourceLike;

Defined in: runtime-web/src/audio-output.ts:57

Returns

PcmAudioBufferSourceLike

resume()

resume(): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:50

Returns

Promise<void>

suspend()

suspend(): Promise<void>;

Defined in: runtime-web/src/audio-output.ts:51

Returns

Promise<void>

---

PrepareBrowserAudioOptions

Defined in: runtime-web/src/audio-conversion.ts:33

Options for prepareBrowserAudio when converting browser capture to WAV. Use to cap capture length or downsample before sending to an Audio LLM.

Properties

Property	Type	Description	Defined in
maxDurationMs?	number	Keep only the newest portion of a long capture.	runtime-web/src/audio-conversion.ts:37
sampleRate?	number	PCM sample rate written to the WAV. Defaults to the decoded source rate.	runtime-web/src/audio-conversion.ts:35

---

WebAudioInputOptions

Defined in: runtime-web/src/audio-input.ts:80

Injected primitives and timing knobs for WebAudioInput. Prefer createWebRuntime to wire browser globals; construct directly only when substituting stubs or a custom capture stack.

Properties

Property	Type	Description	Defined in
audioContext?	AudioContextCtor	Override AudioContext (defaults to the browser global).	runtime-web/src/audio-input.ts:94
bargeInPreRollMs?	number	Encoded audio retained while playback is filtered for barge-in. Default 500 ms.	runtime-web/src/audio-input.ts:92
getUserMedia	GetUserMedia	Microphone permission + stream factory (getUserMedia).	runtime-web/src/audio-input.ts:82
mediaRecorder	MediaRecorderCtor	Encoder constructor (MediaRecorder).	runtime-web/src/audio-input.ts:84
mimeType?	string	MIME type for the recorder, e.g. audio/webm.	runtime-web/src/audio-input.ts:86
now?	() => number	Override clock used for chunk timestamps and timers (tests).	runtime-web/src/audio-input.ts:96
timesliceMs?	number	Emit a chunk every N ms (MediaRecorder timeslice). Default 100.	runtime-web/src/audio-input.ts:88
volumePollMs?	number	Poll microphone RMS level every N ms for VAD. Default 50.	runtime-web/src/audio-input.ts:90

---

WebAudioOutputOptions

Defined in: runtime-web/src/audio-output.ts:65

Injected playback primitives for WebAudioOutput. Prefer createWebRuntime to wire browser Audio / URL / AudioContext; pass stubs when testing or embedding outside a full DOM.

Properties

Property	Type	Description	Defined in
createAudio	() => AudioElementLike	Create a playback element (default () => new Audio() in the browser).	runtime-web/src/audio-output.ts:67
createObjectURL?	(blob) => string	Required for audioBuffer playback; turns a Blob into a URL.	runtime-web/src/audio-output.ts:69
createPcmAudioContext?	() => PcmAudioContextLike	Create a Web Audio context used for gapless incremental PCM playback.	runtime-web/src/audio-output.ts:75
measureAudio?	(audio) => Promise<AudioEnvelope>	Decode encoded audio into RMS frames used as an acoustic echo reference.	runtime-web/src/audio-output.ts:73
now?	() => number	Override clock used for envelope timing (tests).	runtime-web/src/audio-output.ts:77
revokeObjectURL?	(url) => void	Release an object URL from WebAudioOutputOptions.createObjectURL.	runtime-web/src/audio-output.ts:71

---

WebRuntime

Defined in: runtime-web/src/index.ts:62

Browser RuntimeAdapter returned by createWebRuntime. Exposes typed WebAudioInput / WebAudioOutput; no network adapter — providers use global fetch / WebSocket.

Extends

• RuntimeAdapter

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
audioInput	WebAudioInput	Microphone capture via MediaRecorder + optional RMS metering.	RuntimeAdapter.audioInput	-	runtime-web/src/index.ts:64
audioOutput	WebAudioOutput	Encoded and incremental PCM playback.	RuntimeAdapter.audioOutput	-	runtime-web/src/index.ts:66
logger?	LoggerAdapter	Optional logger; core uses it sparingly.	-	RuntimeAdapter.logger	core/dist/types.d.ts:853
network?	NetworkAdapter	Optional HTTP/WebSocket hooks for providers.	-	RuntimeAdapter.network	core/dist/types.d.ts:849
storage?	RuntimeStorageAdapter	Optional persistence for caches.	-	RuntimeAdapter.storage	core/dist/types.d.ts:851

---

WebRuntimeOptions

Defined in: runtime-web/src/index.ts:24

Capture, metering, and playback overrides for createWebRuntime. Omit fields to use browser globals (navigator.mediaDevices, MediaRecorder, Audio, URL, AudioContext). Inject stubs in tests or non-standard hosts.

Properties

Property	Type	Description	Defined in
audioContext?	AudioContextCtor	Override AudioContext used for RMS metering.	runtime-web/src/index.ts:50
bargeInPreRollMs?	number	Encoded audio retained while assistant playback is filtered. Released only after a confirmed barge-in so opening syllables survive. Default 500.	runtime-web/src/index.ts:48
createAudio?	() => AudioElementLike	Factory for HTMLAudioElement-like playback targets.	runtime-web/src/index.ts:30
createObjectURL?	(blob) => string	Inject URL.createObjectURL.	runtime-web/src/index.ts:32
createPcmAudioContext?	() => PcmAudioContextLike	Override factory used for PCM streaming playback.	runtime-web/src/index.ts:52
getUserMedia?	GetUserMedia	Inject navigator.mediaDevices.getUserMedia (defaults to the browser global).	runtime-web/src/index.ts:26
mediaRecorder?	MediaRecorderCtor	Inject MediaRecorder (defaults to the browser global).	runtime-web/src/index.ts:28
mimeType?	string	MediaRecorder MIME type, e.g. audio/webm;codecs=opus. When omitted, the runtime picks a browser-supported Opus/WebM type.	runtime-web/src/index.ts:39
now?	() => number	Override clock (tests).	runtime-web/src/index.ts:54
revokeObjectURL?	(url) => void	Inject URL.revokeObjectURL.	runtime-web/src/index.ts:34
timesliceMs?	number	Encode a chunk every N ms (MediaRecorder timeslice). Default 100.	runtime-web/src/index.ts:41
volumePollMs?	number	Poll microphone RMS every N ms for VAD / barge-in. Default 50.	runtime-web/src/index.ts:43

Type Aliases

AudioContextCtor

type AudioContextCtor = () => AudioContextLike;

Defined in: runtime-web/src/audio-input.ts:73

Constructor for AudioContextLike (browser AudioContext).

Returns

AudioContextLike

---

GetUserMedia

type GetUserMedia = (constraints) => Promise<MediaStreamLike>;

Defined in: runtime-web/src/audio-input.ts:53

navigator.mediaDevices.getUserMedia-compatible capture entry point.

Parameters

Parameter	Type
constraints	unknown

Returns

Promise<MediaStreamLike>

---

MediaRecorderCtor

type MediaRecorderCtor = (stream, options?) => MediaRecorderLike;

Defined in: runtime-web/src/audio-input.ts:47

Constructor for MediaRecorderLike (browser MediaRecorder).

Parameters

Parameter	Type
stream	MediaStreamLike
options?	{ mimeType?: string; }
options.mimeType?	string

Returns

MediaRecorderLike

Functions

createWebRuntime()

function createWebRuntime(options?): WebRuntime;

Defined in: runtime-web/src/index.ts:79

Assemble a browser RuntimeAdapter. With no options it reads the standard web globals (navigator.mediaDevices, MediaRecorder, Audio, URL); every primitive can be overridden for testing or non-standard hosts.

No network adapter is included — providers use the global fetch/WebSocket directly.

Parameters

Parameter	Type	Description
options	WebRuntimeOptions	Capture, metering, and playback overrides. See WebRuntimeOptions.

Returns

WebRuntime

---

encodeMonoWav()

function encodeMonoWav(audio, options?): ArrayBuffer;

Defined in: runtime-web/src/audio-conversion.ts:40

Encode decoded Web Audio samples as mono PCM16 WAV. Exported for tests; prefer prepareBrowserAudio in app code.

Parameters

Parameter	Type
audio	DecodedAudioLike
options	PrepareBrowserAudioOptions

Returns

ArrayBuffer

---

measureBrowserAudioEnvelope()

function measureBrowserAudioEnvelope(input, frameMs?): Promise<AudioEnvelope>;

Defined in: runtime-web/src/audio-conversion.ts:141

Decode an encoded assistant reply into short RMS frames for echo-aware VAD.

Parameters

Parameter	Type	Default value
input	ArrayBuffer	undefined
frameMs	number	50

Returns

Promise<AudioEnvelope>

---

prepareBrowserAudio()

function prepareBrowserAudio(
   input,
   format,
   options?): Promise<{
  audio: ArrayBuffer;
  format: "wav" | "mp3";
}>;

Defined in: runtime-web/src/audio-conversion.ts:123

Decode browser-recorded WebM/Opus and return a WAV accepted by audio LLMs.

Parameters

Parameter	Type
input	ArrayBuffer
format	AudioLLMInputFormat
options	PrepareBrowserAudioOptions

Returns

Promise<{ audio: ArrayBuffer; format: "wav" | "mp3"; }>