@ottervoice/core

Platform-agnostic core for OtterVoice — a TypeScript-first SDK for real-time voice conversation, including full-duplex barge-in.

This package contains no DOM, Node or native dependencies. It provides the session state machine, typed events, transcript buffer, turn detector, usage meter, a normalized error model, and built-in mock providers / runtime for testing.

bun add @ottervoice/core

What’s inside

Export	Purpose
`createVoiceSession` / `createOtterVoiceSession` / `VoiceSession`	Unified audio-turn loop and interruption policy.
`StateMachine`, `canTransition`, `isTerminal`	Session state transitions.
`TypedEmitter`	Strongly-typed, unsubscribe-returning event emitter.
`TranscriptBuffer`	Ordered turns → LLM message projection.
`TurnDetector`	Deterministic local VAD from volume samples.
`UsageMeter`	Per-session usage snapshot (you bill; it measures).
`createVoiceError`, `normalizeError`, `VoiceError`	Unified error model.
`createMockAudioLLM/ASR/LLM/TTS/Pronunciation`, `createMockRuntime`	Session mocks plus trusted-backend building blocks.

Provider & runtime contracts

Implement these interfaces to plug in real services / platforms:

ASRProvider — optional captioning via streaming partial/final transcripts.
AudioLLMProvider — one provider consumes a completed audio turn and returns assistant text + audio. It may be a native model or a server-composed voice stack. Set transcribesInput: true when it also supplies the authoritative user transcript; otherwise configure caption ASR in parallel.
LLMProvider / TTSProvider — low-level contracts for trusted servers implementing a composite AudioLLMProvider; they are not Session slots.
PronunciationProvider — assess() → scores.
RuntimeAdapter — audioInput, audioOutput, optional network / storage / logger.

Every error raised by an adapter should be a NormalizedVoiceError (use createVoiceError), so consumers handle one shape regardless of provider.

Set VoiceSessionConfig.asrPartial to false when provisional captions are not needed. Core passes that preference to the ASR session while preserving asr_final. For batch-backed rolling ASR, providers may implement ASRSession.setInterimResultsEnabled(); volume-based sessions use it to defer paid partial work until VAD confirms speech.

Use turnDetection.strategy: 'volume' for local RMS-based turn boundaries, or 'hybrid' when ASR partial text should also confirm quiet speech before the same local silence timer closes the turn. Use 'manual' for push-to-talk.

Session events

statechange, asr_partial, asr_final, user_audio_end, user_audio_final, assistant_text_delta, assistant_text, assistant_audio, assistant_audio_start, assistant_audio_end, turn, usage, finished, error. Subscribe with session.on(event, cb); the returned function unsubscribes.

Example

See the root README for a runnable, fully-mocked quick start, and examples/node-cli for an end-to-end demo.

License

MIT

Classes

BargeInSpeechGate

Defined in: packages/core/src/playback-echo-filter.ts:44

Detects speech-shaped residual energy without requiring every audio frame to be loud. Natural speech contains short gaps between syllables; a vote over a moving window rejects isolated knocks while preserving those gaps.

Constructors

Constructor

new BargeInSpeechGate(options?): BargeInSpeechGate;

Defined in: packages/core/src/playback-echo-filter.ts:50

Parameters

Parameter	Type
`options`	`BargeInSpeechGateOptions`

Returns

BargeInSpeechGate

Methods

push()

push(level): boolean;

Defined in: packages/core/src/playback-echo-filter.ts:56

Parameters

Parameter	Type
`level`	`number`

Returns

boolean

reset()

reset(): void;

Defined in: packages/core/src/playback-echo-filter.ts:62

Returns

void

MockAudioInput

Defined in: packages/core/src/providers/mock-runtime.ts:24

In-memory audio input. Tests drive it by calling MockAudioInput.emitChunk / MockAudioInput.emitVolume; nothing touches a real microphone.

Implements

AudioInputAdapter

Constructors

Constructor

new MockAudioInput(options?): MockAudioInput;

Defined in: packages/core/src/providers/mock-runtime.ts:33

Parameters

Parameter	Type
`options`	`MockAudioInputOptions`

Returns

MockAudioInput

Properties

Property	Type	Default value	Defined in
`lastOptions`	\| `AudioInputOptions` \| `undefined`	`undefined`	packages/core/src/providers/mock-runtime.ts:31
`paused`	`boolean`	`false`	packages/core/src/providers/mock-runtime.ts:30
`started`	`boolean`	`false`	packages/core/src/providers/mock-runtime.ts:29

Methods

emitChunk()

emitChunk(chunk): void;

Defined in: packages/core/src/providers/mock-runtime.ts:60

Parameters

Parameter	Type
`chunk`	`AudioChunk`

Returns

void

emitError()

emitError(error): void;

Defined in: packages/core/src/providers/mock-runtime.ts:68

Parameters

Parameter	Type
`error`	`NormalizedVoiceError`

Returns

void

emitVolume()

emitVolume(level): void;

Defined in: packages/core/src/providers/mock-runtime.ts:64

Parameters

Parameter	Type
`level`	`number`

Returns

void

onChunk()

onChunk(cb): () => void;

Defined in: packages/core/src/providers/mock-runtime.ts:72

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: packages/core/src/providers/mock-runtime.ts:82

Subscribe to capture failures.

Parameters

Parameter	Type
`cb`	(`error`) => `void`

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onError

onVolume()

onVolume(cb): () => void;

Defined in: packages/core/src/providers/mock-runtime.ts:77

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: packages/core/src/providers/mock-runtime.ts:52

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

Returns

Promise<void>

Implementation of

AudioInputAdapter.pause

requestPermission()

requestPermission(): Promise<boolean>;

Defined in: packages/core/src/providers/mock-runtime.ts:37

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

Returns

Promise<boolean>

Implementation of

AudioInputAdapter.requestPermission

resume()

resume(): Promise<void>;

Defined in: packages/core/src/providers/mock-runtime.ts:56

Resume after pause.

Returns

Promise<void>

Implementation of

AudioInputAdapter.resume

start()

start(options): Promise<void>;

Defined in: packages/core/src/providers/mock-runtime.ts:41

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: packages/core/src/providers/mock-runtime.ts:47

Stop capture and release resources tied to the current start.

Returns

Promise<void>

Implementation of

AudioInputAdapter.stop

MockAudioOutput

Defined in: packages/core/src/providers/mock-runtime.ts:100

In-memory audio output. Records what was “played”.

Implements

AudioOutputAdapter

Constructors

Constructor

new MockAudioOutput(options?): MockAudioOutput;

Defined in: packages/core/src/providers/mock-runtime.ts:114

Parameters

Parameter	Type
`options`	`MockAudioOutputOptions`

Returns

MockAudioOutput

Properties

Property	Type	Default value	Defined in
`paused`	`number`	`0`	packages/core/src/providers/mock-runtime.ts:110
`played`	`AudioPlaybackInput`[]	`[]`	packages/core/src/providers/mock-runtime.ts:108
`resumed`	`number`	`0`	packages/core/src/providers/mock-runtime.ts:111
`stopped`	`number`	`0`	packages/core/src/providers/mock-runtime.ts:109

Methods

emitVolume()

emitVolume(level): void;

Defined in: packages/core/src/providers/mock-runtime.ts:156

Parameters

Parameter	Type
`level`	`number`

Returns

void

fireEnd()

fireEnd(): void;

Defined in: packages/core/src/providers/mock-runtime.ts:150

Returns

void

onEnd()

onEnd(cb): () => void;

Defined in: packages/core/src/providers/mock-runtime.ts:181

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: packages/core/src/providers/mock-runtime.ts:186

Subscribe to playback failures.

Parameters

Parameter	Type
`cb`	(`error`) => `void`

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onError

onPlaybackRequested()

onPlaybackRequested(cb): () => void;

Defined in: packages/core/src/providers/mock-runtime.ts:171

Subscribe when mock playback is requested.

Parameters

Parameter	Type	Description
`cb`	() => `void`	Called once for every call to MockAudioOutput.play.

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onPlaybackRequested

onStart()

onStart(cb): () => void;

Defined in: packages/core/src/providers/mock-runtime.ts:176

Subscribe to confirmed playback start. Adapters with playback telemetry fire this once per utterance when the platform first reports active playback; headless adapters use their closest output acknowledgement. Resuming a paused utterance does not fire it again.

Parameters

Parameter	Type	Description
`cb`	() => `void`	Called when playback first becomes active.

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onStart

onVolume()

onVolume(cb): () => void;

Defined in: packages/core/src/providers/mock-runtime.ts:160

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`) => `void`

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onVolume

pause()

pause(): Promise<void>;

Defined in: packages/core/src/providers/mock-runtime.ts:142

Pause playback without discarding the current utterance (optional).

Returns

Promise<void>

Implementation of

AudioOutputAdapter.pause

play()

play(input): Promise<void>;

Defined in: packages/core/src/providers/mock-runtime.ts:119

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: packages/core/src/providers/mock-runtime.ts:146

Resume after AudioOutputAdapter.pause.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.resume

stop()

stop(): Promise<void>;

Defined in: packages/core/src/providers/mock-runtime.ts:136

Stop current playback and cancel any open PCM stream.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.stop

PlaybackEchoFilter

Defined in: packages/core/src/playback-echo-filter.ts:72

Removes the component of microphone RMS that is correlated with assistant playback. It searches a short delay window because browser playback, loudspeaker travel and microphone analysis are not sample-synchronous.

Constructors

Constructor

new PlaybackEchoFilter(options?): PlaybackEchoFilter;

Defined in: packages/core/src/playback-echo-filter.ts:84

Parameters

Parameter	Type
`options`	`PlaybackEchoFilterOptions`

Returns

PlaybackEchoFilter

Methods

filter()

filter(microphoneLevel, at): number;

Defined in: packages/core/src/playback-echo-filter.ts:118

Parameters

Parameter	Type
`microphoneLevel`	`number`
`at`	`number`

Returns

number

isReady()

isReady(at): boolean;

Defined in: packages/core/src/playback-echo-filter.ts:163

True once enough playback reference frames exist to estimate echo.

Parameters

Parameter	Type
`at`	`number`

Returns

boolean

pushOutput()

pushOutput(level, at): void;

Defined in: packages/core/src/playback-echo-filter.ts:110

Parameters

Parameter	Type
`level`	`number`
`at`	`number`

Returns

void

reset()

reset(): void;

Defined in: packages/core/src/playback-echo-filter.ts:155

Returns

void

start()

start(_at): void;

Defined in: packages/core/src/playback-echo-filter.ts:96

Parameters

Parameter	Type
`_at`	`number`

Returns

void

stop()

stop(): void;

Defined in: packages/core/src/playback-echo-filter.ts:106

Returns

void

SpeechTextSegmenter

Defined in: packages/core/src/internal/speech-text-segmenter.ts:38

Incrementally split an LLM text stream into natural, bounded speech units. Use it to start TTS at the first complete clause while keeping enough text per request for stable prosody.

Constructors

Constructor

new SpeechTextSegmenter(): SpeechTextSegmenter;

Returns

SpeechTextSegmenter

Methods

flush()

flush(): string[];

Defined in: packages/core/src/internal/speech-text-segmenter.ts:58

Emit the remaining text after the LLM stream completes.

Returns

string[]

The last speech unit, or an empty array when nothing remains.

push()

push(delta): string[];

Defined in: packages/core/src/internal/speech-text-segmenter.ts:48

Add newly generated text and return every complete speech unit now ready.

Parameters

Parameter	Type	Description
`delta`	`string`	The next append-only LLM text fragment.

Returns

string[]

Zero or more sentence/clause-sized strings in source order.

StateMachine

Defined in: packages/core/src/state-machine.ts:77

Pure state container. The session owns one of these and is the only thing that mutates it via StateMachine.transition.

Constructors

Constructor

new StateMachine(initial?): StateMachine;

Defined in: packages/core/src/state-machine.ts:80

Parameters

Parameter	Type	Default value
`initial`	`VoiceSessionState`	`'idle'`

Returns

StateMachine

Accessors

state

Get Signature

get state(): VoiceSessionState;

Defined in: packages/core/src/state-machine.ts:84

Returns

VoiceSessionState

Methods

can()

can(to): boolean;

Defined in: packages/core/src/state-machine.ts:88

Parameters

Parameter	Type
`to`	`VoiceSessionState`

Returns

boolean

transition()

transition(to): VoiceSessionState;

Defined in: packages/core/src/state-machine.ts:96

Move to to, returning the previous state. Throws a VoiceError with code invalid_state when the transition is not allowed.

Parameters

Parameter	Type
`to`	`VoiceSessionState`

Returns

VoiceSessionState

TranscriptBuffer

Defined in: packages/core/src/transcript-buffer.ts:30

Ordered store of conversation turns. Owns nothing about providers — it just accumulates turns and projects them into the shape the LLM expects.

Constructors

Constructor

new TranscriptBuffer(generateId, now): TranscriptBuffer;

Defined in: packages/core/src/transcript-buffer.ts:33

Parameters

Parameter	Type
`generateId`	() => `string`
`now`	() => `number`

Returns

TranscriptBuffer

Accessors

size

Get Signature

get size(): number;

Defined in: packages/core/src/transcript-buffer.ts:63

Returns

number

Methods

add()

add(input): VoiceTurn;

Defined in: packages/core/src/transcript-buffer.ts:38

Parameters

Parameter	Type
`input`	`AddTurnInput`

Returns

VoiceTurn

all()

all(): VoiceTurn[];

Defined in: packages/core/src/transcript-buffer.ts:68

Immutable snapshot of all turns.

Returns

VoiceTurn[]

clear()

clear(): void;

Defined in: packages/core/src/transcript-buffer.ts:82

Returns

void

last()

last():
  | VoiceTurn
  | undefined;

Defined in: packages/core/src/transcript-buffer.ts:59

The most recently added turn, or undefined when empty.

Returns

| VoiceTurn | undefined

toMessages()

toMessages(): LLMMessage[];

Defined in: packages/core/src/transcript-buffer.ts:73

Project turns into LLM messages, dropping any with empty text.

Returns

LLMMessage[]

TurnDetector

Defined in: packages/core/src/turn-detector.ts:55

Rule-based local voice-activity detector.

It is driven purely by (volume, timestampMs) samples fed via TurnDetector.pushVolume. It tracks whether the user has begun speaking (volume over threshold for minSpeechMs) and when they have stopped (volume under threshold for silenceTimeoutMs). This keeps the detector free of timers so it is deterministic and trivially testable; the session supplies the clock.

Constructors

Constructor

new TurnDetector(config?): TurnDetector;

Defined in: packages/core/src/turn-detector.ts:62

Parameters

Parameter	Type
`config?`	`TurnDetectionConfig`

Returns

TurnDetector

Accessors

isSpeaking

Get Signature

get isSpeaking(): boolean;

Defined in: packages/core/src/turn-detector.ts:67

Whether sustained user speech is currently active.

Returns

boolean

options

Get Signature

get options(): ResolvedTurnDetectionConfig;

Defined in: packages/core/src/turn-detector.ts:72

Fully resolved detection settings for this detector.

Returns

ResolvedTurnDetectionConfig

Methods

forceSpeechStart()

forceSpeechStart(timestampMs): void;

Defined in: packages/core/src/turn-detector.ts:81

Continue local silence detection after ASR has already confirmed speech.

Parameters

Parameter	Type	Description
`timestampMs`	`number`	Timestamp to use as the beginning of the active speech turn.

Returns

void

pushVolume()

pushVolume(volume, timestampMs):
  | TurnDetectorEvent
  | undefined;

Defined in: packages/core/src/turn-detector.ts:100

Feed a volume sample. Returns an event when a boundary is crossed, else undefined.

speech_start — sustained volume over threshold for minSpeechMs.
speech_end — sustained silence for silenceTimeoutMs after speech.
max_turn — speech has run longer than maxTurnMs (forced end).

Parameters

Parameter	Type	Description
`volume`	`number`	Normalized input volume, typically in `0..1`.
`timestampMs`	`number`	Sample timestamp in a monotonic clock domain.

Returns

| TurnDetectorEvent | undefined

The boundary crossed by this sample, or undefined.

reset()

reset(): void;

Defined in: packages/core/src/turn-detector.ts:141

Reset all speech and silence timing state.

Returns

void

TypedEmitter

Defined in: packages/core/src/emitter.ts:8

Minimal, dependency-free, strongly-typed event emitter.

EventMap maps event names to their payload type. on/once return an unsubscribe function so callers never need to keep references to the original callback.

Type Parameters

Type Parameter
`EventMap` extends `Record`<`string`, `unknown`>

Constructors

Constructor

new TypedEmitter<EventMap>(): TypedEmitter<EventMap>;

Defined in: packages/core/src/emitter.ts:11

Returns

TypedEmitter<EventMap>

Methods

emit()

emit<K>(event, payload): void;

Defined in: packages/core/src/emitter.ts:49

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`
`payload`	`EventMap`[`K`]

Returns

void

listenerCount()

listenerCount<K>(event): number;

Defined in: packages/core/src/emitter.ts:59

Number of registered listeners for an event (primarily for testing).

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`

Returns

number

off()

off<K>(event, cb): void;

Defined in: packages/core/src/emitter.ts:39

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`
`cb`	(`payload`) => `void`

Returns

void

on()

on<K>(event, cb): () => void;

Defined in: packages/core/src/emitter.ts:15

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`
`cb`	(`payload`) => `void`

Returns

() => void

once()

once<K>(event, cb): () => void;

Defined in: packages/core/src/emitter.ts:28

Type Parameters

Type Parameter
`K` extends `string` \| `number` \| `symbol`

Parameters

Parameter	Type
`event`	`K`
`cb`	(`payload`) => `void`

Returns

() => void

removeAllListeners()

removeAllListeners(): void;

Defined in: packages/core/src/emitter.ts:64

Drop every listener. Called when a session is disposed.

Returns

void

UsageMeter

Defined in: packages/core/src/usage-meter.ts:7

Accumulates per-session usage. The SDK measures, it does not bill — business code consumes the VoiceUsageSnapshot to enforce quotas/plans.

Constructors

Constructor

new UsageMeter(now): UsageMeter;

Defined in: packages/core/src/usage-meter.ts:19

Parameters

Parameter	Type
`now`	() => `number`

Returns

UsageMeter

Methods

addAsrAudioMs()

addAsrAudioMs(ms): void;

Defined in: packages/core/src/usage-meter.ts:33

Parameters

Parameter	Type
`ms`	`number`

Returns

void

addAssistantSpeechChars()

addAssistantSpeechChars(chars): void;

Defined in: packages/core/src/usage-meter.ts:37

Parameters

Parameter	Type
`chars`	`number`

Returns

void

addLlmUsage()

addLlmUsage(usage): void;

Defined in: packages/core/src/usage-meter.ts:45

Parameters

Parameter	Type
`usage`	\| `LLMUsage` \| `undefined`

Returns

void

addProviderCost()

addProviderCost(provider, cost): void;

Defined in: packages/core/src/usage-meter.ts:57

Parameters

Parameter	Type
`provider`	`string`
`cost`	`number`

Returns

void

addTtsChars()

addTtsChars(chars): void;

Defined in: packages/core/src/usage-meter.ts:41

Parameters

Parameter	Type
`chars`	`number`

Returns

void

addUserSpeechMs()

addUserSpeechMs(ms): void;

Defined in: packages/core/src/usage-meter.ts:29

Parameters

Parameter	Type
`ms`	`number`

Returns

void

endSession()

endSession(at?): void;

Defined in: packages/core/src/usage-meter.ts:25

Parameters

Parameter	Type
`at`	`number`

Returns

void

snapshot()

snapshot(): VoiceUsageSnapshot;

Defined in: packages/core/src/usage-meter.ts:68

Returns

VoiceUsageSnapshot

startSession()

startSession(at?): void;

Defined in: packages/core/src/usage-meter.ts:21

Parameters

Parameter	Type
`at`	`number`

Returns

void

VoiceError

Defined in: packages/core/src/errors.ts:36

Typed error wrapper so a NormalizedVoiceError can flow through throw/catch and Promise rejection while remaining structurally inspectable.

Extends

Error

Implements

NormalizedVoiceError

Constructors

Constructor

new VoiceError(error): VoiceError;

Defined in: packages/core/src/errors.ts:59

Parameters

Parameter	Type	Description
`error`	`NormalizedVoiceError`	Normalized shape to wrap; `retryable` defaults from `code` when omitted.

Returns

VoiceError

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Overrides	Inherited from	Defined in
`cause?`	`readonly`	`unknown`	Original thrown value. May contain user or provider data.	`NormalizedVoiceError`.`cause` `Error.cause`	-	packages/core/src/errors.ts:52
`code`	`readonly`	`VoiceErrorCode`	Stable application error code.	-	-	packages/core/src/errors.ts:38
`fatal?`	`readonly`	`boolean`	Whether the session entered its terminal `error` state.	-	-	packages/core/src/errors.ts:48
`httpStatus?`	`readonly`	`number`	Upstream HTTP status when a response was received.	-	-	packages/core/src/errors.ts:44
`message`	`public`	`string`	Human-readable message suitable for logs (not always UI-safe).	-	`NormalizedVoiceError`.`message` `Error.message`	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077
`name`	`public`	`string`	-	-	`Error.name`	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076
`provider?`	`readonly`	`string`	Provider name when the failure originated in an adapter.	-	-	packages/core/src/errors.ts:40
`raw?`	`readonly`	`unknown`	Original provider payload or HTTP body. May contain sensitive data.	-	-	packages/core/src/errors.ts:54
`retryable?`	`readonly`	`boolean`	Hint for UI retry; not enforced by the session.	-	-	packages/core/src/errors.ts:46
`safeMessage?`	`readonly`	`string`	Sanitized summary safe for production logs and user-facing diagnostics.	-	-	packages/core/src/errors.ts:50
`stack?`	`public`	`string`	-	-	`Error.stack`	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078
`stage?`	`readonly`	`VoiceErrorStage`	Processing boundary where the failure occurred.	-	-	packages/core/src/errors.ts:42
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	-	`Error.stackTraceLimit`	node_modules/.bun/@types+node@26.0.1/node_modules/@types/node/globals.d.ts:67

Methods

toNormalized()

toNormalized(): NormalizedVoiceError;

Defined in: packages/core/src/errors.ts:77

Flatten back to a plain NormalizedVoiceError for events / logs.

Returns

NormalizedVoiceError

captureStackTrace()

Call Signature

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.bun/@types+node@26.0.1/node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

Error.captureStackTrace

Call Signature

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/.bun/bun-types@1.3.14/node_modules/bun-types/globals.d.ts:1042

Create .stack property on a target object

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

Error.captureStackTrace

isError()

static isError(value): value is Error;

Defined in: node_modules/.bun/bun-types@1.3.14/node_modules/bun-types/globals.d.ts:1037

Check if a value is an instance of Error

Parameters

Parameter	Type	Description
`value`	`unknown`	The value to check

Returns

value is Error

True if the value is an instance of Error, false otherwise

Inherited from

Error.isError

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/.bun/@types+node@26.0.1/node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

VoiceSession

Defined in: packages/core/src/session.ts:76

Voice conversation session with automatic turn-taking and optional full-duplex barge-in.

Drives the loop: listen → user audio turn → unified audio-turn provider → assistant text/audio → listen. The provider may be a native speech model or a trusted server-composed voice stack. Audio I/O comes from the RuntimeAdapter; both are supplied through VoiceSessionConfig.

Constructors

Constructor

new VoiceSession(config): VoiceSession;

Defined in: packages/core/src/session.ts:114

Parameters

Parameter	Type
`config`	`VoiceSessionConfig`

Returns

VoiceSession

Accessors

state

Get Signature

get state(): VoiceSessionState;

Defined in: packages/core/src/session.ts:163

Current finite-state machine value (see VoiceSessionState).

Returns

VoiceSessionState

Methods

dispose()

dispose(): Promise<void>;

Defined in: packages/core/src/session.ts:506

Tear everything down and drop all listeners. Safe to call multiple times. Prefer VoiceSession.finish for a graceful end that emits finished.

Returns

Promise<void>

endUserTurn()

endUserTurn(): Promise<void>;

Defined in: packages/core/src/session.ts:459

Manually end the current user turn (push-to-talk release, or a UI “done” button). Flushes the ASR session so its final result drives the loop.

Returns

Promise<void>

finish()

finish(reason?): Promise<void>;

Defined in: packages/core/src/session.ts:498

End the session normally, emitting a final usage snapshot and finished.

Parameters

Parameter	Type	Default value	Description
`reason`	`string`	`'finished'`	Opaque reason string forwarded on the state transition.

Returns

Promise<void>

getTurns()

getTurns(): VoiceTurn[];

Defined in: packages/core/src/session.ts:207

Committed user/assistant turns recorded so far.

Returns

VoiceTurn[]

getUsage()

getUsage(): VoiceUsageSnapshot;

Defined in: packages/core/src/session.ts:212

Aggregate usage meters for the active (or last) session.

Returns

VoiceUsageSnapshot

off()

off<K>(event, cb): void;

Defined in: packages/core/src/session.ts:199

Remove a previously registered handler.

Type Parameters

Type Parameter
`K` extends keyof `VoiceSessionEventMap`

Parameters

Parameter	Type	Description
`event`	`K`	Event name from VoiceSessionEventMap.
`cb`	(`payload`) => `void`	The same function reference passed to VoiceSession.on.

Returns

void

on()

on<K>(event, cb): () => void;

Defined in: packages/core/src/session.ts:173

Subscribe to a session event. Returns an unsubscribe function.

Type Parameters

Type Parameter
`K` extends keyof `VoiceSessionEventMap`

Parameters

Parameter	Type	Description
`event`	`K`	Event name from VoiceSessionEventMap.
`cb`	(`payload`) => `void`	Handler invoked with the typed payload for that event.

Returns

() => void

once()

once<K>(event, cb): () => void;

Defined in: packages/core/src/session.ts:186

Subscribe for a single delivery, then auto-unsubscribe.

Type Parameters

Type Parameter
`K` extends keyof `VoiceSessionEventMap`

Parameters

Parameter	Type	Description
`event`	`K`	Event name from VoiceSessionEventMap.
`cb`	(`payload`) => `void`	Handler invoked once with the typed payload.

Returns

() => void

pause()

pause(): Promise<void>;

Defined in: packages/core/src/session.ts:477

Pause the session: cancel in-flight replies, stop mic/ASR/playback, and enter the paused state. No-op if the transition is illegal.

Returns

Promise<void>

resume()

resume(): Promise<void>;

Defined in: packages/core/src/session.ts:488

Resume from paused by reopening the microphone for the next user turn.

Returns

Promise<void>

start()

start(): Promise<void>;

Defined in: packages/core/src/session.ts:219

Begin the session and, unless disabled, open the microphone.

Returns

Promise<void>

startListening()

startListening(): Promise<void>;

Defined in: packages/core/src/session.ts:245

Open the microphone and wire ASR for the next user turn.

Returns

Promise<void>

Interfaces

AddTurnInput

Defined in: packages/core/src/transcript-buffer.ts:7

Input for TranscriptBuffer.add. Prefer supplying id when the same id already appears on streaming events.

Properties

Property	Type	Description	Defined in
`audioUrl?`	`string`	Optional playback URL when audio was recorded.	packages/core/src/transcript-buffer.ts:15
`durationMs?`	`number`	Explicit duration; otherwise derived from `endedAt - startedAt` when possible.	packages/core/src/transcript-buffer.ts:21
`endedAt?`	`number`	Epoch millis when the turn ended.	packages/core/src/transcript-buffer.ts:19
`id?`	`string`	Supply a pre-generated id so event ids and turn ids stay in sync.	packages/core/src/transcript-buffer.ts:13
`metadata?`	`Record`<`string`, `unknown`>	Opaque app metadata attached to the turn.	packages/core/src/transcript-buffer.ts:23
`role`	`TurnRole`	Speaker role for the new turn.	packages/core/src/transcript-buffer.ts:9
`startedAt?`	`number`	Epoch millis when the turn started; defaults to now.	packages/core/src/transcript-buffer.ts:17
`text`	`string`	Final text content.	packages/core/src/transcript-buffer.ts:11

ASRCapabilities

Defined in: packages/core/src/types.ts:267

Feature flags advertised by an ASRProvider. Core uses these to choose streaming vs batch capture and whether to expect partial transcripts.

Properties

Property	Type	Description	Defined in
`batch`	`boolean`	True when the provider expects complete turn audio (batch / rolling).	packages/core/src/types.ts:271
`confidence?`	`boolean`	Whether ASRResult.confidence may be populated.	packages/core/src/types.ts:277
`languages`	`string`[]	BCP-47 language tags the provider claims to support (empty = unspecified).	packages/core/src/types.ts:279
`partialResults`	`boolean`	Whether provisional results are available via ASRSession.onPartial.	packages/core/src/types.ts:273
`streaming`	`boolean`	True when the provider accepts live chunked audio over a persistent session.	packages/core/src/types.ts:269
`wordTimestamps?`	`boolean`	Whether ASRResult.words may include timing.	packages/core/src/types.ts:275

ASRProvider

Defined in: packages/core/src/types.ts:377

Speech-to-text adapter. Implement this to plug a vendor ASR or a mock. Declare ASRCapabilities.streaming accurately so core chooses live chunks vs complete-turn audio.

Properties

Property	Type	Description	Defined in
`capabilities`	`ASRCapabilities`	Declared feature flags used by the session when routing audio.	packages/core/src/types.ts:381
`name`	`string`	Stable provider id used in errors and usage (e.g. `deepgram`).	packages/core/src/types.ts:379

Methods

createSession()

createSession(options): Promise<ASRSession>;

Defined in: packages/core/src/types.ts:387

Open a recognition session.

Parameters

Parameter	Type	Description
`options`	`ASRSessionOptions`	Language / encoding hints for this turn or call.

Returns

Promise<ASRSession>

ASRResult

Defined in: packages/core/src/types.ts:311

A partial or final transcript emitted by an ASR session.

Properties

Property	Type	Description	Defined in
`confidence?`	`number`	Provider confidence in `[0, 1]` when available.	packages/core/src/types.ts:315
`endMs?`	`number`	Utterance end offset in milliseconds.	packages/core/src/types.ts:319
`raw?`	`unknown`	Raw provider payload for debugging.	packages/core/src/types.ts:323
`startMs?`	`number`	Utterance start offset in milliseconds.	packages/core/src/types.ts:317
`text`	`string`	Transcript text (accumulated for the current utterance).	packages/core/src/types.ts:313
`words?`	`ASRWord`[]	Optional word timestamps.	packages/core/src/types.ts:321

ASRSession

Defined in: packages/core/src/types.ts:331

Live recognition session returned by ASRProvider.createSession. Core feeds audio via ASRSession.sendAudio and upserts UI from ASRSession.onPartial / ASRSession.onFinal.

Methods

close()

close(): Promise<void>;

Defined in: packages/core/src/types.ts:351

Tear down the underlying connection / resources.

Returns

Promise<void>

onError()

onError(cb): () => void;

Defined in: packages/core/src/types.ts:369

Subscribe to provider failures.

Parameters

Parameter	Type	Description
`cb`	(`error`) => `void`	Receives a NormalizedVoiceError; return value unsubscribes.

Returns

() => void

onFinal()

onFinal(cb): () => void;

Defined in: packages/core/src/types.ts:363

Subscribe to authoritative finals for the current utterance.

Parameters

Parameter	Type	Description
`cb`	(`result`) => `void`	Invoked once per finalized segment; return value unsubscribes.

Returns

() => void

onPartial()

onPartial(cb): () => void;

Defined in: packages/core/src/types.ts:357

Subscribe to provisional transcripts.

Parameters

Parameter	Type	Description
`cb`	(`result`) => `void`	Invoked on each partial; return value unsubscribes.

Returns

() => void

resetAudio()?

optional resetAudio(): void | Promise<void>;

Defined in: packages/core/src/types.ts:339

Drop buffered non-user audio while keeping the session connected.

Returns

void | Promise<void>

sendAudio()

sendAudio(chunk): void | Promise<void>;

Defined in: packages/core/src/types.ts:337

Push the next audio fragment to the provider.

Parameters

Parameter	Type	Description
`chunk`	`ArrayBuffer`	Encoded or PCM bytes matching the session encoding.

Returns

void | Promise<void>

setInterimResultsEnabled()?

optional setInterimResultsEnabled(enabled): void | Promise<void>;

Defined in: packages/core/src/types.ts:347

Pause or resume provisional transcript work without affecting the final transcript. Batch-backed providers can use this to avoid paid rolling requests until voice activity confirms that the user is speaking.

Parameters

Parameter	Type	Description
`enabled`	`boolean`	When `false`, skip rolling / interim work until re-enabled.

Returns

void | Promise<void>

stop()

stop(): Promise<void>;

Defined in: packages/core/src/types.ts:349

Signal end-of-audio and wait for a final transcript when applicable.

Returns

Promise<void>

ASRSessionOptions

Defined in: packages/core/src/types.ts:283

Options passed to ASRProvider.createSession.

Properties

Property	Type	Description	Defined in
`channels?`	`number`	Channel count; typically `1` for voice.	packages/core/src/types.ts:289
`encoding?`	`AudioEncoding`	Encoding of audio bytes sent via ASRSession.sendAudio.	packages/core/src/types.ts:291
`interimResults?`	`boolean`	Request provisional partials when the provider supports them.	packages/core/src/types.ts:293
`language?`	`string`	Preferred recognition language (e.g. `zh-CN`).	packages/core/src/types.ts:285
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter (not interpreted by core).	packages/core/src/types.ts:295
`sampleRate?`	`number`	Input sample rate in Hz when the provider needs it (e.g. PCM streams).	packages/core/src/types.ts:287

ASRWord

Defined in: packages/core/src/types.ts:299

Optional word-level timing from an ASR provider.

Properties

Property	Type	Description	Defined in
`confidence?`	`number`	Provider confidence in `[0, 1]` when available.	packages/core/src/types.ts:307
`endMs?`	`number`	Word end offset within the utterance, in milliseconds.	packages/core/src/types.ts:305
`startMs?`	`number`	Word start offset within the utterance, in milliseconds.	packages/core/src/types.ts:303
`text`	`string`	Recognized token / word.	packages/core/src/types.ts:301

AudioChunk

Defined in: packages/core/src/types.ts:777

Encoded or PCM audio fragment from AudioInputAdapter.

Properties

Property	Type	Description	Defined in
`channels?`	`number`	Channel count when known.	packages/core/src/types.ts:787
`data`	`ArrayBuffer`	Audio bytes (container or raw PCM depending on `encoding`).	packages/core/src/types.ts:779
`delivery?`	`"stream"` \| `"turn"`	`stream` is a low-latency fragment for streaming ASR; `turn` is the complete VAD-delimited recording for batch ASR and audio-LLM input. Omitted keeps the legacy behavior and makes the chunk available to both.	packages/core/src/types.ts:795
`durationMs?`	`number`	Approximate duration of this fragment.	packages/core/src/types.ts:783
`encoding?`	`string`	Codec / container label (e.g. `webm`, `pcm_s16le`).	packages/core/src/types.ts:789
`sampleRate?`	`number`	Sample rate in Hz when known (PCM).	packages/core/src/types.ts:785
`timestamp`	`number`	Capture time in epoch millis.	packages/core/src/types.ts:781

AudioInputAdapter

Defined in: packages/core/src/types.ts:799

Platform microphone capture injected via RuntimeAdapter.

Methods

onChunk()

onChunk(cb): () => void;

Defined in: packages/core/src/types.ts:831

Subscribe to encoded / PCM chunks.

Parameters

Parameter	Type
`cb`	(`chunk`) => `void`

Returns

Unsubscribe function.

() => void

onError()

onError(cb): () => void;

Defined in: packages/core/src/types.ts:843

Subscribe to capture failures.

Parameters

Parameter	Type
`cb`	(`error`) => `void`

Returns

Unsubscribe function.

() => void

onVolume()?

optional onVolume(cb): () => void;

Defined in: packages/core/src/types.ts:837

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

Parameters

Parameter	Type
`cb`	(`level`) => `void`

Returns

Unsubscribe function.

() => void

pause()?

optional pause(): Promise<void>;

Defined in: packages/core/src/types.ts:823

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

Returns

Promise<void>

requestPermission()

requestPermission(): Promise<boolean>;

Defined in: packages/core/src/types.ts:801

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

Returns

Promise<boolean>

resume()?

optional resume(): Promise<void>;

Defined in: packages/core/src/types.ts:825

Resume after pause.

Returns

Promise<void>

resumeCapture()?

optional resumeCapture(options?): Promise<void>;

Defined in: packages/core/src/types.ts:821

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>

start()

start(options): Promise<void>;

Defined in: packages/core/src/types.ts:807

Begin capture.

Parameters

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

Returns

Promise<void>

stop()

stop(): Promise<void>;

Defined in: packages/core/src/types.ts:809

Stop capture and release resources tied to the current start.

Returns

Promise<void>

suspendCapture()?

optional suspendCapture(): Promise<void>;

Defined in: packages/core/src/types.ts:814

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

Returns

Promise<void>

AudioInputOptions

Defined in: packages/core/src/types.ts:759

Capture hints passed to AudioInputAdapter.start. Runtimes may ignore unsupported fields (e.g. browser MediaRecorder encodings).

Properties

Property	Type	Description	Defined in
`autoGainControl?`	`boolean`	Request auto gain control when available.	packages/core/src/types.ts:773
`channels?`	`number`	Channel count; typically `1` for voice.	packages/core/src/types.ts:763
`chunkMs?`	`number`	Preferred encoded chunk duration in milliseconds.	packages/core/src/types.ts:767
`echoCancellation?`	`boolean`	Request hardware / browser echo cancellation when available.	packages/core/src/types.ts:769
`encoding?`	`"pcm_s16le"` \| `"opus"` \| `"webm"`	Encoded chunk format when the runtime can choose.	packages/core/src/types.ts:765
`noiseSuppression?`	`boolean`	Request noise suppression when available.	packages/core/src/types.ts:771
`sampleRate?`	`number`	Target sample rate in Hz (e.g. `16000` for PCM runtimes).	packages/core/src/types.ts:761

AudioLLMAudioChunk

Defined in: packages/core/src/types.ts:490

Streaming PCM fragment from an AudioLLMProvider.

Properties

Property	Type	Description	Defined in
`channels`	`number`	Channel count of `data`.	packages/core/src/types.ts:498
`data`	`ArrayBuffer`	Raw interleaved PCM bytes for immediate playback.	packages/core/src/types.ts:492
`encoding`	`"pcm_s16le"`	Always linear 16-bit PCM for runtime players.	packages/core/src/types.ts:494
`sampleRate`	`number`	Sample rate of `data` in Hz.	packages/core/src/types.ts:496

AudioLLMEncodedAudioSegment

Defined in: packages/core/src/types.ts:502

A complete encoded assistant-audio segment from an AudioLLMProvider.

Properties

Property	Type	Description	Defined in
`data`	`ArrayBuffer`	Encoded audio bytes ready for one-shot playback.	packages/core/src/types.ts:504
`mimeType`	`string`	MIME type of AudioLLMEncodedAudioSegment.data, such as `audio/mpeg`.	packages/core/src/types.ts:506
`sequence`	`number`	Zero-based sequence number used to preserve playback order.	packages/core/src/types.ts:508

AudioLLMGenerateInput

Defined in: packages/core/src/types.ts:512

Input for AudioLLMProvider.generate.

Properties

Property	Type	Description	Defined in
`audio`	`ArrayBuffer`	Complete audio for the current VAD-delimited user turn.	packages/core/src/types.ts:514
`format`	`AudioLLMInputFormat`	Container / codec of `audio`.	packages/core/src/types.ts:516
`maxTokens?`	`number`	Soft cap on output tokens. A server gateway must enforce its own hard ceiling.	packages/core/src/types.ts:527
`messages`	`LLMMessage`[]	Text history from completed earlier turns.	packages/core/src/types.ts:518
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter.	packages/core/src/types.ts:529
`onAudioChunk?`	(`chunk`) => `void` \| `Promise`<`void`>	Receives decoded output audio while the model response is still streaming.	packages/core/src/types.ts:533
`onAudioSegment?`	(`segment`) => `void` \| `Promise`<`void`>	Receives complete encoded audio segments while the response is still streaming.	packages/core/src/types.ts:535
`onInputTranscript?`	(`text`) => `void` \| `Promise`<`void`>	Receives the authoritative transcript of the current input audio.	packages/core/src/types.ts:539
`onTranscriptDelta?`	(`text`) => `void` \| `Promise`<`void`>	Receives the model’s spoken transcript while output audio is streaming.	packages/core/src/types.ts:541
`signal?`	`AbortSignal`	Cancels an in-flight provider request when this turn is superseded.	packages/core/src/types.ts:531
`system?`	`string`	Optional system instruction for trusted/server-side use. A policy gateway must discard client values and inject its own instruction.	packages/core/src/types.ts:523
`temperature?`	`number`	Sampling temperature; provider default when omitted. Lock server-side for untrusted clients.	packages/core/src/types.ts:525

AudioLLMGenerateOutput

Defined in: packages/core/src/types.ts:545

Completed reply from AudioLLMProvider.generate.

Properties

Property	Type	Description	Defined in
`audioBuffer`	`ArrayBuffer`	Full assistant audio buffer (may be empty if only streamed via callbacks).	packages/core/src/types.ts:551
`inputText?`	`string`	Authoritative transcript of the input audio when supplied by the provider.	packages/core/src/types.ts:547
`mimeType`	`string`	MIME type of `audioBuffer`.	packages/core/src/types.ts:553
`raw?`	`unknown`	Provider timing/cost metadata, when available.	packages/core/src/types.ts:557
`text`	`string`	Transcript of the generated assistant audio.	packages/core/src/types.ts:549
`usage?`	`LLMUsage`	Token usage when reported.	packages/core/src/types.ts:555

AudioLLMProvider

Defined in: packages/core/src/types.ts:565

A provider that consumes one user-audio turn and returns assistant text and speech. It may wrap one native audio model or a server-composed voice stack. Use it as the single conversational provider in VoiceSessionConfig.

Properties

Property	Type	Description	Defined in
`name`	`string`	Stable provider id used in errors and usage.	packages/core/src/types.ts:567
`transcribesInput?`	`boolean`	Whether this provider returns the authoritative input-audio transcript.	packages/core/src/types.ts:569

Methods

generate()

generate(input): Promise<AudioLLMGenerateOutput>;

Defined in: packages/core/src/types.ts:575

Run one audio-in / audio-out turn.

Parameters

Parameter	Type	Description
`input`	`AudioLLMGenerateInput`	Completed user audio plus history and stream callbacks.

Returns

Promise<AudioLLMGenerateOutput>

AudioLLMRetryPolicy

Defined in: packages/core/src/types.ts:1140

Retry and recovery policy for one native Audio LLM turn. Use this when a transient gateway/provider failure should not terminate the surrounding VoiceSession.

Properties

Property	Type	Description	Defined in
`backoffMs?`	`number`	Delay before the second attempt in milliseconds. Defaults to `250`; each delay is capped at 30 seconds.	packages/core/src/types.ts:1144
`continueSessionOnFailure?`	`boolean`	Emit `error` and resume listening after exhaustion instead of entering the terminal `error` state.	packages/core/src/types.ts:1150
`exponentialBackoff?`	`boolean`	Multiply `backoffMs` by `2^(attempt - 2)`. Defaults to `true`.	packages/core/src/types.ts:1146
`maxAttempts?`	`number`	Total client attempts including the first request. Defaults to `1`; values above `10` are clamped. Server budgets must not trust this value.	packages/core/src/types.ts:1142
`retryableOnly?`	`boolean`	Retry only errors marked `retryable`. Defaults to `true`.	packages/core/src/types.ts:1148

AudioOutputAdapter

Defined in: packages/core/src/types.ts:891

Platform speaker / playback side injected via RuntimeAdapter.audioOutput. Supports one-shot AudioOutputAdapter.play and optional gapless AudioOutputAdapter.startPcmStream for streaming TTS / audio LLMs.

Methods

onEnd()

onEnd(cb): () => void;

Defined in: packages/core/src/types.ts:945

Subscribe to playback end (natural finish or stop).

Parameters

Parameter	Type
`cb`	() => `void`

Returns

Unsubscribe function.

() => void

onError()

onError(cb): () => void;

Defined in: packages/core/src/types.ts:951

Subscribe to playback failures.

Parameters

Parameter	Type
`cb`	(`error`) => `void`

Returns

Unsubscribe function.

() => void

onPlaybackRequested()?

optional onPlaybackRequested(cb): () => void;

Defined in: packages/core/src/types.ts:929

Subscribe when an output adapter has accepted an utterance and is about to invoke its platform playback primitive. This can fire without a matching AudioOutputAdapter.onStart when playback subsequently fails or is cancelled before audio becomes audible.

Parameters

Parameter	Type	Description
`cb`	() => `void`	Called once for each one-shot or PCM-stream playback request.

Returns

Unsubscribe function.

() => void

onStart()

onStart(cb): () => void;

Defined in: packages/core/src/types.ts:939

Parameters

Parameter	Type	Description
`cb`	() => `void`	Called when playback first becomes active.

Returns

Unsubscribe function.

() => void

onVolume()?

optional onVolume(cb): () => void;

Defined in: packages/core/src/types.ts:919

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

pause()?

optional pause(): Promise<void>;

Defined in: packages/core/src/types.ts:910

Pause playback without discarding the current utterance (optional).

Returns

Promise<void>

play()

play(input): Promise<void>;

Defined in: packages/core/src/types.ts:899

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>

resume()?

optional resume(): Promise<void>;

Defined in: packages/core/src/types.ts:912

Resume after AudioOutputAdapter.pause.

Returns

Promise<void>

startPcmStream()?

optional startPcmStream(options): Promise<AudioOutputStream>;

Defined in: packages/core/src/types.ts:906

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.

stop()

stop(): Promise<void>;

Defined in: packages/core/src/types.ts:908

Stop current playback and cancel any open PCM stream.

Returns

Promise<void>

unlock()?

optional unlock(): Promise<void>;

Defined in: packages/core/src/types.ts:893

Prime browser autoplay permission from a direct user gesture.

Returns

Promise<void>

AudioOutputStream

Defined in: packages/core/src/types.ts:875

Incremental PCM writer returned by AudioOutputAdapter.startPcmStream. Call AudioOutputStream.write for each contiguous block, then AudioOutputStream.close when the utterance ends.

Methods

close()

close(): Promise<void>;

Defined in: packages/core/src/types.ts:883

Signal end-of-stream and resolve after all queued audio has played.

Returns

Promise<void>

write()

write(data): Promise<void>;

Defined in: packages/core/src/types.ts:881

Queue another contiguous PCM block for playback.

Parameters

Parameter	Type	Description
`data`	`ArrayBuffer`	Interleaved PCM matching the stream’s encoding / rate.

Returns

Promise<void>

AudioPlaybackInput

Defined in: packages/core/src/types.ts:847

Input for one-shot AudioOutputAdapter.play.

Properties

Property	Type	Description	Defined in
`audioBuffer?`	`ArrayBuffer`	In-memory audio bytes (takes precedence when both are set, if supported).	packages/core/src/types.ts:851
`audioUrl?`	`string`	Remote or blob URL to fetch and play.	packages/core/src/types.ts:849
`mimeType?`	`string`	MIME type of the audio payload.	packages/core/src/types.ts:853
`volume?`	`number`	Playback gain in `[0, 1]`.	packages/core/src/types.ts:855

BargeInSpeechGateOptions

Defined in: packages/core/src/playback-echo-filter.ts:30

Tuning knobs for BargeInSpeechGate. Raise thresholds to reduce false barge-in from knocks; lower them for quieter speech.

Properties

Property	Type	Description	Defined in
`requiredVoicedFrames?`	`number`	Voiced frames required inside the window to open the gate. Default 4.	packages/core/src/playback-echo-filter.ts:36
`volumeThreshold?`	`number`	Per-frame RMS (post-echo) above which a frame counts as voiced. Default 0.008.	packages/core/src/playback-echo-filter.ts:32
`windowFrames?`	`number`	Moving-window length in frames for the voiced-frame vote. Default 12.	packages/core/src/playback-echo-filter.ts:34

CreateVoiceErrorOptions

Defined in: packages/core/src/errors.ts:98

Optional metadata for createVoiceError. Omitted fields get sensible defaults (retryable from known network/ASR codes).

Properties

Property	Type	Description	Defined in
`cause?`	`unknown`	Original thrown value. May contain user or provider data.	packages/core/src/errors.ts:112
`fatal?`	`boolean`	Whether the session entered its terminal `error` state.	packages/core/src/errors.ts:108
`httpStatus?`	`number`	Upstream HTTP status when a response was received.	packages/core/src/errors.ts:104
`provider?`	`string`	Provider name when the failure originated in an adapter.	packages/core/src/errors.ts:100
`raw?`	`unknown`	Original provider payload or HTTP body. May contain sensitive data.	packages/core/src/errors.ts:114
`retryable?`	`boolean`	Override the default retryability for VoiceErrorCode.	packages/core/src/errors.ts:106
`safeMessage?`	`string`	Sanitized summary; defaults to a stable message for the error code.	packages/core/src/errors.ts:110
`stage?`	`VoiceErrorStage`	Processing boundary where the failure occurred.	packages/core/src/errors.ts:102

LLMGenerateInput

Defined in: packages/core/src/types.ts:413

Input for LLMProvider.generate / LLMProvider.stream.

Properties

Property	Type	Description	Defined in
`maxTokens?`	`number`	Soft cap on completion tokens. A server gateway must enforce its own hard ceiling.	packages/core/src/types.ts:424
`messages`	`LLMMessage`[]	Chronological chat history for the model.	packages/core/src/types.ts:420
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter.	packages/core/src/types.ts:428
`responseFormat?`	`"text"` \| `"json"`	Prefer plain text or structured JSON when the model supports it.	packages/core/src/types.ts:426
`signal?`	`AbortSignal`	Cancels an in-flight provider request when this turn is superseded.	packages/core/src/types.ts:430
`system?`	`string`	Optional system instruction for this request. Treat as trusted policy: untrusted clients must not send it through a passthrough provider gateway.	packages/core/src/types.ts:418
`temperature?`	`number`	Sampling temperature; provider default when omitted. Lock server-side for untrusted clients.	packages/core/src/types.ts:422

LLMGenerateOutput

Defined in: packages/core/src/types.ts:434

Non-streaming completion from LLMProvider.generate.

Properties

Property	Type	Description	Defined in
`json?`	`unknown`	Parsed JSON when `responseFormat` was `json`.	packages/core/src/types.ts:438
`raw?`	`unknown`	Raw provider payload for debugging.	packages/core/src/types.ts:442
`text`	`string`	Assistant reply text.	packages/core/src/types.ts:436
`usage?`	`LLMUsage`	Token usage when reported.	packages/core/src/types.ts:440

LLMMessage

Defined in: packages/core/src/types.ts:395

One chat message forwarded to an LLMProvider.

Properties

Property	Type	Description	Defined in
`content`	`string`	Plain text content.	packages/core/src/types.ts:399
`role`	`"user"` \| `"assistant"` \| `"system"`	Message role in the conversation.	packages/core/src/types.ts:397

LLMProvider

Defined in: packages/core/src/types.ts:462

Low-level text LLM contract for trusted server-side audio-turn composition. Browser/app sessions do not configure this provider directly. Prefer implementing LLMProvider.stream so the UI can show incremental text.

Properties

Property	Type	Description	Defined in
`name`	`string`	Stable provider id used in errors and usage.	packages/core/src/types.ts:464

Methods

generate()

generate(input): Promise<LLMGenerateOutput>;

Defined in: packages/core/src/types.ts:470

Produce a complete reply for the current turn.

Parameters

Parameter	Type	Description
`input`	`LLMGenerateInput`	System prompt, history, and generation knobs.

Returns

Promise<LLMGenerateOutput>

stream()?

optional stream(input): AsyncIterable<LLMStreamChunk>;

Defined in: packages/core/src/types.ts:476

Optional token stream used when available (lower time-to-first-text).

Parameters

Parameter	Type	Description
`input`	`LLMGenerateInput`	Same shape as LLMProvider.generate.

Returns

AsyncIterable<LLMStreamChunk>

LLMStreamChunk

Defined in: packages/core/src/types.ts:446

One chunk from LLMProvider.stream.

Properties

Property	Type	Description	Defined in
`error?`	`NormalizedVoiceError`	Normalized failure for `error`.	packages/core/src/types.ts:454
`text?`	`string`	New text for `text_delta`.	packages/core/src/types.ts:450
`type`	`"error"` \| `"text_delta"` \| `"usage"` \| `"done"`	Chunk kind: text fragment, usage update, completion, or error.	packages/core/src/types.ts:448
`usage?`	`LLMUsage`	Usage snapshot for `usage` / `done`.	packages/core/src/types.ts:452

LLMUsage

Defined in: packages/core/src/types.ts:403

Optional token usage reported by an LLM or Audio LLM provider.

Properties

Property	Type	Description	Defined in
`inputTokens?`	`number`	Prompt / input tokens when the provider reports them.	packages/core/src/types.ts:405
`outputTokens?`	`number`	Completion / output tokens when the provider reports them.	packages/core/src/types.ts:407
`totalTokens?`	`number`	Total tokens when the provider reports a combined figure.	packages/core/src/types.ts:409

LoggerAdapter

Defined in: packages/core/src/types.ts:1035

Optional structured logger injected via RuntimeAdapter.logger.

Methods

debug()

debug(...args): void;

Defined in: packages/core/src/types.ts:1037

Verbose diagnostics (disabled in production by default).

Parameters

Parameter	Type
…`args`	`unknown`[]

Returns

void

error()

error(...args): void;

Defined in: packages/core/src/types.ts:1043

Failures that typically surface as session errors.

Parameters

Parameter	Type
…`args`	`unknown`[]

Returns

void

info()

info(...args): void;

Defined in: packages/core/src/types.ts:1039

Informational lifecycle messages.

Parameters

Parameter	Type
…`args`	`unknown`[]

Returns

void

warn()

warn(...args): void;

Defined in: packages/core/src/types.ts:1041

Recoverable anomalies.

Parameters

Parameter	Type
…`args`	`unknown`[]

Returns

void

MockASROptions

Defined in: packages/core/src/providers/mock.ts:100

Options for createMockASR. Use when wiring tests or the developer profile without a live STT backend.

Properties

Property	Type	Description	Defined in
`emitPartials?`	`boolean`	Emit a partial (half-length) result before each final. Default true.	packages/core/src/providers/mock.ts:104
`failWith?`	`NormalizedVoiceError`	When set, the next `sendAudio` triggers this error instead of a result.	packages/core/src/providers/mock.ts:106
`transcripts`	`string`[]	Scripted final transcripts, emitted one per `sendAudio` call.	packages/core/src/providers/mock.ts:102

MockAudioInputOptions

Defined in: packages/core/src/providers/mock-runtime.ts:15

Options for MockAudioInput. Use when constructing a mock mic for tests without a real capture device.

Properties

Property	Type	Description	Defined in
`permission?`	`boolean`	Permission result returned by `requestPermission`. Default true.	packages/core/src/providers/mock-runtime.ts:17

MockAudioLLMOptions

Defined in: packages/core/src/providers/mock.ts:26

Options for createMockAudioLLM.

Properties

Property	Type	Description	Defined in
`failWith?`	`NormalizedVoiceError`	When set, `generate` rejects with this error.	packages/core/src/providers/mock.ts:46
`inputTranscripts?`	`string`[]	Scripted authoritative input transcripts, consumed one per turn.	packages/core/src/providers/mock.ts:28
`mimeType?`	`string`	MIME type attached to the synthetic audio buffer. Defaults to `audio/mpeg`.	packages/core/src/providers/mock.ts:44
`reply?`	(`input`, `callIndex`, `inputText`) => `string`	Reply generator for one audio turn.	packages/core/src/providers/mock.ts:36
`usage?`	`LLMUsage`	Token usage returned for every turn.	packages/core/src/providers/mock.ts:42

MockAudioOutputOptions

Defined in: packages/core/src/providers/mock-runtime.ts:92

Options for MockAudioOutput. Use when tests need to control whether play auto-completes or fails.

Properties

Property	Type	Description	Defined in
`autoComplete?`	`boolean`	Auto-fire start/end around `play`. Default true.	packages/core/src/providers/mock-runtime.ts:94
`failWith?`	`NormalizedVoiceError`	When set, `play` rejects with this error.	packages/core/src/providers/mock-runtime.ts:96

MockLLMOptions

Defined in: packages/core/src/providers/mock.ts:188

Options for createMockLLM. Use in tests or demos that need a deterministic text reply without a live LLM.

Properties

Property	Type	Description	Defined in
`failWith?`	`NormalizedVoiceError`	When set, `generate`/`stream` reject with this error.	packages/core/src/providers/mock.ts:197
`reply?`	(`input`, `callIndex`) => `string`	Reply generator. Receives the input and 0-based call index. Defaults to echoing the last user message.	packages/core/src/providers/mock.ts:193
`usage?`	`LLMUsage`	Token usage returned on every `generate` / stream completion.	packages/core/src/providers/mock.ts:195

MockPronunciationOptions

Defined in: packages/core/src/providers/mock.ts:313

Options for createMockPronunciation. Use when pronunciation scoring is optional in tests but the provider slot must still be filled.

Properties

Property	Type	Description	Defined in
`failWith?`	`NormalizedVoiceError`	When set, `assess` rejects with this error.	packages/core/src/providers/mock.ts:317
`score?`	`number`	Overall / per-dimension score returned for every assessment. Default 80.	packages/core/src/providers/mock.ts:315

MockRuntime

Defined in: packages/core/src/providers/mock-runtime.ts:207

In-memory RuntimeAdapter with typed mock input/output adapters. Prefer createMockRuntime over constructing this shape by hand.

Extends

RuntimeAdapter

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
`audioInput`	`MockAudioInput`	Controllable mock microphone.	`RuntimeAdapter`.`audioInput`	-	packages/core/src/providers/mock-runtime.ts:209
`audioOutput`	`MockAudioOutput`	Controllable mock speaker.	`RuntimeAdapter`.`audioOutput`	-	packages/core/src/providers/mock-runtime.ts:211
`logger?`	`LoggerAdapter`	Optional logger; core uses it sparingly.	-	`RuntimeAdapter`.`logger`	packages/core/src/types.ts:1061
`network?`	`NetworkAdapter`	Optional HTTP/WebSocket hooks for providers.	-	`RuntimeAdapter`.`network`	packages/core/src/types.ts:1057
`storage?`	`RuntimeStorageAdapter`	Optional persistence for caches.	-	`RuntimeAdapter`.`storage`	packages/core/src/types.ts:1059

MockRuntimeOptions

Defined in: packages/core/src/providers/mock-runtime.ts:196

Options for createMockRuntime. Forwards into MockAudioInput / MockAudioOutput constructors.

Properties

Property	Type	Description	Defined in
`input?`	`MockAudioInputOptions`	Microphone mock options. See MockAudioInputOptions.	packages/core/src/providers/mock-runtime.ts:198
`output?`	`MockAudioOutputOptions`	Speaker mock options. See MockAudioOutputOptions.	packages/core/src/providers/mock-runtime.ts:200

MockTTSOptions

Defined in: packages/core/src/providers/mock.ts:263

Options for createMockTTS. Use when tests need a TTS adapter that returns synthetic audio bytes.

Properties

Property	Type	Description	Defined in
`durationMsPerChar?`	`number`	Estimated playback duration in ms; defaults to 60ms per character.	packages/core/src/providers/mock.ts:265
`failWith?`	`NormalizedVoiceError`	When set, `synthesize` rejects with this error.	packages/core/src/providers/mock.ts:267

NetworkAdapter

Defined in: packages/core/src/types.ts:999

Platform HTTP / WebSocket hooks used by providers that need them.

Methods

createWebSocket()

createWebSocket(url, protocols?): RuntimeWebSocket;

Defined in: packages/core/src/types.ts:1013

Open a WebSocket for streaming providers.

Parameters

Parameter	Type	Description
`url`	`string`	WebSocket URL.
`protocols?`	`string` \| `string`[]	Optional subprotocol(s).

Returns

RuntimeWebSocket

fetch()

fetch(input, init?): Promise<Response>;

Defined in: packages/core/src/types.ts:1006

Fetch implementation (browser fetch, undici, etc.).

Parameters

Parameter	Type	Description
`input`	`RequestInfo` \| `URL`	Request URL or `RequestInfo`.
`init?`	`RequestInit`	Optional fetch init.

Returns

Promise<Response>

NormalizedVoiceError

Defined in: packages/core/src/types.ts:83

Vendor-neutral error shape used by session events, providers, and VoiceError. Construct via createVoiceError when possible so retryable defaults apply.

Properties

Property	Type	Description	Defined in
`cause?`	`unknown`	Original thrown value, when available. May contain user or provider data.	packages/core/src/types.ts:101
`code`	`VoiceErrorCode`	Stable application error code.	packages/core/src/types.ts:85
`fatal?`	`boolean`	Whether the session entered its terminal `error` state. Session events populate this.	packages/core/src/types.ts:97
`httpStatus?`	`number`	Upstream HTTP status when an HTTP response was received.	packages/core/src/types.ts:93
`message`	`string`	Human-readable message suitable for logs (not always UI-safe).	packages/core/src/types.ts:87
`provider?`	`string`	Provider name when the failure originated in an adapter.	packages/core/src/types.ts:89
`raw?`	`unknown`	Original provider payload or HTTP body. Development-only; it may contain sensitive data.	packages/core/src/types.ts:103
`retryable?`	`boolean`	Hint for UI retry; not enforced by the session.	packages/core/src/types.ts:95
`safeMessage?`	`string`	Sanitized summary safe for user-facing diagnostics and production logs.	packages/core/src/types.ts:99
`stage?`	`VoiceErrorStage`	Processing boundary where the failure occurred.	packages/core/src/types.ts:91

PcmAudioStreamOptions

Defined in: packages/core/src/types.ts:859

Options for AudioOutputAdapter.startPcmStream.

Extended by

ExpoPcmChunkFileInput

Properties

Property	Type	Description	Defined in
`channels`	`number`	Channel count of subsequent `write` payloads.	packages/core/src/types.ts:865
`encoding`	`"pcm_s16le"`	Always linear 16-bit PCM for incremental streams.	packages/core/src/types.ts:861
`sampleRate`	`number`	Sample rate of subsequent `write` payloads in Hz.	packages/core/src/types.ts:863
`volume?`	`number`	Playback gain in `[0, 1]`.	packages/core/src/types.ts:867

PlaybackEchoFilterOptions

Defined in: packages/core/src/playback-echo-filter.ts:6

Tuning knobs for PlaybackEchoFilter. Use when default delay/warmup margins are too aggressive or too timid for a given device or speaker layout.

Properties

Property	Type	Description	Defined in
`echoMargin?`	`number`	Multiplier on estimated echo gain before subtracting from mic RMS. Default 1.12.	packages/core/src/playback-echo-filter.ts:16
`frameMs?`	`number`	Step size (ms) when searching for playback↔mic delay alignment. Default 50.	packages/core/src/playback-echo-filter.ts:8
`historyMs?`	`number`	How long (ms) of mic/output samples to retain for correlation. Default 1200.	packages/core/src/playback-echo-filter.ts:12
`maxDelayMs?`	`number`	Maximum acoustic delay (ms) to consider when correlating echo. Default 300.	packages/core/src/playback-echo-filter.ts:10
`noiseFloor?`	`number`	Absolute RMS floor subtracted after echo estimate (avoids digital noise trips). Default 0.003.	packages/core/src/playback-echo-filter.ts:18
`warmupMs?`	`number`	Suppress barge-in for this many ms after playback reference begins. Default 350.	packages/core/src/playback-echo-filter.ts:14

PronunciationInput

Defined in: packages/core/src/types.ts:696

Input for optional pronunciation / speaking assessment providers.

Properties

Property	Type	Description	Defined in
`audio?`	`string` \| `ArrayBuffer`	Raw audio bytes or a remote URL the provider can fetch.	packages/core/src/types.ts:698
`durationMs?`	`number`	Spoken duration in milliseconds when known.	packages/core/src/types.ts:706
`language?`	`string`	BCP-47 language for scoring models.	packages/core/src/types.ts:704
`metadata?`	`Record`<`string`, `unknown`>	Opaque adapter metadata.	packages/core/src/types.ts:710
`referenceText?`	`string`	Expected reference sentence when scoring against a prompt.	packages/core/src/types.ts:702
`transcript`	`string`	Recognized or user-submitted spoken text.	packages/core/src/types.ts:700
`words?`	`ASRWord`[]	Optional word timings from ASR to align scoring.	packages/core/src/types.ts:708

PronunciationProvider

Defined in: packages/core/src/types.ts:739

Optional adapter for scoring user pronunciation after a turn.

Properties

Property	Type	Description	Defined in
`name`	`string`	Stable provider id used in errors and usage.	packages/core/src/types.ts:741

Methods

assess()

assess(input): Promise<PronunciationResult>;

Defined in: packages/core/src/types.ts:748

Score a spoken utterance.

Parameters

Parameter	Type	Description
`input`	`PronunciationInput`	Audio and/or transcript to assess.

Returns

Promise<PronunciationResult>

Normalized PronunciationResult.

PronunciationResult

Defined in: packages/core/src/types.ts:714

Normalized scores from a PronunciationProvider.

Properties

Property	Type	Description	Defined in
`accuracy?`	`number`	Pronunciation accuracy component.	packages/core/src/types.ts:718
`completeness?`	`number`	Completeness vs reference text.	packages/core/src/types.ts:722
`fluency?`	`number`	Fluency / pacing component.	packages/core/src/types.ts:720
`overall?`	`number`	Overall 0–100 (or provider scale) score when available.	packages/core/src/types.ts:716
`prosody?`	`number`	Prosody / intonation component.	packages/core/src/types.ts:724
`raw?`	`unknown`	Original upstream payload for debugging.	packages/core/src/types.ts:735
`words?`	{ `errorType?`: `string`; `score?`: `number`; `text`: `string`; }[]	Per-word diagnostics when the provider returns them.	packages/core/src/types.ts:726

ResolvedTurnDetectionConfig

Defined in: packages/core/src/turn-detector.ts:4

Fully populated turn-detection settings used internally and in diagnostics.

Extends

Required<TurnDetectionConfig>

Properties

Property	Type	Description	Inherited from	Defined in
`maxTurnMs`	`number`	Hard local cap on a single user turn length. The server must enforce its own request/audio limit.	`TurnDetectionConfig`.`maxTurnMs`	packages/core/src/types.ts:1089
`minSpeechMs`	`number`	Minimum voiced time before speech is considered started.	`TurnDetectionConfig`.`minSpeechMs`	packages/core/src/types.ts:1085
`silenceTimeoutMs`	`number`	Quiet time after speech before the turn is closed.	`TurnDetectionConfig`.`silenceTimeoutMs`	packages/core/src/types.ts:1087
`strategy`	`TurnDetectionStrategy`	How speech start and the end of a user turn are detected.	`TurnDetectionConfig`.`strategy`	packages/core/src/types.ts:1083
`volumeThreshold`	`number`	RMS threshold when using local volume detection (approximately 0–1).	`TurnDetectionConfig`.`volumeThreshold`	packages/core/src/types.ts:1091

RuntimeAdapter

Defined in: packages/core/src/types.ts:1051

Platform boundary: microphone + playback (+ optional network/storage/logger). Created by @ottervoice/runtime-web, runtime-react-native, runtime-node, or createMockRuntime.

Extended by

Properties

Property	Type	Description	Defined in
`audioInput`	`AudioInputAdapter`	Microphone / capture side.	packages/core/src/types.ts:1053
`audioOutput`	`AudioOutputAdapter`	Speaker / playback side.	packages/core/src/types.ts:1055
`logger?`	`LoggerAdapter`	Optional logger; core uses it sparingly.	packages/core/src/types.ts:1061
`network?`	`NetworkAdapter`	Optional HTTP/WebSocket hooks for providers.	packages/core/src/types.ts:1057
`storage?`	`RuntimeStorageAdapter`	Optional persistence for caches.	packages/core/src/types.ts:1059

RuntimeStorageAdapter

Defined in: packages/core/src/types.ts:1017

Optional key/value store for adapter caches (not required by core).

Methods

get()

get(key): Promise<string | null>;

Defined in: packages/core/src/types.ts:1022

Parameters

Parameter	Type	Description
`key`	`string`	Storage key.

Returns

Promise<string | null>

Stored string or null when missing.

remove()

remove(key): Promise<void>;

Defined in: packages/core/src/types.ts:1031

Parameters

Parameter	Type	Description
`key`	`string`	Storage key to delete.

Returns

Promise<void>

set()

set(key, value): Promise<void>;

Defined in: packages/core/src/types.ts:1027

Parameters

Parameter	Type	Description
`key`	`string`	Storage key.
`value`	`string`	Value to persist.

Returns

Promise<void>

RuntimeWebSocket

Defined in: packages/core/src/types.ts:958

Minimal WebSocket surface returned by NetworkAdapter.createWebSocket. Keeps providers free of DOM/ws type coupling; subscribe via the on* helpers.

Methods

close()

close(code?, reason?): void;

Defined in: packages/core/src/types.ts:971

Close the socket.

Parameters

Parameter	Type	Description
`code?`	`number`	Optional WebSocket close code.
`reason?`	`string`	Optional human-readable reason.

Returns

void

onClose()

onClose(cb): () => void;

Defined in: packages/core/src/types.ts:995

Subscribe to close.

Parameters

Parameter	Type
`cb`	() => `void`

Returns

Unsubscribe function.

() => void

onError()

onError(cb): () => void;

Defined in: packages/core/src/types.ts:989

Subscribe to socket-level errors.

Parameters

Parameter	Type
`cb`	(`error`) => `void`

Returns

Unsubscribe function.

() => void

onMessage()

onMessage(cb): () => void;

Defined in: packages/core/src/types.ts:983

Subscribe to inbound frames.

Parameters

Parameter	Type
`cb`	(`data`) => `void`

Returns

Unsubscribe function.

() => void

onOpen()

onOpen(cb): () => void;

Defined in: packages/core/src/types.ts:977

Subscribe to the open event.

Parameters

Parameter	Type
`cb`	() => `void`

Returns

Unsubscribe function.

() => void

send()

send(data): void;

Defined in: packages/core/src/types.ts:964

Send a text or binary frame.

Parameters

Parameter	Type	Description
`data`	`string` \| `ArrayBuffer`	UTF-8 text or binary payload.

Returns

void

TTSAudioChunk

Defined in: packages/core/src/types.ts:637

One raw-PCM fragment yielded by TTSProvider.stream.

Properties

Property	Type	Description	Defined in
`channels`	`number`	Channel count of TTSAudioChunk.data.	packages/core/src/types.ts:645
`data`	`ArrayBuffer`	Raw interleaved PCM bytes ready for incremental playback.	packages/core/src/types.ts:639
`encoding`	`"pcm_s16le"`	Linear signed 16-bit little-endian PCM.	packages/core/src/types.ts:641
`sampleRate`	`number`	Sample rate of TTSAudioChunk.data in Hz.	packages/core/src/types.ts:643

TTSCapabilities

Defined in: packages/core/src/types.ts:603

Declared voices / formats for a TTSProvider.

Properties

Property	Type	Description	Defined in
`formats`	`TTSFormat`[]	Output formats the adapter can produce.	packages/core/src/types.ts:609
`languages`	`string`[]	BCP-47 language tags supported for synthesis.	packages/core/src/types.ts:611
`streaming`	`boolean`	Whether the provider implements low-latency TTSProvider.stream.	packages/core/src/types.ts:605
`voices`	`TTSVoice`[]	Voices advertised by the adapter.	packages/core/src/types.ts:607

TTSInput

Defined in: packages/core/src/types.ts:615

Input for TTSProvider.synthesize.

Properties

Property	Type	Description	Defined in
`cacheKey?`	`string`	Optional cache key for adapters that memoize synthesis.	packages/core/src/types.ts:629
`format?`	`TTSFormat`	Preferred output container / codec.	packages/core/src/types.ts:627
`language?`	`string`	Preferred language for multilingual voices.	packages/core/src/types.ts:621
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter.	packages/core/src/types.ts:631
`pitch?`	`number`	Pitch adjustment (provider-specific scale).	packages/core/src/types.ts:625
`signal?`	`AbortSignal`	Cancels synthesis when the turn is interrupted or superseded.	packages/core/src/types.ts:633
`speed?`	`number`	Speaking rate multiplier. Allowlist or override it at an untrusted-client gateway.	packages/core/src/types.ts:623
`text`	`string`	Text to speak.	packages/core/src/types.ts:617
`voice?`	`string`	Provider voice id / name. Allowlist or override it at an untrusted-client gateway.	packages/core/src/types.ts:619

TTSOutput

Defined in: packages/core/src/types.ts:649

Audio returned by TTSProvider.synthesize.

Properties

Property	Type	Description	Defined in
`audioBuffer?`	`ArrayBuffer`	In-memory audio bytes (preferred for local playback).	packages/core/src/types.ts:653
`audioUrl?`	`string`	Remote or blob URL for playback when buffering is inconvenient.	packages/core/src/types.ts:651
`cached?`	`boolean`	True when served from an adapter cache.	packages/core/src/types.ts:659
`durationMs?`	`number`	Estimated duration when known.	packages/core/src/types.ts:657
`mimeType`	`string`	MIME type of `audioUrl` / `audioBuffer`.	packages/core/src/types.ts:655
`raw?`	`unknown`	Raw provider payload for debugging.	packages/core/src/types.ts:661

TTSProvider

Defined in: packages/core/src/types.ts:668

Low-level text-to-speech contract for trusted server-side audio-turn composition. Browser/app sessions do not configure this provider directly.

Properties

Property	Type	Description	Defined in
`capabilities`	`TTSCapabilities`	Declared voices and formats.	packages/core/src/types.ts:672
`name`	`string`	Stable provider id used in errors and usage.	packages/core/src/types.ts:670

Methods

stream()?

optional stream(input): AsyncIterable<TTSAudioChunk>;

Defined in: packages/core/src/types.ts:688

Optionally stream raw PCM while speech is still being synthesized. Implement this together with capabilities.streaming: true; core falls back to sentence-sized TTSProvider.synthesize calls when absent.

Parameters

Parameter	Type	Description
`input`	`TTSInput`	Text, voice hints, and cancellation signal. Providers may force `pcm` because streamed chunks must match TTSAudioChunk.

Returns

AsyncIterable<TTSAudioChunk>

An async sequence of contiguous PCM chunks.

synthesize()

synthesize(input): Promise<TTSOutput>;

Defined in: packages/core/src/types.ts:678

Synthesize speech for the given text.

Parameters

Parameter	Type	Description
`input`	`TTSInput`	Text plus optional voice / format hints.

Returns

Promise<TTSOutput>

TTSVoice

Defined in: packages/core/src/types.ts:589

A synthesizable voice advertised by a TTSProvider.

Properties

Property	Type	Description	Defined in
`gender?`	`"male"` \| `"female"` \| `"neutral"`	Optional gender metadata for filtering.	packages/core/src/types.ts:597
`id`	`string`	Stable voice id passed to TTSInput.voice.	packages/core/src/types.ts:591
`language`	`string`	Primary BCP-47 language for this voice.	packages/core/src/types.ts:595
`name`	`string`	Human-readable display name for UI pickers.	packages/core/src/types.ts:593
`style?`	`string`[]	Optional style tags (e.g. `cheerful`, `news`).	packages/core/src/types.ts:599

TurnDetectionConfig

Defined in: packages/core/src/types.ts:1081

Voice-activity knobs while listening for the user. Passed via VoiceSessionConfig.turnDetection; pair with VoiceSessionConfig.interruptionDetection for barge-in thresholds.

Properties

Property	Type	Description	Defined in
`maxTurnMs?`	`number`	Hard local cap on a single user turn length. The server must enforce its own request/audio limit.	packages/core/src/types.ts:1089
`minSpeechMs?`	`number`	Minimum voiced time before speech is considered started.	packages/core/src/types.ts:1085
`silenceTimeoutMs?`	`number`	Quiet time after speech before the turn is closed.	packages/core/src/types.ts:1087
`strategy`	`TurnDetectionStrategy`	How speech start and the end of a user turn are detected.	packages/core/src/types.ts:1083
`volumeThreshold?`	`number`	RMS threshold when using local volume detection (approximately 0–1).	packages/core/src/types.ts:1091

VoiceSessionConfig

Defined in: packages/core/src/types.ts:1162

Top-level configuration for createVoiceSession, createOtterVoiceSession, or VoiceSession.

Every session uses one audio-turn provider. That provider may call one native speech model or a trusted server route that composes ASR, LLM, and TTS. Add a separate ASR only when the audio-turn provider does not return the input transcript itself.

Properties

Property	Type	Description	Defined in
`asrPartial?`	`boolean`	Emit provisional `asr_partial` results. Defaults to true. Disabling this does not affect the authoritative `asr_final` transcript. Batch-backed rolling ASR can increase requests, so server quotas must not trust it.	packages/core/src/types.ts:1172
`audioLlmMaxTokens?`	`number`	Cap audio-turn output tokens (native audio and transcript may share this budget). Omit to use the model’s default maximum — required for long-form speech. An untrusted-client gateway must still enforce a server-side hard ceiling.	packages/core/src/types.ts:1183
`audioLlmRetry?`	`AudioLLMRetryPolicy`	Retry/recovery behavior for each native Audio LLM turn. See AudioLLMRetryPolicy; server idempotency and budgets remain authoritative.	packages/core/src/types.ts:1193
`audioLlmStartTiming?`	`"after_audio"` \| `"after_asr_final"`	Choose when an Audio LLM request begins. `after_audio` starts as soon as VAD finalizes the user audio and runs caption ASR in parallel for the lowest response latency. `after_asr_final` waits for the authoritative caption first, avoiding provider spend when a natural pause is superseded. Defaults to `after_asr_final`.	packages/core/src/types.ts:1191
`audioLlmSystemPrompt?`	`string`	Optional trusted-runtime system instruction forwarded to an audio-turn provider. Browser/app integrations should omit this and let their policy gateway inject it.	packages/core/src/types.ts:1177
`generateId?`	() => `string`	Override id generation (useful for deterministic tests).	packages/core/src/types.ts:1217
`interruptionDetection?`	`Partial`<`Omit`<`TurnDetectionConfig`, `"strategy"`>>	Stricter VAD used only while assistant audio is playing. Keeping this separate prevents taps and playback echo from triggering barge-in without making normal listening less sensitive.	packages/core/src/types.ts:1213
`language?`	`string`	Preferred ASR language; omit to auto-detect. A gateway may override/ignore this with server policy.	packages/core/src/types.ts:1195
`metadata?`	`Record`<`string`, `unknown`>	Opaque app metadata (not interpreted by core).	packages/core/src/types.ts:1221
`mode`	`VoiceSessionMode`	Duplex / PTT mode. See VoiceSessionMode.	packages/core/src/types.ts:1166
`now?`	() => `number`	Override the clock (useful for deterministic tests).	packages/core/src/types.ts:1219
`policy?`	`VoiceSessionPolicy`	Session-level timers and barge-in recovery knobs.	packages/core/src/types.ts:1215
`providers`	{ `asr?`: `ASRProvider`; `audioLlm`: `AudioLLMProvider`; `pronunciation?`: `PronunciationProvider`; }	-	packages/core/src/types.ts:1198
`providers.asr?`	`ASRProvider`	Optional caption ASR; omit when AudioLLMProvider.transcribesInput is true.	packages/core/src/types.ts:1200
`providers.audioLlm`	`AudioLLMProvider`	Unified audio-turn provider: native speech model or server-composed voice stack.	packages/core/src/types.ts:1202
`providers.pronunciation?`	`PronunciationProvider`	Optional pronunciation scoring after a user turn.	packages/core/src/types.ts:1204
`runtime`	`RuntimeAdapter`	Platform audio (and optional network/storage/logger) adapter.	packages/core/src/types.ts:1197
`turnDetection?`	`TurnDetectionConfig`	Local voice-activity detection while listening for the user.	packages/core/src/types.ts:1207

VoiceSessionPolicy

Defined in: packages/core/src/types.ts:1112

Session-level timers and barge-in recovery knobs.

Properties

Property	Type	Description	Defined in
`allowInterruption?`	`boolean`	Allow barge-in while the assistant is speaking.	packages/core/src/types.ts:1122
`autoStartListening?`	`boolean`	After `start()`, automatically enter listening. Defaults to true.	packages/core/src/types.ts:1120
`falseInterruptionSilenceMs?`	`number`	Silence after a tentative pause before playback is resumed as a false interruption.	packages/core/src/types.ts:1124
`falseInterruptionTimeoutMs?`	`number`	Maximum time to keep playback tentatively paused without confirming speech.	packages/core/src/types.ts:1126
`interruptionCooldownMs?`	`number`	Ignore new barge-in candidates shortly after resuming a false interruption.	packages/core/src/types.ts:1130
`interruptionTailIgnoreMs?`	`number`	Ignore microphone energy right after a tentative pause while speaker echo decays. Defaults to 200 ms.	packages/core/src/types.ts:1128
`maxSessionDurationMs?`	`number`	Force-finish the session after this wall-clock duration.	packages/core/src/types.ts:1118
`maxTurnDurationMs?`	`number`	Hard local cap on one user turn. The server must enforce its own request/audio limit.	packages/core/src/types.ts:1116
`postPlaybackVadRearmMs?`	`number`	Maximum time to wait for a quiet microphone baseline after assistant playback. Defaults to 300 ms.	packages/core/src/types.ts:1132
`silenceTimeoutMs?`	`number`	Quiet time that ends a listening turn when no other detector wins.	packages/core/src/types.ts:1114

VoiceTurn

Defined in: packages/core/src/types.ts:117

One conversation turn recorded by the session / TranscriptBuffer. Emitted on turn / turn_end events and available via transcript APIs.

Properties

Property	Type	Description	Defined in
`audioUrl?`	`string`	Optional local or remote playback URL when recorded.	packages/core/src/types.ts:125
`durationMs?`	`number`	Convenience duration (`endedAt - startedAt`) when known.	packages/core/src/types.ts:131
`endedAt?`	`number`	Epoch millis when the turn ended.	packages/core/src/types.ts:129
`id`	`string`	Stable turn id shared with streaming events.	packages/core/src/types.ts:119
`metadata?`	`Record`<`string`, `unknown`>	Opaque app metadata attached to the turn.	packages/core/src/types.ts:133
`role`	`TurnRole`	Who spoke this turn.	packages/core/src/types.ts:121
`startedAt`	`number`	Epoch millis when the turn started.	packages/core/src/types.ts:127
`text`	`string`	Final transcript or assistant text for the turn.	packages/core/src/types.ts:123

VoiceUsageSnapshot

Defined in: packages/core/src/types.ts:140

Cumulative usage counters for a live VoiceSession. Emitted periodically / on finish for cost and latency dashboards.

Properties

Property	Type	Description	Defined in
`asrAudioMs`	`number`	Audio milliseconds forwarded to ASR.	packages/core/src/types.ts:148
`assistantSpeechChars`	`number`	Assistant spoken character count (approx).	packages/core/src/types.ts:146
`llmInputTokens?`	`number`	Accumulated LLM prompt tokens when providers report usage.	packages/core/src/types.ts:152
`llmOutputTokens?`	`number`	Accumulated LLM completion tokens when providers report usage.	packages/core/src/types.ts:154
`providerCosts?`	`Record`<`string`, `number`>	Optional per-provider cost estimates in billable units.	packages/core/src/types.ts:156
`sessionDurationMs`	`number`	Wall time since VoiceSession.start.	packages/core/src/types.ts:142
`ttsChars`	`number`	Characters sent to TTS.	packages/core/src/types.ts:150
`userSpeechMs`	`number`	Accumulated user speech duration when runtimes report chunk durations.	packages/core/src/types.ts:144

Type Aliases

AudioEncoding

type AudioEncoding = "pcm_s16le" | "opus" | "webm" | "wav" | "mp3";

Defined in: packages/core/src/types.ts:260

Wire encoding of audio bytes sent to ASR / Audio LLM adapters. Runtimes stamp this on AudioChunk; providers may narrow further.

AudioLLMInputFormat

type AudioLLMInputFormat = "webm" | "wav" | "mp3" | "opus";

Defined in: packages/core/src/types.ts:487

Container / codec accepted by AudioLLMGenerateInput.format. WebM/Opus often need a runtime prepareAudio step before OpenAI-style APIs.

TTSFormat

type TTSFormat = "mp3" | "wav" | "ogg" | "opus" | "pcm";

Defined in: packages/core/src/types.ts:586

Output audio container requested from a TTSProvider. Passed via TTSInput.format and listed in TTSCapabilities.formats.

TurnDetectionStrategy

type TurnDetectionStrategy = "volume" | "manual" | "hybrid";

Defined in: packages/core/src/types.ts:1074

How user turns are detected while listening:

volume — local RMS VAD (TurnDetectionConfig.volumeThreshold)
manual — caller drives VoiceSession.endUserTurn
hybrid — combine ASR speech confirmation with local silence detection

TurnDetectorEvent

type TurnDetectorEvent = "speech_start" | "speech_end" | "max_turn";

Defined in: packages/core/src/turn-detector.ts:43

Boundary event returned by TurnDetector.pushVolume when a threshold is crossed (undefined when the sample does not change state).

TurnRole

type TurnRole = "user" | "assistant" | "system";

Defined in: packages/core/src/types.ts:111

Speaker role for a VoiceTurn in the transcript.

VoiceErrorCode

type VoiceErrorCode =
  | "permission_denied"
  | "microphone_unavailable"
  | "network_error"
  | "asr_connection_failed"
  | "asr_timeout"
  | "llm_failed"
  | "tts_failed"
  | "audio_playback_failed"
  | "provider_rate_limited"
  | "provider_quota_exceeded"
  | "unsupported_runtime"
  | "invalid_state"
  | "aborted"
  | "unknown";

Defined in: packages/core/src/types.ts:49

Stable application error codes for voice sessions and providers. Prefer these over free-form strings when building NormalizedVoiceError or createVoiceError.

VoiceErrorStage

type VoiceErrorStage =
  | "capture"
  | "audio_prepare"
  | "gateway"
  | "provider"
  | "stream"
  | "playback"
  | "session";

Defined in: packages/core/src/types.ts:70

Processing stage where a NormalizedVoiceError originated. Use this with NormalizedVoiceError.code to route diagnostics without parsing provider messages.

VoiceSessionEventMap

type VoiceSessionEventMap = {
  asr_final: {
     confidence?: number;
     durationMs?: number;
     text: string;
     turnId: string;
  };
  asr_partial: {
     confidence?: number;
     text: string;
     turnId: string;
  };
  assistant_audio: {
     audio?: ArrayBuffer;
     audioUrl?: string;
     durationMs?: number;
     mimeType: string;
     turnId: string;
  };
  assistant_audio_end: {
     turnId: string;
  };
  assistant_audio_start: {
     turnId: string;
  };
  assistant_text: {
     text: string;
     turnId: string;
  };
  assistant_text_delta: {
     delta: string;
     text: string;
     turnId: string;
  };
  error: NormalizedVoiceError;
  finished: {
     turns: VoiceTurn[];
  };
  statechange: {
     from: VoiceSessionState;
     reason?: string;
     to: VoiceSessionState;
  };
  turn: {
     turn: VoiceTurn;
  };
  usage: VoiceUsageSnapshot;
  user_audio_end: {
     at: number;
     turnId: string;
  };
  user_audio_final: {
     audio: ArrayBuffer;
     durationMs?: number;
     format: string;
     turnId: string;
  };
};

Defined in: packages/core/src/types.ts:167

Strongly typed event payloads for VoiceSession. Subscribe with session.on('eventName', handler).

Properties

Property	Type	Description	Defined in
`asr_final`	{ `confidence?`: `number`; `durationMs?`: `number`; `text`: `string`; `turnId`: `string`; }	Authoritative user transcript for the turn.	packages/core/src/types.ts:182
`asr_final.confidence?`	`number`	-	packages/core/src/types.ts:185
`asr_final.durationMs?`	`number`	-	packages/core/src/types.ts:186
`asr_final.text`	`string`	-	packages/core/src/types.ts:183
`asr_final.turnId`	`string`	-	packages/core/src/types.ts:184
`asr_partial`	{ `confidence?`: `number`; `text`: `string`; `turnId`: `string`; }	Provisional ASR caption; upsert by `turnId`.	packages/core/src/types.ts:175
`asr_partial.confidence?`	`number`	-	packages/core/src/types.ts:179
`asr_partial.text`	`string`	Accumulated provisional transcript.	packages/core/src/types.ts:177
`asr_partial.turnId`	`string`	-	packages/core/src/types.ts:178
`assistant_audio`	{ `audio?`: `ArrayBuffer`; `audioUrl?`: `string`; `durationMs?`: `number`; `mimeType`: `string`; `turnId`: `string`; }	Complete assistant audio snapshot for persistence, emitted before playback completes.	packages/core/src/types.ts:226
`assistant_audio.audio?`	`ArrayBuffer`	In-memory audio bytes when the provider returned a buffer.	packages/core/src/types.ts:230
`assistant_audio.audioUrl?`	`string`	Remote audio URL when the provider returned a URL instead of bytes.	packages/core/src/types.ts:232
`assistant_audio.durationMs?`	`number`	Provider-estimated duration when available.	packages/core/src/types.ts:236
`assistant_audio.mimeType`	`string`	MIME type of `audio` or `audioUrl`.	packages/core/src/types.ts:234
`assistant_audio.turnId`	`string`	Assistant turn shared with text and playback events.	packages/core/src/types.ts:228
`assistant_audio_end`	{ `turnId`: `string`; }	Assistant audio playback ended (completed or interrupted).	packages/core/src/types.ts:222
`assistant_audio_end.turnId`	`string`	-	packages/core/src/types.ts:223
`assistant_audio_start`	{ `turnId`: `string`; }	Assistant audio playback began for this turn.	packages/core/src/types.ts:218
`assistant_audio_start.turnId`	`string`	-	packages/core/src/types.ts:219
`assistant_text`	{ `text`: `string`; `turnId`: `string`; }	Final assistant text for the turn (may normalize streaming text).	packages/core/src/types.ts:205
`assistant_text.text`	`string`	-	packages/core/src/types.ts:206
`assistant_text.turnId`	`string`	-	packages/core/src/types.ts:207
`assistant_text_delta`	{ `delta`: `string`; `text`: `string`; `turnId`: `string`; }	Incremental assistant transcript emitted before `assistant_text`.	packages/core/src/types.ts:210
`assistant_text_delta.delta`	`string`	Newly received text fragment.	packages/core/src/types.ts:212
`assistant_text_delta.text`	`string`	Complete assistant text accumulated for this turn so far.	packages/core/src/types.ts:214
`assistant_text_delta.turnId`	`string`	-	packages/core/src/types.ts:215
`error`	`NormalizedVoiceError`	Normalized failure; see NormalizedVoiceError.	packages/core/src/types.ts:249
`finished`	{ `turns`: `VoiceTurn`[]; }	Session completed gracefully; turns are the full history.	packages/core/src/types.ts:245
`finished.turns`	`VoiceTurn`[]	-	packages/core/src/types.ts:246
`statechange`	{ `from`: `VoiceSessionState`; `reason?`: `string`; `to`: `VoiceSessionState`; }	FSM transition with optional reason string.	packages/core/src/types.ts:169
`statechange.from`	`VoiceSessionState`	-	packages/core/src/types.ts:170
`statechange.reason?`	`string`	-	packages/core/src/types.ts:172
`statechange.to`	`VoiceSessionState`	-	packages/core/src/types.ts:171
`turn`	{ `turn`: `VoiceTurn`; }	A committed VoiceTurn was added to history.	packages/core/src/types.ts:239
`turn.turn`	`VoiceTurn`	-	packages/core/src/types.ts:240
`usage`	`VoiceUsageSnapshot`	Latest usage meters.	packages/core/src/types.ts:243
`user_audio_end`	{ `at`: `number`; `turnId`: `string`; }	VAD/manual boundary used as the response-latency start point.	packages/core/src/types.ts:189
`user_audio_end.at`	`number`	-	packages/core/src/types.ts:191
`user_audio_end.turnId`	`string`	-	packages/core/src/types.ts:190
`user_audio_final`	{ `audio`: `ArrayBuffer`; `durationMs?`: `number`; `format`: `string`; `turnId`: `string`; }	Complete VAD-delimited user recording, emitted after capture is stopped and flushed.	packages/core/src/types.ts:194
`user_audio_final.audio`	`ArrayBuffer`	Complete encoded recording assembled in capture order.	packages/core/src/types.ts:198
`user_audio_final.durationMs?`	`number`	Approximate captured duration when the runtime reports chunk durations.	packages/core/src/types.ts:202
`user_audio_final.format`	`string`	Runtime-reported container, codec, or MIME type of the recording.	packages/core/src/types.ts:200
`user_audio_final.turnId`	`string`	User turn shared with `asr_final`.	packages/core/src/types.ts:196

VoiceSessionMode

type VoiceSessionMode = "half_duplex" | "full_duplex" | "push_to_talk" | "streaming_transcript";

Defined in: packages/core/src/types.ts:1105

Conversation duplex mode:

half_duplex — listen only after assistant playback finishes
full_duplex — keep listening (and allow barge-in) while speaking
push_to_talk — caller drives VoiceSession.endUserTurn
streaming_transcript — captions without the full reply loop

VoiceSessionState

type VoiceSessionState =
  | "idle"
  | "starting"
  | "assistant_speaking"
  | "listening"
  | "user_speaking"
  | "processing"
  | "scoring"
  | "paused"
  | "finished"
  | "error";

Defined in: packages/core/src/types.ts:18

Finite-state machine states for VoiceSession. Subscribe via the statechange event on VoiceSessionEventMap.

Variables

DEFAULT_TURN_DETECTION

const DEFAULT_TURN_DETECTION: ResolvedTurnDetectionConfig;

Defined in: packages/core/src/turn-detector.ts:11

Default TurnDetectionConfig values used by resolveTurnDetection and TurnDetector when the session omits knobs.

Functions

canTransition()

function canTransition(from, to): boolean;

Defined in: packages/core/src/state-machine.ts:65

Whether a direct transition from from → to is allowed by the session FSM. Same-state transitions always return false.

Parameters

Parameter	Type	Description
`from`	`VoiceSessionState`	Current state.
`to`	`VoiceSessionState`	Desired next state.

Returns

boolean

createIdGenerator()

function createIdGenerator(prefix?): () => string;

Defined in: packages/core/src/internal/ids.ts:5

Default monotonic-ish id generator. Avoids a crypto dependency so the core stays runtime-agnostic; sessions may inject their own via config.

Parameters

Parameter	Type	Default value
`prefix`	`string`	`'id'`

Returns

() => string

createMockASR()

function createMockASR(options): ASRProvider;

Defined in: packages/core/src/providers/mock.ts:116

Deterministic ASR for tests and the developer profile. Each sendAudio advances through transcripts; partial + final callbacks fire synchronously.

Parameters

Parameter	Type	Description
`options`	`MockASROptions`	Scripted transcripts and failure overrides. See MockASROptions.

Returns

ASRProvider

An ASRProvider with name mock_asr.

createMockAudioLLM()

function createMockAudioLLM(options?): AudioLLMProvider;

Defined in: packages/core/src/providers/mock.ts:57

Create a deterministic unified audio-turn provider for tests and examples. It reports a scripted input transcript and encodes the reply text as the returned synthetic audio bytes.

Parameters

Parameter	Type	Description
`options`	`MockAudioLLMOptions`	Scripted transcripts, reply behavior, usage, and failures.

Returns

AudioLLMProvider

An AudioLLMProvider with name mock_audio_turn.

createMockLLM()

function createMockLLM(options?): LLMProvider;

Defined in: packages/core/src/providers/mock.ts:215

Deterministic LLMProvider for tests and the developer profile. generate returns a full string; stream yields word-sized text deltas.

Parameters

Parameter	Type	Description
`options`	`MockLLMOptions`	Reply, usage, and failure overrides. See MockLLMOptions.

Returns

LLMProvider

An LLMProvider with name mock_llm.

createMockPronunciation()

function createMockPronunciation(options?): PronunciationProvider;

Defined in: packages/core/src/providers/mock.ts:328

Deterministic PronunciationProvider for tests and demos. Splits the transcript into words and assigns MockPronunciationOptions.score to each dimension.

Parameters

Parameter	Type	Description
`options`	`MockPronunciationOptions`	Score and failure overrides. See MockPronunciationOptions.

Returns

PronunciationProvider

A PronunciationProvider with name mock_pronunciation.

createMockRuntime()

function createMockRuntime(options?): MockRuntime;

Defined in: packages/core/src/providers/mock-runtime.ts:220

Assemble a fully in-memory RuntimeAdapter for tests and Node demos.

Parameters

Parameter	Type	Description
`options`	`MockRuntimeOptions`	Optional input/output mock knobs. See MockRuntimeOptions.

Returns

MockRuntime

A MockRuntime with MockAudioInput and MockAudioOutput.

createMockTTS()

function createMockTTS(options?): TTSProvider;

Defined in: packages/core/src/providers/mock.ts:278

Deterministic TTSProvider for tests and demos. Encodes the input text as UTF-8 bytes and reports a duration from MockTTSOptions.durationMsPerChar.

Parameters

Parameter	Type	Description
`options`	`MockTTSOptions`	Duration and failure overrides. See MockTTSOptions.

Returns

TTSProvider

A TTSProvider with name mock_tts.

createOtterVoiceSession()

function createOtterVoiceSession(config): VoiceSession;

Defined in: packages/core/src/session.ts:1905

Create an OtterVoice session using the unified audio-turn contract.

Parameters

Parameter	Type	Description
`config`	`VoiceSessionConfig`	Runtime, audio-turn provider, optional caption ASR, VAD, and policy.

Returns

VoiceSession

A session that must be dispose()d when finished.

createVoiceError()

function createVoiceError(
   code,
   message,
   options?): NormalizedVoiceError;

Defined in: packages/core/src/errors.ts:125

Build a NormalizedVoiceError with sensible retryable defaults.

Parameters

Parameter	Type	Description
`code`	`VoiceErrorCode`	Stable VoiceErrorCode.
`message`	`string`	Human-readable message for logs.
`options`	`CreateVoiceErrorOptions`	Optional stage, provider, retry, safe-message, and diagnostic metadata. See CreateVoiceErrorOptions.

Returns

NormalizedVoiceError

A plain NormalizedVoiceError (not a thrown Error).

createVoiceSession()

function createVoiceSession(config): VoiceSession;

Defined in: packages/core/src/session.ts:1895

Create a VoiceSession from a fully wired VoiceSessionConfig.

Parameters

Parameter	Type	Description
`config`	`VoiceSessionConfig`	Runtime adapter, audio-turn provider, optional caption ASR, VAD, and policy.

Returns

VoiceSession

A session that must be dispose()d when finished.

defaultNow()

function defaultNow(): number;

Defined in: packages/core/src/internal/ids.ts:15

Default wall-clock used by sessions when no now override is injected.

Returns

number

isTerminal()

function isTerminal(state): boolean;

Defined in: packages/core/src/state-machine.ts:54

Whether state ends the session lifecycle (currently only finished).

Parameters

Parameter	Type	Description
`state`	`VoiceSessionState`	Candidate VoiceSessionState.

Returns

boolean

normalizeError()

function normalizeError(
   value,
   fallbackCode?,
   provider?,
   stage?): NormalizedVoiceError;

Defined in: packages/core/src/errors.ts:186

Coerce an arbitrary thrown value into a NormalizedVoiceError.

Used by the session and provider adapters so that every error surfaced to consumers shares one shape, regardless of where it originated.

Parameters

Parameter	Type	Default value	Description
`value`	`unknown`	`undefined`	Unknown thrown/rejected value.
`fallbackCode`	`VoiceErrorCode`	`'unknown'`	Code used when `value` has no recognized shape. Defaults to `unknown`.
`provider?`	`string`	`undefined`	Optional provider name attached when missing on `value`.
`stage?`	`VoiceErrorStage`	`undefined`	Optional processing stage attached when missing on `value`.

Returns

NormalizedVoiceError

A NormalizedVoiceError suitable for session error events.

resolveTurnDetection()

function resolveTurnDetection(config?): ResolvedTurnDetectionConfig;

Defined in: packages/core/src/turn-detector.ts:25

Merge a partial TurnDetectionConfig with DEFAULT_TURN_DETECTION.

Parameters

Parameter	Type	Description
`config?`	`TurnDetectionConfig`	Optional TurnDetectionConfig overrides from the session.

Returns

ResolvedTurnDetectionConfig

A fully populated config object (no missing fields).