react-native-mp3-player 1.0.11 → 1.1.1

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/SwiftAudioEx/Sources/SwiftAudioEx/AudioTap.swift

@@ -84,9 +84,8 @@ extension AVPlayerWrapper {
             audioTap.process(numberOfFrames: numberFrames, buffer: UnsafeMutableAudioBufferListPointer(bufferListInOut))
         }
         
-        
-        // 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).
+        // Newer Xcode / SDK versions import MTAudioProcessingTapCreate’s tap out-parameter as
+        // UnsafeMutablePointer<Unmanaged<MTAudioProcessingTap>?>; AudioToolbox returns a +1 retained tap.
         var tapRef: Unmanaged<MTAudioProcessingTap>?
         let error = MTAudioProcessingTapCreate(kCFAllocatorDefault, &callbacks, kMTAudioProcessingTapCreationFlag_PreEffects, &tapRef)
         assert(error == noErr)

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.11",
+  "version": "1.1.1",
   "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;
+}