react-native-mp3-player 1.0.0 → 1.0.2

package/README.md

@@ -23,7 +23,15 @@ React Native audio player with **reliable iOS background playback**, media contr
 npm install react-native-mp3-player
 ```
 
-Link native projects (see [React Native docs](https://reactnative.dev/docs/linking-libraries-ios)). On iOS, enable **Background Modes → Audio** in your app capabilities.
+Link native projects (see [React Native docs](https://reactnative.dev/docs/linking-libraries-ios)).
+
+### iOS background playback
+
+For audio to continue when the app is backgrounded or the screen is locked (and to avoid the ~50 second cutoff), you must:
+
+1. **Enable Background Modes → Audio** (or “Audio, AirPlay, and Picture in Picture”) in your app’s Xcode project: select your target → **Signing & Capabilities** → **+ Capability** → **Background Modes** → check **Audio**.
+2. The package configures **AVAudioSession** (category `.playback` with options for Bluetooth, AirPlay, ducking) and handles **interruptions** and **background transitions** so that playback can continue when the app is backgrounded.
+3. **Lock screen and Control Center** controls (play, pause, seek, 15-second skip) are handled **natively**, so they work even when the JavaScript thread is suspended (e.g. screen locked). When the app returns to the foreground, events are emitted so your UI stays in sync.
 
 ## Quick start
 
@@ -58,13 +66,13 @@ TrackPlayer.registerPlaybackService(() => PlaybackService);
 ## API overview
 
 - **Lifecycle:** `setupPlayer(options?, background?)`, `registerPlaybackService(factory)`, `reset()`
-- **Queue:** `add()`, `load()`, `remove()`, `skip()`, `skipToNext()`, `skipToPrevious()`, `setQueue()`, `getQueue()`, `getActiveTrack()`, `getActiveTrackIndex()`
+- **Queue:** `add()`, `load()`, `remove()`, `skip()`, `skipToNext()`, `skipToPrevious()`, `setQueue()`, `getQueue()`, **`getActiveTrack()`** (current track), `getActiveTrackIndex()`
 - **Playback:** `play()`, `pause()`, `stop()`, `seekTo()`, `seekBy()`, `setVolume()`, `setRate()`, `setRepeatMode()`
 - **State:** `getPlaybackState()`, `getProgress()`, `getVolume()`, `getRate()`
 - **Events:** `addEventListener(event, listener)` – see `Event` enum.
-- **Hooks:** `useProgress()`, `usePlaybackState()`, `useActiveTrack()`, `useIsPlaying()`, `useTrackPlayerEvents()`, etc.
+- **Hooks:** **`useProgress(updateInterval?, background?)`** (interval in **milliseconds**; e.g. `useProgress(250)` = every 250 ms), `usePlaybackState()`, `useActiveTrack()`, `useIsPlaying()`, `useTrackPlayerEvents()`, etc.
 
-Types and options are in the package TypeScript definitions.
+**Setup options** (e.g. in `setupPlayer` / `updateOptions`): `iosCategory` (e.g. `'playback'`), `iosCategoryOptions` (e.g. `['allowAirPlay','allowBluetooth','duckOthers']`), `autoHandleInterruptions`, `autoUpdateMetadata`, `waitForBuffer`, `minBuffer` / buffer-related options, `forwardJumpInterval` / `backwardJumpInterval` (seconds, e.g. 15), `progressUpdateEventInterval` (seconds). Types and options are in the package TypeScript definitions.
 
 ## Example app
 

package/ios/RNTrackPlayer/RNTrackPlayer.swift

@@ -7,6 +7,7 @@ import Foundation
 import AVFoundation
 import MediaPlayer
 import React
+import UIKit
 
 @objc public protocol RNTPDelegate {
     func sendEvent(name: String, body: Any)
@@ -32,10 +33,13 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
 
     // MARK: - Lifecycle Methods
 
+    /// Default options for .playback category (no .defaultToSpeaker; that is only valid for .playbackAndRecord).
+    private static let defaultPlaybackCategoryOptions: AVAudioSession.CategoryOptions = [.allowBluetooth, .allowBluetoothA2DP, .allowAirPlay, .duckOthers]
+
     public override init() {
         super.init()
         audioSessionController.delegate = self
-        player.playWhenReady = false;
+        player.playWhenReady = false
         player.event.receiveChapterMetadata.addListener(self, handleAudioPlayerChapterMetadataReceived)
         player.event.receiveTimedMetadata.addListener(self, handleAudioPlayerTimedMetadataReceived)
         player.event.receiveCommonMetadata.addListener(self, handleAudioPlayerCommonMetadataReceived)
@@ -44,6 +48,12 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         player.event.currentItem.addListener(self, handleAudioPlayerCurrentItemChange)
         player.event.secondElapse.addListener(self, handleAudioPlayerSecondElapse)
         player.event.playWhenReadyChange.addListener(self, handlePlayWhenReadyChange)
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleDidEnterBackground),
+            name: UIApplication.didEnterBackgroundNotification,
+            object: nil
+        )
     }
 
     deinit {
@@ -65,10 +75,12 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
             ])
         case let .ended(shouldResume):
             if shouldResume {
-                if (shouldResumePlaybackAfterInterruptionEnds) {
+                do {
+                    try AVAudioSession.sharedInstance().setActive(true, options: [])
+                } catch {}
+                if shouldResumePlaybackAfterInterruptionEnds {
                     player.play()
                 }
-                // Interruption Ended - playback should resume
                 emit(event: EventType.RemoteDuck, body: [
                     "paused": false
                 ])
@@ -154,8 +166,11 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         }
 
         let sessionCategoryOptsStr = config["iosCategoryOptions"] as? [String]
-        let mappedCategoryOpts = sessionCategoryOptsStr?.compactMap { SessionCategoryOptions(rawValue: $0)?.mapConfigToAVAudioSessionCategoryOptions() } ?? []
-        sessionCategoryOptions = AVAudioSession.CategoryOptions(mappedCategoryOpts)
+        if let opts = sessionCategoryOptsStr?.compactMap({ SessionCategoryOptions(rawValue: $0)?.mapConfigToAVAudioSessionCategoryOptions() }), !opts.isEmpty {
+            sessionCategoryOptions = AVAudioSession.CategoryOptions(opts)
+        } else if sessionCategory == .playback {
+            sessionCategoryOptions = Self.defaultPlaybackCategoryOptions
+        }
 
         if config["iosCategoryPolicy"] == nil && sessionCategory == .playback {
             sessionCategoryPolicy = .longFormAudio
@@ -164,67 +179,84 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         configureAudioSessionForBackgroundPlayback()
         configureAudioSession()
 
-        // setup event listeners
+        // Remote command handlers: perform native action first (so lock screen/Control Center work when JS is suspended), then emit for UI sync.
         player.remoteCommandController.handleChangePlaybackPositionCommand = { [weak self] event in
-            if let event = event as? MPChangePlaybackPositionCommandEvent {
-                self?.emit(event: EventType.RemoteSeek, body: ["position": event.positionTime])
-                return MPRemoteCommandHandlerStatus.success
+            guard let self = self, let event = event as? MPChangePlaybackPositionCommandEvent else {
+                return MPRemoteCommandHandlerStatus.commandFailed
             }
-
-            return MPRemoteCommandHandlerStatus.commandFailed
+            self.player.seek(to: event.positionTime)
+            self.emit(event: EventType.RemoteSeek, body: ["position": event.positionTime])
+            return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handleNextTrackCommand = { [weak self] _ in
-            self?.emit(event: EventType.RemoteNext)
+            guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.player.next()
+            self.emit(event: EventType.RemoteNext)
             return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handlePauseCommand = { [weak self] _ in
-            self?.emit(event: EventType.RemotePause)
+            guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.player.pause()
+            self.emit(event: EventType.RemotePause)
             return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handlePlayCommand = { [weak self] _ in
-            self?.emit(event: EventType.RemotePlay)
+            guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.player.play()
+            self.emit(event: EventType.RemotePlay)
             return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handlePreviousTrackCommand = { [weak self] _ in
-            self?.emit(event: EventType.RemotePrevious)
+            guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.player.previous()
+            self.emit(event: EventType.RemotePrevious)
             return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handleSkipBackwardCommand = { [weak self] event in
-            if let command = event.command as? MPSkipIntervalCommand,
-               let interval = command.preferredIntervals.first {
-                self?.emit(event: EventType.RemoteJumpBackward, body: ["interval": interval])
-                return MPRemoteCommandHandlerStatus.success
+            guard let self = self,
+                  let command = event.command as? MPSkipIntervalCommand,
+                  let interval = command.preferredIntervals.first else {
+                return MPRemoteCommandHandlerStatus.commandFailed
             }
-
-            return MPRemoteCommandHandlerStatus.commandFailed
+            let secs = Double(truncating: interval)
+            self.player.seek(to: self.player.currentTime - secs)
+            self.emit(event: EventType.RemoteJumpBackward, body: ["interval": interval])
+            return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handleSkipForwardCommand = { [weak self] event in
-            if let command = event.command as? MPSkipIntervalCommand,
-               let interval = command.preferredIntervals.first {
-                self?.emit(event: EventType.RemoteJumpForward, body: ["interval": interval])
-                return MPRemoteCommandHandlerStatus.success
+            guard let self = self,
+                  let command = event.command as? MPSkipIntervalCommand,
+                  let interval = command.preferredIntervals.first else {
+                return MPRemoteCommandHandlerStatus.commandFailed
             }
-
-            return MPRemoteCommandHandlerStatus.commandFailed
+            let secs = Double(truncating: interval)
+            self.player.seek(to: self.player.currentTime + secs)
+            self.emit(event: EventType.RemoteJumpForward, body: ["interval": interval])
+            return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handleStopCommand = { [weak self] _ in
-            self?.emit(event: EventType.RemoteStop)
+            guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.player.stop()
+            self.emit(event: EventType.RemoteStop)
             return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handleTogglePlayPauseCommand = { [weak self] _ in
-            self?.emit(event: self?.player.playerState == .paused
-                ? EventType.RemotePlay
-                : EventType.RemotePause
-            )
-
+            guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            if self.player.playerState == .paused {
+                self.player.play()
+                self.emit(event: EventType.RemotePlay)
+            } else {
+                self.player.pause()
+                self.emit(event: EventType.RemotePause)
+            }
             return MPRemoteCommandHandlerStatus.success
         }
 
@@ -261,13 +293,14 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     }
 
     private func configureAudioSession() {
-
-        if (player.currentItem == nil) {
-            try? audioSessionController.deactivateSession()
+        if player.currentItem == nil {
+            if UIApplication.shared.applicationState == .active {
+                try? audioSessionController.deactivateSession()
+            }
             return
         }
 
-        if (player.playWhenReady) {
+        if player.playWhenReady {
             try? audioSessionController.activateSession()
             if #available(iOS 11.0, *) {
                 try? AVAudioSession.sharedInstance().setCategory(sessionCategory, mode: sessionCategoryMode, policy: sessionCategoryPolicy, options: sessionCategoryOptions)
@@ -278,6 +311,19 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         }
     }
 
+    @objc private func handleDidEnterBackground() {
+        guard player.currentItem != nil else { return }
+        let session = AVAudioSession.sharedInstance()
+        do {
+            if #available(iOS 11.0, *) {
+                try session.setCategory(sessionCategory, mode: sessionCategoryMode, policy: sessionCategoryPolicy, options: sessionCategoryOptions)
+            } else {
+                try session.setCategory(sessionCategory, mode: sessionCategoryMode, options: sessionCategoryOptions)
+            }
+            try session.setActive(true, options: [])
+        } catch {}
+    }
+
     @objc(isServiceRunning:rejecter:)
     public func isServiceRunning(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         // TODO That is probably always true
@@ -633,7 +679,7 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         }
         player.clear()
         try? player.add(items: tracks)
-        resolve(index)
+        resolve(NSNull())
     }
 
     @objc(getActiveTrack:rejecter:)

package/ios/SwiftAudioEx/Sources/SwiftAudioEx/AudioTap.swift

@@ -86,12 +86,12 @@ extension AVPlayerWrapper {
         
         
         // https://stackoverflow.com/questions/79679383/unmanaged-object-pointer-build-issues-in-xcode-26-beta
-        // XCode 26 sdk change
-        var tapRef: MTAudioProcessingTap?
+        // Xcode 16+ / 26 SDK: tapOut expects Unmanaged<MTAudioProcessingTap>? (API returns retained CF object).
+        var tapRef: Unmanaged<MTAudioProcessingTap>?
         let error = MTAudioProcessingTapCreate(kCFAllocatorDefault, &callbacks, kMTAudioProcessingTapCreationFlag_PreEffects, &tapRef)
         assert(error == noErr)
         
-        params.audioTapProcessor = tapRef
+        params.audioTapProcessor = tapRef?.takeRetainedValue()
         
         audioMix.inputParameters = [params]
         item.audioMix = audioMix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-mp3-player",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "React Native audio player with reliable iOS background playback. Media controls, queue, hooks. Built for stability and long-running playback.",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",

package/react-native-mp3-player.podspec

@@ -3,7 +3,7 @@ require "json"
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))
 
 Pod::Spec.new do |s|
-  s.name = "react-native-track-player"
+  s.name = "react-native-mp3-player"
   s.version = package["version"]
   s.summary = package["description"]
   s.license = package["license"]