🎤 rns-recplay

A high-performance React Native audio recording and playback module with native-level control & compatible with webRTC. Designed for voice notes, chats, and media apps, offering smooth looping, precise progress tracking, and automatic playback interruption.

✨ Features

• 🎙️ Audio Recording

  • High-quality AAC / M4A format
  • Real-time recording timer
  • Pause & resume support

• 🔊 Audio Playback

  • Powered by ExoPlayer (Android) and AVPlayer (iOS)
  • Native-level performance

• 🔄 Seamless Looping

  • Gapless looping handled natively

• 📊 Progress Tracking

  • Position & duration updates every 500ms

• 🛡️ Smart Audio Control

  • Automatically stops playback when recording begins
  • Prevents overlapping audio sessions

📦 Installation

npm install rns-recplay

or (Expo):

npx expo install rns-recplay

⚙️ Expo Configuration

Add the plugin to your app.json or app.config.json:

[
  "rns-recplay",
  {
    "microphonePermission": "Microphone is used strictly for voice messages and live audio or video interactions. Tap 'Allow' to enable microphone usage when needed."
  }
]

🚀 Usage

🎙️ Recording Example

import Recplay from 'rns-recplay';

const startMyRecording = async () => {
  try {
    const fileName = await Recplay.startRecording({
      fileName: "my_voice_note", // optional file name
      shouldStopPlayback: true,
      duck: true,
      mixWithOthers: true,
      onSecondsUpdate: (seconds) => console.log(`Recorded: ${seconds}s`)
    });

    console.log("Recording started:", fileName);
  } catch (err) {
    console.error(err);
  }
};

const stopMyRecording = async () => {
  const fileUri = await Recplay.stopRecording();
  console.log("File saved at:", fileUri);
};

🔊 Playback Example (Looping Enabled)

import Recplay from 'rns-recplay';

Recplay.playAudio({
  uri: "file:///path/to/audio.m4a",
  shouldStopPrevious: true,
  loop: true,
  mixWithOthers: true,
  duck: false,
  callbacks: {
    onStatus: (status) => console.log("Status:", status),
    onProgress: (position, duration) => console.log(`Progress: ${position} / ${duration}`),
    onPlaybackFinished: () => console.log("Playback finished"),
  }
});

📚 API Reference

🔌 Permission Checks

| Method | Description | | --------------------- | ------------------------------------------------ | | checkPermission() | Checks the current microphone permission status. | | requestPermission() | Triggers the system permission dialog. |

Returns: Promise<"granted" | "denied" | "blocked" | "unavailable">

Status Meanings:

• granted: Permission is active. Ready to record.
• denied: Not asked yet (iOS) or dismissed (Android). Can still ask.
• blocked: User selected "Don't Allow" or "Never ask again". Must redirect to System Settings.
• unavailable: Hardware is missing or restricted by OS.

🎙️ Recording

startRecording({ fileName?, shouldStopPlayback?, duck?, mixWithOthers?, onSecondsUpdate? })

| Parameter | Type | Default | Description | | -------------------- | ---------- | ------- | ------------------------------------------- | | fileName | string | null | Custom .m4a file name | | shouldStopPlayback | boolean | true | Stops any playing audio | | duck | boolean | true | Reduce volume of other audio when recording | | mixWithOthers | boolean | true | Mix recording with device playing audio | | onSecondsUpdate | function | null | Called every second |

Returns: Promise<string> (file name)

stopRecording()

Stops recording and releases the microphone.

Returns: Promise<string> (file URI)

pauseRecording()

Pauses the active recording session.

resumeRecording()

Resumes a paused recording session.

🔊 Playback

playAudio({ uri, shouldStopPrevious?, loop?, mixWithOthers?, duck?, callbacks? })

| Parameter | Type | Default | Description | | -------------------- | --------- | ------- | -------------------------------------------- | | uri | string | — | Audio file URI | | shouldStopPrevious | boolean | false | Stops previous playback | | loop | boolean | false | Enables native looping | | mixWithOthers | boolean | true | Mix audio playback with device playing audio | | duck | boolean | false | Reduce volume of other audio when playing | | callbacks | object | {} | Playback event callbacks |

Callback Options

| Callback | Params | Description | | -------------------- | ---------------------- | ------------------------ | | onStatus | (status) | Player state updates | | onProgress | (position, duration) | Playback progress | | onPlaybackFinished | () | Fired when playback ends |

stopPlayback()

Stops playback immediately.

togglePlayback()

Toggles between play and pause.

seekTo({ seconds })

| Parameter | Type | Description | | --------- | -------- | ------------------------ | | seconds | number | Seek position in seconds |

📌 Status Types

• BUFFERING
• PLAYING
• PAUSED
• ERROR
• ENDED
• IDLE

🛠️ Platform Support

| Platform | Supported | | ---------------- | --------- | | Android | ✅ | | iOS | ✅ | | Expo (Dev / EAS) | ✅ |

📄 License

MIT License