@ottervoice/runtime-node

Documentation

---

Documentation / @ottervoice/runtime-node

@ottervoice/runtime-node

Node.js runtime adapter for OtterVoice, with network, stream-based audio I/O, and console logging adapters.

Install

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

Usage

import { createNodeRuntime } from '@ottervoice/runtime-node';

const runtime = createNodeRuntime();

Pass the returned runtime to your OtterVoice session configuration. Every adapter can be overridden for custom audio, network, and logging integration.

Links

Documentation · GitHub

License

MIT

Classes

ConsoleLogger

Defined in: runtime-node/src/logger.ts:15

LoggerAdapter that forwards to console (or an injected console).

Implements

• LoggerAdapter

Constructors

Constructor

new ConsoleLogger(out?): ConsoleLogger;

Defined in: runtime-node/src/logger.ts:16

Parameters

Parameter	Type	Default value
out	ConsoleLike	console

Returns

ConsoleLogger

Methods

debug()

debug(...args): void;

Defined in: runtime-node/src/logger.ts:18

Verbose diagnostics (disabled in production by default).

Parameters

Parameter	Type
…args	unknown[]

Returns

void

Implementation of

LoggerAdapter.debug

error()

error(...args): void;

Defined in: runtime-node/src/logger.ts:30

Failures that typically surface as session errors.

Parameters

Parameter	Type
…args	unknown[]

Returns

void

Implementation of

LoggerAdapter.error

info()

info(...args): void;

Defined in: runtime-node/src/logger.ts:22

Informational lifecycle messages.

Parameters

Parameter	Type
…args	unknown[]

Returns

void

Implementation of

LoggerAdapter.info

warn()

warn(...args): void;

Defined in: runtime-node/src/logger.ts:26

Recoverable anomalies.

Parameters

Parameter	Type
…args	unknown[]

Returns

void

Implementation of

LoggerAdapter.warn

---

NodeAudioInput

Defined in: runtime-node/src/audio.ts:43

Reads audio bytes from an async iterable (a mic subprocess, a file stream, …) and emits AudioChunks. Node has no permission model, so requestPermission always resolves true.

Implements

• AudioInputAdapter

Constructors

Constructor

new NodeAudioInput(options?): NodeAudioInput;

Defined in: runtime-node/src/audio.ts:52

Parameters

Parameter	Type
options	NodeAudioInputOptions

Returns

NodeAudioInput

Properties

Property	Type	Description	Defined in
whenDrained	Promise<void>	Resolves when the source has been fully consumed (or stopped).	runtime-node/src/audio.ts:50

Methods

onChunk()

onChunk(cb): () => void;

Defined in: runtime-node/src/audio.ts:107

Subscribe to encoded / PCM chunks.

Parameters

Parameter	Type
cb	(chunk) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onChunk

onError()

onError(cb): () => void;

Defined in: runtime-node/src/audio.ts:112

Subscribe to capture failures.

Parameters

Parameter	Type
cb	(error) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onError

pause()

pause(): Promise<void>;

Defined in: runtime-node/src/audio.ts:99

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

Returns

Promise<void>

Implementation of

AudioInputAdapter.pause

requestPermission()

requestPermission(): Promise<boolean>;

Defined in: runtime-node/src/audio.ts:56

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

Returns

Promise<boolean>

Implementation of

AudioInputAdapter.requestPermission

resume()

resume(): Promise<void>;

Defined in: runtime-node/src/audio.ts:103

Resume after pause.

Returns

Promise<void>

Implementation of

AudioInputAdapter.resume

start()

start(startOptions?): Promise<void>;

Defined in: runtime-node/src/audio.ts:60

Begin capture.

Parameters

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

Returns

Promise<void>

Implementation of

AudioInputAdapter.start

stop()

stop(): Promise<void>;

Defined in: runtime-node/src/audio.ts:95

Stop capture and release resources tied to the current start.

Returns

Promise<void>

Implementation of

AudioInputAdapter.stop

---

NodeAudioOutput

Defined in: runtime-node/src/audio.ts:135

Node has no built-in UI playback. By default this records what would have played; supply a sink to actually emit audio (file/speaker subprocess).

Implements

• AudioOutputAdapter

Constructors

Constructor

new NodeAudioOutput(options?): NodeAudioOutput;

Defined in: runtime-node/src/audio.ts:141

Parameters

Parameter	Type
options	NodeAudioOutputOptions

Returns

NodeAudioOutput

Properties

Property	Type	Default value	Defined in
played	AudioPlaybackInput[]	[]	runtime-node/src/audio.ts:139

Methods

onEnd()

onEnd(cb): () => void;

Defined in: runtime-node/src/audio.ts:167

Subscribe to playback end (natural finish or stop).

Parameters

Parameter	Type
cb	() => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onEnd

onError()

onError(cb): () => void;

Defined in: runtime-node/src/audio.ts:172

Subscribe to playback failures.

Parameters

Parameter	Type
cb	(error) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onError

onStart()

onStart(cb): () => void;

Defined in: runtime-node/src/audio.ts:162

Subscribe to playback start.

Parameters

Parameter	Type
cb	() => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onStart

play()

play(input): Promise<void>;

Defined in: runtime-node/src/audio.ts:143

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

stop()

stop(): Promise<void>;

Defined in: runtime-node/src/audio.ts:158

Stop current playback and cancel any open PCM stream.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.stop

---

NodeNetworkAdapter

Defined in: runtime-node/src/network.ts:99

NetworkAdapter backed by global (or injected) fetch/WebSocket.

Implements

• NetworkAdapter

Constructors

Constructor

new NodeNetworkAdapter(options?): NodeNetworkAdapter;

Defined in: runtime-node/src/network.ts:103

Parameters

Parameter	Type
options	NodeNetworkOptions

Returns

NodeNetworkAdapter

Methods

createWebSocket()

createWebSocket(url, protocols?): RuntimeWebSocket;

Defined in: runtime-node/src/network.ts:112

Open a WebSocket for streaming providers.

Parameters

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

Returns

RuntimeWebSocket

Implementation of

NetworkAdapter.createWebSocket

fetch()

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

Defined in: runtime-node/src/network.ts:108

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>

Implementation of

NetworkAdapter.fetch

---

NodeRuntimeWebSocket

Defined in: runtime-node/src/network.ts:49

Adapts a WebSocketLike to the core RuntimeWebSocket contract.

Implements

• RuntimeWebSocket

Constructors

Constructor

new NodeRuntimeWebSocket(ws): NodeRuntimeWebSocket;

Defined in: runtime-node/src/network.ts:50

Parameters

Parameter	Type
ws	WebSocketLike

Returns

NodeRuntimeWebSocket

Methods

close()

close(code?, reason?): void;

Defined in: runtime-node/src/network.ts:58

Close the socket.

Parameters

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

Returns

void

Implementation of

RuntimeWebSocket.close

onClose()

onClose(cb): () => void;

Defined in: runtime-node/src/network.ts:80

Subscribe to close.

Parameters

Parameter	Type
cb	() => void

Returns

Unsubscribe function.

() => void

Implementation of

RuntimeWebSocket.onClose

onError()

onError(cb): () => void;

Defined in: runtime-node/src/network.ts:74

Subscribe to socket-level errors.

Parameters

Parameter	Type
cb	(error) => void

Returns

Unsubscribe function.

() => void

Implementation of

RuntimeWebSocket.onError

onMessage()

onMessage(cb): () => void;

Defined in: runtime-node/src/network.ts:68

Subscribe to inbound frames.

Parameters

Parameter	Type
cb	(data) => void

Returns

Unsubscribe function.

() => void

Implementation of

RuntimeWebSocket.onMessage

onOpen()

onOpen(cb): () => void;

Defined in: runtime-node/src/network.ts:62

Subscribe to the open event.

Parameters

Parameter	Type
cb	() => void

Returns

Unsubscribe function.

() => void

Implementation of

RuntimeWebSocket.onOpen

send()

send(data): void;

Defined in: runtime-node/src/network.ts:54

Send a text or binary frame.

Parameters

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

Returns

void

Implementation of

RuntimeWebSocket.send

Interfaces

ConsoleLike

Defined in: runtime-node/src/logger.ts:7

Minimal console surface accepted by ConsoleLogger and NodeRuntimeOptions.logger.

Methods

debug()

debug(...args): void;

Defined in: runtime-node/src/logger.ts:8

Parameters

Parameter	Type
…args	unknown[]

Returns

void

error()

error(...args): void;

Defined in: runtime-node/src/logger.ts:11

Parameters

Parameter	Type
…args	unknown[]

Returns

void

info()

info(...args): void;

Defined in: runtime-node/src/logger.ts:9

Parameters

Parameter	Type
…args	unknown[]

Returns

void

warn()

warn(...args): void;

Defined in: runtime-node/src/logger.ts:10

Parameters

Parameter	Type
…args	unknown[]

Returns

void

---

NodeAudioInputOptions

Defined in: runtime-node/src/audio.ts:24

Options for NodeAudioInput. Pass a NodeAudioInputOptions.source to stream bytes from a subprocess or file; omit it for a no-op / caller-driven input under createNodeRuntime.

Properties

Property	Type	Description	Defined in
encoding?	string	Default encoding stamped on chunks when start does not override.	runtime-node/src/audio.ts:35
now?	() => number	Override clock used for AudioChunk.timestamp (tests).	runtime-node/src/audio.ts:31
sampleRate?	number	Default sample rate stamped on chunks when start does not override.	runtime-node/src/audio.ts:33
source?	AsyncIterable<ArrayBuffer | Uint8Array<ArrayBufferLike>, any, any>	The PCM/byte source — e.g. a child process stdout exposed as an async iterable. When omitted, the input produces nothing (caller-driven).	runtime-node/src/audio.ts:29

---

NodeAudioOutputOptions

Defined in: runtime-node/src/audio.ts:123

Options for NodeAudioOutput. Supply a NodeAudioOutputOptions.sink to emit audio; otherwise played inputs accumulate in NodeAudioOutput.played for inspection.

Properties

Property	Type	Description	Defined in
sink?	(input) => void | Promise<void>	Where to send synthesized audio — write a file, pipe to a speaker process, etc. When omitted, audio is collected in NodeAudioOutput.played.	runtime-node/src/audio.ts:128

---

NodeNetworkOptions

Defined in: runtime-node/src/network.ts:91

Injected HTTP / WebSocket constructors for NodeNetworkAdapter. Defaults to globalThis.fetch and globalThis.WebSocket when omitted.

Properties

Property	Type	Description	Defined in
fetch?	FetchLike	Override fetch (defaults to the global).	runtime-node/src/network.ts:93
webSocket?	WebSocketCtor	Override the WebSocket constructor (defaults to the global).	runtime-node/src/network.ts:95

---

NodeRuntime

Defined in: runtime-node/src/index.ts:36

Node.js RuntimeAdapter returned by createNodeRuntime. Includes audio adapters plus a NodeNetworkAdapter for providers that need explicit fetch / WebSocket hooks.

Extends

• RuntimeAdapter

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
audioInput	NodeAudioInput	Byte-source microphone (async iterable or caller-driven).	RuntimeAdapter.audioInput	-	runtime-node/src/index.ts:38
audioOutput	NodeAudioOutput	Sink or in-memory playback recorder.	RuntimeAdapter.audioOutput	-	runtime-node/src/index.ts:40
logger?	LoggerAdapter	Optional logger; core uses it sparingly.	-	RuntimeAdapter.logger	core/dist/types.d.ts:853
network	NodeNetworkAdapter	HTTP / WebSocket adapter for providers.	RuntimeAdapter.network	-	runtime-node/src/index.ts:42
storage?	RuntimeStorageAdapter	Optional persistence for caches.	-	RuntimeAdapter.storage	core/dist/types.d.ts:851

---

NodeRuntimeOptions

Defined in: runtime-node/src/index.ts:20

Optional overrides for createNodeRuntime. Use when piping a subprocess mic, writing audio to a sink, stubbing fetch/WebSocket, or redirecting / disabling the console logger.

Properties

Property	Type	Description	Defined in
audioInput?	NodeAudioInputOptions	Optional overrides for the default in-memory / stdin-style audio input.	runtime-node/src/index.ts:22
audioOutput?	NodeAudioOutputOptions	Optional overrides for the default console/file audio output.	runtime-node/src/index.ts:24
logger?	| false | ConsoleLike	Provide false to omit the logger, or a console to redirect it.	runtime-node/src/index.ts:28
network?	NodeNetworkOptions	Optional overrides for fetch / WebSocket.	runtime-node/src/index.ts:26

---

WebSocketLike

Defined in: runtime-node/src/network.ts:4

Minimal surface of a browser/Bun/ws WebSocket the wrapper relies on.

Properties

Property	Type	Description	Defined in
binaryType?	string	Prefer 'arraybuffer' when the peer sends binary frames.	runtime-node/src/network.ts:6

Methods

addEventListener()

addEventListener(type, listener): void;

Defined in: runtime-node/src/network.ts:12

Subscribe to socket events (open / message / error / close).

Parameters

Parameter	Type
type	string
listener	(event) => void

Returns

void

close()

close(code?, reason?): void;

Defined in: runtime-node/src/network.ts:10

Close the socket; optional close code and reason.

Parameters

Parameter	Type
code?	number
reason?	string

Returns

void

removeEventListener()

removeEventListener(type, listener): void;

Defined in: runtime-node/src/network.ts:14

Unsubscribe a listener previously added with WebSocketLike.addEventListener.

Parameters

Parameter	Type
type	string
listener	(event) => void

Returns

void

send()

send(data): void;

Defined in: runtime-node/src/network.ts:8

Send a text or binary frame to the peer.

Parameters

Parameter	Type
data	string | ArrayBufferLike | ArrayBufferView<ArrayBufferLike>

Returns

void

Type Aliases

FetchLike

type FetchLike = (input, init?) => Promise<Response>;

Defined in: runtime-node/src/network.ts:24

fetch-compatible HTTP entry point used by NodeNetworkAdapter.

Parameters

Parameter	Type
input	RequestInfo | URL
init?	RequestInit

Returns

Promise<Response>

---

WebSocketCtor

type WebSocketCtor = (url, protocols?) => WebSocketLike;

Defined in: runtime-node/src/network.ts:18

Constructor for WebSocketLike (global WebSocket or ws).

Parameters

Parameter	Type
url	string
protocols?	string | string[]

Returns

WebSocketLike

Functions

createNodeRuntime()

function createNodeRuntime(options?): NodeRuntime;

Defined in: runtime-node/src/index.ts:50

Assemble a Node.js RuntimeAdapter.

Parameters

Parameter	Type	Description
options	NodeRuntimeOptions	Optional audio, network, and logger overrides. See NodeRuntimeOptions.

Returns

NodeRuntime

---

normalizeWsData()

function normalizeWsData(data): string | ArrayBuffer;

Defined in: runtime-node/src/network.ts:35

Normalize a WebSocket message event’s data to string | ArrayBuffer.

Parameters

Parameter	Type	Description
data	unknown	Raw MessageEvent.data (string, ArrayBuffer, or TypedArray view).

Returns

string | ArrayBuffer

A copy suitable for RuntimeWebSocket callbacks.