react-native-audio-recorder-player

🎉 Version 4.0.0 Released with NitroModule Support!

This is a high-performance React Native module for audio recording and playback, now powered by NitroModules for direct native module access without bridge overhead. The library provides simple recorder and player functionalities for both Android and iOS platforms with full TypeScript support and type safety.

Preview

Documentation & Resources

• 📚 Version 4.0.0 Migration Guide
• 📝 Version 3 Release Note
• 📰 Original Blog Post
• 🔧 NitroModules Documentation

What's New in 4.0.0 🚀

NitroModule Migration

Version 4.0.0 introduces a complete rewrite using NitroModules, offering:

• Zero Bridge Overhead: Direct native module access for maximum performance
• Full Type Safety: TypeScript definitions generated from native specs
• Synchronous Methods: Where appropriate, for better developer experience
• Event Listeners: Native callbacks with type-safe event payloads
• Cross-Platform Code Generation: Automatic code generation for iOS (Swift) and Android (Kotlin)

Requirements

• React Native >= 0.73.0
• iOS >= 13.0
• Android minSdk >= 24
• Expo SDK >= 50 (for Expo users)

Breaking Changes from 3.x

API Changes

1. Import Change: The module is now imported differently:

   1// Before (3.x)
   2import AudioRecorderPlayer from 'react-native-audio-recorder-player';
   3const audioRecorderPlayer = new AudioRecorderPlayer();
   4
   5// After (4.0.0)
   6import { AudioRecorderPlayerNitro } from 'react-native-audio-recorder-player';
   7const audioRecorderPlayer = new AudioRecorderPlayerNitro();

2. Event Listeners: New event listener API:

   1// Before (3.x)
   2audioRecorderPlayer.addRecordBackListener((e) => { ... });
   3
   4// After (4.0.0)
   5audioRecorderPlayer.onRecordingProgress = (e) => { ... };
   6audioRecorderPlayer.onPlaybackProgress = (e) => { ... };

3. Promise Return Types: All methods now have proper TypeScript types

Previous Breaking Changes (3.x)

• From version 3.0.+, a critical migration has been done. Also note that it supports iOS platform version 10.0 or newer.

  1. Codebase has been re-written to kotlin for Android and swift for iOS. Please follow the post installation for this changes.

     [iOS]

     • AVAudioPlayer has been migrated to AVPlayer which supports stream and more possibilities #231, #245, #275.

  2. pauseRecorder and resumeRecorder features are added.

     • Caveat Android now requires minSdk of 24.

  3. Renamed callback variables.

     1export type RecordBackType = {
     2  isRecording?: boolean;
     3  currentPosition: number;
     4  currentMetering?: number;
     5};
     6
     7export type PlayBackType = {
     8  isMuted?: boolean;
     9  currentPosition: number;
     10  duration: number;
     11};

  4. subscriptionDuration offset not defaults to 0.5 which is 500ms.

     • Resolve #273

Migration Guide

From 3.x to 4.0.0 (NitroModule)

3.x API	4.0.0 NitroModule API
new AudioRecorderPlayer()	new AudioRecorderPlayerNitro()
addRecordBackListener(cb)	onRecordingProgress = cb
removeRecordBackListener()	onRecordingProgress = undefined
addPlayBackListener(cb)	onPlaybackProgress = cb
removePlayBackListener()	onPlaybackProgress = undefined

From 1.x to 2.x/3.x

1.x.x	2.x.x & 3.x.x
startRecord	startRecorder
	pauseRecorder (3.x.x)
	resumeRecorder (3.x.x)
stopRecord	stopRecorder
startPlay	startPlayer
stopPlay	stopPlayer
pausePlay	pausePlayer
resume	resumePlayer
seekTo	seekToPlayer
	setSubscriptionDuration
addPlayBackListener	addPlayBackListener
setRecordInterval	addRecordBackListener
removeRecordInterval	``
	setVolume

Getting started

1bun add react-native-audio-recorder-player

Or using npm/yarn:

1npm install react-native-audio-recorder-player
2# or
3yarn add react-native-audio-recorder-player

Installation

React Native CLI

iOS

1cd ios && pod install

Android

No additional steps required. The module uses autolinking.

Post-installation for NitroModule (Required)

After installing the package, you need to run the code generation:

1# Using bun (recommended)
2bun x nitro-codegen
3
4# Or using npm/yarn
5npx nitro-codegen
6# or
7yarn nitro-codegen

This will generate the necessary native code bindings for both iOS and Android platforms.

Expo

This library supports Expo SDK 50+ via a config plugin. The plugin handles all native configuration automatically.

Installation

1expo install react-native-audio-recorder-player

Post-installation

For Expo managed workflow, you need to prebuild your app after adding the plugin:

1expo prebuild

Configuration in app.json / app.config.js

1{
2  "expo": {
3    "plugins": [
4      "react-native-audio-recorder-player"
5    ]
6  }
7}

Or with custom iOS microphone permission text:

1{
2  "expo": {
3    "plugins": [
4      [
5        "react-native-audio-recorder-player",
6        {
7          "microphonePermissionText": "This app needs access to your microphone to record audio."
8        }
9      ]
10    ]
11  }
12}

The plugin automatically configures:

• iOS: NSMicrophoneUsageDescription in Info.plist
• Android: RECORD_AUDIO, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE permissions in AndroidManifest.xml
• NitroModule: All necessary native module configurations

⚠️ Important for Expo users: After adding the plugin, you must run expo prebuild to generate the native code. For development builds, use:

1eas build --profile development --platform all

Manual Installation (Not recommended with NitroModule)

⚠️ Note: Manual installation is not recommended for NitroModule 4.0.0. Use autolinking instead.

If you must use manual installation:

1. Follow the standard installation steps
2. Run bun x nitro-codegen to generate native bindings
3. The generated code will be in the nitrogen directory
4. Link the generated native modules to your project

Platform-specific Configuration

iOS Configuration

1. Microphone Permission: Add to your Info.plist:

   1<key>NSMicrophoneUsageDescription</key>
   2<string>Give $(PRODUCT_NAME) permission to use your microphone. Your record wont be shared without your permission.</string>

2. Minimum iOS Version: Ensure your minimum deployment target is iOS 13.0 or higher in your Podfile:

   1platform :ios, '13.0'

3. Swift Support: The module uses Swift. If your project doesn't have a bridging header, it will be created automatically during pod installation.

Android Configuration

On Android you need to add a permission to AndroidManifest.xml:

1<uses-permission android:name="android.permission.RECORD_AUDIO" />
2<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
3<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

If your app requires broad access to external storage, you'll need:

1<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" tools:ignore="ScopedStorage" />

Also, android above Marshmallow needs runtime permission to record audio. Using react-native-permissions will help you out with this problem. Below is sample usage before when before staring the recording.

1if (Platform.OS === 'android') {
2  try {
3    const grants = await PermissionsAndroid.requestMultiple([
4      PermissionsAndroid.PERMISSIONS.WRITE_EXTERNAL_STORAGE,
5      PermissionsAndroid.PERMISSIONS.READ_EXTERNAL_STORAGE,
6      PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
7    ]);
8
9    console.log('write external storage', grants);
10
11    if (
12      grants['android.permission.WRITE_EXTERNAL_STORAGE'] ===
13        PermissionsAndroid.RESULTS.GRANTED &&
14      grants['android.permission.READ_EXTERNAL_STORAGE'] ===
15        PermissionsAndroid.RESULTS.GRANTED &&
16      grants['android.permission.RECORD_AUDIO'] ===
17        PermissionsAndroid.RESULTS.GRANTED
18    ) {
19      console.log('Permissions granted');
20    } else {
21      console.log('All required permissions not granted');
22      return;
23    }
24  } catch (err) {
25    console.warn(err);
26    return;
27  }
28}

2. Build Configuration: Update your android/build.gradle:

   1buildscript {
   2  ext {
   3      buildToolsVersion = "33.0.0"
   4      minSdkVersion = 24  // Required for pause/resume features
   5      compileSdkVersion = 33
   6      targetSdkVersion = 33
   7      kotlinVersion = '1.8.0'  // Required for NitroModule
   8      
   9      ndkVersion = "23.1.7779620"
   10  }
   11}

3. CMake Support: NitroModule requires CMake for Android. It's automatically configured, but ensure you have CMake installed in Android Studio:

   • Open Android Studio
   • Go to Tools → SDK Manager → SDK Tools
   • Check "CMake" and click "Apply"

Troubleshooting

Common Issues

1. Build Error: "Cannot find module 'react-native-nitro-modules'"
   • Solution: Run bun x nitro-codegen after installation
2. iOS Build Error: "No such module 'NitroAudioRecorderPlayer'"
   • Solution: Run cd ios && pod install
3. Android Build Error: "CMake not found"
   • Solution: Install CMake through Android Studio SDK Manager
4. Expo Error: "Plugin is not compatible with Expo Go"
   • Solution: Use development builds with eas build or expo prebuild

Methods

NitroModule API (4.0.0)

Method	Param	Return	Description
mmss	number seconds	string	Convert seconds to minute:second string
mmssss	number seconds	string	Convert seconds to minute:second:millisecond string
setSubscriptionDuration	number duration	void	Set callback interval in ms (default 500ms)
startRecorder	string? uri, AudioSet? audioSet,	Promise<string>	Start recording with optional path and audio settings
	boolean? meteringEnabled
pauseRecorder		Promise<string>	Pause recording
resumeRecorder		Promise<string>	Resume recording
stopRecorder		Promise<string>	Stop recording and return file path
startPlayer	string? uri, Record<string, string>? headers	Promise<string>	Start playback with optional URI and HTTP headers
stopPlayer		Promise<string>	Stop playback
pausePlayer		Promise<string>	Pause playback
resumePlayer		Promise<string>	Resume playback
seekToPlayer	number milliseconds	Promise<string>	Seek to position in milliseconds
setVolume	number value	Promise<string>	Set volume (0.0 - 1.0)
onRecordingProgress	(event: RecordBackType) => void	void	Set recording progress callback
onPlaybackProgress	(event: PlayBackType) => void	void	Set playback progress callback

Legacy API (for backward compatibility)

Method	Param	Return	Description
addRecordBackListener	Function callBack	void	Add recording progress listener (deprecated, use onRecordingProgress)
removeRecordBackListener	Function callBack	void	Remove recording listener
addPlayBackListener	Function callBack	void	Add playback progress listener (deprecated, use onPlaybackProgress)
removePlayBackListener	Function callBack	void	Remove playback listener

Customizing Audio Quality

Audio Configuration Options

1interface AudioSet {
2  // iOS Options
3  AVSampleRateKeyIOS?: number;              // Sample rate (e.g., 44100)
4  AVFormatIDKeyIOS?: AVEncodingType;        // Audio format (e.g., aac, mp4)
5  AVModeIOS?: AVModeType;                   // Audio session mode
6  AVNumberOfChannelsKeyIOS?: number;        // Number of channels (1 = mono, 2 = stereo)
7  AVEncoderAudioQualityKeyIOS?: AVEncoderAudioQualityIOSType; // Quality level
8  
9  // Android Options
10  AudioSourceAndroid?: AudioSourceAndroidType;     // Audio source (e.g., MIC)
11  OutputFormatAndroid?: OutputFormatAndroidType;   // Output format
12  AudioEncoderAndroid?: AudioEncoderAndroidType;   // Encoder type
13}

Example Configuration

1const audioSet: AudioSet = {
2  // iOS Settings
3  AVSampleRateKeyIOS: 44100,
4  AVFormatIDKeyIOS: AVEncodingOption.aac,
5  AVModeIOS: AVModeIOSOption.measurement,
6  AVEncoderAudioQualityKeyIOS: AVEncoderAudioQualityIOSType.high,
7  AVNumberOfChannelsKeyIOS: 2,
8  
9  // Android Settings
10  AudioEncoderAndroid: AudioEncoderAndroidType.AAC,
11  AudioSourceAndroid: AudioSourceAndroidType.MIC,
12  OutputFormatAndroid: OutputFormatAndroidType.AAC_ADTS,
13};
14
15const meteringEnabled = true; // Enable audio metering
16
17const uri = await audioRecorderPlayer.startRecorder(
18  undefined, // Use default path
19  audioSet,
20  meteringEnabled
21);

Default Path

• Default path for android uri is {cacheDir}/sound.mp4.
• Default path for ios uri is {cacheDir}/sound.m4a.

Usage

Basic Usage with NitroModule (4.0.0)

1import { AudioRecorderPlayerNitro } from 'react-native-audio-recorder-player';
2
3const audioRecorderPlayer = new AudioRecorderPlayerNitro();
4
5// Recording
6const onStartRecord = async () => {
7  // Set up recording progress listener
8  audioRecorderPlayer.onRecordingProgress = (e) => {
9    console.log('Recording progress:', e.currentPosition, e.currentMetering);
10    setState({
11      recordSecs: e.currentPosition,
12      recordTime: audioRecorderPlayer.mmssss(Math.floor(e.currentPosition)),
13    });
14  };
15  
16  const result = await audioRecorderPlayer.startRecorder();
17  console.log('Recording started:', result);
18};
19
20const onStopRecord = async () => {
21  const result = await audioRecorderPlayer.stopRecorder();
22  audioRecorderPlayer.onRecordingProgress = undefined; // Clear listener
23  console.log('Recording stopped:', result);
24};
25
26// Playback
27const onStartPlay = async () => {
28  // Set up playback progress listener
29  audioRecorderPlayer.onPlaybackProgress = (e) => {
30    console.log('Playback progress:', e.currentPosition, e.duration);
31    setState({
32      currentPositionSec: e.currentPosition,
33      currentDurationSec: e.duration,
34      playTime: audioRecorderPlayer.mmssss(Math.floor(e.currentPosition)),
35      duration: audioRecorderPlayer.mmssss(Math.floor(e.duration)),
36    });
37  };
38  
39  const result = await audioRecorderPlayer.startPlayer();
40  console.log('Playback started:', result);
41};
42
43const onPausePlay = async () => {
44  await audioRecorderPlayer.pausePlayer();
45};
46
47const onStopPlay = async () => {
48  audioRecorderPlayer.stopPlayer();
49  audioRecorderPlayer.onPlaybackProgress = undefined; // Clear listener
50};

Legacy API (for backward compatibility)

If you need to maintain backward compatibility, you can still use the legacy API:

1import AudioRecorderPlayer from 'react-native-audio-recorder-player';
2
3const audioRecorderPlayer = new AudioRecorderPlayer();
4
5// Legacy callback style still works
6audioRecorderPlayer.addRecordBackListener((e) => {
7  // Handle recording progress
8});

TIPS

If you want to get actual uri from the record or play file to actually grab it and upload it to your bucket, just grab the resolved message when using startPlay or startRecord method like below.

To access the file with more reliability, please use react-native-blob-util or react-native-file-access. See below for examples.

react-native-blob-util

1import ReactNativeBlobUtil from 'react-native-blob-util'
2...
3const dirs = ReactNativeBlobUtil.fs.dirs;
4const path = Platform.select({
5  ios: 'hello.m4a',
6  android: `${dirs.CacheDir}/hello.mp3`,
7});
8
9const uri = await audioRecorderPlayer.startRecord(path);

Also, above example helps you to setup manual path to record audio. Not giving path param will record in default path as mentioned above.

To pass in specific URI in IOS, you need to append file:// to the path. As an example using RFNS.

1import RNFetchBlob from 'rn-fetch-blob';
2...
3const dirs = RNFetchBlob.fs.dirs;
4const path = Platform.select({
5  ios: `file://${RNFS.DocumentDirectoryPath}/hello.m4a`,
6  android: `${this.dirs.CacheDir}/hello.mp3`,
7});
8
9const uri = await audioRecorderPlayer.startRecord(path);

react-native-file-access

1import { Dirs } from "react-native-file-access";
2...
3const path = Platform.select({
4  ios: 'hello.m4a',
5  android: `${Dirs.CacheDir}/hello.mp3`,
6});
7
8const uri = await audioRecorderPlayer.startRecord(path);

Example App

Running the Example

1. Navigate to the example directory:

   1cd Example

2. Install dependencies:

   1bun install

3. Generate NitroModule bindings:

   1bun x nitro-codegen

4. Start the development server:

   1bun start

5. Run on your platform:

   1# iOS
   2bun ios
   3
   4# Android
   5bun android

Special Thanks

mansya - logo designer.

Help Maintenance

I've been maintaining quite many repos these days and burning out slowly. If you could help me cheer up, buying me a cup of coffee will make my life really happy and get much energy out of it.