react-native-live-audio

Live microphone buffering for React Native with pre-roll and post-roll capture to a WAV file on disk. Implemented as a Nitro module (native Swift on Apple platforms).

Features

• Continuous tap on the microphone input while start() is active, with a configurable rolling history buffer.
• capture() exports a window that includes audio before and after the call (pre-roll / post-roll).
• Optional gain applied only at export time (live buffer stays unprocessed).
• Typed JavaScript API and autolinking via react-native-nitro-modules.

Platform support

| Platform | Support | | -------- | ------- | | iOS | Yes | | visionOS | Yes (via CocoaPods target) | | Android | Not supported by this library (no native module). |

Requirements

• React Native >= 0.76 (tested with 0.84.x).
• react-native-nitro-modules compatible with your Nitro codegen (this repo is developed against 0.35.x).
• Node.js >= 18.
• iOS: Xcode and CocoaPods; microphone usage string in Info.plist (see below).

Installation

npm install react-native-live-audio react-native-nitro-modules

Then install iOS pods from your app’s ios directory:

cd ios && bundle exec pod install

Rebuild the native app after adding the dependency.

iOS configuration

Add a microphone usage description to your app’s Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>Explain why your app needs the microphone.</string>

Without this key, iOS will terminate or block microphone access when you call LiveAudio.start().

Quick start

import { LiveAudio } from 'react-native-live-audio';

// Begin buffering (default max pre-roll history: 10 seconds)
LiveAudio.start({ maxPreRollSeconds: 10 });

// Later: export ~1.5s before + ~1.5s after this moment to a temp WAV path
const path = await LiveAudio.capture({
  preRollSeconds: 1.5,
  postRollSeconds: 1.5,
  gain: 5,
});

LiveAudio.stop();

If capture() fails or there is no usable audio, the promise resolves to an empty string (check before uploading or playing the file).

API

LiveAudio.start(options?)

Starts the audio engine and ring buffer.

• options.maxPreRollSeconds (optional, default 10): Upper bound on how much history is kept for pre-roll. Must be between 0 and 60. Increase this if you call capture() with a larger preRollSeconds than the default.

LiveAudio.stop()

Stops the engine, clears the buffer, and cancels any in-flight capture.

LiveAudio.hello(): string

Returns a short native status string (for example idle, recording, or capturing). Useful for debugging.

LiveAudio.capture(options?): Promise<string>

Exports a WAV file while start() has the engine running.

• preRollSeconds (default 1.5): Audio taken from the ring buffer before the capture instant. Must be between 0 and the current maxPreRollSeconds used in start().
• postRollSeconds (default 1.5): Audio recorded after the call until this duration elapses. Must be between 0 and 30.
• gain (default 5): Linear gain applied only in the exported file. Must be between 0.01 and 50.

Resolves with an absolute file path to a file under the app’s temporary directory (for example …/tmp/capture_<UUID>.wav). Only one capture may run at a time.

Constants

• DEFAULT_MAX_PRE_ROLL_SECONDS — default 10.
• DEFAULT_CAPTURE_OPTIONS — default preRollSeconds, postRollSeconds, and gain used when options are omitted.

Example app

This repository includes an example app under example/. See example/README.md for how to run it.

Troubleshooting

• LiveAudio.start() must be called before capture() — Call start() and wait until the engine is running before capture().
• Empty path after capture() — Often no chunks in the pre/post window, export error, or missing microphone permission. Confirm NSMicrophoneUsageDescription and system microphone permission for the app.
• Android — This package does not ship an Android implementation; importing it on Android will not provide native functionality.

Contributing

Issues and pull requests are welcome on GitHub. For larger changes, please open an issue first to agree on direction.

Publishing (maintainers)

• From the repository root, npm publish runs prepublishOnly, which executes npm run build so the lib/ output is always included in the tarball (see the files field in package.json).
• This repo is wired for semantic-release via npm run release (see release.config.cjs and .github/workflows/release.yml). Use conventional commits so versions and CHANGELOG.md stay accurate.

License

MIT. See LICENSE.

Credits

Scaffolded with create-nitro-module.