@ottervoice/runtime-react-native

Documentation

---

Documentation / @ottervoice/runtime-react-native

@ottervoice/runtime-react-native

React Native and Expo runtime adapter for OtterVoice recording and gapless PCM playback.

Install

npm install @ottervoice/core @ottervoice/runtime-react-native

Usage

import { createExpoRuntime } from '@ottervoice/runtime-react-native';

const runtime = createExpoRuntime({
  input: audioInputBindings,
  output: audioOutputBindings,
});

Native capture and playback primitives are injected so the runtime has no hard dependency on a particular Expo audio library. See the repository’s examples/react-native-expo app for a complete integration.

Links

Documentation · React Native example · GitHub

License

MIT

Classes

ExpoAudioInput

Defined in: runtime-react-native/src/audio-input.ts:134

Expo microphone capture with two modes:

• Expo SDK 57 native PCM streaming: continuous RMS/VAD plus a complete WAV emitted at turn end. Encoded capture can be suspended during assistant playback while the volume stream stays active for barge-in.
• Legacy file recording: one recorded-file chunk per start/stop cycle.

Implements

• AudioInputAdapter

Constructors

Constructor

new ExpoAudioInput(options): ExpoAudioInput;

Defined in: runtime-react-native/src/audio-input.ts:147

Parameters

Parameter	Type
options	ExpoAudioInputOptions

Returns

ExpoAudioInput

Methods

onChunk()

onChunk(cb): () => void;

Defined in: runtime-react-native/src/audio-input.ts:281

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-react-native/src/audio-input.ts:291

Subscribe to capture failures.

Parameters

Parameter	Type
cb	(error) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onError

onVolume()

onVolume(cb): () => void;

Defined in: runtime-react-native/src/audio-input.ts:286

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

Parameters

Parameter	Type
cb	(level) => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioInputAdapter.onVolume

pause()

pause(): Promise<void>;

Defined in: runtime-react-native/src/audio-input.ts:269

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

Returns

Promise<void>

Implementation of

AudioInputAdapter.pause

requestPermission()

requestPermission(): Promise<boolean>;

Defined in: runtime-react-native/src/audio-input.ts:151

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-react-native/src/audio-input.ts:273

Resume after pause.

Returns

Promise<void>

Implementation of

AudioInputAdapter.resume

resumeCapture()

resumeCapture(): Promise<void>;

Defined in: runtime-react-native/src/audio-input.ts:265

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

Returns

Promise<void>

Implementation of

AudioInputAdapter.resumeCapture

start()

start(options?): Promise<void>;

Defined in: runtime-react-native/src/audio-input.ts:155

Begin capture.

Parameters

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

Returns

Promise<void>

Implementation of

AudioInputAdapter.start

stop()

stop(): Promise<void>;

Defined in: runtime-react-native/src/audio-input.ts:211

Stop capture and release resources tied to the current start.

Returns

Promise<void>

Implementation of

AudioInputAdapter.stop

suspendCapture()

suspendCapture(): Promise<void>;

Defined in: runtime-react-native/src/audio-input.ts:257

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

Returns

Promise<void>

Implementation of

AudioInputAdapter.suspendCapture

---

ExpoAudioOutput

Defined in: runtime-react-native/src/audio-output.ts:122

Expo audio playback with an optional gapless PCM response queue. The latter lets React Native start speaking as soon as OpenRouter’s first SSE audio delta arrives instead of waiting for the complete WAV response.

Implements

• AudioOutputAdapter

Constructors

Constructor

new ExpoAudioOutput(options): ExpoAudioOutput;

Defined in: runtime-react-native/src/audio-output.ts:133

Parameters

Parameter	Type
options	ExpoAudioOutputOptions

Returns

ExpoAudioOutput

Properties

Property	Modifier	Type	Description	Defined in
startPcmStream?	readonly	(options) => Promise<AudioOutputStream>	Begin incremental raw-PCM playback for low-latency speech streaming.	runtime-react-native/src/audio-output.ts:129

Methods

onEnd()

onEnd(cb): () => void;

Defined in: runtime-react-native/src/audio-output.ts:427

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-react-native/src/audio-output.ts:432

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-react-native/src/audio-output.ts:422

Subscribe to playback start.

Parameters

Parameter	Type
cb	() => void

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onStart

onVolume()

onVolume(cb): () => void;

Defined in: runtime-react-native/src/audio-output.ts:417

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

Parameters

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

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onVolume

pause()

pause(): Promise<void>;

Defined in: runtime-react-native/src/audio-output.ts:393

Pause playback without discarding the current utterance (optional).

Returns

Promise<void>

Implementation of

AudioOutputAdapter.pause

play()

play(input): Promise<void>;

Defined in: runtime-react-native/src/audio-output.ts:139

Play a complete encoded buffer or URL.

Parameters

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

Returns

Promise<void>

Implementation of

AudioOutputAdapter.play

resume()

resume(): Promise<void>;

Defined in: runtime-react-native/src/audio-output.ts:401

Resume after AudioOutputAdapter.pause.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.resume

stop()

stop(): Promise<void>;

Defined in: runtime-react-native/src/audio-output.ts:382

Stop current playback and cancel any open PCM stream.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.stop

Interfaces

ExpoAudioInputOptions

Defined in: runtime-react-native/src/audio-input.ts:46

Injected mic / file helpers for ExpoAudioInput. Prefer ExpoAudioInputOptions.createPcmStream for full-duplex VAD; fall back to ExpoAudioInputOptions.createRecording for batch capture. Wired by createExpoRuntime via ExpoRuntimeOptions.input.

Properties

Property	Type	Description	Defined in
createPcmStream?	(options, onBuffer) => | ExpoPcmInputStream | Promise<ExpoPcmInputStream>	Create a native PCM microphone stream. Expo SDK 57 useAudioStream can supply this without custom native code, so it also works in Expo Go.	runtime-react-native/src/audio-input.ts:55
createRecording?	() => Promise<ExpoRecordingHandle>	Legacy file recorder factory. Prefer createPcmStream for full duplex.	runtime-react-native/src/audio-input.ts:48
now?	() => number	Override clock used for chunk timestamps (tests).	runtime-react-native/src/audio-input.ts:62
readAudioFile?	(uri) => Promise<ArrayBuffer>	Read a legacy recorded file URI into an ArrayBuffer.	runtime-react-native/src/audio-input.ts:50
requestPermission?	() => Promise<boolean>	Microphone permission (wrap requestRecordingPermissionsAsync).	runtime-react-native/src/audio-input.ts:60

---

ExpoAudioOutputOptions

Defined in: runtime-react-native/src/audio-output.ts:71

Injected playback / file helpers for ExpoAudioOutput. Provide ExpoAudioOutputOptions.createPcmPlaylist plus ExpoAudioOutputOptions.writePcmChunk for streaming assistant audio; ExpoAudioOutputOptions.createSound covers one-shot URI playback. Wired by createExpoRuntime via ExpoRuntimeOptions.output.

Properties

Property	Type	Description	Defined in
createPcmPlaylist?	() => | ExpoPcmPlaylist | Promise<ExpoPcmPlaylist>	Create an Expo AudioPlaylist configured for frequent status updates.	runtime-react-native/src/audio-output.ts:77
createSound	(uri) => Promise<ExpoSound>	Load a sound from a URI (wrap createAudioPlayer).	runtime-react-native/src/audio-output.ts:73
deleteAudioFile?	(uri) => void | Promise<void>	Best-effort cleanup for temporary response chunk files.	runtime-react-native/src/audio-output.ts:81
writeAudioFile?	(buffer, mimeType) => Promise<string>	Persist a complete audio buffer to a file URI.	runtime-react-native/src/audio-output.ts:75
writePcmChunk?	(input) => Promise<string>	Wrap and persist one PCM16 response chunk as a small WAV file.	runtime-react-native/src/audio-output.ts:79

---

ExpoPcmChunkFileInput

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

One PCM16 fragment to persist as a WAV URI for playlist playback.

Extends

• PcmAudioStreamOptions

Properties

Property	Type	Description	Inherited from	Defined in
channels	number	Channel count of subsequent write payloads.	PcmAudioStreamOptions.channels	core/dist/types.d.ts:678
data	ArrayBuffer	Interleaved PCM16 bytes for this chunk.	-	runtime-react-native/src/audio-output.ts:59
encoding	"pcm_s16le"	Always linear 16-bit PCM for incremental streams.	PcmAudioStreamOptions.encoding	core/dist/types.d.ts:674
index	number	Monotonic chunk index used for temp filenames.	-	runtime-react-native/src/audio-output.ts:61
sampleRate	number	Sample rate of subsequent write payloads in Hz.	PcmAudioStreamOptions.sampleRate	core/dist/types.d.ts:676
volume?	number	Playback gain in [0, 1].	PcmAudioStreamOptions.volume	core/dist/types.d.ts:680

---

ExpoPcmInputBuffer

Defined in: runtime-react-native/src/audio-input.ts:17

A raw PCM block produced by Expo SDK 57’s useAudioStream.

Properties

Property	Type	Defined in
channels	number	runtime-react-native/src/audio-input.ts:21
data	ArrayBuffer	runtime-react-native/src/audio-input.ts:18
encoding	"pcm_s16le"	runtime-react-native/src/audio-input.ts:19
sampleRate	number	runtime-react-native/src/audio-input.ts:20

---

ExpoPcmInputStream

Defined in: runtime-react-native/src/audio-input.ts:25

The small part of Expo’s native AudioStream used by the runtime.

Methods

start()

start(): Promise<void>;

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

Returns

Promise<void>

stop()

stop(): void | Promise<void>;

Defined in: runtime-react-native/src/audio-input.ts:27

Returns

void | Promise<void>

---

ExpoPcmInputStreamOptions

Defined in: runtime-react-native/src/audio-input.ts:31

Sample format requested when creating ExpoPcmInputStream.

Properties

Property	Type	Description	Defined in
channels	number	Channel count (typically 1).	runtime-react-native/src/audio-input.ts:35
encoding	"pcm_s16le"	Always linear 16-bit PCM little-endian for this runtime.	runtime-react-native/src/audio-input.ts:37
sampleRate	number	Capture sample rate in Hz.	runtime-react-native/src/audio-input.ts:33

---

ExpoPcmPlaylist

Defined in: runtime-react-native/src/audio-output.ts:46

Gapless Expo AudioPlaylist surface used for incremental PCM playback.

Methods

add()

add(uri): void;

Defined in: runtime-react-native/src/audio-output.ts:47

Parameters

Parameter	Type
uri	string

Returns

void

clear()

clear(): void;

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

Returns

void

destroy()

destroy(): void;

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

Returns

void

next()

next(): void;

Defined in: runtime-react-native/src/audio-output.ts:48

Returns

void

pause()

pause(): void | Promise<void>;

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

Returns

void | Promise<void>

play()

play(): void | Promise<void>;

Defined in: runtime-react-native/src/audio-output.ts:49

Returns

void | Promise<void>

setOnPlaybackStatusUpdate()

setOnPlaybackStatusUpdate(cb): () => void;

Defined in: runtime-react-native/src/audio-output.ts:53

Parameters

Parameter	Type
cb	(status) => void

Returns

() => void

---

ExpoPcmPlaylistStatus

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

Status callback payload from an ExpoPcmPlaylist.

Properties

Property	Type	Description	Defined in
currentIndex	number	Index of the track currently playing or last finished.	runtime-react-native/src/audio-output.ts:30
currentTime	number	Playback position of the current track, in seconds.	runtime-react-native/src/audio-output.ts:32
didJustFinish	boolean	true when the playlist reached its end.	runtime-react-native/src/audio-output.ts:34
error?	string | null	Native error string when playback failed.	runtime-react-native/src/audio-output.ts:42
isBuffering?	boolean	Whether playback is waiting for the current local track to become ready.	runtime-react-native/src/audio-output.ts:38
playing	boolean	Whether audio is currently audible.	runtime-react-native/src/audio-output.ts:36
trackCount	number	Number of URIs queued in the playlist.	runtime-react-native/src/audio-output.ts:40

---

ExpoPlaybackStatus

Defined in: runtime-react-native/src/audio-output.ts:11

Status callback payload from an ExpoSound player.

Properties

Property	Type	Description	Defined in
didJustFinish?	boolean	true when playback completed successfully.	runtime-react-native/src/audio-output.ts:13
error?	string | null	Native error string when playback failed.	runtime-react-native/src/audio-output.ts:15

---

ExpoRecordingHandle

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

An Expo file-recording handle, kept for backwards-compatible batch capture.

Methods

getURI()

getURI(): string | null;

Defined in: runtime-react-native/src/audio-input.ts:13

Returns

string | null

startAsync()

startAsync(): Promise<void>;

Defined in: runtime-react-native/src/audio-input.ts:11

Returns

Promise<void>

stopAndUnloadAsync()

stopAndUnloadAsync(): Promise<void>;

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

Returns

Promise<void>

---

ExpoRuntime

Defined in: runtime-react-native/src/index.ts:24

Expo / React Native RuntimeAdapter returned by createExpoRuntime. No network adapter — providers use global fetch / WebSocket.

Extends

• RuntimeAdapter

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
audioInput	ExpoAudioInput	Microphone capture (PCM stream or legacy file recorder).	RuntimeAdapter.audioInput	-	runtime-react-native/src/index.ts:26
audioOutput	ExpoAudioOutput	One-shot and gapless PCM playlist playback.	RuntimeAdapter.audioOutput	-	runtime-react-native/src/index.ts:28
logger?	LoggerAdapter	Optional logger; core uses it sparingly.	-	RuntimeAdapter.logger	core/dist/types.d.ts:853
network?	NetworkAdapter	Optional HTTP/WebSocket hooks for providers.	-	RuntimeAdapter.network	core/dist/types.d.ts:849
storage?	RuntimeStorageAdapter	Optional persistence for caches.	-	RuntimeAdapter.storage	core/dist/types.d.ts:851

---

ExpoRuntimeOptions

Defined in: runtime-react-native/src/index.ts:13

Injected Expo audio bindings for createExpoRuntime. Pass platform primitives from expo-audio / file helpers so the package stays free of a hard Expo dependency and remains testable.

Properties

Property	Type	Description	Defined in
input	ExpoAudioInputOptions	Injected PCM capture bindings (Expo AudioStream / file helpers).	runtime-react-native/src/index.ts:15
output	ExpoAudioOutputOptions	Injected playback bindings (AudioPlaylist / PCM stream).	runtime-react-native/src/index.ts:17

---

ExpoSound

Defined in: runtime-react-native/src/audio-output.ts:19

An Expo AudioPlayer-like handle (abstracted for injection/testing).

Methods

pauseAsync()?

optional pauseAsync(): Promise<void>;

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

Returns

Promise<void>

playAsync()

playAsync(): Promise<void>;

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

Returns

Promise<void>

setOnPlaybackStatusUpdate()

setOnPlaybackStatusUpdate(cb): void;

Defined in: runtime-react-native/src/audio-output.ts:24

Parameters

Parameter	Type
cb	(status) => void

Returns

void

stopAsync()

stopAsync(): Promise<void>;

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

Returns

Promise<void>

unloadAsync()

unloadAsync(): Promise<void>;

Defined in: runtime-react-native/src/audio-output.ts:23

Returns

Promise<void>

Functions

createExpoRuntime()

function createExpoRuntime(options): ExpoRuntime;

Defined in: runtime-react-native/src/index.ts:39

Assemble an Expo RuntimeAdapter. You inject the Expo Audio / expo-file-system primitives (so the adapter stays testable and free of a hard Expo dependency). No network adapter is included — providers use the global fetch/WebSocket available in React Native.

Parameters

Parameter	Type	Description
options	ExpoRuntimeOptions	Injected input/output primitives. See ExpoRuntimeOptions.

Returns

ExpoRuntime

---

pcm16ToWav()

function pcm16ToWav(
   pcm,
   sampleRate,
   channels): ArrayBuffer;

Defined in: runtime-react-native/src/audio-input.ts:83

Wrap interleaved little-endian PCM16 in a standard WAV container.

Parameters

Parameter	Type	Description
pcm	Uint8Array	Interleaved PCM16 samples.
sampleRate	number	Sample rate in Hz.
channels	number	Channel count (typically 1).

Returns

ArrayBuffer

A standard WAV container buffer.