react-native-mp3-player 1.0.2 → 1.0.4

package/README.md

@@ -9,7 +9,9 @@ React Native audio player with **reliable iOS background playback**, media contr
 
 ## Features
 
-- **iOS background playback** – Audio continues when the app is in the background (no ~50s cutoff). Uses `AVAudioSession` with `.longFormAudio` and interruption handling.
+- **Background playback (iOS & Android)** – Audio continues when the app is in the background or the screen is locked. No patches required; compatible with current Xcode and Android 14/15.
+- **iOS** – Uses `AVAudioSession` with `.longFormAudio` and interruption handling; lock screen and Control Center work natively.
+- **Android** – Uses Media3 `MediaLibraryService` with `foregroundServiceType="mediaPlayback"`; system media notification, lock screen, and Android Auto are supported.
 - **Multi-platform** – Android, iOS, Windows.
 - **Media controls** – Lock screen, notification, Bluetooth, Android Auto.
 - **Queue & playback** – Add, remove, reorder tracks; play, pause, seek, repeat, crossfade (where supported).
@@ -33,6 +35,15 @@ For audio to continue when the app is backgrounded or the screen is locked (and
 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.
 
+### Android background playback
+
+The package is built for **Android 14+** compatibility and works when the app is in the background or the screen is off:
+
+1. **Foreground service:** The library declares `FOREGROUND_SERVICE_MEDIA_PLAYBACK` and uses `android:foregroundServiceType="mediaPlayback"` on the playback service, as required since Android 14. No extra setup in your app is needed.
+2. **Media3 / ExoPlayer:** Playback runs in a **MediaLibraryService** (Media3), which correctly starts as a foreground service with type `mediaPlayback`, so background playback and the media notification are allowed by the system.
+3. **Media controls:** The service is advertised via **MediaSessionService** and **MediaLibraryService** so the system media notification, lock screen, Bluetooth, and Android Auto can discover and control playback.
+4. **Target SDK:** The library compiles with `compileSdkVersion` 35 and defaults to `targetSdkVersion` 34. Your app can override these via `react-native-mp3-player`’s build extras if needed. **Android 15:** Do not start the media service from a `BOOT_COMPLETED` receiver; the platform no longer allows that for media playback.
+
 ## Quick start
 
 ```javascript
@@ -68,8 +79,8 @@ TrackPlayer.registerPlaybackService(() => PlaybackService);
 - **Lifecycle:** `setupPlayer(options?, background?)`, `registerPlaybackService(factory)`, `reset()`
 - **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.
+- **State & progress:** **`getPlaybackState()`** (returns `{ state }`; use this, not `getState`), **`getProgress()`** (returns `{ position, duration, buffered }` in seconds), **`getPosition()`** and **`getDuration()`** (convenience wrappers around `getProgress()`), `getVolume()`, `getRate()`
+- **Events:** `addEventListener(event, listener)` – see `Event` enum. Listen for `Event.PlaybackState` so the UI stays in sync when the user taps play/pause.
 - **Hooks:** **`useProgress(updateInterval?, background?)`** (interval in **milliseconds**; e.g. `useProgress(250)` = every 250 ms), `usePlaybackState()`, `useActiveTrack()`, `useIsPlaying()`, `useTrackPlayerEvents()`, etc.
 
 **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.

package/android/src/main/AndroidManifest.xml

@@ -17,6 +17,7 @@
             android:foregroundServiceType="mediaPlayback">
             <intent-filter>
                 <action android:name="android.intent.action.MEDIA_BUTTON" />
+                <action android:name="androidx.media3.session.MediaSessionService" />
                 <action android:name="androidx.media3.session.MediaLibraryService" />
                 <action android:name="android.media.browse.MediaBrowserService" />
             </intent-filter>

package/ios/RNTrackPlayer/Models/MetadataAdapter.swift

@@ -1,6 +1,6 @@
 //
 //  MetadataAdapter.swift
-//  react-native-track-player
+//  react-native-mp3-player
 //
 //  Created by David Chavez on 01.08.23.
 //  Copyright © 2023 Double Symmetry. All rights reserved.

package/ios/RNTrackPlayer/RNTrackPlayer.swift

@@ -27,6 +27,9 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     private var forwardJumpInterval: NSNumber? = nil;
     private var backwardJumpInterval: NSNumber? = nil;
     private var sessionCategory: AVAudioSession.Category = .playback
+    /// Timer work item for updating Now Playing elapsed/duration every second so the lock screen widget stays in sync.
+    private var nowPlayingUpdateWorkItem: DispatchWorkItem? = nil
+    private let nowPlayingUpdateQueue = DispatchQueue.main
     private var sessionCategoryMode: AVAudioSession.Mode = .default
     private var sessionCategoryPolicy: AVAudioSession.RouteSharingPolicy = .longFormAudio
     private var sessionCategoryOptions: AVAudioSession.CategoryOptions = []
@@ -531,6 +534,7 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     public func reset(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         if (rejectWhenNotInitialized(reject: reject)) { return }
 
+        stopNowPlayingUpdateTimer()
         player.stop()
         player.clear()
         resolve(NSNull())
@@ -541,6 +545,8 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         if (rejectWhenNotInitialized(reject: reject)) { return }
         player.play()
         resolve(NSNull())
+        // Emit PlaybackState immediately so in-app UI (play/pause button) updates without waiting for native state transition.
+        emit(event: EventType.PlaybackState, body: getPlaybackStateBodyKeyValues(state: .playing))
     }
 
     @objc(pause:rejecter:)
@@ -549,6 +555,8 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
 
         player.pause()
         resolve(NSNull())
+        // Emit PlaybackState immediately so in-app UI (play/pause button) updates without waiting for native state transition.
+        emit(event: EventType.PlaybackState, body: getPlaybackStateBodyKeyValues(state: .paused))
     }
 
     @objc(setPlayWhenReady:resolver:rejecter:)
@@ -823,6 +831,33 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
                 "position": player.currentTime,
             ] as [String : Any])
         }
+        // Keep Now Playing widget elapsed/duration in sync: update every second when we have a current item and are ready/playing/paused.
+        switch state {
+        case .ready, .playing, .paused:
+            if player.currentItem != nil && player.automaticallyUpdateNowPlayingInfo {
+                scheduleNextNowPlayingUpdate()
+            } else {
+                stopNowPlayingUpdateTimer()
+            }
+        default:
+            stopNowPlayingUpdateTimer()
+        }
+    }
+
+    private func scheduleNextNowPlayingUpdate() {
+        stopNowPlayingUpdateTimer()
+        let workItem = DispatchWorkItem { [weak self] in
+            guard let self = self, self.player.currentItem != nil, self.player.automaticallyUpdateNowPlayingInfo else { return }
+            self.player.updateNowPlayingPlaybackValues()
+            self.scheduleNextNowPlayingUpdate()
+        }
+        nowPlayingUpdateWorkItem = workItem
+        nowPlayingUpdateQueue.asyncAfter(deadline: .now() + 1.0, execute: workItem)
+    }
+
+    private func stopNowPlayingUpdateTimer() {
+        nowPlayingUpdateWorkItem?.cancel()
+        nowPlayingUpdateWorkItem = nil
     }
     
     func handleAudioPlayerCommonMetadataReceived(metadata: [AVMetadataItem]) {

package/ios/RNTrackPlayer/TrackPlayer.mm

@@ -1,9 +1,9 @@
 #import "TrackPlayer.h"
 
-#if __has_include("react_native_track_player-Swift.h")
-#import "react_native_track_player-Swift.h"
+#if __has_include("react_native_mp3_player-Swift.h")
+#import "react_native_mp3_player-Swift.h"
 #else
-#import "react_native_track_player/react_native_track_player-Swift.h"
+#import "react_native_mp3_player/react_native_mp3_player-Swift.h"
 #endif
 
 @interface NativeTrackPlayer () <RNTPDelegate>

package/lib/src/trackPlayer.d.ts

@@ -269,6 +269,14 @@ export declare function getActiveTrack(): Promise<Track | undefined>;
  * duration in seconds.
  */
 export declare function getProgress(): Promise<Progress>;
+/**
+ * Gets the current playback position in seconds. Convenience wrapper around getProgress().
+ */
+export declare function getPosition(): Promise<number>;
+/**
+ * Gets the duration of the current track in seconds. Convenience wrapper around getProgress().
+ */
+export declare function getDuration(): Promise<number>;
 /**
  * Gets the playback state of the player.
  *

package/lib/src/trackPlayer.js

@@ -474,6 +474,20 @@ export async function getProgress() {
     // @ts-expect-error codegen issues
     return TrackPlayer.getProgress();
 }
+/**
+ * Gets the current playback position in seconds. Convenience wrapper around getProgress().
+ */
+export async function getPosition() {
+    const { position } = await getProgress();
+    return position;
+}
+/**
+ * Gets the duration of the current track in seconds. Convenience wrapper around getProgress().
+ */
+export async function getDuration() {
+    const { duration } = await getProgress();
+    return duration;
+}
 /**
  * Gets the playback state of the player.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-mp3-player",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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/src/trackPlayer.ts

@@ -633,6 +633,22 @@ export async function getProgress(): Promise<Progress> {
   return TrackPlayer.getProgress();
 }
 
+/**
+ * Gets the current playback position in seconds. Convenience wrapper around getProgress().
+ */
+export async function getPosition(): Promise<number> {
+  const { position } = await getProgress();
+  return position;
+}
+
+/**
+ * Gets the duration of the current track in seconds. Convenience wrapper around getProgress().
+ */
+export async function getDuration(): Promise<number> {
+  const { duration } = await getProgress();
+  return duration;
+}
+
 /**
  * Gets the playback state of the player.
  *