react-native-mp3-player 1.0.4 → 1.0.6

package/PERFORMANCE.md

@@ -0,0 +1,76 @@
+# Performance and optimization
+
+This document describes how to get the best speed and lowest overhead from **react-native-mp3-player**, and what the package does internally to reduce work.
+
+---
+
+## 1. Progress updates (fewer bridge calls)
+
+### Prefer native-driven progress when possible
+
+- **Set `progressUpdateEventInterval`** in `updateOptions()` (in **seconds**, e.g. `1` for every second). The native layer will then emit `Event.PlaybackProgressUpdated` at that interval instead of you polling.
+- **Use `useProgress(intervalMs, background, { useNativeEvents: true })`** so the hook subscribes to `PlaybackProgressUpdated` and updates state from events. You still get a slow fallback poll (e.g. every 3 s) for drift. This reduces bridge round-trips compared to polling every second.
+
+Example:
+
+```ts
+// In your setup / updateOptions:
+await TrackPlayer.updateOptions({
+  capabilities: [...],
+  progressUpdateEventInterval: 1, // seconds; native emits every 1 s
+});
+
+// In your component:
+const progress = useProgress(1000, true, { useNativeEvents: true });
+```
+
+- **Avoid** using a very small `updateInterval` in `useProgress` (e.g. 250 ms) without `useNativeEvents: true`; that causes 4+ `getProgress()` bridge calls per second. If you need smooth progress, set `progressUpdateEventInterval` to 0.25 and use `useNativeEvents: true` with a fallback poll of ~2–3 s.
+
+---
+
+## 2. iOS: Now Playing and progress tick
+
+- When **`progressUpdateEventInterval`** is set and ≤ 1 second, the native progress tick also updates **MPNowPlayingInfoCenter** (elapsed/duration). A separate 1-second timer is not used in that case, so there is only one periodic task instead of two.
+- When `progressUpdateEventInterval` is 0 or > 1 s, a dedicated 1-second timer runs to keep the lock screen / Control Center widget in sync.
+
+---
+
+## 3. Batch and debounce in your app
+
+- **Seeking:** If the user drags a slider, debounce or throttle `seekTo()` (e.g. at most one call every 200–300 ms) so you don’t flood the bridge.
+- **Metadata:** Prefer a single `updateNowPlayingMetadata()` or `updateMetadataForTrack()` with all fields instead of multiple small updates.
+- **Queue changes:** Prefer `setQueue()` or a single `add()` with multiple tracks over many small `add()` calls when building a queue.
+
+---
+
+## 4. Buffer and streaming (setup options)
+
+- Use **`minBuffer`**, **`maxBuffer`**, **`playBuffer`** (and Android equivalents where supported) to tune buffering. Larger buffers can reduce stalling on slow networks but use more memory; smaller values can reduce memory and startup time for short clips.
+- For **local files**, you typically need minimal buffering; the default or small values are usually enough.
+
+---
+
+## 5. Android
+
+- **Progress:** When `progressUpdateEventInterval` is set, the service uses a single coroutine/flow to emit progress at that interval. No change needed on your side; avoid polling with `getProgress()` at a higher rate than the native interval if you can use `Event.PlaybackProgressUpdated` and `useProgress(..., { useNativeEvents: true })` instead.
+- **Service:** Playback runs in a Media3 `MediaLibraryService`; the system manages the process. Avoid doing heavy work on the JS thread while playback is active so the bridge can process events promptly.
+
+---
+
+## 6. General
+
+- **Events vs polling:** Prefer `addEventListener(Event.PlaybackState, ...)` and similar for state changes instead of repeatedly calling `getPlaybackState()` in a loop.
+- **Cleanup:** Remove event listeners and cancel any app-side timers when components unmount or when the player is reset, so the bridge and native side aren’t doing work for inactive UI.
+- **Single source of truth:** Use one place (e.g. one context or hook) to drive progress and playback state so you don’t have multiple subscribers or timers doing the same work.
+
+---
+
+## Summary
+
+| Goal                     | Recommendation                                                                 |
+|--------------------------|-------------------------------------------------------------------------------|
+| Fewer bridge calls       | Set `progressUpdateEventInterval` and use `useProgress(..., { useNativeEvents: true })`. |
+| Smoother progress UI     | Use native events (e.g. interval 0.25–1 s) + `useNativeEvents: true`; avoid very fast polling. |
+| Less duplicate work (iOS)| Use `progressUpdateEventInterval` ≤ 1 s so one tick drives both progress and Now Playing. |
+| Responsive seek UI       | Throttle/debounce `seekTo()` while the user drags the slider.                |
+| Lower memory / faster start | Tune buffer options for your use case (streaming vs local).               |

package/README.md

@@ -34,6 +34,7 @@ For audio to continue when the app is backgrounded or the screen is locked (and
 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.
+4. **Now Playing widget:** The package sets and updates **MPNowPlayingInfoCenter** as soon as a track is loaded (title, artist, duration, elapsed, rate, artwork) and keeps it updated every second during playback. When you pause, the widget shows the track as paused (rate 0), not "Not Playing". Now playing info is only cleared when there is no current track (e.g. after `reset()`).
 
 ### Android background playback
 
@@ -99,6 +100,7 @@ See [example/README.md](./example/README.md) for running the example app.
 
 ## Documentation
 
+- [PERFORMANCE.md](./PERFORMANCE.md) – Optimizing speed and reducing bridge calls (progress, events, buffers).
 - [NOTICE](./NOTICE) – Attribution and license.
 - [LICENSE](./LICENSE) – Apache-2.0.
 

package/ios/RNTrackPlayer/RNTrackPlayer.swift

@@ -22,7 +22,11 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     private var hasInitialized = false
     private let player = QueuedAudioPlayer()
     private let audioSessionController = AudioSessionController.shared
+    /// Synchronous playback state for getPlaybackState() and events. Set on play()/pause() (and remote) so the next getPlaybackState() returns the new state before the wrapper's async state update. Updated from handleAudioPlayerStateChange so ended/failed/loading etc. are correct.
+    private var effectivePlaybackState: AVPlayerWrapperState? = nil
     private var shouldEmitProgressEvent: Bool = false
+    /// When > 0 and <= 1, the progress tick already fires every second; we use it to update Now Playing instead of a separate timer.
+    private var progressUpdateEventIntervalSeconds: Double = 0
     private var shouldResumePlaybackAfterInterruptionEnds: Bool = false
     private var forwardJumpInterval: NSNumber? = nil;
     private var backwardJumpInterval: NSNumber? = nil;
@@ -201,14 +205,20 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
 
         player.remoteCommandController.handlePauseCommand = { [weak self] _ in
             guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.effectivePlaybackState = .paused
             self.player.pause()
+            self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
+            self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .paused))
             self.emit(event: EventType.RemotePause)
             return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handlePlayCommand = { [weak self] _ in
             guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.effectivePlaybackState = .playing
             self.player.play()
+            self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
+            self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .playing))
             self.emit(event: EventType.RemotePlay)
             return MPRemoteCommandHandlerStatus.success
         }
@@ -246,18 +256,28 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
 
         player.remoteCommandController.handleStopCommand = { [weak self] _ in
             guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.effectivePlaybackState = .stopped
             self.player.stop()
+            self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
+            self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .stopped))
             self.emit(event: EventType.RemoteStop)
             return MPRemoteCommandHandlerStatus.success
         }
 
         player.remoteCommandController.handleTogglePlayPauseCommand = { [weak self] _ in
             guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
-            if self.player.playerState == .paused {
+            let currentState = self.effectivePlaybackState ?? self.player.playerState
+            if currentState == .paused || currentState == .stopped || currentState == .ended {
+                self.effectivePlaybackState = .playing
                 self.player.play()
+                self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
+                self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .playing))
                 self.emit(event: EventType.RemotePlay)
             } else {
+                self.effectivePlaybackState = .paused
                 self.player.pause()
+                self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
+                self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .paused))
                 self.emit(event: EventType.RemotePause)
             }
             return MPRemoteCommandHandlerStatus.success
@@ -357,9 +377,9 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
                 )
             }
 
-        configureProgressUpdateEvent(
-            interval: ((options["progressUpdateEventInterval"] as? NSNumber) ?? 0).doubleValue
-        )
+        let interval = ((options["progressUpdateEventInterval"] as? NSNumber) ?? 0).doubleValue
+        progressUpdateEventIntervalSeconds = interval
+        configureProgressUpdateEvent(interval: interval)
 
         resolve(NSNull())
     }
@@ -534,6 +554,7 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     public func reset(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         if (rejectWhenNotInitialized(reject: reject)) { return }
 
+        effectivePlaybackState = nil
         stopNowPlayingUpdateTimer()
         player.stop()
         player.clear()
@@ -543,19 +564,20 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     @objc(play:rejecter:)
     public func play(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         if (rejectWhenNotInitialized(reject: reject)) { return }
+        effectivePlaybackState = .playing
         player.play()
+        updateNowPlayingPlaybackValuesOnMainIfNeeded()
         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:)
     public func pause(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         if (rejectWhenNotInitialized(reject: reject)) { return }
-
+        effectivePlaybackState = .paused
         player.pause()
+        updateNowPlayingPlaybackValuesOnMainIfNeeded()
         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))
     }
 
@@ -749,7 +771,8 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     @objc(getPlaybackState:rejecter:)
     public func getPlaybackState(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         if (rejectWhenNotInitialized(reject: reject)) { return }
-        resolve(getPlaybackStateBodyKeyValues(state: player.playerState))
+        let state = effectivePlaybackState ?? player.playerState
+        resolve(getPlaybackStateBodyKeyValues(state: state))
     }
 
     @objc(updateMetadataForTrack:metadata:resolver:rejecter:)
@@ -824,6 +847,7 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     // MARK: - QueuedAudioPlayer Event Handlers
 
     func handleAudioPlayerStateChange(state: AVPlayerWrapperState) {
+        effectivePlaybackState = state
         emit(event: EventType.PlaybackState, body: getPlaybackStateBodyKeyValues(state: state))
         if (state == .ended) {
             emit(event: EventType.PlaybackQueueEnded, body: [
@@ -831,11 +855,14 @@ 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.
+        // Keep Now Playing widget elapsed/duration in sync. When progress events fire every second (interval > 0 and <= 1), use that tick instead of a separate timer.
         switch state {
         case .ready, .playing, .paused:
             if player.currentItem != nil && player.automaticallyUpdateNowPlayingInfo {
-                scheduleNextNowPlayingUpdate()
+                let useProgressTickForNowPlaying = shouldEmitProgressEvent && progressUpdateEventIntervalSeconds > 0 && progressUpdateEventIntervalSeconds <= 1.0
+                if !useProgressTickForNowPlaying {
+                    scheduleNextNowPlayingUpdate()
+                }
             } else {
                 stopNowPlayingUpdateTimer()
             }
@@ -859,6 +886,12 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         nowPlayingUpdateWorkItem?.cancel()
         nowPlayingUpdateWorkItem = nil
     }
+
+    /// Updates MPNowPlayingInfoCenter (rate, elapsed, duration) synchronously so the widget reflects play/pause before we return to JS. Call after play()/pause() from JS or remote.
+    private func updateNowPlayingPlaybackValuesOnMainIfNeeded() {
+        guard player.currentItem != nil, player.automaticallyUpdateNowPlayingInfo else { return }
+        player.updateNowPlayingPlaybackValuesSync()
+    }
     
     func handleAudioPlayerCommonMetadataReceived(metadata: [AVMetadataItem]) {
         let commonMetadata = MetadataAdapter.convertToCommonMetadata(metadata: metadata, skipRaw: true)
@@ -948,6 +981,9 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         // _after_ a manipulation to the queu causing no currentItem to exist (see reset)
         // in which case we shouldn't emit anything or we'll get an exception.
         if !shouldEmitProgressEvent || player.currentItem == nil { return }
+        if player.automaticallyUpdateNowPlayingInfo {
+            player.updateNowPlayingPlaybackValues()
+        }
         emit(
             event: EventType.PlaybackProgressUpdated,
             body: [

package/ios/SwiftAudioEx/Sources/SwiftAudioEx/AudioPlayer.swift

@@ -211,12 +211,12 @@ public class AudioPlayer: AVPlayerWrapperDelegate {
             currentItem = item
 
             if (automaticallyUpdateNowPlayingInfo) {
-                // Reset playback values without updating, because that will happen in
-                // the loadNowPlayingMetaValues call straight after:
-                nowPlayingInfoController.setWithoutUpdate(keyValues: [
-                    MediaItemProperty.duration(nil),
-                    NowPlayingInfoProperty.playbackRate(nil),
-                    NowPlayingInfoProperty.elapsedPlaybackTime(nil)
+                // Set initial playback values so the Now Playing widget never shows "Not Playing"
+                // (duration/elapsed/rate must be set; use 0 until the player reports real values).
+                nowPlayingInfoController.set(keyValues: [
+                    MediaItemProperty.duration(0),
+                    NowPlayingInfoProperty.playbackRate(playWhenReady ? 1.0 : 0.0),
+                    NowPlayingInfoProperty.elapsedPlaybackTime(0)
                 ])
                 loadNowPlayingMetaValues()
             }
@@ -348,6 +348,14 @@ public class AudioPlayer: AVPlayerWrapperDelegate {
         ])
     }
 
+    /// Pushes current duration/elapsed/rate to MPNowPlayingInfoCenter synchronously on main so the widget updates before returning (e.g. after play/pause).
+    func updateNowPlayingPlaybackValuesSync() {
+        let duration = wrapper.duration
+        let elapsed = wrapper.currentTime
+        let rate = wrapper.playWhenReady ? Double(wrapper.rate) : 0
+        nowPlayingInfoController.setPlaybackValuesSync(duration: duration, elapsed: elapsed, rate: rate)
+    }
+
     public func clear() {
         let playbackWasActive = wrapper.playbackActive
         currentItem = nil

package/ios/SwiftAudioEx/Sources/SwiftAudioEx/NowPlayingInfoController/NowPlayingInfoController.swift

@@ -9,13 +9,14 @@ import Foundation
 import MediaPlayer
 
 public class NowPlayingInfoController: NowPlayingInfoControllerProtocol {
+    private let lock = NSLock()
     private var infoQueue: DispatchQueueType = DispatchQueue(
         label: "NowPlayingInfoController.infoQueue",
         attributes: .concurrent
     )
 
-    private(set) var infoCenter: NowPlayingInfoCenter
     private(set) var info: [String: Any] = [:]
+    private(set) var infoCenter: NowPlayingInfoCenter
     
     public required init() {
         infoCenter = MPNowPlayingInfoCenter.default()
@@ -32,41 +33,74 @@ public class NowPlayingInfoController: NowPlayingInfoControllerProtocol {
     }
     
     public func set(keyValues: [NowPlayingInfoKeyValue]) {
-        infoQueue.async(flags: .barrier) { [weak self] in
-            guard let self = self else { return }
-            keyValues.forEach {
-                (keyValue) in self.info[keyValue.getKey()] = keyValue.getValue()
-            }
-            self.update()
+        lock.lock()
+        keyValues.forEach { keyValue in
+            self.info[keyValue.getKey()] = keyValue.getValue()
         }
+        let snapshot = self.info
+        lock.unlock()
+        pushToCenter(snapshot)
     }
 
     public func setWithoutUpdate(keyValues: [NowPlayingInfoKeyValue]) {
-        infoQueue.async(flags: .barrier) { [weak self] in
-            guard let self = self else { return }
-            keyValues.forEach {
-                (keyValue) in self.info[keyValue.getKey()] = keyValue.getValue()
-            }
+        lock.lock()
+        keyValues.forEach { keyValue in
+            self.info[keyValue.getKey()] = keyValue.getValue()
         }
+        lock.unlock()
     }
     
     public func set(keyValue: NowPlayingInfoKeyValue) {
-        infoQueue.async(flags: .barrier) { [weak self] in
-            guard let self = self else { return }
-            self.info[keyValue.getKey()] = keyValue.getValue()
-            self.update()
+        lock.lock()
+        self.info[keyValue.getKey()] = keyValue.getValue()
+        let snapshot = self.info
+        lock.unlock()
+        pushToCenter(snapshot)
+    }
+
+    public func setPlaybackValuesSync(duration: TimeInterval, elapsed: TimeInterval, rate: Double) {
+        lock.lock()
+        self.info[MPMediaItemPropertyPlaybackDuration] = NSNumber(value: duration)
+        self.info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = NSNumber(value: elapsed)
+        self.info[MPNowPlayingInfoPropertyPlaybackRate] = NSNumber(value: rate)
+        let snapshot = self.info
+        lock.unlock()
+        if Thread.isMainThread {
+            infoCenter.nowPlayingInfo = snapshot
+        } else {
+            DispatchQueue.main.sync { [weak self] in
+                self?.infoCenter.nowPlayingInfo = snapshot
+            }
         }
     }
    
     private func update() {
-        infoCenter.nowPlayingInfo = info
+        lock.lock()
+        let snapshot = self.info
+        lock.unlock()
+        pushToCenter(snapshot)
+    }
+
+    private func pushToCenter(_ snapshot: [String: Any]) {
+        if Thread.isMainThread {
+            infoCenter.nowPlayingInfo = snapshot
+        } else {
+            DispatchQueue.main.async { [weak self] in
+                self?.infoCenter.nowPlayingInfo = snapshot
+            }
+        }
     }
     
     public func clear() {
-        infoQueue.async(flags: .barrier) { [weak self] in
-            guard let self = self else { return }
-            self.info = [:]
-            self.infoCenter.nowPlayingInfo = nil
+        lock.lock()
+        self.info = [:]
+        lock.unlock()
+        if Thread.isMainThread {
+            infoCenter.nowPlayingInfo = nil
+        } else {
+            DispatchQueue.main.async { [weak self] in
+                self?.infoCenter.nowPlayingInfo = nil
+            }
         }
     }
     

package/ios/SwiftAudioEx/Sources/SwiftAudioEx/NowPlayingInfoController/NowPlayingInfoControllerProtocol.swift

@@ -23,4 +23,16 @@ public protocol NowPlayingInfoControllerProtocol {
     
     func clear()
     
+    /// Optional: push playback values to the system synchronously on main (e.g. so play/pause widget updates before returning). Default merges and calls set() (async).
+    func setPlaybackValuesSync(duration: TimeInterval, elapsed: TimeInterval, rate: Double)
+}
+
+extension NowPlayingInfoControllerProtocol {
+    public func setPlaybackValuesSync(duration: TimeInterval, elapsed: TimeInterval, rate: Double) {
+        set(keyValues: [
+            MediaItemProperty.duration(duration),
+            NowPlayingInfoProperty.elapsedPlaybackTime(elapsed),
+            NowPlayingInfoProperty.playbackRate(rate)
+        ])
+    }
 }

package/lib/src/hooks/useProgress.d.ts

@@ -1,7 +1,12 @@
 import type { Progress } from '../interfaces';
+export interface UseProgressOptions {
+    /** If true, subscribe to Event.PlaybackProgressUpdated (native-driven) when you set progressUpdateEventInterval in updateOptions. Reduces bridge round-trips vs polling. Default false. */
+    useNativeEvents?: boolean;
+}
 /**
- * Poll for track progress for the given interval (in miliseconds)
- * @param updateInterval - ms interval
- * @param background - if update state in background. default true. may severely affects performance.
+ * Track progress (position, duration, buffered) for the current track.
+ * @param updateInterval - Polling interval in ms when not using native events. Default 1000.
+ * @param background - Update state when app is in background. Default true. Can affect performance.
+ * @param options - useNativeEvents: true to prefer Event.PlaybackProgressUpdated (set progressUpdateEventInterval in updateOptions). Fewer bridge calls.
  */
-export declare function useProgress(updateInterval?: number, background?: boolean): Progress;
+export declare function useProgress(updateInterval?: number, background?: boolean, options?: UseProgressOptions): Progress;

package/lib/src/hooks/useProgress.js

@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react';
 import { AppState } from 'react-native';
-import { getProgress } from '../trackPlayer';
+import { getProgress, addEventListener } from '../trackPlayer';
 import { Event } from '../constants';
 import { useTrackPlayerEvents } from './useTrackPlayerEvents';
 const INITIAL_STATE = {
@@ -9,39 +9,63 @@ const INITIAL_STATE = {
     buffered: 0,
 };
 /**
- * Poll for track progress for the given interval (in miliseconds)
- * @param updateInterval - ms interval
- * @param background - if update state in background. default true. may severely affects performance.
+ * Track progress (position, duration, buffered) for the current track.
+ * @param updateInterval - Polling interval in ms when not using native events. Default 1000.
+ * @param background - Update state when app is in background. Default true. Can affect performance.
+ * @param options - useNativeEvents: true to prefer Event.PlaybackProgressUpdated (set progressUpdateEventInterval in updateOptions). Fewer bridge calls.
  */
-export function useProgress(updateInterval = 1000, background = true) {
+export function useProgress(updateInterval = 1000, background = true, options = {}) {
     const [state, setState] = useState(INITIAL_STATE);
     useTrackPlayerEvents([Event.PlaybackActiveTrackChanged], () => {
         setState(INITIAL_STATE);
     });
     useEffect(() => {
         let mounted = true;
-        const update = async () => {
+        const updateFromProgress = (next) => {
+            if (!mounted)
+                return;
+            setState((prev) => next.position === prev.position &&
+                next.duration === prev.duration &&
+                next.buffered === prev.buffered
+                ? prev
+                : next);
+        };
+        const updateFromBridge = async () => {
             try {
                 if (!mounted)
                     return;
                 if (!background && AppState.currentState !== 'active')
                     return;
-                const { position, duration, buffered } = await getProgress();
-                setState((state) => position === state.position &&
-                    duration === state.duration &&
-                    buffered === state.buffered
-                    ? state
-                    : { position, duration, buffered });
+                const next = await getProgress();
+                updateFromProgress(next);
             }
             catch {
-                // these method only throw while you haven't yet setup, ignore failure.
+                // only throws when player not set up
             }
         };
+        let progressSub = null;
+        if (options.useNativeEvents) {
+            progressSub = addEventListener(Event.PlaybackProgressUpdated, (payload) => {
+                updateFromProgress({
+                    position: payload.position,
+                    duration: payload.duration,
+                    buffered: payload.buffered,
+                });
+            });
+        }
         const poll = async () => {
-            await update();
-            if (!mounted)
-                return;
-            await new Promise((resolve) => setTimeout(resolve, updateInterval));
+            if (options.useNativeEvents) {
+                await updateFromBridge();
+                if (!mounted)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, Math.max(updateInterval * 3, 3000)));
+            }
+            else {
+                await updateFromBridge();
+                if (!mounted)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, updateInterval));
+            }
             if (!mounted)
                 return;
             poll();
@@ -49,7 +73,8 @@ export function useProgress(updateInterval = 1000, background = true) {
         poll();
         return () => {
             mounted = false;
+            progressSub?.remove();
         };
-    }, [updateInterval]);
+    }, [updateInterval, options?.useNativeEvents ?? false]);
     return state;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-mp3-player",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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",
@@ -20,6 +20,7 @@
   "files": [
     "src",
     "lib/**/*",
+    "PERFORMANCE.md",
     "ios/**/*",
     "android/src/**/*",
     "android/build.gradle",

package/src/hooks/useProgress.ts

@@ -1,23 +1,33 @@
 import { useEffect, useState } from 'react';
 import { AppState } from 'react-native';
 
-import { getProgress } from '../trackPlayer';
+import { getProgress, addEventListener } from '../trackPlayer';
 import { Event } from '../constants';
 import type { Progress } from '../interfaces';
 import { useTrackPlayerEvents } from './useTrackPlayerEvents';
 
-const INITIAL_STATE = {
+const INITIAL_STATE: Progress = {
   position: 0,
   duration: 0,
   buffered: 0,
 };
 
+export interface UseProgressOptions {
+  /** If true, subscribe to Event.PlaybackProgressUpdated (native-driven) when you set progressUpdateEventInterval in updateOptions. Reduces bridge round-trips vs polling. Default false. */
+  useNativeEvents?: boolean;
+}
+
 /**
- * Poll for track progress for the given interval (in miliseconds)
- * @param updateInterval - ms interval
- * @param background - if update state in background. default true. may severely affects performance.
+ * Track progress (position, duration, buffered) for the current track.
+ * @param updateInterval - Polling interval in ms when not using native events. Default 1000.
+ * @param background - Update state when app is in background. Default true. Can affect performance.
+ * @param options - useNativeEvents: true to prefer Event.PlaybackProgressUpdated (set progressUpdateEventInterval in updateOptions). Fewer bridge calls.
  */
-export function useProgress(updateInterval = 1000, background = true) {
+export function useProgress(
+  updateInterval = 1000,
+  background = true,
+  options: UseProgressOptions = {},
+) {
   const [state, setState] = useState<Progress>(INITIAL_STATE);
 
   useTrackPlayerEvents([Event.PlaybackActiveTrackChanged], () => {
@@ -27,28 +37,56 @@ export function useProgress(updateInterval = 1000, background = true) {
   useEffect(() => {
     let mounted = true;
 
-    const update = async () => {
+    const updateFromProgress = (next: Progress) => {
+      if (!mounted) return;
+      setState((prev) =>
+        next.position === prev.position &&
+        next.duration === prev.duration &&
+        next.buffered === prev.buffered
+          ? prev
+          : next
+      );
+    };
+
+    const updateFromBridge = async () => {
       try {
         if (!mounted) return;
         if (!background && AppState.currentState !== 'active') return;
-
-        const { position, duration, buffered } = await getProgress();
-        setState((state) =>
-          position === state.position &&
-          duration === state.duration &&
-          buffered === state.buffered
-            ? state
-            : { position, duration, buffered }
-        );
+        const next = await getProgress();
+        updateFromProgress(next);
       } catch {
-        // these method only throw while you haven't yet setup, ignore failure.
+        // only throws when player not set up
       }
     };
 
+    let progressSub: { remove: () => void } | null = null;
+    if (options.useNativeEvents) {
+      progressSub = addEventListener(
+        Event.PlaybackProgressUpdated,
+        (payload: { position: number; duration: number; buffered: number }) => {
+          updateFromProgress({
+            position: payload.position,
+            duration: payload.duration,
+            buffered: payload.buffered,
+          });
+        },
+      );
+    }
+
     const poll = async () => {
-      await update();
-      if (!mounted) return;
-      await new Promise<void>((resolve) => setTimeout(resolve, updateInterval));
+      if (options.useNativeEvents) {
+        await updateFromBridge();
+        if (!mounted) return;
+        await new Promise<void>((resolve) =>
+          setTimeout(resolve, Math.max(updateInterval * 3, 3000)),
+        );
+      } else {
+        await updateFromBridge();
+        if (!mounted) return;
+        await new Promise<void>((resolve) =>
+          setTimeout(resolve, updateInterval),
+        );
+      }
       if (!mounted) return;
       poll();
     };
@@ -57,8 +95,9 @@ export function useProgress(updateInterval = 1000, background = true) {
 
     return () => {
       mounted = false;
+      progressSub?.remove();
     };
-  }, [updateInterval]);
+  }, [updateInterval, options?.useNativeEvents ?? false]);
 
   return state;
 }