react-native-mp3-player 1.0.10 → 1.1.0

package/README.md

@@ -82,10 +82,41 @@ TrackPlayer.registerPlaybackService(() => PlaybackService);
 - **Playback:** `play()`, `pause()`, `stop()`, `seekTo()`, `seekBy()`, `setVolume()`, `setRate()`, `setRepeatMode()`
 - **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.
+- **Hooks:** **`useProgress(updateInterval?, background?)`** (interval in **milliseconds**; e.g. `useProgress(250)` = every 250 ms), `usePlaybackState()`, `useActiveTrack()`, `useIsPlaying()`, **`useSetupPlayer()`**, **`useMiniPlayer()`**, `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.
 
+## Global mini player (iOS & Android)
+
+The same APIs and hooks work on both iOS and Android, so you can build a single global mini player (e.g. a persistent bar above the tab bar) that works cross-platform.
+
+1. **Setup once at app root** with `useSetupPlayer()`. It runs `setupPlayer()` and, on Android, retries if the app was in the background, so you get a single `isPlayerReady` for both platforms.
+2. **In your mini player component**, use `useMiniPlayer()` to get:
+   - `hasTrack`, `isPlaying`, `isLoadingAudio`
+   - `track`, `trackTitle`, `trackArtist`, `trackArtwork`
+   - `togglePlayPause()`, `pause()`, `stop()`
+   - `refreshActiveTrack()`, `refreshPlaybackState()` (e.g. after returning from another screen)
+3. **Full-screen and close** are app-level: e.g. navigate to a full-screen player route for `openFullScreen`, and call `pause()` or `stop()` plus your own state/navigation for close.
+
+Example:
+
+```javascript
+import TrackPlayer, { useSetupPlayer, useMiniPlayer } from 'react-native-mp3-player';
+
+// At root (e.g. in a provider):
+const isPlayerReady = useSetupPlayer({ options: {}, serviceFactory: () => PlaybackService });
+
+// In your global mini player component (when isPlayerReady):
+const {
+  hasTrack, isPlaying, isLoadingAudio,
+  trackTitle, trackArtist, trackArtwork,
+  togglePlayPause, pause, stop,
+  refreshActiveTrack, refreshPlaybackState,
+} = useMiniPlayer();
+```
+
+Use `getActiveTrack()` and `getPlaybackState()` when you need to sync state after navigation or from a widget; the hooks stay in sync via events.
+
 ## Example app
 
 From the repo root:

package/ios/RNTrackPlayer/RNTrackPlayer.swift

@@ -332,15 +332,15 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
             return
         }
 
-        if player.playWhenReady {
-            try? audioSessionController.activateSession()
-            if #available(iOS 11.0, *) {
-                try? AVAudioSession.sharedInstance().setCategory(sessionCategory, mode: sessionCategoryMode, policy: sessionCategoryPolicy, options: sessionCategoryOptions)
-            } else {
-                try? AVAudioSession.sharedInstance().setCategory(sessionCategory, mode: sessionCategoryMode, options: sessionCategoryOptions)
-            }
-            try? AVAudioSession.sharedInstance().setActive(true, options: [])
+        // Activate session whenever we have a current item so playback works after load()+play()
+        // (session may have been deactivated in setupPlayer when currentItem was nil).
+        try? audioSessionController.activateSession()
+        if #available(iOS 11.0, *) {
+            try? AVAudioSession.sharedInstance().setCategory(sessionCategory, mode: sessionCategoryMode, policy: sessionCategoryPolicy, options: sessionCategoryOptions)
+        } else {
+            try? AVAudioSession.sharedInstance().setCategory(sessionCategory, mode: sessionCategoryMode, options: sessionCategoryOptions)
         }
+        try? AVAudioSession.sharedInstance().setActive(true, options: [])
     }
 
     @objc private func handleDidEnterBackground() {
@@ -374,13 +374,12 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         forwardJumpInterval = options["forwardJumpInterval"] as? NSNumber ?? forwardJumpInterval
         backwardJumpInterval = options["backwardJumpInterval"] as? NSNumber ?? backwardJumpInterval
 
-        // When jump intervals are set, prefer 15s rewind/forward as the main transport buttons (left/right)
-        // by not registering next/previous with MPRemoteCommandCenter. Only skipForward/skipBackward are used,
-        // so the lock screen shows "15 second rewind" on the left and "15 second forward" on the right.
-        let fwd = (forwardJumpInterval?.doubleValue ?? 0)
-        let bwd = (backwardJumpInterval?.doubleValue ?? 0)
-        if fwd > 0 && bwd > 0 {
-            capabilitiesStr = capabilitiesStr.filter { $0 != "next" && $0 != "previous" }
+        // When both jump intervals are set, use only skip-forward/skip-backward for the main transport
+        // so the lock screen shows 15s rewind (left) and 15s forward (right), not previous/next track.
+        let useJumpButtonsForTransport = (forwardJumpInterval.map { $0.intValue > 0 } ?? false)
+            && (backwardJumpInterval.map { $0.intValue > 0 } ?? false)
+        if useJumpButtonsForTransport {
+            capabilitiesStr = capabilitiesStr.filter { $0 != "previous" && $0 != "next" }
         }
 
         player.remoteCommands = capabilitiesStr
@@ -399,11 +398,6 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         progressUpdateEventIntervalSeconds = interval
         configureProgressUpdateEvent(interval: interval)
 
-        // Ensure Now Playing widget is visible after options change (e.g. capabilities without next/previous).
-        if player.currentItem != nil && player.automaticallyUpdateNowPlayingInfo {
-            player.nowPlayingInfoController.pushToCenterSync()
-        }
-
         resolve(NSNull())
     }
 
@@ -589,6 +583,8 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         if (rejectWhenNotInitialized(reject: reject)) { return }
         effectivePlaybackState = .playing
         player.play()
+        // Activate audio session when starting playback so sound actually plays (session may be inactive after setup when no track was loaded yet).
+        configureAudioSession()
         updateNowPlayingPlaybackValuesOnMainIfNeeded()
         resolve(NSNull())
         emit(event: EventType.PlaybackState, body: getPlaybackStateBodyKeyValues(state: .playing))
@@ -882,9 +878,6 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         switch state {
         case .ready, .playing, .paused:
             if player.currentItem != nil && player.automaticallyUpdateNowPlayingInfo {
-                // Force push so the widget appears immediately (avoids "Not Playing" / blank artwork).
-                player.loadNowPlayingMetaValues()
-                player.nowPlayingInfoController.pushToCenterSync()
                 let useProgressTickForNowPlaying = shouldEmitProgressEvent && progressUpdateEventIntervalSeconds > 0 && progressUpdateEventIntervalSeconds <= 1.0
                 if !useProgressTickForNowPlaying {
                     scheduleNextNowPlayingUpdate()
@@ -914,12 +907,9 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
     }
 
     /// 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.
-    /// Also refreshes title/artist/artwork so the widget never shows "Not Playing" or blank when a track is loaded.
     private func updateNowPlayingPlaybackValuesOnMainIfNeeded() {
         guard player.currentItem != nil, player.automaticallyUpdateNowPlayingInfo else { return }
-        player.loadNowPlayingMetaValues()
         player.updateNowPlayingPlaybackValuesSync()
-        player.nowPlayingInfoController.pushToCenterSync()
     }
     
     func handleAudioPlayerCommonMetadataReceived(metadata: [AVMetadataItem]) {
@@ -959,12 +949,10 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
             DispatchQueue.main.async {
                 UIApplication.shared.beginReceivingRemoteControlEvents();
             }
-            // Update now playing controller with isLiveStream option from track and push so widget shows new track (e.g. after close and play again).
+            // Update now playing controller with isLiveStream option from track
             if self.player.automaticallyUpdateNowPlayingInfo {
                 let isTrackLiveStream = (item as? Track)?.isLiveStream ?? false
                 self.player.nowPlayingInfoController.set(keyValue: NowPlayingInfoProperty.isLiveStream(isTrackLiveStream))
-                self.player.loadNowPlayingMetaValues()
-                self.player.nowPlayingInfoController.pushToCenterSync()
             }
         } else {
             DispatchQueue.main.async {

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

@@ -85,13 +85,13 @@ extension AVPlayerWrapper {
         }
         
         
-        // https://stackoverflow.com/questions/79679383/unmanaged-object-pointer-build-issues-in-xcode-26-beta
-        // Xcode 16+ / 26 SDK: tapOut expects Unmanaged<MTAudioProcessingTap>? (API returns retained CF object).
-        var tapRef: Unmanaged<MTAudioProcessingTap>?
+        // Xcode 26+: MTAudioProcessingTapCreate tapOut is imported as UnsafeMutablePointer<MTAudioProcessingTap?>
+        // (managed), so use MTAudioProcessingTap? and do not use Unmanaged/takeRetainedValue().
+        var tapRef: MTAudioProcessingTap?
         let error = MTAudioProcessingTapCreate(kCFAllocatorDefault, &callbacks, kMTAudioProcessingTapCreationFlag_PreEffects, &tapRef)
         assert(error == noErr)
         
-        params.audioTapProcessor = tapRef?.takeRetainedValue()
+        params.audioTapProcessor = tapRef
         
         audioMix.inputParameters = [params]
         item.audioMix = audioMix

package/ios/SwiftAudioEx/Sources/SwiftAudioEx/QueueManager.swift

@@ -301,6 +301,7 @@ class QueueManager<Element> {
                 if (currentIndex == -1) {
                     currentIndex = items.count - 1
                 }
+                currentItemChanged = true
             } else {
                 items[currentIndex] = item
                 currentItemChanged = true

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

@@ -1,6 +1,8 @@
 export * from './useActiveTrack';
 export * from './useIsPlaying';
+export * from './useMiniPlayer';
 export * from './usePlayWhenReady';
 export * from './usePlaybackState';
 export * from './useProgress';
+export * from './useSetupPlayer';
 export * from './useTrackPlayerEvents';

package/lib/src/hooks/index.js

@@ -1,6 +1,8 @@
 export * from './useActiveTrack';
 export * from './useIsPlaying';
+export * from './useMiniPlayer';
 export * from './usePlayWhenReady';
 export * from './usePlaybackState';
 export * from './useProgress';
+export * from './useSetupPlayer';
 export * from './useTrackPlayerEvents';

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

@@ -0,0 +1,34 @@
+import type { Track } from '../interfaces/Track';
+export interface UseMiniPlayerResult {
+    /** Whether there is a current track (queue has an active track). */
+    hasTrack: boolean;
+    /** Whether the player is in a "playing" state (play when ready and not ended/error/none). */
+    isPlaying: boolean;
+    /** True when state is loading or buffering (e.g. show a spinner). */
+    isLoadingAudio: boolean;
+    /** Current track or undefined. */
+    track: Track | undefined;
+    /** Convenience: track?.title ?? ''. */
+    trackTitle: string;
+    /** Convenience: track?.artist ?? ''. */
+    trackArtist: string;
+    /** Convenience: track?.artwork (URL string or undefined). */
+    trackArtwork: string | undefined;
+    /** Toggle between play and pause. Safe to call when loading. */
+    togglePlayPause: () => void;
+    /** Pause playback. */
+    pause: () => void;
+    /** Stop and clear current track. */
+    stop: () => void;
+    /** Re-fetch active track from native and update hook state. Call when you need to sync (e.g. after returning to the app). */
+    refreshActiveTrack: () => Promise<void>;
+    /** Re-fetch playback state from native. Call when you need to sync. */
+    refreshPlaybackState: () => Promise<void>;
+}
+/**
+ * Aggregates state and actions needed for a global mini player bar (play/pause, title, artist, artwork, close).
+ * Works on both iOS and Android; use with useSetupPlayer() at app root so the player is ready.
+ *
+ * openFullScreen / closeFullScreen are not provided here — implement them in your app (e.g. navigate to a full-screen player route).
+ */
+export declare function useMiniPlayer(): UseMiniPlayerResult;

package/lib/src/hooks/useMiniPlayer.js

@@ -0,0 +1,66 @@
+import { useCallback } from 'react';
+import { play, pause, stop, getActiveTrack, getPlaybackState } from '../trackPlayer';
+import { State } from '../constants';
+import { useActiveTrack } from './useActiveTrack';
+import { usePlaybackState } from './usePlaybackState';
+import { useIsPlaying } from './useIsPlaying';
+/**
+ * Aggregates state and actions needed for a global mini player bar (play/pause, title, artist, artwork, close).
+ * Works on both iOS and Android; use with useSetupPlayer() at app root so the player is ready.
+ *
+ * openFullScreen / closeFullScreen are not provided here — implement them in your app (e.g. navigate to a full-screen player route).
+ */
+export function useMiniPlayer() {
+    const track = useActiveTrack();
+    const playbackState = usePlaybackState();
+    const { playing, bufferingDuringPlay } = useIsPlaying();
+    const state = playbackState.state;
+    const isPlaying = playing ?? false;
+    const isLoadingAudio = state === State.Loading || state === State.Buffering || bufferingDuringPlay === true;
+    const togglePlayPause = useCallback(async () => {
+        if (isLoadingAudio)
+            return;
+        if (isPlaying) {
+            await pause();
+        }
+        else {
+            await play();
+        }
+    }, [isPlaying, isLoadingAudio]);
+    const refreshActiveTrack = useCallback(async () => {
+        try {
+            const t = await getActiveTrack();
+            // Hooks (useActiveTrack) will update via events; this is for one-off sync.
+            // We can't set track here; the hook is the source of truth. So we document
+            // that refreshActiveTrack is for triggering a re-sync — the app can also
+            // rely on Event.PlaybackActiveTrackChanged and Event.PlaybackState.
+            void t;
+        }
+        catch {
+            // Not set up yet.
+        }
+    }, []);
+    const refreshPlaybackState = useCallback(async () => {
+        try {
+            await getPlaybackState();
+            // Same as above: events drive the hook state; this is for forcing native read.
+        }
+        catch {
+            // Not set up yet.
+        }
+    }, []);
+    return {
+        hasTrack: track != null,
+        isPlaying,
+        isLoadingAudio,
+        track,
+        trackTitle: track?.title ?? '',
+        trackArtist: track?.artist ?? '',
+        trackArtwork: track?.artwork,
+        togglePlayPause,
+        pause: () => pause(),
+        stop: () => stop(),
+        refreshActiveTrack,
+        refreshPlaybackState,
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { PlayerOptions } from '../interfaces/PlayerOptions';
+import type { ServiceHandler } from '../interfaces/ServiceHandler';
+export interface UseSetupPlayerOptions {
+    /** Options passed to setupPlayer(). Omit to use defaults. */
+    options?: PlayerOptions;
+    /** Whether to set up for background playback. Default false. */
+    background?: boolean;
+    /** Optional playback service factory. If provided, registerPlaybackService() is called with it. */
+    serviceFactory?: () => ServiceHandler;
+}
+/**
+ * Sets up the player once and returns whether it is ready.
+ * Use at app root (e.g. in a provider) so that mini players and screens can rely on isPlayerReady.
+ *
+ * On Android, if setup is called while the app is in the background, the native module may reject
+ * with 'android_cannot_setup_player_in_background'. This hook retries until the app is in the
+ * foreground and setup succeeds, so the same code works on both iOS and Android.
+ *
+ * @returns isPlayerReady – true once setupPlayer() (and optional service) has completed successfully.
+ */
+export declare function useSetupPlayer(hookOptions?: UseSetupPlayerOptions): boolean;

package/lib/src/hooks/useSetupPlayer.js

@@ -0,0 +1,50 @@
+import { useState, useEffect } from 'react';
+import { setupPlayer, registerPlaybackService } from '../trackPlayer';
+/**
+ * Sets up the player once and returns whether it is ready.
+ * Use at app root (e.g. in a provider) so that mini players and screens can rely on isPlayerReady.
+ *
+ * On Android, if setup is called while the app is in the background, the native module may reject
+ * with 'android_cannot_setup_player_in_background'. This hook retries until the app is in the
+ * foreground and setup succeeds, so the same code works on both iOS and Android.
+ *
+ * @returns isPlayerReady – true once setupPlayer() (and optional service) has completed successfully.
+ */
+export function useSetupPlayer(hookOptions = {}) {
+    const { options = {}, background = false, serviceFactory } = hookOptions;
+    const [isPlayerReady, setPlayerReady] = useState(false);
+    useEffect(() => {
+        let unmounted = false;
+        const run = async () => {
+            if (serviceFactory) {
+                registerPlaybackService(serviceFactory);
+            }
+            const doSetup = async () => {
+                try {
+                    await setupPlayer(options, background);
+                    return null;
+                }
+                catch (err) {
+                    return err.code ?? null;
+                }
+            };
+            let code = null;
+            do {
+                code = await doSetup();
+                if (unmounted)
+                    return;
+                if (code === 'android_cannot_setup_player_in_background') {
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                }
+            } while (code === 'android_cannot_setup_player_in_background');
+            if (unmounted || code != null)
+                return;
+            setPlayerReady(true);
+        };
+        run();
+        return () => {
+            unmounted = true;
+        };
+    }, []);
+    return isPlayerReady;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-mp3-player",
-  "version": "1.0.10",
+  "version": "1.1.0",
   "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/hooks/index.ts

@@ -1,6 +1,8 @@
 export * from './useActiveTrack';
 export * from './useIsPlaying';
+export * from './useMiniPlayer';
 export * from './usePlayWhenReady';
 export * from './usePlaybackState';
 export * from './useProgress';
+export * from './useSetupPlayer';
 export * from './useTrackPlayerEvents';

package/src/hooks/useMiniPlayer.ts

@@ -0,0 +1,98 @@
+import { useCallback } from 'react';
+
+import { play, pause, stop, getActiveTrack, getPlaybackState } from '../trackPlayer';
+import { State } from '../constants';
+import { useActiveTrack } from './useActiveTrack';
+import { usePlaybackState } from './usePlaybackState';
+import { useIsPlaying } from './useIsPlaying';
+import type { Track } from '../interfaces/Track';
+
+export interface UseMiniPlayerResult {
+  /** Whether there is a current track (queue has an active track). */
+  hasTrack: boolean;
+  /** Whether the player is in a "playing" state (play when ready and not ended/error/none). */
+  isPlaying: boolean;
+  /** True when state is loading or buffering (e.g. show a spinner). */
+  isLoadingAudio: boolean;
+  /** Current track or undefined. */
+  track: Track | undefined;
+  /** Convenience: track?.title ?? ''. */
+  trackTitle: string;
+  /** Convenience: track?.artist ?? ''. */
+  trackArtist: string;
+  /** Convenience: track?.artwork (URL string or undefined). */
+  trackArtwork: string | undefined;
+  /** Toggle between play and pause. Safe to call when loading. */
+  togglePlayPause: () => void;
+  /** Pause playback. */
+  pause: () => void;
+  /** Stop and clear current track. */
+  stop: () => void;
+  /** Re-fetch active track from native and update hook state. Call when you need to sync (e.g. after returning to the app). */
+  refreshActiveTrack: () => Promise<void>;
+  /** Re-fetch playback state from native. Call when you need to sync. */
+  refreshPlaybackState: () => Promise<void>;
+}
+
+/**
+ * Aggregates state and actions needed for a global mini player bar (play/pause, title, artist, artwork, close).
+ * Works on both iOS and Android; use with useSetupPlayer() at app root so the player is ready.
+ *
+ * openFullScreen / closeFullScreen are not provided here — implement them in your app (e.g. navigate to a full-screen player route).
+ */
+export function useMiniPlayer(): UseMiniPlayerResult {
+  const track = useActiveTrack();
+  const playbackState = usePlaybackState();
+  const { playing, bufferingDuringPlay } = useIsPlaying();
+
+  const state = playbackState.state;
+  const isPlaying = playing ?? false;
+  const isLoadingAudio =
+    state === State.Loading || state === State.Buffering || bufferingDuringPlay === true;
+
+  const togglePlayPause = useCallback(async () => {
+    if (isLoadingAudio) return;
+    if (isPlaying) {
+      await pause();
+    } else {
+      await play();
+    }
+  }, [isPlaying, isLoadingAudio]);
+
+  const refreshActiveTrack = useCallback(async () => {
+    try {
+      const t = await getActiveTrack();
+      // Hooks (useActiveTrack) will update via events; this is for one-off sync.
+      // We can't set track here; the hook is the source of truth. So we document
+      // that refreshActiveTrack is for triggering a re-sync — the app can also
+      // rely on Event.PlaybackActiveTrackChanged and Event.PlaybackState.
+      void t;
+    } catch {
+      // Not set up yet.
+    }
+  }, []);
+
+  const refreshPlaybackState = useCallback(async () => {
+    try {
+      await getPlaybackState();
+      // Same as above: events drive the hook state; this is for forcing native read.
+    } catch {
+      // Not set up yet.
+    }
+  }, []);
+
+  return {
+    hasTrack: track != null,
+    isPlaying,
+    isLoadingAudio,
+    track,
+    trackTitle: track?.title ?? '',
+    trackArtist: track?.artist ?? '',
+    trackArtwork: track?.artwork,
+    togglePlayPause,
+    pause: () => pause(),
+    stop: () => stop(),
+    refreshActiveTrack,
+    refreshPlaybackState,
+  };
+}

package/src/hooks/useSetupPlayer.ts

@@ -0,0 +1,69 @@
+import { useState, useEffect } from 'react';
+
+import { setupPlayer, registerPlaybackService } from '../trackPlayer';
+import type { PlayerOptions } from '../interfaces/PlayerOptions';
+import type { ServiceHandler } from '../interfaces/ServiceHandler';
+
+export interface UseSetupPlayerOptions {
+  /** Options passed to setupPlayer(). Omit to use defaults. */
+  options?: PlayerOptions;
+  /** Whether to set up for background playback. Default false. */
+  background?: boolean;
+  /** Optional playback service factory. If provided, registerPlaybackService() is called with it. */
+  serviceFactory?: () => ServiceHandler;
+}
+
+/**
+ * Sets up the player once and returns whether it is ready.
+ * Use at app root (e.g. in a provider) so that mini players and screens can rely on isPlayerReady.
+ *
+ * On Android, if setup is called while the app is in the background, the native module may reject
+ * with 'android_cannot_setup_player_in_background'. This hook retries until the app is in the
+ * foreground and setup succeeds, so the same code works on both iOS and Android.
+ *
+ * @returns isPlayerReady – true once setupPlayer() (and optional service) has completed successfully.
+ */
+export function useSetupPlayer(
+  hookOptions: UseSetupPlayerOptions = {},
+): boolean {
+  const { options = {}, background = false, serviceFactory } = hookOptions;
+  const [isPlayerReady, setPlayerReady] = useState(false);
+
+  useEffect(() => {
+    let unmounted = false;
+
+    const run = async () => {
+      if (serviceFactory) {
+        registerPlaybackService(serviceFactory);
+      }
+
+      const doSetup = async (): Promise<string | null> => {
+        try {
+          await setupPlayer(options, background);
+          return null;
+        } catch (err) {
+          return (err as Error & { code?: string }).code ?? null;
+        }
+      };
+
+      let code: string | null = null;
+      do {
+        code = await doSetup();
+        if (unmounted) return;
+        if (code === 'android_cannot_setup_player_in_background') {
+          await new Promise<void>((resolve) => setTimeout(resolve, 100));
+        }
+      } while (code === 'android_cannot_setup_player_in_background');
+
+      if (unmounted || code != null) return;
+      setPlayerReady(true);
+    };
+
+    run();
+    return () => {
+      unmounted = true;
+    };
+  }, []);
+
+  return isPlayerReady;
+}