@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, provider router, 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` / `VoiceSession`	Conversation loop and full-duplex interruption policy.
`StateMachine`, `canTransition`, `isTerminal`	Session state transitions.
`TypedEmitter`	Strongly-typed, unsubscribe-returning event emitter.
`TranscriptBuffer`	Ordered turns → LLM message projection.
`TurnDetector`	Rule-based VAD / endpointing from volume samples.
`UsageMeter`	Per-session usage snapshot (you bill; it measures).
`ProviderRegistry`, `providerProfiles`, `resolveProfile`	Provider routing.
`createVoiceError`, `normalizeError`, `VoiceError`	Unified error model.
`createMockASR/LLM/TTS/Pronunciation`, `createMockRuntime`	Test doubles.

Provider & runtime contracts

Implement these interfaces to plug in real services / platforms:

ASRProvider — createSession() → streaming partial/final transcripts.
LLMProvider — generate() (and optional stream()).
AudioLLMProvider — one model consumes a completed audio turn and returns assistant transcript + audio; set pipeline: 'audio_llm'. Caption ASR runs in parallel and does not feed the model.
TTSProvider — synthesize() → audio buffer or URL.
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.

Session events

statechange, asr_partial, asr_final, user_audio_end, assistant_text, 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:113

Parameters

Parameter	Type
`options`	`MockAudioOutputOptions`

Returns

MockAudioOutput

Properties

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

Methods

emitVolume()

emitVolume(level): void;

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

Parameters

Parameter	Type
`level`	`number`

Returns

void

fireEnd()

fireEnd(): void;

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

Returns

void

onEnd()

onEnd(cb): () => void;

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

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:173

Subscribe to playback failures.

Parameters

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

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onError

onStart()

onStart(cb): () => void;

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

Subscribe to playback start.

Parameters

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

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onStart

onVolume()

onVolume(cb): () => void;

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

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:140

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:118

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:144

Resume after AudioOutputAdapter.pause.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.resume

stop()

stop(): Promise<void>;

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

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

ProviderRegistry

Defined in: packages/core/src/provider-router.ts:156

Maps provider ids (as used in ProviderProfile) to concrete provider instances, and resolves a profile into a usable ResolvedProviders bundle for a import(‘./session’).VoiceSession.

Constructors

Constructor

new ProviderRegistry(initial?): ProviderRegistry;

Defined in: packages/core/src/provider-router.ts:162

Parameters

Parameter	Type
`initial?`	`RegisteredProviders`

Returns

ProviderRegistry

Methods

getProfile()

getProfile(name): ProviderProfile;

Defined in: packages/core/src/provider-router.ts:199

Parameters

Parameter	Type
`name`	`ProviderProfileName`

Returns

ProviderProfile

registerASR()

registerASR(id, provider): this;

Defined in: packages/core/src/provider-router.ts:179

Parameters

Parameter	Type
`id`	`string`
`provider`	`ASRProvider`

Returns

this

registerLLM()

registerLLM(id, provider): this;

Defined in: packages/core/src/provider-router.ts:184

Parameters

Parameter	Type
`id`	`string`
`provider`	`LLMProvider`

Returns

this

registerPronunciation()

registerPronunciation(id, provider): this;

Defined in: packages/core/src/provider-router.ts:194

Parameters

Parameter	Type
`id`	`string`
`provider`	`PronunciationProvider`

Returns

this

registerTTS()

registerTTS(id, provider): this;

Defined in: packages/core/src/provider-router.ts:189

Parameters

Parameter	Type
`id`	`string`
`provider`	`TTSProvider`

Returns

this

resolve()

resolve(profileOrName): ResolvedProviders;

Defined in: packages/core/src/provider-router.ts:203

Parameters

Parameter	Type
`profileOrName`	\| `ProviderProfileName` \| `ProviderProfile`

Returns

ResolvedProviders

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:51

Rule-based voice-activity / endpointing 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:58

Parameters

Parameter	Type
`config?`	`TurnDetectionConfig`

Returns

TurnDetector

Accessors

isSpeaking

Get Signature

get isSpeaking(): boolean;

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

Returns

boolean

options

Get Signature

get options(): Required<TurnDetectionConfig>;

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

Returns

Required<TurnDetectionConfig>

Methods

forceSpeechStart()

forceSpeechStart(timestampMs): void;

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

Continue endpointing after another detector has already confirmed speech.

Parameters

Parameter	Type
`timestampMs`	`number`

Returns

void

pushVolume()

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

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

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
`volume`	`number`
`timestampMs`	`number`

Returns

| TurnDetectorEvent | undefined

reset()

reset(): void;

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

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:15

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:28

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	Inherited from	Defined in
`cause?`	`public`	`unknown`	The cause of the error.	`Error.cause`	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
`code`	`readonly`	`VoiceErrorCode`	Stable application error code.	-	packages/core/src/errors.ts:17
`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:19
`raw?`	`readonly`	`unknown`	Original thrown value or HTTP body, when available.	-	packages/core/src/errors.ts:23
`retryable?`	`readonly`	`boolean`	Hint for UI retry; not enforced by the session.	-	packages/core/src/errors.ts:21
`stack?`	`public`	`string`	-	`Error.stack`	node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078
`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:41

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:69

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

Drives the loop: assistant speaks → listen → user speaks → ASR → LLM → assistant speaks → … It is platform-agnostic; audio I/O comes from the RuntimeAdapter and cloud capabilities from the providers, both supplied through VoiceSessionConfig.

Constructors

Constructor

new VoiceSession(config): VoiceSession;

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

Parameters

Parameter	Type
`config`	`VoiceSessionConfig`

Returns

VoiceSession

Accessors

state

Get Signature

get state(): VoiceSessionState;

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

Current finite-state machine value (see VoiceSessionState).

Returns

VoiceSessionState

Methods

dispose()

dispose(): Promise<void>;

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

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:408

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:456

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:200

Committed user/assistant turns recorded so far.

Returns

VoiceTurn[]

getUsage()

getUsage(): VoiceUsageSnapshot;

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

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

Returns

VoiceUsageSnapshot

off()

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

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

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:166

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:179

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:435

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:446

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

Returns

Promise<void>

start()

start(initialPrompt?): Promise<void>;

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

Begin the session. Speaks the initial assistant message (from the agent plugin or initialPrompt) and then, unless disabled, opens the mic.

Parameters

Parameter	Type	Description
`initialPrompt?`	`string`	Optional opening line when no agent plugin supplies one.

Returns

Promise<void>

startListening()

startListening(): Promise<void>;

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

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

Returns

Promise<void>

submitUserText()

submitUserText(text): Promise<void>;

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

Inject user text directly, bypassing audio/ASR. Useful for text fallback and deterministic flows.

Parameters

Parameter	Type
`text`	`string`

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

AgentSessionInput

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

Arguments passed to VoiceAgentPlugin.shouldFinishSession and VoiceAgentPlugin.generateReport.

Properties

Property	Type	Description	Defined in
`turns`	`VoiceTurn`[]	Completed turns in chronological order.	packages/core/src/types.ts:975

AgentTurnInput

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

Arguments passed to VoiceAgentPlugin.generateNextAssistantMessage. Contains the full turn history plus the latest user utterance for convenience.

Properties

Property	Type	Description	Defined in
`lastUserText`	`string`	Text of the most recent user turn.	packages/core/src/types.ts:966
`turns`	`VoiceTurn`[]	Completed turns in chronological order (includes the latest user turn).	packages/core/src/types.ts:964

ASRCapabilities

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

Feature flags advertised by an ASRProvider. Core uses these to choose streaming vs batch capture and whether to expect partials / endpointing.

Properties

Property	Type	Description	Defined in
`batch`	`boolean`	True when the provider expects complete turn audio (batch / rolling).	packages/core/src/types.ts:223
`confidence?`	`boolean`	Whether ASRResult.confidence may be populated.	packages/core/src/types.ts:229
`endpointing?`	`boolean`	Whether the provider can emit utterance-end / endpoint signals.	packages/core/src/types.ts:231
`languages`	`string`[]	BCP-47 language tags the provider claims to support (empty = unspecified).	packages/core/src/types.ts:233
`partialResults`	`boolean`	Whether provisional results are available via ASRSession.onPartial.	packages/core/src/types.ts:225
`streaming`	`boolean`	True when the provider accepts live chunked audio over a persistent session.	packages/core/src/types.ts:221
`wordTimestamps?`	`boolean`	Whether ASRResult.words may include timing.	packages/core/src/types.ts:227

ASRProvider

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

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:337
`name`	`string`	Stable provider id used in errors and usage (e.g. `deepgram`).	packages/core/src/types.ts:335

Methods

createSession()

createSession(options): Promise<ASRSession>;

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

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:267

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:271
`endMs?`	`number`	Utterance end offset in milliseconds.	packages/core/src/types.ts:275
`raw?`	`unknown`	Raw provider payload for debugging.	packages/core/src/types.ts:279
`startMs?`	`number`	Utterance start offset in milliseconds.	packages/core/src/types.ts:273
`text`	`string`	Transcript text (accumulated for the current utterance).	packages/core/src/types.ts:269
`words?`	`ASRWord`[]	Optional word timestamps.	packages/core/src/types.ts:277

ASRSession

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

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:307

Tear down the underlying connection / resources.

Returns

Promise<void>

onError()

onError(cb): () => void;

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

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:319

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:313

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:295

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:293

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:303

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:305

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

Returns

Promise<void>

ASRSessionOptions

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

Options passed to ASRProvider.createSession.

Properties

Property	Type	Description	Defined in
`channels?`	`number`	Channel count; typically `1` for voice.	packages/core/src/types.ts:243
`encoding?`	`AudioEncoding`	Encoding of audio bytes sent via ASRSession.sendAudio.	packages/core/src/types.ts:245
`endpointing?`	`boolean`	Ask the provider to emit endpointing / utterance-end signals when available.	packages/core/src/types.ts:249
`interimResults?`	`boolean`	Request provisional partials when the provider supports them.	packages/core/src/types.ts:247
`language?`	`string`	Preferred recognition language (e.g. `zh-CN`).	packages/core/src/types.ts:239
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter (not interpreted by core).	packages/core/src/types.ts:251
`sampleRate?`	`number`	Input sample rate in Hz when the provider needs it (e.g. PCM streams).	packages/core/src/types.ts:241

ASRWord

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

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:263
`endMs?`	`number`	Word end offset within the utterance, in milliseconds.	packages/core/src/types.ts:261
`startMs?`	`number`	Word start offset within the utterance, in milliseconds.	packages/core/src/types.ts:259
`text`	`string`	Recognized token / word.	packages/core/src/types.ts:257

AudioChunk

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

Encoded or PCM audio fragment from AudioInputAdapter.

Properties

Property	Type	Description	Defined in
`channels?`	`number`	Channel count when known.	packages/core/src/types.ts:691
`data`	`ArrayBuffer`	Audio bytes (container or raw PCM depending on `encoding`).	packages/core/src/types.ts:683
`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:699
`durationMs?`	`number`	Approximate duration of this fragment.	packages/core/src/types.ts:687
`encoding?`	`string`	Codec / container label (e.g. `webm`, `pcm_s16le`).	packages/core/src/types.ts:693
`sampleRate?`	`number`	Sample rate in Hz when known (PCM).	packages/core/src/types.ts:689
`timestamp`	`number`	Capture time in epoch millis.	packages/core/src/types.ts:685

AudioInputAdapter

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

Platform microphone capture injected via RuntimeAdapter.

Methods

onChunk()

onChunk(cb): () => void;

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

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:747

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:741

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:727

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

Returns

Promise<void>

requestPermission()

requestPermission(): Promise<boolean>;

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

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:729

Resume after pause.

Returns

Promise<void>

resumeCapture()?

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

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

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:711

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:713

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:718

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:663

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:677
`channels?`	`number`	Channel count; typically `1` for voice.	packages/core/src/types.ts:667
`chunkMs?`	`number`	Preferred encoded chunk duration in milliseconds.	packages/core/src/types.ts:671
`echoCancellation?`	`boolean`	Request hardware / browser echo cancellation when available.	packages/core/src/types.ts:673
`encoding?`	`"pcm_s16le"` \| `"opus"` \| `"webm"`	Encoded chunk format when the runtime can choose.	packages/core/src/types.ts:669
`noiseSuppression?`	`boolean`	Request noise suppression when available.	packages/core/src/types.ts:675
`sampleRate?`	`number`	Target sample rate in Hz (e.g. `16000` for PCM runtimes).	packages/core/src/types.ts:665

AudioLLMAudioChunk

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

Streaming PCM fragment from an AudioLLMProvider.

Properties

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

AudioLLMGenerateInput

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

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:456
`format`	`AudioLLMInputFormat`	Container / codec of `audio`.	packages/core/src/types.ts:458
`maxTokens?`	`number`	Soft cap on output tokens (often shared by audio + transcript).	packages/core/src/types.ts:466
`messages`	`LLMMessage`[]	Text history from completed earlier turns.	packages/core/src/types.ts:460
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter.	packages/core/src/types.ts:468
`onAudioChunk?`	(`chunk`) => `void` \| `Promise`<`void`>	Receives decoded output audio while the model response is still streaming.	packages/core/src/types.ts:472
`onTranscriptDelta?`	(`text`) => `void` \| `Promise`<`void`>	Receives the model’s spoken transcript while output audio is streaming.	packages/core/src/types.ts:474
`signal?`	`AbortSignal`	Cancels an in-flight provider request when this turn is superseded.	packages/core/src/types.ts:470
`system?`	`string`	Optional system instruction for this request.	packages/core/src/types.ts:462
`temperature?`	`number`	Sampling temperature; provider default when omitted.	packages/core/src/types.ts:464

AudioLLMGenerateOutput

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

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:482
`mimeType`	`string`	MIME type of `audioBuffer`.	packages/core/src/types.ts:484
`raw?`	`unknown`	Provider timing/cost metadata, when available.	packages/core/src/types.ts:488
`text`	`string`	Transcript of the generated assistant audio.	packages/core/src/types.ts:480
`usage?`	`LLMUsage`	Token usage when reported.	packages/core/src/types.ts:486

AudioLLMProvider

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

A single model that consumes user audio and directly generates speech (used when VoiceSessionConfig.pipeline is audio_llm).

Properties

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

Methods

generate()

generate(input): Promise<AudioLLMGenerateOutput>;

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

Run one audio-in / audio-out turn.

Parameters

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

Returns

Promise<AudioLLMGenerateOutput>

AudioOutputAdapter

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

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:835

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:841

Subscribe to playback failures.

Parameters

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

Returns

Unsubscribe function.

() => void

onStart()

onStart(cb): () => void;

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

Subscribe to playback start.

Parameters

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

Returns

Unsubscribe function.

() => void

onVolume()?

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

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

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:814

Pause playback without discarding the current utterance (optional).

Returns

Promise<void>

play()

play(input): Promise<void>;

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

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:816

Resume after AudioOutputAdapter.pause.

Returns

Promise<void>

startPcmStream()?

optional startPcmStream(options): Promise<AudioOutputStream>;

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

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:812

Stop current playback and cancel any open PCM stream.

Returns

Promise<void>

unlock()?

optional unlock(): Promise<void>;

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

Prime browser autoplay permission from a direct user gesture.

Returns

Promise<void>

AudioOutputStream

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

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:787

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:785

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:751

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:755
`audioUrl?`	`string`	Remote or blob URL to fetch and play.	packages/core/src/types.ts:753
`mimeType?`	`string`	MIME type of the audio payload.	packages/core/src/types.ts:757
`volume?`	`number`	Playback gain in `[0, 1]`.	packages/core/src/types.ts:759

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:57

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

Properties

Property	Type	Description	Defined in
`provider?`	`string`	Provider name when the failure originated in an adapter.	packages/core/src/errors.ts:59
`raw?`	`unknown`	Original thrown value or HTTP body, when available.	packages/core/src/errors.ts:63
`retryable?`	`boolean`	Override the default retryability for VoiceErrorCode.	packages/core/src/errors.ts:61

LLMGenerateInput

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

Input for LLMProvider.generate / LLMProvider.stream.

Properties

Property	Type	Description	Defined in
`maxTokens?`	`number`	Soft cap on completion tokens.	packages/core/src/types.ts:377
`messages`	`LLMMessage`[]	Chronological chat history for the model.	packages/core/src/types.ts:373
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter.	packages/core/src/types.ts:381
`responseFormat?`	`"text"` \| `"json"`	Prefer plain text or structured JSON when the model supports it.	packages/core/src/types.ts:379
`signal?`	`AbortSignal`	Cancels an in-flight provider request when this turn is superseded.	packages/core/src/types.ts:383
`system?`	`string`	Optional system instruction for this request.	packages/core/src/types.ts:371
`temperature?`	`number`	Sampling temperature; provider default when omitted.	packages/core/src/types.ts:375

LLMGenerateOutput

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

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:391
`raw?`	`unknown`	Raw provider payload for debugging.	packages/core/src/types.ts:395
`text`	`string`	Assistant reply text.	packages/core/src/types.ts:389
`usage?`	`LLMUsage`	Token usage when reported.	packages/core/src/types.ts:393

LLMMessage

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

One chat message forwarded to an LLMProvider.

Properties

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

LLMProvider

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

Text LLM used by the classic asr_llm_tts pipeline. 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:416

Methods

generate()

generate(input): Promise<LLMGenerateOutput>;

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

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:428

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:399

One chunk from LLMProvider.stream.

Properties

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

LLMUsage

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

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:361
`outputTokens?`	`number`	Completion / output tokens when the provider reports them.	packages/core/src/types.ts:363
`totalTokens?`	`number`	Total tokens when the provider reports a combined figure.	packages/core/src/types.ts:365

LoggerAdapter

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

Optional structured logger injected via RuntimeAdapter.logger.

Methods

debug()

debug(...args): void;

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

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:933

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:929

Informational lifecycle messages.

Parameters

Parameter	Type
…`args`	`unknown`[]

Returns

void

warn()

warn(...args): void;

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

Recoverable anomalies.

Parameters

Parameter	Type
…`args`	`unknown`[]

Returns

void

MockASROptions

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

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:30
`failWith?`	`NormalizedVoiceError`	When set, the next `sendAudio` triggers this error instead of a result.	packages/core/src/providers/mock.ts:32
`transcripts`	`string`[]	Scripted final transcripts, emitted one per `sendAudio` call.	packages/core/src/providers/mock.ts:28

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

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:114

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:123
`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:119
`usage?`	`LLMUsage`	Token usage returned on every `generate` / stream completion.	packages/core/src/providers/mock.ts:121

MockPronunciationOptions

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

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:243
`score?`	`number`	Overall / per-dimension score returned for every assessment. Default 80.	packages/core/src/providers/mock.ts:241

MockRuntime

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

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:196
`audioOutput`	`MockAudioOutput`	Controllable mock speaker.	`RuntimeAdapter`.`audioOutput`	-	packages/core/src/providers/mock-runtime.ts:198
`logger?`	`LoggerAdapter`	Optional logger; core uses it sparingly.	-	`RuntimeAdapter`.`logger`	packages/core/src/types.ts:951
`network?`	`NetworkAdapter`	Optional HTTP/WebSocket hooks for providers.	-	`RuntimeAdapter`.`network`	packages/core/src/types.ts:947
`storage?`	`RuntimeStorageAdapter`	Optional persistence for caches.	-	`RuntimeAdapter`.`storage`	packages/core/src/types.ts:949

MockRuntimeOptions

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

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:185
`output?`	`MockAudioOutputOptions`	Speaker mock options. See MockAudioOutputOptions.	packages/core/src/providers/mock-runtime.ts:187

MockTTSOptions

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

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:191
`failWith?`	`NormalizedVoiceError`	When set, `synthesize` rejects with this error.	packages/core/src/providers/mock.ts:193

NetworkAdapter

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

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

Methods

createWebSocket()

createWebSocket(url, protocols?): RuntimeWebSocket;

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

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:896

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:69

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
`code`	`VoiceErrorCode`	Stable application error code.	packages/core/src/types.ts:71
`message`	`string`	Human-readable message suitable for logs (not always UI-safe).	packages/core/src/types.ts:73
`provider?`	`string`	Provider name when the failure originated in an adapter.	packages/core/src/types.ts:75
`raw?`	`unknown`	Original thrown value or HTTP body, when available.	packages/core/src/types.ts:79
`retryable?`	`boolean`	Hint for UI retry; not enforced by the session.	packages/core/src/types.ts:77

PcmAudioStreamOptions

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

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:769
`encoding`	`"pcm_s16le"`	Always linear 16-bit PCM for incremental streams.	packages/core/src/types.ts:765
`sampleRate`	`number`	Sample rate of subsequent `write` payloads in Hz.	packages/core/src/types.ts:767
`volume?`	`number`	Playback gain in `[0, 1]`.	packages/core/src/types.ts:771

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:600

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:602
`durationMs?`	`number`	Spoken duration in milliseconds when known.	packages/core/src/types.ts:610
`language?`	`string`	BCP-47 language for scoring models.	packages/core/src/types.ts:608
`metadata?`	`Record`<`string`, `unknown`>	Opaque adapter metadata.	packages/core/src/types.ts:614
`referenceText?`	`string`	Expected reference sentence when scoring against a prompt.	packages/core/src/types.ts:606
`transcript`	`string`	Recognized or user-submitted spoken text.	packages/core/src/types.ts:604
`words?`	`ASRWord`[]	Optional word timings from ASR to align scoring.	packages/core/src/types.ts:612

PronunciationProvider

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

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:645

Methods

assess()

assess(input): Promise<PronunciationResult>;

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

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:618

Normalized scores from a PronunciationProvider.

Properties

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

ProviderProfile

Defined in: packages/core/src/provider-router.ts:23

Provider-id recipe for one product mode. String values are registry keys resolved by ProviderRegistry into concrete adapters — never vendor SDK imports.

Properties

Property	Type	Description	Defined in
`asr`	`string`	Registered ASR provider id.	packages/core/src/provider-router.ts:27
`llmConversation`	`string`	Registered LLM used for conversational turns.	packages/core/src/provider-router.ts:29
`llmScoring?`	`string`	Optional LLM used for scoring / reports; defaults to conversation LLM.	packages/core/src/provider-router.ts:31
`name`	`string`	Stable profile id (usually matches a ProviderProfileName).	packages/core/src/provider-router.ts:25
`pronunciation?`	`string`	Optional pronunciation / assessment provider id.	packages/core/src/provider-router.ts:35
`tts?`	`string`	Optional TTS provider id for the classic pipeline.	packages/core/src/provider-router.ts:33

ProviderRoutingContext

Defined in: packages/core/src/provider-router.ts:97

Inputs for resolveProfile. Prefer setting ProviderRoutingContext.region and ProviderRoutingContext.plan; latency/cost are forward-compatible knobs.

Properties

Property	Type	Description	Defined in
`costPreference?`	`"low"` \| `"balanced"` \| `"quality"`	Prefer lower cost when a future policy uses it.	packages/core/src/provider-router.ts:107
`feature?`	`ProviderFeature`	Feature being selected (optional; ignored by the default policy).	packages/core/src/provider-router.ts:103
`latencyPreference?`	`"low"` \| `"balanced"` \| `"quality"`	Prefer lower latency when a future policy uses it.	packages/core/src/provider-router.ts:105
`plan?`	`ProviderPlan`	Subscription tier.	packages/core/src/provider-router.ts:101
`region?`	`ProviderRegion`	User / deployment region.	packages/core/src/provider-router.ts:99

RegisteredProviders

Defined in: packages/core/src/provider-router.ts:123

Initial map of provider ids → instances for the ProviderRegistry constructor. Keys must match those used in ProviderProfile.

Properties

Property	Type	Description	Defined in
`asr?`	`Record`<`string`, `ASRProvider`>	ASR adapters keyed by profile `asr` id.	packages/core/src/provider-router.ts:125
`llm?`	`Record`<`string`, `LLMProvider`>	LLM adapters keyed by conversation / scoring ids.	packages/core/src/provider-router.ts:127
`pronunciation?`	`Record`<`string`, `PronunciationProvider`>	Pronunciation adapters keyed by profile `pronunciation` id.	packages/core/src/provider-router.ts:131
`tts?`	`Record`<`string`, `TTSProvider`>	TTS adapters keyed by profile `tts` id.	packages/core/src/provider-router.ts:129

ResolvedProviders

Defined in: packages/core/src/provider-router.ts:138

Concrete provider bundle produced by ProviderRegistry.resolve. Ready to pass into a import(‘./session’).VoiceSession config.

Properties

Property	Type	Description	Defined in
`asr`	`ASRProvider`	Live ASR for the classic pipeline.	packages/core/src/provider-router.ts:140
`llm`	`LLMProvider`	Conversational text LLM.	packages/core/src/provider-router.ts:142
`llmScoring`	`LLMProvider`	LLM used for scoring / reports (may alias ResolvedProviders.llm).	packages/core/src/provider-router.ts:144
`pronunciation?`	`PronunciationProvider`	Optional pronunciation assessor.	packages/core/src/provider-router.ts:148
`tts?`	`TTSProvider`	Optional TTS when synthesizing speech separately.	packages/core/src/provider-router.ts:146

RuntimeAdapter

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

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:943
`audioOutput`	`AudioOutputAdapter`	Speaker / playback side.	packages/core/src/types.ts:945
`logger?`	`LoggerAdapter`	Optional logger; core uses it sparingly.	packages/core/src/types.ts:951
`network?`	`NetworkAdapter`	Optional HTTP/WebSocket hooks for providers.	packages/core/src/types.ts:947
`storage?`	`RuntimeStorageAdapter`	Optional persistence for caches.	packages/core/src/types.ts:949

RuntimeStorageAdapter

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

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:912

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:921

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:917

Parameters

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

Returns

Promise<void>

RuntimeWebSocket

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

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:861

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:885

Subscribe to close.

Parameters

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

Returns

Unsubscribe function.

() => void

onError()

onError(cb): () => void;

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

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:873

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:867

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:854

Send a text or binary frame.

Parameters

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

Returns

void

TTSCapabilities

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

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:537
`languages`	`string`[]	BCP-47 language tags supported for synthesis.	packages/core/src/types.ts:539
`streaming`	`boolean`	Whether the provider can stream partial audio (future use).	packages/core/src/types.ts:533
`voices`	`TTSVoice`[]	Voices advertised by the adapter.	packages/core/src/types.ts:535

TTSInput

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

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:557
`format?`	`TTSFormat`	Preferred output container / codec.	packages/core/src/types.ts:555
`language?`	`string`	Preferred language for multilingual voices.	packages/core/src/types.ts:549
`metadata?`	`Record`<`string`, `unknown`>	Opaque metadata forwarded to the adapter.	packages/core/src/types.ts:559
`pitch?`	`number`	Pitch adjustment (provider-specific scale).	packages/core/src/types.ts:553
`speed?`	`number`	Speaking rate multiplier (provider-specific scale).	packages/core/src/types.ts:551
`text`	`string`	Text to speak.	packages/core/src/types.ts:545
`voice?`	`string`	Provider voice id / name.	packages/core/src/types.ts:547

TTSOutput

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

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:567
`audioUrl?`	`string`	Remote or blob URL for playback when buffering is inconvenient.	packages/core/src/types.ts:565
`cached?`	`boolean`	True when served from an adapter cache.	packages/core/src/types.ts:573
`durationMs?`	`number`	Estimated duration when known.	packages/core/src/types.ts:571
`mimeType`	`string`	MIME type of `audioUrl` / `audioBuffer`.	packages/core/src/types.ts:569
`raw?`	`unknown`	Raw provider payload for debugging.	packages/core/src/types.ts:575

TTSProvider

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

Text-to-speech adapter for the classic asr_llm_tts pipeline. Required when VoiceSessionConfig.pipeline is asr_llm_tts.

Properties

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

Methods

synthesize()

synthesize(input): Promise<TTSOutput>;

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

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:517

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:525
`id`	`string`	Stable voice id passed to TTSInput.voice.	packages/core/src/types.ts:519
`language`	`string`	Primary BCP-47 language for this voice.	packages/core/src/types.ts:523
`name`	`string`	Human-readable display name for UI pickers.	packages/core/src/types.ts:521
`style?`	`string`[]	Optional style tags (e.g. `cheerful`, `news`).	packages/core/src/types.ts:527

TurnDetectionConfig

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

Voice-activity and endpointing 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 cap on a single user turn length.	packages/core/src/types.ts:1035
`minSpeechMs?`	`number`	Minimum voiced time before speech is considered started.	packages/core/src/types.ts:1031
`silenceTimeoutMs?`	`number`	Quiet time after speech before the turn is closed.	packages/core/src/types.ts:1033
`strategy`	`TurnDetectionStrategy`	How end-of-utterance is decided.	packages/core/src/types.ts:1029
`volumeThreshold?`	`number`	RMS threshold when using volume-based strategies (≈0–1).	packages/core/src/types.ts:1037

VoiceAgentPlugin

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

Optional higher-level dialog controller (opening line, next line, finish rule). When set, the session may call these instead of / in addition to a raw LLM.

Methods

generateNextAssistantMessage()

generateNextAssistantMessage(input): Promise<string>;

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

Produce the next assistant line after a completed user turn.

Parameters

Parameter	Type	Description
`input`	`AgentTurnInput`	Full history plus the latest user text.

Returns

Promise<string>

generateReport()?

optional generateReport(input): Promise<unknown>;

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

Optional end-of-session artifact (scores, summary, etc.).

Parameters

Parameter	Type	Description
`input`	`AgentSessionInput`	Full turn history.

Returns

Promise<unknown>

getInitialAssistantMessage()

getInitialAssistantMessage(): Promise<string>;

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

Spoken (or displayed) opening line after VoiceSession.start.

Returns

Promise<string>

shouldFinishSession()

shouldFinishSession(input): boolean;

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

Return true to end the session after the latest turn.

Parameters

Parameter	Type	Description
`input`	`AgentSessionInput`	Full turn history.

Returns

boolean

VoiceSessionConfig

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

Top-level configuration for createVoiceSession / VoiceSession. Create at the application composition root; keep provider credentials out of UI code.

Properties

Property	Type	Description	Defined in
`agent?`	`VoiceAgentPlugin`	Optional higher-level dialog plugin (opening line, next line, finish rule).	packages/core/src/types.ts:1129
`asrPartial?`	`boolean`	Emit provisional `asr_partial` results. Defaults to true. Disabling this does not affect the authoritative `asr_final` transcript.	packages/core/src/types.ts:1096
`audioLlmMaxTokens?`	`number`	Cap native audio LLM output tokens (audio + transcript share this budget). Omit to use the model’s default maximum — required for long-form speech.	packages/core/src/types.ts:1103
`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:1111
`audioLlmSystemPrompt?`	`string`	Optional system instruction forwarded to a native audio LLM.	packages/core/src/types.ts:1098
`generateId?`	() => `string`	Override id generation (useful for deterministic tests).	packages/core/src/types.ts:1141
`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:1137
`language?`	`string`	Preferred ASR language; omit to let compatible providers auto-detect.	packages/core/src/types.ts:1113
`metadata?`	`Record`<`string`, `unknown`>	Opaque app metadata (not interpreted by core).	packages/core/src/types.ts:1145
`mode`	`VoiceSessionMode`	Duplex / PTT mode. See VoiceSessionMode.	packages/core/src/types.ts:1089
`now?`	() => `number`	Override the clock (useful for deterministic tests).	packages/core/src/types.ts:1143
`pipeline?`	`"asr_llm_tts"` \| `"audio_llm"`	Defaults to the classic ASR -> LLM -> TTS cascade.	packages/core/src/types.ts:1091
`policy?`	`VoiceSessionPolicy`	Session-level timers and barge-in recovery knobs.	packages/core/src/types.ts:1139
`providers`	{ `asr`: `ASRProvider`; `audioLlm?`: `AudioLLMProvider`; `llm`: `LLMProvider`; `pronunciation?`: `PronunciationProvider`; `tts?`: `TTSProvider`; }	-	packages/core/src/types.ts:1116
`providers.asr`	`ASRProvider`	Speech-to-text provider (required for live captions / classic pipeline).	packages/core/src/types.ts:1118
`providers.audioLlm?`	`AudioLLMProvider`	Required when `pipeline` is `audio_llm`; ASR supplies captions while request timing follows VoiceSessionConfig.audioLlmStartTiming.	packages/core/src/types.ts:1124
`providers.llm`	`LLMProvider`	Text LLM used by `asr_llm_tts` (and optional agents).	packages/core/src/types.ts:1120
`providers.pronunciation?`	`PronunciationProvider`	Optional pronunciation scoring after a user turn.	packages/core/src/types.ts:1126
`providers.tts?`	`TTSProvider`	Text-to-speech; required when `pipeline` is `asr_llm_tts`.	packages/core/src/types.ts:1122
`runtime`	`RuntimeAdapter`	Platform audio (and optional network/storage/logger) adapter.	packages/core/src/types.ts:1115
`turnDetection?`	`TurnDetectionConfig`	VAD / endpointing while listening for the user.	packages/core/src/types.ts:1131

VoiceSessionPolicy

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

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:1068
`autoStartListening?`	`boolean`	After `start()`, automatically enter listening. Defaults to true.	packages/core/src/types.ts:1066
`falseInterruptionSilenceMs?`	`number`	Silence after a tentative pause before playback is resumed as a false interruption.	packages/core/src/types.ts:1070
`falseInterruptionTimeoutMs?`	`number`	Maximum time to keep playback tentatively paused without confirming speech.	packages/core/src/types.ts:1072
`interruptionCooldownMs?`	`number`	Ignore new barge-in candidates shortly after resuming a false interruption.	packages/core/src/types.ts:1076
`interruptionTailIgnoreMs?`	`number`	Ignore microphone energy right after a tentative pause while speaker echo decays. Defaults to 200 ms.	packages/core/src/types.ts:1074
`maxSessionDurationMs?`	`number`	Force-finish the session after this wall-clock duration.	packages/core/src/types.ts:1064
`maxTurnDurationMs?`	`number`	Hard cap on one user turn.	packages/core/src/types.ts:1062
`postPlaybackVadRearmMs?`	`number`	Maximum time to wait for a quiet microphone baseline after assistant playback. Defaults to 300 ms.	packages/core/src/types.ts:1078
`silenceTimeoutMs?`	`number`	Quiet time that ends a listening turn when no other detector wins.	packages/core/src/types.ts:1060

VoiceTurn

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

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:101
`durationMs?`	`number`	Convenience duration (`endedAt - startedAt`) when known.	packages/core/src/types.ts:107
`endedAt?`	`number`	Epoch millis when the turn ended.	packages/core/src/types.ts:105
`id`	`string`	Stable turn id shared with streaming events.	packages/core/src/types.ts:95
`metadata?`	`Record`<`string`, `unknown`>	Opaque app metadata attached to the turn.	packages/core/src/types.ts:109
`role`	`TurnRole`	Who spoke this turn.	packages/core/src/types.ts:97
`startedAt`	`number`	Epoch millis when the turn started.	packages/core/src/types.ts:103
`text`	`string`	Final transcript or assistant text for the turn.	packages/core/src/types.ts:99

VoiceUsageSnapshot

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

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:124
`assistantSpeechChars`	`number`	Assistant spoken character count (approx).	packages/core/src/types.ts:122
`llmInputTokens?`	`number`	Accumulated LLM prompt tokens when providers report usage.	packages/core/src/types.ts:128
`llmOutputTokens?`	`number`	Accumulated LLM completion tokens when providers report usage.	packages/core/src/types.ts:130
`providerCosts?`	`Record`<`string`, `number`>	Optional per-provider cost estimates in billable units.	packages/core/src/types.ts:132
`sessionDurationMs`	`number`	Wall time since VoiceSession.start.	packages/core/src/types.ts:118
`ttsChars`	`number`	Characters sent to TTS.	packages/core/src/types.ts:126
`userSpeechMs`	`number`	Accumulated user speech duration when runtimes report chunk durations.	packages/core/src/types.ts:120

Type Aliases

AudioEncoding

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

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

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:439

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

ProviderFeature

type ProviderFeature = "conversation" | "transcription" | "scoring" | "pronunciation";

Defined in: packages/core/src/provider-router.ts:86

Feature being routed (reserved for finer policy; resolveProfile currently keys primarily on region / plan).

ProviderPlan

type ProviderPlan = "free" | "basic" | "pro";

Defined in: packages/core/src/provider-router.ts:81

Commercial plan hint for resolveProfile.

ProviderProfileName

type ProviderProfileName = "global_budget" | "global_pro" | "china_fallback" | "developer_test";

Defined in: packages/core/src/provider-router.ts:13

Built-in named stacks in providerProfiles. Pass to ProviderRegistry.resolve or resolveProfile.

ProviderRegion

type ProviderRegion = "global" | "china" | "unknown";

Defined in: packages/core/src/provider-router.ts:79

Deployment region hint for resolveProfile.

TTSFormat

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

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

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

TurnDetectionStrategy

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

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

How end-of-utterance is decided while listening:

volume — local RMS VAD (TurnDetectionConfig.volumeThreshold)
asr_endpointing — trust provider utterance-end signals
manual — caller drives VoiceSession.endUserTurn
hybrid — combine ASR speech confirmation / endpointing with local silence

TurnDetectorEvent

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

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

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:87

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.

VoiceSessionEventMap

type VoiceSessionEventMap = {
  asr_final: {
     confidence?: number;
     durationMs?: number;
     text: string;
     turnId: string;
  };
  asr_partial: {
     confidence?: number;
     text: 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;
  };
};

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

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:158
`asr_final.confidence?`	`number`	-	packages/core/src/types.ts:161
`asr_final.durationMs?`	`number`	-	packages/core/src/types.ts:162
`asr_final.text`	`string`	-	packages/core/src/types.ts:159
`asr_final.turnId`	`string`	-	packages/core/src/types.ts:160
`asr_partial`	{ `confidence?`: `number`; `text`: `string`; `turnId`: `string`; }	Provisional ASR caption; upsert by `turnId`.	packages/core/src/types.ts:151
`asr_partial.confidence?`	`number`	-	packages/core/src/types.ts:155
`asr_partial.text`	`string`	Accumulated provisional transcript.	packages/core/src/types.ts:153
`asr_partial.turnId`	`string`	-	packages/core/src/types.ts:154
`assistant_audio_end`	{ `turnId`: `string`; }	Assistant audio playback ended (completed or interrupted).	packages/core/src/types.ts:187
`assistant_audio_end.turnId`	`string`	-	packages/core/src/types.ts:188
`assistant_audio_start`	{ `turnId`: `string`; }	Assistant audio playback began for this turn.	packages/core/src/types.ts:183
`assistant_audio_start.turnId`	`string`	-	packages/core/src/types.ts:184
`assistant_text`	{ `text`: `string`; `turnId`: `string`; }	Final assistant text for the turn (may normalize streaming text).	packages/core/src/types.ts:170
`assistant_text.text`	`string`	-	packages/core/src/types.ts:171
`assistant_text.turnId`	`string`	-	packages/core/src/types.ts:172
`assistant_text_delta`	{ `delta`: `string`; `text`: `string`; `turnId`: `string`; }	Incremental assistant transcript emitted before `assistant_text`.	packages/core/src/types.ts:175
`assistant_text_delta.delta`	`string`	Newly received text fragment.	packages/core/src/types.ts:177
`assistant_text_delta.text`	`string`	Complete assistant text accumulated for this turn so far.	packages/core/src/types.ts:179
`assistant_text_delta.turnId`	`string`	-	packages/core/src/types.ts:180
`error`	`NormalizedVoiceError`	Normalized failure; see NormalizedVoiceError.	packages/core/src/types.ts:201
`finished`	{ `turns`: `VoiceTurn`[]; }	Session completed gracefully; turns are the full history.	packages/core/src/types.ts:197
`finished.turns`	`VoiceTurn`[]	-	packages/core/src/types.ts:198
`statechange`	{ `from`: `VoiceSessionState`; `reason?`: `string`; `to`: `VoiceSessionState`; }	FSM transition with optional reason string.	packages/core/src/types.ts:145
`statechange.from`	`VoiceSessionState`	-	packages/core/src/types.ts:146
`statechange.reason?`	`string`	-	packages/core/src/types.ts:148
`statechange.to`	`VoiceSessionState`	-	packages/core/src/types.ts:147
`turn`	{ `turn`: `VoiceTurn`; }	A committed VoiceTurn was added to history.	packages/core/src/types.ts:191
`turn.turn`	`VoiceTurn`	-	packages/core/src/types.ts:192
`usage`	`VoiceUsageSnapshot`	Latest usage meters.	packages/core/src/types.ts:195
`user_audio_end`	{ `at`: `number`; `turnId`: `string`; }	VAD/manual boundary used as the response-latency start point.	packages/core/src/types.ts:165
`user_audio_end.at`	`number`	-	packages/core/src/types.ts:167
`user_audio_end.turnId`	`string`	-	packages/core/src/types.ts:166

VoiceSessionMode

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

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

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: Required<TurnDetectionConfig>;

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

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

providerProfiles

const providerProfiles: {
  china_fallback: {
     asr: string;
     llmConversation: string;
     llmScoring: string;
     name: string;
     pronunciation: string;
     tts: string;
  };
  developer_test: {
     asr: string;
     llmConversation: string;
     llmScoring: string;
     name: string;
     pronunciation: string;
     tts: string;
  };
  global_budget: {
     asr: string;
     llmConversation: string;
     llmScoring: string;
     name: string;
     pronunciation: string;
     tts: string;
  };
  global_pro: {
     asr: string;
     llmConversation: string;
     llmScoring: string;
     name: string;
     pronunciation: string;
     tts: string;
  };
};

Defined in: packages/core/src/provider-router.ts:43

Built-in profiles. The string values are provider ids that a ProviderRegistry resolves into concrete provider instances — the router never imports a vendor SDK itself.

Type Declaration

Name	Type	Default value	Defined in
`china_fallback`	{ `asr`: `string`; `llmConversation`: `string`; `llmScoring`: `string`; `name`: `string`; `pronunciation`: `string`; `tts`: `string`; }	-	packages/core/src/provider-router.ts:60
`china_fallback.asr`	`string`	`'xfyun_streaming'`	packages/core/src/provider-router.ts:62
`china_fallback.llmConversation`	`string`	`'deepseek_or_qwen'`	packages/core/src/provider-router.ts:63
`china_fallback.llmScoring`	`string`	`'deepseek_or_qwen'`	packages/core/src/provider-router.ts:64
`china_fallback.name`	`string`	`'china_fallback'`	packages/core/src/provider-router.ts:61
`china_fallback.pronunciation`	`string`	`'xfyun_or_approximation'`	packages/core/src/provider-router.ts:66
`china_fallback.tts`	`string`	`'xfyun_tts'`	packages/core/src/provider-router.ts:65
`developer_test`	{ `asr`: `string`; `llmConversation`: `string`; `llmScoring`: `string`; `name`: `string`; `pronunciation`: `string`; `tts`: `string`; }	-	packages/core/src/provider-router.ts:68
`developer_test.asr`	`string`	`'mock_asr'`	packages/core/src/provider-router.ts:70
`developer_test.llmConversation`	`string`	`'mock_llm'`	packages/core/src/provider-router.ts:71
`developer_test.llmScoring`	`string`	`'mock_llm'`	packages/core/src/provider-router.ts:72
`developer_test.name`	`string`	`'developer_test'`	packages/core/src/provider-router.ts:69
`developer_test.pronunciation`	`string`	`'mock_pronunciation'`	packages/core/src/provider-router.ts:74
`developer_test.tts`	`string`	`'mock_tts'`	packages/core/src/provider-router.ts:73
`global_budget`	{ `asr`: `string`; `llmConversation`: `string`; `llmScoring`: `string`; `name`: `string`; `pronunciation`: `string`; `tts`: `string`; }	-	packages/core/src/provider-router.ts:44
`global_budget.asr`	`string`	`'elevenlabs_scribe_realtime'`	packages/core/src/provider-router.ts:46
`global_budget.llmConversation`	`string`	`'openrouter_gemini_flash_lite'`	packages/core/src/provider-router.ts:47
`global_budget.llmScoring`	`string`	`'openrouter_gemini_flash'`	packages/core/src/provider-router.ts:48
`global_budget.name`	`string`	`'global_budget'`	packages/core/src/provider-router.ts:45
`global_budget.pronunciation`	`string`	`'approximation'`	packages/core/src/provider-router.ts:50
`global_budget.tts`	`string`	`'azure_neural_tts'`	packages/core/src/provider-router.ts:49
`global_pro`	{ `asr`: `string`; `llmConversation`: `string`; `llmScoring`: `string`; `name`: `string`; `pronunciation`: `string`; `tts`: `string`; }	-	packages/core/src/provider-router.ts:52
`global_pro.asr`	`string`	`'deepgram_nova_streaming'`	packages/core/src/provider-router.ts:54
`global_pro.llmConversation`	`string`	`'openrouter_gemini_flash'`	packages/core/src/provider-router.ts:55
`global_pro.llmScoring`	`string`	`'openai_or_claude'`	packages/core/src/provider-router.ts:56
`global_pro.name`	`string`	`'global_pro'`	packages/core/src/provider-router.ts:53
`global_pro.pronunciation`	`string`	`'azure_pronunciation'`	packages/core/src/provider-router.ts:58
`global_pro.tts`	`string`	`'elevenlabs_flash'`	packages/core/src/provider-router.ts:57

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:42

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.

createMockLLM()

function createMockLLM(options?): LLMProvider;

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

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:254

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:207

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:204

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.

createVoiceError()

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

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

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 provider, retryable, and raw. See CreateVoiceErrorOptions.

Returns

NormalizedVoiceError

A plain NormalizedVoiceError (not a thrown Error).

createVoiceSession()

function createVoiceSession(config): VoiceSession;

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

Create a VoiceSession from a fully wired VoiceSessionConfig.

Parameters

Parameter	Type	Description
`config`	`VoiceSessionConfig`	Runtime adapter, providers, mode/pipeline, 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?): NormalizedVoiceError;

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

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`.

Returns

NormalizedVoiceError

A NormalizedVoiceError suitable for session error events.

resolveProfile()

function resolveProfile(ctx?): ProviderProfileName;

Defined in: packages/core/src/provider-router.ts:111

Default policy: China routes to the fallback profile, Pro plans to pro.

Parameters

Parameter	Type
`ctx`	`ProviderRoutingContext`

Returns

ProviderProfileName

resolveTurnDetection()

function resolveTurnDetection(config?): Required<TurnDetectionConfig>;

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

Merge a partial TurnDetectionConfig with DEFAULT_TURN_DETECTION.

Parameters

Parameter	Type	Description
`config?`	`TurnDetectionConfig`	Optional overrides from import(‘./types’).VoiceSessionConfig.turnDetection.

Returns

Required<TurnDetectionConfig>

A fully populated config object (no missing fields).