@ottervoice/runtime-react-native

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.

The adapters cancel native microphone/player setup that completes after stop(), making them safe for backgrounding and rapid session restarts. Provide deleteAudioFile to clean both one-shot and streamed temporary audio.

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

Parameters

Parameter	Type
`options`	`ExpoAudioInputOptions`

Returns

ExpoAudioInput

Methods

onChunk()

onChunk(cb): () => void;

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

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

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

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

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

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

Resume after pause.

Returns

Promise<void>

Implementation of

AudioInputAdapter.resume

resumeCapture()

resumeCapture(): Promise<void>;

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

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

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

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

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

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

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

Methods

onEnd()

onEnd(cb): () => void;

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

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

Subscribe to playback failures.

Parameters

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

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onError

onPlaybackRequested()

onPlaybackRequested(cb): () => void;

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

Subscribe when native one-shot or playlist playback is requested.

Parameters

Parameter	Type	Description
`cb`	() => `void`	Called once immediately before the native play primitive.

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onPlaybackRequested

onStart()

onStart(cb): () => void;

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

Subscribe to the first native status confirming active playback.

Parameters

Parameter	Type	Description
`cb`	() => `void`	Called once when `playing` first becomes `true`.

Returns

Unsubscribe function.

() => void

Implementation of

AudioOutputAdapter.onStart

onVolume()

onVolume(cb): () => void;

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

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

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

resume()

resume(): Promise<void>;

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

Resume after AudioOutputAdapter.pause.

Returns

Promise<void>

Implementation of

AudioOutputAdapter.resume

stop()

stop(): Promise<void>;

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

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

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:79
`createSound`	(`uri`) => `Promise`<`ExpoSound`>	Load a sound from a URI (wrap `createAudioPlayer`).	runtime-react-native/src/audio-output.ts:75
`deleteAudioFile?`	(`uri`) => `void` \| `Promise`<`void`>	Best-effort cleanup for one-shot and streamed temporary response audio.	runtime-react-native/src/audio-output.ts:83
`writeAudioFile?`	(`buffer`, `mimeType`) => `Promise`<`string`>	Persist a complete audio buffer to a file URI.	runtime-react-native/src/audio-output.ts:77
`writePcmChunk?`	(`input`) => `Promise`<`string`>	Wrap and persist one PCM16 response chunk as a small WAV file.	runtime-react-native/src/audio-output.ts:81

ExpoPcmChunkFileInput

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

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:762
`data`	`ArrayBuffer`	Interleaved PCM16 bytes for this chunk.	-	runtime-react-native/src/audio-output.ts:61
`encoding`	`"pcm_s16le"`	Always linear 16-bit PCM for incremental streams.	`PcmAudioStreamOptions`.`encoding`	core/dist/types.d.ts:758
`index`	`number`	Monotonic chunk index used for temp filenames.	-	runtime-react-native/src/audio-output.ts:63
`sampleRate`	`number`	Sample rate of subsequent `write` payloads in Hz.	`PcmAudioStreamOptions`.`sampleRate`	core/dist/types.d.ts:760
`volume?`	`number`	Playback gain in `[0, 1]`.	`PcmAudioStreamOptions`.`volume`	core/dist/types.d.ts:764

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

Gapless Expo AudioPlaylist surface used for incremental PCM playback.

Methods

add()

add(uri): void;

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

Parameters

Parameter	Type
`uri`	`string`

Returns

void

clear()

clear(): void;

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

Returns

void

destroy()

destroy(): void;

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

Returns

void

next()

next(): void;

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

Returns

void

pause()

pause(): void | Promise<void>;

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

Returns

void | Promise<void>

play()

play(): void | Promise<void>;

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

Returns

void | Promise<void>

setOnPlaybackStatusUpdate()

setOnPlaybackStatusUpdate(cb): () => void;

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

Parameters

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

Returns

() => void

ExpoPcmPlaylistStatus

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

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:32
`currentTime`	`number`	Playback position of the current track, in seconds.	runtime-react-native/src/audio-output.ts:34
`didJustFinish`	`boolean`	`true` when the playlist reached its end.	runtime-react-native/src/audio-output.ts:36
`error?`	`string` \| `null`	Native error string when playback failed.	runtime-react-native/src/audio-output.ts:44
`isBuffering?`	`boolean`	Whether playback is waiting for the current local track to become ready.	runtime-react-native/src/audio-output.ts:40
`playing`	`boolean`	Whether audio is currently audible.	runtime-react-native/src/audio-output.ts:38
`trackCount`	`number`	Number of URIs queued in the playlist.	runtime-react-native/src/audio-output.ts:42

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:15
`error?`	`string` \| `null`	Native error string when playback failed.	runtime-react-native/src/audio-output.ts:17
`playing`	`boolean`	Whether the native player reports that audio is actively playing.	runtime-react-native/src/audio-output.ts:13

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:951
`network?`	`NetworkAdapter`	Optional HTTP/WebSocket hooks for providers.	-	`RuntimeAdapter`.`network`	core/dist/types.d.ts:947
`storage?`	`RuntimeStorageAdapter`	Optional persistence for caches.	-	`RuntimeAdapter`.`storage`	core/dist/types.d.ts:949

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

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

Methods

pauseAsync()?

optional pauseAsync(): Promise<void>;

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

Returns

Promise<void>

playAsync()

playAsync(): Promise<void>;

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

Returns

Promise<void>

setOnPlaybackStatusUpdate()

setOnPlaybackStatusUpdate(cb): void;

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

Parameters

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

Returns

void

stopAsync()

stopAsync(): Promise<void>;

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

Returns

Promise<void>

unloadAsync()

unloadAsync(): Promise<void>;

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

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.