rns-recplay 1.3.2 → 1.3.4

package/README.md

@@ -66,11 +66,11 @@ import Recplay from 'rns-recplay';
 
 const startMyRecording = async () => {
   try {
-    const fileName = await Recplay.startRecording(
-      "my_voice_note", // optional file name (null for auto-generated)
-      true, // stop any playing audio
-      (seconds) => console.log(`Recorded: ${seconds}s`)
-    );
+    const fileName = await Recplay.startRecording({
+      fileName: "my_voice_note", // optional file name
+      shouldStopPlayback: true,
+      onSecondsUpdate: (seconds) => console.log(`Recorded: ${seconds}s`)
+    });
 
     console.log("Recording started:", fileName);
   } catch (err) {
@@ -91,48 +91,47 @@ const stopMyRecording = async () => {
 ```js
 import Recplay from 'rns-recplay';
 
-Recplay.playAudio(
-  "file:///path/to/audio.m4a",
-  true, // stop previous playback
-  true, // loop audio
-  true, // mixWithOthers
-  {
+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}`),
-    onFinished: () => console.log("Playback finished"),
+    onProgress: (position, duration) => console.log(`Progress: ${position} / ${duration}`),
+    onPlaybackFinished: () => console.log("Playback finished"),
   }
-);
+});
 ```
 
 ---
 
 ## 📚 API Reference
 
-#### 🔌 Permission Checks
-
+### 🔌 Permission Checks
 
-| Method              | Description                                      |
-|---------------------|--------------------------------------------------|
-| `checkPermission()`   | Checks the current microphone permission status. |
-| `requestPermission()` | Triggers the system permission dialog.           |
+| 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.
+- 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?, onSecondsUpdate?)`
+### 🎙️ Recording
+
+#### `startRecording({ fileName?, shouldStopPlayback?, onSecondsUpdate? })`
 
 | Parameter | Type | Default | Description |
-|--------|------|---------|------------|
+|-----------|------|---------|-------------|
 | `fileName` | `string` | `null` | Custom `.m4a` file name |
 | `shouldStopPlayback` | `boolean` | `true` | Stops any playing audio |
 | `onSecondsUpdate` | `function` | `null` | Called every second |
@@ -159,23 +158,24 @@ Resumes a paused recording session.
 
 ### 🔊 Playback
 
-#### `playAudio(uri, shouldStopPrevious?, loop?, mixWithOthers?, callbacks?)`
+#### `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` | `false` | Mix audio playback with device playing audio |
+| `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 |
-| `onFinished` | `()` | Fired when playback ends |
+| `onPlaybackFinished` | `()` | Fired when playback ends |
 
 ---
 
@@ -185,10 +185,10 @@ Stops playback immediately.
 #### `togglePlayback()`
 Toggles between play and pause.
 
-#### `seekTo(seconds)`
+#### `seekTo({ seconds })`
 
 | Parameter | Type | Description |
-|--------|------|-------------|
+|-----------|------|-------------|
 | `seconds` | `number` | Seek position in seconds |
 
 ---
@@ -206,7 +206,7 @@ Toggles between play and pause.
 ## 🛠️ Platform Support
 
 | Platform | Supported |
-|--------|-----------|
+|----------|-----------|
 | Android | ✅ |
 | iOS | ✅ |
 | Expo (Dev / EAS) | ✅ |
@@ -216,3 +216,4 @@ Toggles between play and pause.
 ## 📄 License
 
 MIT License
+

package/android/src/main/java/com/rnsrecplay/RecPlayModule.kt

@@ -203,92 +203,34 @@ class RecPlayModule(
         uriString: String,
         shouldStopPrevious: Boolean,
         loop: Boolean,
-        mixWithOthers: Boolean, // Added parameter
+        mixWithOthers: Boolean,
+        duck: Boolean,
     ) {
         handler.post {
             try {
                 if (player == null) {
                     player = ExoPlayer.Builder(reactContext).build()
+                } else if (shouldStopPrevious) {
+                    player?.pause()
+                    player?.stop()
+                    player?.clearMediaItems()
+                }
 
-                    // Set Audio Attributes based on mixWithOthers
-                    val audioAttributes =
-                        com.google.android.exoplayer2.audio.AudioAttributes
-                            .Builder()
-                            .setUsage(
-                                if (mixWithOthers) {
-                                    com.google.android.exoplayer2.C.USAGE_NOTIFICATION
-                                } else {
-                                    com.google.android.exoplayer2.C.USAGE_MEDIA
-                                },
-                            ).setContentType(com.google.android.exoplayer2.C.AUDIO_CONTENT_TYPE_SONIFICATION)
-                            .build()
-
-                    player?.setAudioAttributes(audioAttributes, !mixWithOthers) // handleAudioFocus = !mixWithOthers
-
-                    player?.addListener(
-                        object : Player.Listener {
-                            override fun onPlaybackStateChanged(state: Int) {
-                                val params = Arguments.createMap()
-                                val status =
-                                    when (state) {
-                                        Player.STATE_BUFFERING -> "BUFFERING"
-                                        Player.STATE_READY -> if (player?.isPlaying == true) "PLAYING" else "PAUSED"
-                                        Player.STATE_ENDED -> "ENDED"
-                                        else -> "IDLE"
-                                    }
-                                params.putString("status", status)
-                                reactContext
-                                    .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
-                                    .emit("onPlaybackStatus", params)
-
-                                if (state == Player.STATE_READY && player?.isPlaying == true) {
-                                    playbackHandler.post(playbackRunnable)
-                                } else if (state == Player.STATE_ENDED) {
-                                    playbackHandler.removeCallbacks(playbackRunnable)
-                                    val finishParams = Arguments.createMap()
-                                    finishParams.putBoolean("finished", true)
-                                    reactContext
-                                        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
-                                        .emit("onPlaybackFinished", finishParams)
-                                }
-                            }
-
-                            override fun onIsPlayingChanged(isPlaying: Boolean) {
-                                val params = Arguments.createMap()
-                                params.putString("status", if (isPlaying) "PLAYING" else "PAUSED")
-                                reactContext
-                                    .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
-                                    .emit("onPlaybackStatus", params)
-
-                                if (isPlaying) {
-                                    playbackHandler.post(playbackRunnable)
-                                } else {
-                                    playbackHandler.removeCallbacks(playbackRunnable)
-                                }
-                            }
-                        },
-                    )
-                } else {
-                    if (shouldStopPrevious) {
-                        playbackHandler.removeCallbacks(playbackRunnable)
-                        player?.stop()
-                        player?.clearMediaItems()
+                val usage =
+                    when {
+                        mixWithOthers -> com.google.android.exoplayer2.C.USAGE_NOTIFICATION
+                        duck -> com.google.android.exoplayer2.C.USAGE_ASSISTANCE_SONIFICATION
+                        else -> com.google.android.exoplayer2.C.USAGE_MEDIA
                     }
 
-                    // Update attributes for existing player if strategy changed
-                    val audioAttributes =
-                        com.google.android.exoplayer2.audio.AudioAttributes
-                            .Builder()
-                            .setUsage(
-                                if (mixWithOthers) {
-                                    com.google.android.exoplayer2.C.USAGE_NOTIFICATION
-                                } else {
-                                    com.google.android.exoplayer2.C.USAGE_MEDIA
-                                },
-                            ).setContentType(com.google.android.exoplayer2.C.AUDIO_CONTENT_TYPE_SONIFICATION)
-                            .build()
-                    player?.setAudioAttributes(audioAttributes, !mixWithOthers)
-                }
+                val audioAttributes =
+                    com.google.android.exoplayer2.audio.AudioAttributes
+                        .Builder()
+                        .setUsage(usage)
+                        .setContentType(com.google.android.exoplayer2.C.AUDIO_CONTENT_TYPE_MUSIC)
+                        .build()
+
+                player?.setAudioAttributes(audioAttributes, !mixWithOthers && !duck)
 
                 val mediaItem = MediaItem.fromUri(Uri.parse(uriString))
                 player?.apply {

package/index.d.ts

@@ -1,44 +1,135 @@
+export type PermissionStatus = "granted" | "denied" | "blocked" | "unavailable";
 export type PlaybackStatus = "BUFFERING" | "PLAYING" | "PAUSED" | "ENDED" | "IDLE";
 
+/**
+ * Options for playback audio
+ */
+export type PlaybackOptions = {
+    /** Audio URI or local file path */
+    uri: string;
+    /** Stop previous playback? Default: false */
+    shouldStopPrevious?: boolean;
+    /** Loop playback? Default: false */
+    loop?: boolean;
+    /** Mix audio with other apps? Default: true */
+    mixWithOthers?: boolean;
+    /** Duck other audio while playing? Default: false */
+    duck?: boolean;
+    /** Callback handlers */
+    callbacks?: {
+        /** Called when playback finishes */
+        onPlaybackFinished?: () => void;
+        /** Called on playback status changes */
+        onStatus?: (status: PlaybackStatus) => void;
+        /** Called periodically with current position and duration */
+        onProgress?: (currentPosition: number, duration: number) => void;
+    };
+};
+
+/**
+ * Options for recording audio
+ */
+export type RecordingOptions = {
+    /** Optional file name. Default: "rec_<timestamp>" */
+    fileName?: string | null;
+    /** Stop other playback while recording? Default: true */
+    shouldStopPlayback?: boolean;
+    /** Callback fired every second with elapsed seconds */
+    onSecondsUpdate?: (seconds: number) => void;
+};
+
+/**
+ * Recplay Module
+ * All functions use options objects for better autocomplete and clarity.
+ */
 declare const Recplay: {
-    startRecording: (
-        fileName?: string | null,
-        shouldStopPlayback?: boolean,
-        onSecondsUpdate?: (seconds: number) => void
-    ) => Promise<string>;
+    /**
+     * Start recording audio
+     * @example
+     * const fileName = await Recplay.startRecording({
+     *   fileName: "myrec",
+     *   shouldStopPlayback: true,
+     *   onSecondsUpdate: (s) => console.log("Recording seconds:", s)
+     * });
+     */
+    startRecording: (options?: RecordingOptions) => Promise<string>;
 
+    /**
+     * Stop current recording
+     * @example
+     * const recordedFile = await Recplay.stopRecording();
+     * console.log("Recorded file path:", recordedFile);
+     */
     stopRecording: () => Promise<string>;
+
+    /**
+     * Pause current recording
+     * @example
+     * await Recplay.pauseRecording();
+     */
     pauseRecording: () => Promise<boolean>;
+
+    /**
+     * Resume paused recording
+     * @example
+     * await Recplay.resumeRecording();
+     */
     resumeRecording: () => Promise<boolean>;
-    seekTo: (seconds: number) => void;
 
     /**
-     * Checks the current microphone permission status.
+     * Seek current playback to seconds
+     * @example
+     * Recplay.seekTo({ seconds: 30 });
+     */
+    seekTo: (options: { seconds: number }) => void;
+
+    /**
+     * Check microphone permission
+     * @example
+     * const status = await Recplay.checkPermission();
+     * console.log(status); // "granted" | "denied" | "blocked" | "unavailable"
      */
     checkPermission: () => Promise<PermissionStatus>;
 
     /**
-     * Triggers the system permission dialog.
+     * Request microphone permission
+     * @example
+     * const status = await Recplay.requestPermission();
+     * console.log(status); // "granted" | "denied" | "blocked" | "unavailable"
      */
     requestPermission: () => Promise<PermissionStatus>;
 
     /**
-     * Plays audio with optional status and progress tracking.
-     * Order: uri, shouldStopPrevious, loop, mixWithOthers, callbacks
+     * Play audio with options object
+     * @example
+     * Recplay.playAudio({
+     *   uri: "file.mp3",
+     *   shouldStopPrevious: true,
+     *   loop: false,
+     *   mixWithOthers: false,
+     *   duck: true,
+     *   callbacks: {
+     *     onStatus: (s) => console.log("Status:", s),
+     *     onProgress: (cur, dur) => console.log("Progress:", cur, "/", dur),
+     *     onPlaybackFinished: () => console.log("Playback finished")
+     *   }
+     * });
      */
-    playAudio: (
-        uri: string,
-        shouldStopPrevious?: boolean,
-        loop?: boolean,
-        mixWithOthers?: boolean,
-        callbacks?: {
-            onPlaybackFinished?: () => void;
-            onStatus?: (status: PlaybackStatus) => void;
-            onProgress?: (currentPosition: number, duration: number) => void;
-        }
-    ) => void;
+    playAudio: (options: PlaybackOptions) => void;
 
-    stopPlayback: () => Promise<boolean>;
+    /**
+     * Stop current playback
+     * @example
+     * await Recplay.stopPlayback({ notifyOthers: true });
+     */
+    stopPlayback: (options?: { notifyOthers?: boolean }) => Promise<boolean>;
+
+
+    /**
+     * Toggle playback pause/resume
+     * @example
+     * Recplay.togglePlayback();
+     */
     togglePlayback: () => void;
 };
 

package/index.js

@@ -9,47 +9,44 @@ let internalStatusSub = null;
 let internalProgressSub = null;
 
 const Recplay = {
-    startRecording: async (fileName = null, shouldStopPlayback = true, onSecondsUpdate = null) => {
+
+    /** Start recording with options object */
+    startRecording: async ({ fileName = null, shouldStopPlayback = true, onSecondsUpdate = null } = {}) => {
         if (internalSub) internalSub.remove();
         if (onSecondsUpdate) {
             internalSub = eventEmitter.addListener('onTimerUpdate', (data) => onSecondsUpdate(data.seconds));
         }
         return RecPlayModule.startRecording(fileName, shouldStopPlayback);
     },
-    /**
-         * Checks the current microphone permission status.
-         * Expected returns from Native: "granted", "denied", "blocked", or "unavailable"
-         */
-    checkPermission: async () => {
-        return RecPlayModule.checkPermission();
-    },
-
-    /**
-     * Triggers the system permission dialog.
-     */
-    requestPermission: async () => {
-        return RecPlayModule.requestPermission();
-    },
 
+    /** Stop recording */
     stopRecording: async () => {
         if (internalSub) { internalSub.remove(); internalSub = null; }
         return RecPlayModule.stopRecording();
     },
 
-    /**
-      * @param {string} uri 
-      * @param {boolean} shouldStopPrevious 
-      * @param {boolean} loop 
-      * @param {boolean} mixWithOthers
-      * @param {object} callbacks 
-      */
-    playAudio: (uri, shouldStopPrevious = false, loop = false, mixWithOthers = true, callbacks = {}) => {
-        // Cleanup listeners
+    /** Pause recording */
+    pauseRecording: () => RecPlayModule.pauseRecording(),
+
+    /** Resume recording */
+    resumeRecording: () => RecPlayModule.resumeRecording(),
+
+    /** Seek playback with options object */
+    seekTo: ({ seconds }) => RecPlayModule.seekTo(seconds),
+
+    /** Check microphone permission */
+    checkPermission: () => RecPlayModule.checkPermission(),
+
+    /** Request microphone permission */
+    requestPermission: () => RecPlayModule.requestPermission(),
+
+    /** Play audio with options object */
+    playAudio: ({ uri, shouldStopPrevious = false, loop = false, mixWithOthers = true, duck = false, callbacks = {} }) => {
         [internalPlaySub, internalStatusSub, internalProgressSub].forEach(s => s?.remove());
 
-        if (callbacks.onFinished) {
+        if (callbacks.onPlaybackFinished) {
             internalPlaySub = eventEmitter.addListener('onPlaybackFinished', () => {
-                callbacks.onFinished();
+                callbacks.onPlaybackFinished();
                 internalPlaySub?.remove();
             });
         }
@@ -64,19 +61,18 @@ const Recplay = {
             );
         }
 
-        // Pass all three arguments to Native
-        RecPlayModule.playAudio(uri, shouldStopPrevious, loop, mixWithOthers);
+        // Map named params to native positional params
+        RecPlayModule.playAudio(uri, shouldStopPrevious, loop, mixWithOthers, duck);
     },
 
-    stopPlayback: () => {
+    /** Stop playback */
+    stopPlayback: ({ notifyOthers = true } = {}) => {
         [internalPlaySub, internalStatusSub, internalProgressSub].forEach(s => s?.remove());
-        return RecPlayModule.stopPlayback();
+        return RecPlayModule.stopPlayback(notifyOthers);
     },
 
-    seekTo: (seconds) => RecPlayModule.seekTo(seconds),
-    pauseRecording: () => RecPlayModule.pauseRecording(),
-    resumeRecording: () => RecPlayModule.resumeRecording(),
-    togglePlayback: () => RecPlayModule.togglePlayback()
+    /** Toggle playback pause/resume */
+    togglePlayback: () => RecPlayModule.togglePlayback(),
 };
 
-export default Recplay;
+export default Recplay;

package/ios/RecPlayModule.m

@@ -1,41 +1,65 @@
 #import <React/RCTBridgeModule.h>
 #import <React/RCTEventEmitter.h>
 
-@interface RCT_EXTERN_MODULE (RecPlayModule, RCTEventEmitter)
+@interface RCT_EXTERN_MODULE(RecPlayModule, RCTEventEmitter)
 
 // --- Permissions ---
-RCT_EXTERN_METHOD(checkPermission : (RCTPromiseResolveBlock)
-                      resolve rejecter : (RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(checkPermission
+                  : (RCTPromiseResolveBlock)resolve
+                  rejecter
+                  : (RCTPromiseRejectBlock)reject)
 
-RCT_EXTERN_METHOD(requestPermission : (RCTPromiseResolveBlock)
-                      resolve rejecter : (RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(requestPermission
+                  : (RCTPromiseResolveBlock)resolve
+                  rejecter
+                  : (RCTPromiseRejectBlock)reject)
 
 // --- Recording ---
-RCT_EXTERN_METHOD(startRecording : (NSString *)fileName shouldStopPlayback : (
-    BOOL)shouldStopPlayback resolver : (RCTPromiseResolveBlock)
-                      resolve rejecter : (RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(startRecording
+                  : (NSString *)fileName
+                  shouldStopPlayback
+                  : (BOOL)shouldStopPlayback
+                  resolver
+                  : (RCTPromiseResolveBlock)resolve
+                  rejecter
+                  : (RCTPromiseRejectBlock)reject)
 
-RCT_EXTERN_METHOD(stopRecording : (RCTPromiseResolveBlock)
-                      resolve rejecter : (RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(stopRecording
+                  : (RCTPromiseResolveBlock)resolve
+                  rejecter
+                  : (RCTPromiseRejectBlock)reject)
 
-RCT_EXTERN_METHOD(pauseRecording : (RCTPromiseResolveBlock)
-                      resolve rejecter : (RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(pauseRecording
+                  : (RCTPromiseResolveBlock)resolve
+                  rejecter
+                  : (RCTPromiseRejectBlock)reject)
 
-RCT_EXTERN_METHOD(resumeRecording : (RCTPromiseResolveBlock)
-                      resolve rejecter : (RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(resumeRecording
+                  : (RCTPromiseResolveBlock)resolve
+                  rejecter
+                  : (RCTPromiseRejectBlock)reject)
 
 // --- Playback ---
-// UPDATED: Added mixWithOthers (BOOL) parameter
-RCT_EXTERN_METHOD(playAudio : (NSString *)uri 
-                  shouldStopPrevious : (BOOL)shouldStopPrevious 
-                  loop : (BOOL)loop 
-                  mixWithOthers : (BOOL)mixWithOthers)
+// UPDATED: mixWithOthers + duckOthers
+RCT_EXTERN_METHOD(playAudio
+                  : (NSString *)uri
+                  shouldStopPrevious
+                  : (BOOL)shouldStopPrevious
+                  loop
+                  : (BOOL)loop
+                  mixWithOthers
+                  : (BOOL)mixWithOthers
+                  duckOthers
+                  : (BOOL)duckOthers)
 
-RCT_EXTERN_METHOD(stopPlayback : (RCTPromiseResolveBlock)
-                      resolve rejecter : (RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(stopPlayback
+                  : (RCTPromiseResolveBlock)resolve
+                  rejecter
+                  : (RCTPromiseRejectBlock)reject)
 
-RCT_EXTERN_METHOD(seekTo : (double)seconds)
+RCT_EXTERN_METHOD(seekTo
+                  : (double)seconds)
 
 RCT_EXTERN_METHOD(togglePlayback)
 
-@end
+@end

package/ios/RecPlayModule.swift

@@ -9,7 +9,6 @@ class RecPlayModule: RCTEventEmitter {
     private var audioPlayer: AVPlayer?
     private var playerItem: AVPlayerItem?
     private var timeObserverToken: Any?
-
     private var recordingTimer: Timer?
     private var secondsElapsed = 0
     private var isPaused = false
@@ -20,14 +19,36 @@ class RecPlayModule: RCTEventEmitter {
     }
 
     override func supportedEvents() -> [String]! {
-        return ["onTimerUpdate", "onPlaybackStatus", "onPlaybackProgress", "onPlaybackFinished"]
+        return ["onTimerUpdate", "onPlaybackStatus", "onPlaybackProgress", "onPlaybackFinished", "onAudioInterruption"]
+    }
+
+    override init() {
+        super.init()
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleAudioSessionInterruption(_:)),
+            name: AVAudioSession.interruptionNotification,
+            object: nil
+        )
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleRouteChange(_:)),
+            name: AVAudioSession.routeChangeNotification,
+            object: nil
+        )
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
     }
 
     // MARK: - Recording Logic
 
     @objc(startRecording:shouldStopPlayback:resolver:rejecter:)
     func startRecording(
-        fileName: String?, shouldStopPlayback: Bool, resolve: @escaping RCTPromiseResolveBlock,
+        fileName: String?,
+        shouldStopPlayback: Bool,
+        resolve: @escaping RCTPromiseResolveBlock,
         reject: @escaping RCTPromiseRejectBlock
     ) {
 
@@ -36,42 +57,51 @@ class RecPlayModule: RCTEventEmitter {
         }
 
         let session = AVAudioSession.sharedInstance()
+
         do {
-            try session.setCategory(
-                .playAndRecord, mode: .default, options: [.defaultToSpeaker, .allowBluetooth])
+            // use mixWithOthers so existing music can continue (if possible)
+            let options: AVAudioSession.CategoryOptions = [.defaultToSpeaker, .duckOthers]
+
+            // If session was previously active in playback, reset to clean slate
+            try? session.setActive(false)
+
+            try session.setCategory(.playAndRecord, mode: .default, options: options)
             try session.setActive(true)
 
             let name = fileName ?? "rec_\(Int(Date().timeIntervalSince1970))"
-            let fileURL = FileManager.default.temporaryDirectory.appendingPathComponent(
-                "\(name).m4a")
+            let fileURL = FileManager.default.temporaryDirectory
+                .appendingPathComponent("\(name).m4a")
 
             let settings: [String: Any] = [
                 AVFormatIDKey: Int(kAudioFormatMPEG4AAC),
                 AVSampleRateKey: 44100,
                 AVNumberOfChannelsKey: 1,
                 AVEncoderAudioQualityKey: AVAudioQuality.high.rawValue,
-                AVEncoderBitRateKey: 128000,
+                AVEncoderBitRateKey: 128000
             ]
 
             audioRecorder = try AVAudioRecorder(url: fileURL, settings: settings)
             audioRecorder?.prepareToRecord()
             audioRecorder?.record()
 
-            self.secondsElapsed = 0
-            self.isPaused = false
+            secondsElapsed = 0
+            isPaused = false
 
             DispatchQueue.main.async {
                 self.recordingTimer?.invalidate()
-                self.recordingTimer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) {
-                    _ in
+                self.recordingTimer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { _ in
                     if !self.isPaused {
                         self.sendEvent(
-                            withName: "onTimerUpdate", body: ["seconds": self.secondsElapsed])
+                            withName: "onTimerUpdate",
+                            body: ["seconds": self.secondsElapsed]
+                        )
                         self.secondsElapsed += 1
                     }
                 }
             }
+
             resolve(name)
+
         } catch {
             reject("REC_ERROR", "Failed to start recording", error)
         }
@@ -79,8 +109,10 @@ class RecPlayModule: RCTEventEmitter {
 
     @objc(stopRecording:rejecter:)
     func stopRecording(
-        resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
     ) {
+
         recordingTimer?.invalidate()
         recordingTimer = nil
 
@@ -88,6 +120,14 @@ class RecPlayModule: RCTEventEmitter {
         let url = audioRecorder?.url
         audioRecorder = nil
 
+        // notify other audio that we deactivated so they can resume
+        do {
+            try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+        } catch {
+            // non-fatal
+            print("⚠️ setActive(false) failed: \(error.localizedDescription)")
+        }
+
         if let fileUrl = url {
             resolve(fileUrl.absoluteString)
         } else {
@@ -113,8 +153,10 @@ class RecPlayModule: RCTEventEmitter {
 
     @objc(checkPermission:rejecter:)
     func checkPermission(
-        resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
     ) {
+
         let status = AVAudioSession.sharedInstance().recordPermission
 
         switch status {
@@ -123,7 +165,7 @@ class RecPlayModule: RCTEventEmitter {
         case .denied:
             resolve("blocked")
         case .undetermined:
-            resolve("denied")  // "denied" in JS means "not asked yet", so we can request
+            resolve("denied")
         @unknown default:
             resolve("unavailable")
         }
@@ -131,121 +173,145 @@ class RecPlayModule: RCTEventEmitter {
 
     @objc(requestPermission:rejecter:)
     func requestPermission(
-        resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock
+        resolve: @escaping RCTPromiseResolveBlock,
+        reject: @escaping RCTPromiseRejectBlock
     ) {
+
         AVAudioSession.sharedInstance().requestRecordPermission { granted in
-            if granted {
-                resolve("granted")
-            } else {
-                // After the popup, if they say no, it becomes blocked
-                resolve("blocked")
-            }
+            resolve(granted ? "granted" : "blocked")
         }
     }
 
-    // MARK: - Playback Logic
+    // MARK: - Playback Logic (UPDATED)
+    @objc(playAudio:shouldStopPrevious:loop:mixWithOthers:duckOthers:)
+    func playAudio(
+        uri: String,
+        shouldStopPrevious: Bool,
+        loop: Bool,
+       mixWithOthers: Bool,
+        duckOthers: Bool
+    ) {DispatchQueue.main.async { [weak self] in
+        guard let self = self else { return }
+
+        if shouldStopPrevious {
+            self.stopPlaybackInternal()
+        }
 
-    @objc(playAudio:shouldStopPrevious:loop:mixWithOthers:)
-func playAudio(uri: String, shouldStopPrevious: Bool, loop: Bool, mixWithOthers: Bool) {
-    if shouldStopPrevious {
-        stopPlaybackInternal()
-    }
+        let session = AVAudioSession.sharedInstance()
 
-    let session = AVAudioSession.sharedInstance()
-    do {
-        if mixWithOthers {
-            // MixWithOthers: Plays alongside background music
-            // DefaultToSpeaker: Uses main speaker instead of earpiece
-            try session.setCategory(
-                .playback, 
-                mode: .default, 
-                options: [.mixWithOthers, .defaultToSpeaker]
-            )
+        do {
+            try session.setActive(false)
+
+            var options: AVAudioSession.CategoryOptions = []
+
+            if mixWithOthers {
+                options.insert(.mixWithOthers)
+            } else if duckOthers {
+                options.insert(.duckOthers)
+            }
+
+            try session.setCategory(.playback, mode: .default, options: options)
+            try session.setActive(true)
+
+        } catch {
+            print("⚠️ Audio Session Error: \(error.localizedDescription)")
+            return
+        }
+
+        let url: URL
+        if uri.hasPrefix("http") || uri.hasPrefix("file://") {
+            guard let u = URL(string: uri) else { return }
+            url = u
         } else {
-            // Standard: Stops other audio apps (Spotify/Music)
-            try session.setCategory(
-                .playback, 
-                mode: .default, 
-                options: [.defaultToSpeaker]
-            )
+            url = URL(fileURLWithPath: uri)
         }
-        try session.setActive(true)
-    } catch {
-        print("DEBUG: Failed to set audio session: \(error)")
-        self.sendEvent(withName: "onPlaybackStatus", body: ["status": "ERROR"])
-        return
-    }
 
-    guard let url = URL(string: uri) else { return }
+        let asset = AVURLAsset(url: url)
+        self.playerItem = AVPlayerItem(asset: asset)
+        self.isLooping = loop
 
-    let asset = AVURLAsset(url: url)
-    self.playerItem = AVPlayerItem(asset: asset)
-    self.isLooping = loop
+        self.playerItem?.addObserver(self, forKeyPath: "status", options: [.new], context: nil)
 
-    self.playerItem?.preferredForwardBufferDuration = 2.0
-    self.playerItem?.addObserver(self, forKeyPath: "status", options: [.new], context: nil)
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(self.playerDidFinishPlaying),
+            name: .AVPlayerItemDidPlayToEndTime,
+            object: self.playerItem
+        )
 
-    NotificationCenter.default.addObserver(
-        self, 
-        selector: #selector(playerDidFinishPlaying), 
-        name: .AVPlayerItemDidPlayToEndTime,
-        object: self.playerItem
-    )
+        if self.audioPlayer == nil {
+            self.audioPlayer = AVPlayer(playerItem: self.playerItem)
+        } else {
+            self.audioPlayer?.replaceCurrentItem(with: self.playerItem)
+        }
 
-    if audioPlayer == nil {
-        audioPlayer = AVPlayer(playerItem: self.playerItem)
-    } else {
-        audioPlayer?.replaceCurrentItem(with: self.playerItem)
-    }
+        self.setupProgressObserver()
+        self.audioPlayer?.play()
 
-    audioPlayer?.automaticallyWaitsToMinimizeStalling = true
+        self.sendEvent(withName: "onPlaybackStatus", body: ["status": "PLAYING"])
+    }}
 
-    setupProgressObserver()
-    audioPlayer?.play()
-    self.sendEvent(withName: "onPlaybackStatus", body: ["status": "PLAYING"])
-}
 
     private func setupProgressObserver() {
+
         if let token = timeObserverToken {
             audioPlayer?.removeTimeObserver(token)
         }
+
         let interval = CMTime(seconds: 0.5, preferredTimescale: 1000)
+
         timeObserverToken = audioPlayer?.addPeriodicTimeObserver(
-            forInterval: interval, queue: .main
+            forInterval: interval,
+            queue: .main
         ) { [weak self] time in
-            guard let self = self,
+            guard
+                let self = self,
                 let duration = self.audioPlayer?.currentItem?.duration.seconds,
-                duration > 0, !duration.isNaN
+                duration > 0,
+                !duration.isNaN
             else { return }
 
             self.sendEvent(
                 withName: "onPlaybackProgress",
                 body: [
                     "currentPosition": time.seconds,
-                    "duration": duration,
-                ])
+                    "duration": duration
+                ]
+            )
         }
     }
 
     @objc(stopPlayback:rejecter:)
     func stopPlayback(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         stopPlaybackInternal()
+        // notify others so they can resume
+        do {
+            try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+        } catch {
+            print("⚠️ setActive(false) failed: \(error.localizedDescription)")
+        }
         resolve(true)
     }
 
     private func stopPlaybackInternal() {
+
         if let token = timeObserverToken {
             audioPlayer?.removeTimeObserver(token)
             timeObserverToken = nil
         }
+
         audioPlayer?.pause()
         audioPlayer = nil
 
         if let item = playerItem {
             item.removeObserver(self, forKeyPath: "status")
             NotificationCenter.default.removeObserver(
-                self, name: .AVPlayerItemDidPlayToEndTime, object: item)
+                self,
+                name: .AVPlayerItemDidPlayToEndTime,
+                object: item
+            )
         }
+
         playerItem = nil
     }
 
@@ -265,25 +331,86 @@ func playAudio(uri: String, shouldStopPrevious: Bool, loop: Bool, mixWithOthers:
     }
 
     override func observeValue(
-        forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey: Any]?,
+        forKeyPath keyPath: String?,
+        of object: Any?,
+        change: [NSKeyValueChangeKey: Any]?,
         context: UnsafeMutableRawPointer?
     ) {
+
         if keyPath == "status", let item = object as? AVPlayerItem {
             if item.status == .failed {
-                self.sendEvent(withName: "onPlaybackStatus", body: ["status": "ERROR"])
+                sendEvent(withName: "onPlaybackStatus", body: ["status": "ERROR"])
             } else if item.status == .readyToPlay {
+                // ready, but we don't force other players to resume here
                 print("DEBUG: Audio Ready")
             }
         }
     }
 
     @objc func playerDidFinishPlaying(note: NSNotification) {
+
         if isLooping {
             audioPlayer?.seek(to: .zero)
             audioPlayer?.play()
         } else {
-            self.sendEvent(withName: "onPlaybackFinished", body: ["finished": true])
-            self.sendEvent(withName: "onPlaybackStatus", body: ["status": "ENDED"])
+            sendEvent(withName: "onPlaybackFinished", body: ["finished": true])
+            sendEvent(withName: "onPlaybackStatus", body: ["status": "ENDED"])
+            // deactivate so others can resume
+            do {
+                try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+            } catch {
+                print("⚠️ setActive(false) failed: \(error.localizedDescription)")
+            }
+        }
+    }
+
+    // MARK: - Interruption & Route Handling
+
+    @objc private func handleAudioSessionInterruption(_ notification: Notification) {
+        guard let info = notification.userInfo,
+              let typeValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
+              let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
+            return
+        }
+
+        switch type {
+        case .began:
+            // interruption began (phone call, Siri, alarm, etc.)
+            sendEvent(withName: "onAudioInterruption", body: ["type": "began"])
+            print("🔇 Audio interruption began")
+        case .ended:
+            // interruption ended — optionally reactivate
+            let optionsValue = info[AVAudioSessionInterruptionOptionKey] as? UInt
+            let shouldResume = (optionsValue ?? 0) & AVAudioSession.InterruptionOptions.shouldResume.rawValue != 0
+            sendEvent(withName: "onAudioInterruption", body: ["type": "ended", "shouldResume": shouldResume])
+            if shouldResume {
+                // try to reactivate and resume playback if appropriate
+                do {
+                    try AVAudioSession.sharedInstance().setActive(true)
+                    audioPlayer?.play()
+                } catch {
+                    print("⚠️ Failed to reactivate after interruption: \(error.localizedDescription)")
+                }
+            }
+            print("🔊 Audio interruption ended. shouldResume: \(shouldResume)")
+        @unknown default:
+            break
+        }
+    }
+
+    @objc private func handleRouteChange(_ notification: Notification) {
+        guard let userInfo = notification.userInfo,
+              let reasonValue = userInfo[AVAudioSessionRouteChangeReasonKey] as? UInt,
+              let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else { return }
+
+        switch reason {
+        case .oldDeviceUnavailable:
+            // e.g., headphones unplugged
+            print("🔊 Route changed: old device unavailable")
+        case .newDeviceAvailable:
+            print("🔊 Route changed: new device available")
+        default:
+            break
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rns-recplay",
-    "version": "1.3.2",
+    "version": "1.3.4",
     "description": "High-performance React Native module for audio recording and audio playback on Android and iOS.",
     "main": "index.js",
     "types": "index.d.ts",