react-native-mp3-player 1.0.5 → 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

@@ -100,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,10 +205,9 @@ 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()
-            if self.player.currentItem != nil && self.player.automaticallyUpdateNowPlayingInfo {
-                self.player.updateNowPlayingPlaybackValues()
-            }
+            self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
             self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .paused))
             self.emit(event: EventType.RemotePause)
             return MPRemoteCommandHandlerStatus.success
@@ -212,10 +215,9 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
 
         player.remoteCommandController.handlePlayCommand = { [weak self] _ in
             guard let self = self else { return MPRemoteCommandHandlerStatus.commandFailed }
+            self.effectivePlaybackState = .playing
             self.player.play()
-            if self.player.currentItem != nil && self.player.automaticallyUpdateNowPlayingInfo {
-                self.player.updateNowPlayingPlaybackValues()
-            }
+            self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
             self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .playing))
             self.emit(event: EventType.RemotePlay)
             return MPRemoteCommandHandlerStatus.success
@@ -254,10 +256,9 @@ 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()
-            if self.player.currentItem != nil && self.player.automaticallyUpdateNowPlayingInfo {
-                self.player.updateNowPlayingPlaybackValues()
-            }
+            self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
             self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .stopped))
             self.emit(event: EventType.RemoteStop)
             return MPRemoteCommandHandlerStatus.success
@@ -265,18 +266,17 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
 
         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()
-                if self.player.currentItem != nil && self.player.automaticallyUpdateNowPlayingInfo {
-                    self.player.updateNowPlayingPlaybackValues()
-                }
+                self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
                 self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .playing))
                 self.emit(event: EventType.RemotePlay)
             } else {
+                self.effectivePlaybackState = .paused
                 self.player.pause()
-                if self.player.currentItem != nil && self.player.automaticallyUpdateNowPlayingInfo {
-                    self.player.updateNowPlayingPlaybackValues()
-                }
+                self.updateNowPlayingPlaybackValuesOnMainIfNeeded()
                 self.emit(event: EventType.PlaybackState, body: self.getPlaybackStateBodyKeyValues(state: .paused))
                 self.emit(event: EventType.RemotePause)
             }
@@ -377,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())
     }
@@ -554,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()
@@ -563,11 +564,9 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     @objc(play:rejecter:)
     public func play(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         if (rejectWhenNotInitialized(reject: reject)) { return }
+        effectivePlaybackState = .playing
         player.play()
-        // Update Now Playing widget immediately (rate 1, current elapsed) so it never shows "Not Playing".
-        if player.currentItem != nil && player.automaticallyUpdateNowPlayingInfo {
-            player.updateNowPlayingPlaybackValues()
-        }
+        updateNowPlayingPlaybackValuesOnMainIfNeeded()
         resolve(NSNull())
         emit(event: EventType.PlaybackState, body: getPlaybackStateBodyKeyValues(state: .playing))
     }
@@ -575,12 +574,9 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     @objc(pause:rejecter:)
     public func pause(resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) {
         if (rejectWhenNotInitialized(reject: reject)) { return }
-
+        effectivePlaybackState = .paused
         player.pause()
-        // Update Now Playing widget immediately (rate 0, current elapsed) so it shows "Paused" not "Not Playing".
-        if player.currentItem != nil && player.automaticallyUpdateNowPlayingInfo {
-            player.updateNowPlayingPlaybackValues()
-        }
+        updateNowPlayingPlaybackValuesOnMainIfNeeded()
         resolve(NSNull())
         emit(event: EventType.PlaybackState, body: getPlaybackStateBodyKeyValues(state: .paused))
     }
@@ -775,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:)
@@ -850,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: [
@@ -857,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()
             }
@@ -885,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)
@@ -974,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

@@ -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.5",
+  "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;
 }