rns-recplay 2.0.3 → 3.0.0

package/README.md

@@ -1,35 +1,20 @@
 # 🎤 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.
+A **high-performance React Native audio recording and audio playback** compatible with WebRTC.  
+Designed for **voice notes, audio workstations, and media apps**, offering real-time volume metering, smooth looping, precise seek, and automatic playback interruption handling.
 
 ---
 
 ## ✨ 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
+- 🎙️ **Audio Recording** — High-quality AAC / M4A, real-time timer, pause & resume
+- 📊 **Real-time Volume Metering** — dB + normalized (0.0–1.0) every 100ms for UI visualizers
+- 🔊 **Audio Playback** — Powered by **ExoPlayer (Android)** and **AVPlayer (iOS)**
+- 🎯 **Precision Seek** — Zero-tolerance sample-accurate seeking
+- 🔄 **Seamless Looping** — Gapless looping handled natively
+- 📈 **Smooth Progress Tracking** — Position & duration updates every **50ms**
+- 🛡️ **Smart Audio Control** — Audio focus, interruption handling, headphone unplug detection
+- 🎙️ **WebRTC Compatible** — Detects active calls and adapts audio routing automatically
 
 ---
 
@@ -39,8 +24,6 @@ Designed for **voice notes, chats, and media apps**, offering smooth looping, pr
 npm install rns-recplay
 ```
 
-or (Expo):
-
 ```bash
 npx expo install rns-recplay
 ```
@@ -49,185 +32,274 @@ npx expo install rns-recplay
 
 ## ⚙️ Expo Configuration
 
-Add the plugin to your **app.json** or **app.config.json**:
+Add the plugin to your `app.json` or `app.config.js`:
 
 ```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."
-  }
-]
+{
+  "plugins": [
+    [
+      "rns-recplay",
+      {
+        "microphonePermission": "Allow microphone access for voice recording."
+      }
+    ]
+  ]
+}
 ```
 
 ---
 
 ## 🚀 Usage
 
-### 🎙️ Recording Example
+### 🎙️ Start & Stop Recording
 
 ```js
 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);
-  }
-};
+// Start recording
+const fileName = await Recplay.startRecording({
+  fileName: "my_voice_note",       // optional, defaults to rec_<timestamp>
+  shouldStopPlayback: true,        // stop any playing audio first
+  duck: true,                      // lower other audio while recording
+  mixWithOthers: true,             // mix with other audio sessions
+  useBT: false,                    // false = force built-in mic (recommended)
+  onSecondsUpdate: (seconds) => {
+    console.log(`Recorded: ${seconds}s`);
+  },
+  onVolumeUpdate: (db, normalized) => {
+    // db: raw decibel value (~-60 to 0)
+    // normalized: 0.0 to 1.0 — use this to drive a waveform visualizer
+    console.log(`Volume: ${normalized}`);
+  },
+});
+
+console.log("Recording started, file name:", fileName);
 
-const stopMyRecording = async () => {
-  const fileUri = await Recplay.stopRecording();
-  console.log("File saved at:", fileUri);
-};
+// Stop recording
+const result = await Recplay.stopRecording();
+console.log("URI:", result.uri);           // file:///...path/to/file.m4a
+console.log("Duration:", result.duration); // seconds, e.g. 5.4
 ```
 
 ---
 
-### 🔊 Playback Example (Looping Enabled)
+### ⏸️ Pause & Resume Recording
 
 ```js
-import Recplay from 'rns-recplay';
+await Recplay.pauseRecording();
+await Recplay.resumeRecording();
+```
+
+---
 
+### 🔊 Playback
+
+```js
 Recplay.playAudio({
   uri: "file:///path/to/audio.m4a",
   shouldStopPrevious: true,
-  loop: true,
+  loop: false,
   mixWithOthers: true,
-  duck: false,
+  duck: true,
   callbacks: {
-    onStatus: (status) => console.log("Status:", status),
-    onProgress: (position, duration) => console.log(`Progress: ${position} / ${duration}`),
-    onPlaybackFinished: () => console.log("Playback finished"),
+    onStatus: (status) => {
+      // 'BUFFERING' | 'PLAYING' | 'PAUSED' | 'ENDED' | 'ERROR'
+      console.log("Status:", status);
+      if (status === 'PLAYING') {
+        // safe to seek or update UI
+      }
+      if (status === 'ENDED') {
+        // reset playhead
+      }
+    },
+    onProgress: (currentPosition, duration) => {
+      // fires every ~50ms while playing
+      console.log(`${currentPosition} / ${duration}`);
+    },
+    onPlaybackFinished: () => {
+      console.log("Playback finished");
+    },
   }
 });
 ```
 
 ---
 
-## 📚 API Reference
+### 🎯 Seek, Toggle & Stop
 
-### 🔌 Permission Checks
+```js
+// Seek to a specific time (sample-accurate)
+Recplay.seekTo({ seconds: 30.5 });
 
-| Method                | Description                                      |
-| --------------------- | ------------------------------------------------ |
-| `checkPermission()`   | Checks the current microphone permission status. |
-| `requestPermission()` | Triggers the system permission dialog.           |
+// Toggle between play and pause
+Recplay.togglePlayback();
 
-Returns: Promise<"granted" | "denied" | "blocked" | "unavailable">
+// Stop playback and release resources
+await Recplay.stopPlayback();
+```
 
-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.
+### 🔐 Permissions
+
+```js
+// Check current status
+const status = await Recplay.checkPermission();
+// Returns: 'granted' | 'denied' | 'blocked' | 'unavailable'
+
+// Request permission
+const result = await Recplay.requestPermission();
+// Returns: 'granted' | 'denied'
+```
 
 ---
 
-### 🎙️ Recording
+## 📚 API Reference
 
-#### `startRecording({ fileName?, shouldStopPlayback?, duck?, mixWithOthers?, onSecondsUpdate? })`
+### `startRecording(options?)`
 
-| 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                         |
+| Parameter            | Type       | Default | Description                                                         |
+|----------------------|------------|---------|---------------------------------------------------------------------|
+| `fileName`           | `string`   | `null`  | Output file name (without extension). Defaults to `rec_<timestamp>` |
+| `shouldStopPlayback` | `boolean`  | `true`  | Stop any active playback before recording                           |
+| `duck`               | `boolean`  | `true`  | Lower volume of other audio while recording                         |
+| `mixWithOthers`      | `boolean`  | `true`  | Allow mixing with other active audio sessions                       |
+| `useBT`              | `boolean`  | `false` | Use Bluetooth mic. `false` forces the built-in microphone           |
+| `onSecondsUpdate`    | `function` | `null`  | Called once per second with `(seconds: number)`                     |
+| `onVolumeUpdate`     | `function` | `null`  | Called every 100ms with `(db: number, normalized: number)`          |
 
-**Returns:** `Promise<string>` (file name)
+**Returns:** `Promise<string>` — the file name (without extension)
 
 ---
 
-#### `stopRecording()`
+### `stopRecording()`
 
-Stops recording and releases the microphone.
+Stops the active recording, releases the microphone, and returns the saved file info.
 
-**Returns:** `Promise<string>` (file URI)
+**Returns:** `Promise<{ uri: string, duration: number }>`
+
+| Field      | Type     | Description                       |
+|------------|----------|-----------------------------------|
+| `uri`      | `string` | Full file URI, e.g. `file:///...` |
+| `duration` | `number` | Duration in seconds, e.g. `5.4`  |
 
 ---
 
-#### `pauseRecording()`
+### `pauseRecording()`
 
-Pauses the active recording session.
+Pauses the active recording session. Elapsed time is preserved accurately across pauses.
 
-#### `resumeRecording()`
+**Returns:** `Promise<boolean>`
+
+---
+
+### `resumeRecording()`
 
 Resumes a paused recording session.
 
+**Returns:** `Promise<boolean>`
+
 ---
 
-### 🔊 Playback
+### `playAudio(options)`
+
+| Parameter            | Type      | Default | Description                               |
+|----------------------|-----------|---------|-------------------------------------------|
+| `uri`                | `string`  | —       | Audio file URI or HTTP URL                |
+| `shouldStopPrevious` | `boolean` | `false` | Stop and release any previous playback    |
+| `loop`               | `boolean` | `false` | Loop playback natively (gapless)          |
+| `mixWithOthers`      | `boolean` | `true`  | Mix with other active audio sessions      |
+| `duck`               | `boolean` | `false` | Lower volume of other audio while playing |
+| `callbacks`          | `object`  | `{}`    | Event callbacks (see below)               |
 
-#### `playAudio({ uri, shouldStopPrevious?, loop?, mixWithOthers?, duck?, callbacks? })`
+#### 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             | Signature                                                 | Description                       |
+|----------------------|-----------------------------------------------------------|-----------------------------------|
+| `onStatus`           | `(status: string) => void`                                | Player state changes (see below)  |
+| `onProgress`         | `(currentPosition: number, duration: number) => void`     | Fires every ~50ms while playing   |
+| `onPlaybackFinished` | `() => void`                                              | Fires when non-looping audio ends |
+
+---
 
-##### Callback Options
+### `stopPlayback()`
 
-| Callback             | Params                 | Description              |
-| -------------------- | ---------------------- | ------------------------ |
-| `onStatus`           | `(status)`             | Player state updates     |
-| `onProgress`         | `(position, duration)` | Playback progress        |
-| `onPlaybackFinished` | `()`                   | Fired when playback ends |
+Stops playback, removes all observers, and releases the player.
+
+**Returns:** `Promise<boolean>`
 
 ---
 
-#### `stopPlayback()`
+### `togglePlayback()`
 
-Stops playback immediately.
+Toggles between play and pause on the current player instance.
 
-#### `togglePlayback()`
+---
 
-Toggles between play and pause.
+### `seekTo({ seconds })`
 
-#### `seekTo({ seconds })`
+Seeks to a precise position. Uses zero-tolerance seeking for sample accuracy.
 
-| Parameter | Type     | Description              |
-| --------- | -------- | ------------------------ |
-| `seconds` | `number` | Seek position in seconds |
+| Parameter | Type     | Description                |
+|-----------|----------|----------------------------|
+| `seconds` | `number` | Target position in seconds |
 
 ---
 
-## 📌 Status Types
+### `checkPermission()`
+
+**Returns:** `Promise<'granted' | 'denied' | 'blocked' | 'unavailable'>`
 
-* `BUFFERING`
-* `PLAYING`
-* `PAUSED`
-* `ERROR`
-* `ENDED`
-* `IDLE`
+| Status        | Meaning                                                                  |
+|---------------|--------------------------------------------------------------------------|
+| `granted`     | Microphone is available and permitted                                    |
+| `denied`      | Not asked yet (iOS) or dismissed once (Android) — can still request     |
+| `blocked`     | User selected "Don't Allow" / "Never ask again" — redirect to Settings  |
+| `unavailable` | Hardware missing or OS-restricted                                        |
+
+---
+
+### `requestPermission()`
+
+Triggers the native system permission dialog.
+
+**Returns:** `Promise<'granted' | 'denied'>`
+
+---
+
+## 📌 Playback Status Values
+
+| Status      | When                                          |
+|-------------|-----------------------------------------------|
+| `BUFFERING` | Loading / rebuffering (network or large file) |
+| `PLAYING`   | Audio is actively playing                     |
+| `PAUSED`    | Paused by user or audio focus loss            |
+| `ENDED`     | Playback reached the end of the file          |
+| `ERROR`     | Playback failed (bad URI, decode error, etc.) |
 
 ---
 
 ## 🛠️ Platform Support
 
 | Platform         | Supported |
-| ---------------- | --------- |
-| Android          | ✅         |
-| iOS              | ✅         |
-| Expo (Dev / EAS) | ✅         |
+|------------------|-----------|
+| Android          | ✅        |
+| iOS              | ✅        |
+| Expo (Dev / EAS) | ✅        |
+
+---
+
+## 📝 Notes
+
+- Recorded files are saved in the app's **cache directory** as `.m4a` (AAC, 44.1kHz, 128kbps, mono)
+- `onVolumeUpdate` fires at 100ms intervals — use `normalized` (0.0–1.0) to drive waveform visualizer bars
+- `onSecondsUpdate` fires once per second only on whole-second boundaries to avoid flooding JS
+- `useBT: false` (default) forces the phone's **built-in microphone** even when Bluetooth headphones are connected — this prevents Lightning/Bluetooth accessories from switching to low-quality HFP mode
+- `seekTo` is safe to call immediately after `onStatus: 'PLAYING'` fires
+- Calling `stopPlayback` cleans up all native observers — no memory leaks
 
 ---
 
 ## 📄 License
 
-MIT License
+MIT