react-native-queue-player 1.0.0

package/src/hooks/useCast.ts

@@ -0,0 +1,121 @@
+import { useEffect, useState } from 'react';
+import {
+  addDiscoveryStateListener,
+  addLocalNetworkPermissionListener,
+  addReceiversListener,
+  addRouteListener,
+  addSessionDiedListener,
+  getCurrentRoute,
+  getReceivers,
+  getSupportedProtocols,
+  isCastAvailable,
+  isDiscovering,
+  localRoute,
+  type CastLocalNetworkPermission,
+  type CastProtocol,
+  type CastReceiver,
+  type CastRoute,
+  type CastSessionDiedEvent,
+} from '../cast';
+
+export interface CastSnapshot {
+  /** Protocols compiled into the current build (AirPlay / Chromecast). */
+  supportedProtocols: CastProtocol[];
+  /** `true` if at least one cast protocol is available on the device. */
+  isAvailable: boolean;
+  /** Live receiver list, replayed once synchronously on subscribe. */
+  receivers: CastReceiver[];
+  /** Currently active route — falls back to a synthesised local route. */
+  route: CastRoute;
+  /** `true` while at least one backend is actively scanning. */
+  isDiscovering: boolean;
+  /**
+   * Last `onSessionDied` event, or `null` until one arrives. Consumers
+   * clear by re-reading state after surfacing a banner.
+   */
+  lastSessionDied: CastSessionDiedEvent | null;
+  /** iOS Local Network permission state; `'granted'` on Android. */
+  permission: CastLocalNetworkPermission;
+}
+
+const INITIAL: CastSnapshot = {
+  supportedProtocols: [],
+  isAvailable: false,
+  receivers: [],
+  route: localRoute(),
+  isDiscovering: false,
+  lastSessionDied: null,
+  permission: 'undetermined',
+};
+
+/**
+ * Aggregated cast state for picker UIs. Subscribes to all five Cast
+ * event streams + reads the initial snapshot synchronously on mount.
+ *
+ * Returns a single object so consumers can pattern-match without
+ * threading five hook calls through their render. Consumers needing
+ * just one slice (e.g. only `receivers`) should still prefer this
+ * hook over the underlying listeners — the lib already debounces +
+ * coalesces updates.
+ */
+export function useCast(): CastSnapshot {
+  const [snapshot, setSnapshot] = useState<CastSnapshot>(() => {
+    try {
+      const protocols = getSupportedProtocols();
+      return {
+        supportedProtocols: protocols,
+        isAvailable: protocols.length > 0,
+        receivers: getReceivers(),
+        route: getCurrentRoute(),
+        isDiscovering: isDiscovering(),
+        lastSessionDied: null,
+        permission: 'undetermined',
+      };
+    } catch {
+      return INITIAL;
+    }
+  });
+
+  useEffect(() => {
+    if (!isCastAvailable()) return;
+
+    // Each `addXxxListener` synchronously replays the current value on
+    // subscribe. The initial `useState` initializer already captured
+    // every initial value; skipping the first replay per stream avoids
+    // five back-to-back `setSnapshot` calls on mount.
+    let firstRoute = true;
+    let firstReceivers = true;
+    let firstDiscovery = true;
+    let firstPermission = true;
+
+    const routeSub = addRouteListener((route) => {
+      if (firstRoute) { firstRoute = false; return; }
+      setSnapshot((prev) => ({ ...prev, route }));
+    });
+    const receiversSub = addReceiversListener((receivers) => {
+      if (firstReceivers) { firstReceivers = false; return; }
+      setSnapshot((prev) => ({ ...prev, receivers }));
+    });
+    const discoverySub = addDiscoveryStateListener((state) => {
+      if (firstDiscovery) { firstDiscovery = false; return; }
+      setSnapshot((prev) => ({ ...prev, isDiscovering: state.isDiscovering }));
+    });
+    const deathSub = addSessionDiedListener((event) =>
+      setSnapshot((prev) => ({ ...prev, lastSessionDied: event }))
+    );
+    const permissionSub = addLocalNetworkPermissionListener((event) => {
+      if (firstPermission) { firstPermission = false; return; }
+      setSnapshot((prev) => ({ ...prev, permission: event.state }));
+    });
+
+    return () => {
+      routeSub.remove();
+      receiversSub.remove();
+      discoverySub.remove();
+      deathSub.remove();
+      permissionSub.remove();
+    };
+  }, []);
+
+  return snapshot;
+}

package/src/hooks/useEqualizer.ts

@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useState } from 'react';
+import { getEqualizer } from '../clients';
+import type { EqualizerBand, EqualizerPreset } from '../types';
+
+export interface UseEqualizerResult {
+  enabled: boolean;
+  bands: EqualizerBand[];
+  presets: EqualizerPreset[];
+  setEnabled: (enabled: boolean) => Promise<void>;
+  setBandGain: (index: number, gainDb: number) => Promise<void>;
+  setAllBandGains: (gains: number[]) => Promise<void>;
+  applyPreset: (name: string) => Promise<void>;
+  saveCustomPreset: (name: string) => Promise<void>;
+  deleteCustomPreset: (name: string) => Promise<void>;
+  reset: () => Promise<void>;
+}
+
+/**
+ * Subscribes to Equalizer band-change events and exposes imperative setters.
+ * Initial state is pulled synchronously on mount so consumers don't flash
+ * empty bands.
+ */
+export function useEqualizer(): UseEqualizerResult {
+  const [enabled, setEnabledState] = useState<boolean>(() => {
+    try {
+      return getEqualizer().isEnabled();
+    } catch {
+      return false;
+    }
+  });
+  const [bands, setBands] = useState<EqualizerBand[]>(() => {
+    try {
+      return getEqualizer().getBands();
+    } catch {
+      return [];
+    }
+  });
+  const [presets, setPresets] = useState<EqualizerPreset[]>(() => {
+    try {
+      return getEqualizer().getPresets();
+    } catch {
+      return [];
+    }
+  });
+
+  useEffect(() => {
+    const eq = getEqualizer();
+    const dispose = eq.onBandChange((updated) => {
+      setBands(updated);
+    });
+    return dispose;
+  }, []);
+
+  const setEnabled = useCallback(async (next: boolean) => {
+    const eq = getEqualizer();
+    await eq.setEnabled(next);
+    // Read back rather than echoing the requested value: the native
+    // side may reject (or coerce) the change in a future build, and
+    // mirroring its actual state keeps JS aligned without a separate
+    // `onEnabledChange` event. Fall back to the requested value when
+    // the read-back throws (today's behaviour against the
+    // unimplemented native — matches the seed's try/catch on init).
+    try {
+      setEnabledState(eq.isEnabled());
+    } catch {
+      setEnabledState(next);
+    }
+  }, []);
+
+  const setBandGain = useCallback(async (index: number, gainDb: number) => {
+    await getEqualizer().setBandGain(index, gainDb);
+  }, []);
+
+  const setAllBandGains = useCallback(async (gains: number[]) => {
+    await getEqualizer().setAllBandGains(gains);
+  }, []);
+
+  const applyPreset = useCallback(async (name: string) => {
+    await getEqualizer().applyPreset(name);
+  }, []);
+
+  // TODO: wire onPresetsChange when added to Equalizer.nitro.ts —
+  // until then, save/delete refresh the local presets list with a
+  // manual sync re-fetch.
+  const saveCustomPreset = useCallback(async (name: string) => {
+    await getEqualizer().saveCustomPreset(name);
+    setPresets(getEqualizer().getPresets());
+  }, []);
+
+  const deleteCustomPreset = useCallback(async (name: string) => {
+    await getEqualizer().deleteCustomPreset(name);
+    setPresets(getEqualizer().getPresets());
+  }, []);
+
+  const reset = useCallback(async () => {
+    await getEqualizer().reset();
+  }, []);
+
+  return {
+    enabled,
+    bands,
+    presets,
+    setEnabled,
+    setBandGain,
+    setAllBandGains,
+    applyPreset,
+    saveCustomPreset,
+    deleteCustomPreset,
+    reset,
+  };
+}

package/src/hooks/useFullyBuffered.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+
+/**
+ * Subscribes to native `onFullyBufferedChange` and returns whether the active
+ * track has fully downloaded (`true` once the whole media is buffered). Distinct
+ * from `useBufferState() === 'full'` (which is "enough buffered to keep up") —
+ * a track can keep up while still downloading. Use it to push a buffered bar to
+ * 100% or enable a full-length scrubber once nothing is left to transfer.
+ *
+ * ```tsx
+ * const fullyBuffered = useFullyBuffered();
+ * ```
+ *
+ * Always `false` for a live / unknown-length stream that never completes.
+ */
+export function useFullyBuffered(): boolean {
+  const [fullyBuffered, setFullyBuffered] = useState<boolean>(() => {
+    try {
+      return getTrackPlayer().isFullyBuffered();
+    } catch {
+      return false;
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    return player.onFullyBufferedChange(setFullyBuffered);
+  }, []);
+
+  return fullyBuffered;
+}

package/src/hooks/useLookaheadCache.ts

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+import type { CacheStatus, LookaheadCacheConfig } from '../types';
+
+export interface UseLookaheadCacheResult {
+  status: CacheStatus;
+  setConfig: (config: LookaheadCacheConfig) => Promise<void>;
+  clear: () => Promise<void>;
+}
+
+// Pre-install fallback. `maxSizeMb: 100` matches the lib's documented
+// default so consumers reading the value before the first
+// `onCacheStatusChange` event don't see a misleading "0 MB budget".
+// The first event overrides this with the actual configured value.
+const INITIAL: CacheStatus = {
+  enabled: false,
+  currentSizeMb: 0,
+  maxSizeMb: 100,
+  tracksFullyCached: 0,
+  currentlyCaching: [],
+};
+
+/**
+ * Subscribes to lookahead-cache status updates and exposes imperative
+ * setters for runtime reconfiguration (e.g. switch from wifi → cellular
+ * and drop the lookahead count).
+ */
+export function useLookaheadCache(): UseLookaheadCacheResult {
+  const [status, setStatus] = useState<CacheStatus>(() => {
+    try {
+      return getTrackPlayer().getLookaheadCacheStatus();
+    } catch {
+      return INITIAL;
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    const dispose = player.onCacheStatusChange((next) => {
+      setStatus(next);
+    });
+    return dispose;
+  }, []);
+
+  const setConfig = useCallback(async (config: LookaheadCacheConfig) => {
+    await getTrackPlayer().setLookaheadCache(config);
+  }, []);
+
+  const clear = useCallback(async () => {
+    await getTrackPlayer().clearLookaheadCache();
+  }, []);
+
+  return { status, setConfig, clear };
+}

package/src/hooks/useNowPlayingFormat.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+import type { NowPlayingFormat } from '../types';
+
+/**
+ * Subscribes to native `onNowPlayingFormatChange` updates.
+ *
+ * Returns `null` until the native side has resolved the active
+ * track's audio format. iOS requires `await asset.load(.tracks,
+ * .formatDescriptions, .estimatedDataRate)` per item; Android lands
+ * the data via `Player.Listener.onTracksChanged(Tracks)` before
+ * STATE_READY. Either way the format arrives moments after the
+ * `onTrackChange` event for that item — render against `null`
+ * during the gap.
+ *
+ * The first-render seed reads `getNowPlayingFormat()` synchronously
+ * so a tab re-mount mid-playback doesn't transiently flash `null`
+ * if the format is already known.
+ */
+export function useNowPlayingFormat(): NowPlayingFormat | null {
+  const [format, setFormat] = useState<NowPlayingFormat | null>(() => {
+    try {
+      return getTrackPlayer().getNowPlayingFormat();
+    } catch {
+      return null;
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    // Nitrogen types this callback parameter as `NowPlayingFormat | null
+    // | undefined` (the variant is generated as nullable-optional). Both
+    // native implementations always emit the explicit-null variant, but
+    // normalising `undefined → null` keeps the hook's React state strict
+    // against the documented `NowPlayingFormat | null` contract.
+    const dispose = player.onNowPlayingFormatChange((next) => {
+      setFormat(next ?? null);
+    });
+    return dispose;
+  }, []);
+
+  return format;
+}

package/src/hooks/usePlaybackState.ts

@@ -0,0 +1,34 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+import type { PlayerState, StateChangeReason } from '../types';
+
+export interface PlaybackStateSnapshot {
+  state: PlayerState;
+  /** Why the state last changed. `'system'` for the initial render. */
+  reason: StateChangeReason;
+}
+
+const INITIAL: PlaybackStateSnapshot = { state: 'none', reason: 'system' };
+
+/** Subscribes to native `onStateChange` updates. */
+export function usePlaybackState(): PlaybackStateSnapshot {
+  const [snapshot, setSnapshot] = useState<PlaybackStateSnapshot>(() => {
+    // Pull the current state synchronously on first render so consumers
+    // don't flash 'none' on mount.
+    try {
+      return { state: getTrackPlayer().getState(), reason: 'system' };
+    } catch {
+      return INITIAL;
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    const dispose = player.onStateChange((state, reason) => {
+      setSnapshot({ state, reason });
+    });
+    return dispose;
+  }, []);
+
+  return snapshot;
+}

package/src/hooks/useProgress.ts

@@ -0,0 +1,36 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+
+export interface ProgressState {
+  /** Seconds from start of the current track. 0 when no track active. */
+  position: number;
+  /** Seconds. 0 when duration is unknown or no track active. */
+  duration: number;
+  /** Seconds buffered ahead of `position`. 0 when unknown. */
+  buffered: number;
+}
+
+const INITIAL: ProgressState = { position: 0, duration: 0, buffered: 0 };
+
+/**
+ * Subscribes to native `onProgress` updates. Progress is driven by a native
+ * periodic timer (see NOTES.md §5), so this hook stays accurate even when
+ * the app is backgrounded.
+ */
+export function useProgress(): ProgressState {
+  const [progress, setProgress] = useState<ProgressState>(INITIAL);
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    const dispose = player.onProgress((p) => {
+      setProgress({
+        position: p.position,
+        duration: p.duration,
+        buffered: p.buffered,
+      });
+    });
+    return dispose;
+  }, []);
+
+  return progress;
+}

package/src/hooks/useSleepTimer.ts

@@ -0,0 +1,63 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+import type { SleepTimerState } from '../types';
+
+const INACTIVE: SleepTimerState = { active: false, endOfTrack: false };
+
+/** Whole seconds until the wall-clock deadline, or undefined when there isn't one yet. */
+function remainingFrom(state: SleepTimerState): number | undefined {
+  if (state.endsAtEpochMs === undefined) return undefined;
+  return Math.max(0, Math.round((state.endsAtEpochMs - Date.now()) / 1000));
+}
+
+/**
+ * Subscribes to native `onSleepTimerChange` and exposes the current sleep-timer
+ * state. `remainingSeconds` is recomputed locally once a second from the
+ * wall-clock `endsAtEpochMs`, so a countdown label stays live — the native side
+ * emits only on arm / clear / end-of-track conversion / fire, not on every tick.
+ *
+ * ```tsx
+ * const timer = useSleepTimer();
+ * // arm: player.setSleepTimer(15 * 60) or player.setSleepTimerToTrackEnd()
+ * {timer.active && (
+ *   <Text>
+ *     {timer.remainingSeconds === undefined
+ *       ? 'Stopping at end of track'
+ *       : `Sleeping in ${timer.remainingSeconds}s`}
+ *   </Text>
+ * )}
+ * ```
+ *
+ * When end-of-track is armed, `endsAtEpochMs` / `remainingSeconds` are absent
+ * while `endOfTrack` is true. Once the current track enters the tail window the
+ * timer converts to a concrete countdown: `endOfTrack` flips to false and
+ * `remainingSeconds` starts counting down.
+ */
+export function useSleepTimer(): SleepTimerState {
+  const [state, setState] = useState<SleepTimerState>(() => {
+    try {
+      return getTrackPlayer().getSleepTimer();
+    } catch {
+      return INACTIVE;
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    return player.onSleepTimerChange(setState);
+  }, []);
+
+  const [remainingSeconds, setRemainingSeconds] = useState<number | undefined>(
+    () => remainingFrom(state)
+  );
+  useEffect(() => {
+    setRemainingSeconds(remainingFrom(state));
+    // Only a concrete duration has a deadline to count down; inactive and
+    // awaiting-end-of-track states carry no `endsAtEpochMs`, so no interval runs.
+    if (state.endsAtEpochMs === undefined) return;
+    const id = setInterval(() => setRemainingSeconds(remainingFrom(state)), 1000);
+    return () => clearInterval(id);
+  }, [state]);
+
+  return { ...state, remainingSeconds };
+}

package/src/hooks/useVisualizerState.ts

@@ -0,0 +1,121 @@
+import { useEffect, useRef, useState } from 'react';
+import { getVisualizer } from '../clients';
+import type {
+  VisualizerConfig,
+  VisualizerErrorReason,
+  VisualizerFrame as BridgeVisualizerFrame,
+} from '../types';
+
+export interface VisualizerState {
+  /**
+   * Float32Array view over the FFT magnitudes. Length = `fftSize / 2`.
+   * `null` until the first frame lands.
+   */
+  fft: Float32Array | null;
+  /**
+   * Float32Array view over the raw PCM samples. Length = `fftSize`.
+   * `null` unless the subscription was opened with
+   * `config.includeSamples === true` AND a frame has landed.
+   */
+  samples: Float32Array | null;
+  /** Stream sample rate in Hz, or 0 before any frame lands. */
+  sampleRate: number;
+  /** True once any frame has landed and no error reason is active. */
+  available: boolean;
+  /** Last-reported error reason, or `null` if frames are flowing. */
+  reason: VisualizerErrorReason | null;
+}
+
+const INITIAL: VisualizerState = {
+  fft: null,
+  samples: null,
+  sampleRate: 0,
+  available: false,
+  reason: null,
+};
+
+/**
+ * Subscribe to the Visualizer for the lifetime of the hook + surface
+ * the latest frame as plain React state at `sampleRateHz` cadence
+ * (default 30 Hz).
+ *
+ * The native bridge fires frames at `config.updateIntervalMs` (the
+ * audio render thread cadence — typically 60+ Hz). Throttling to
+ * 30 Hz on the React side keeps re-render pressure manageable; ~25
+ * FPS is enough for the visualizer aesthetic and renders smoothly
+ * on 60 Hz screens.
+ *
+ * The subscription re-creates only on primitive `config` field
+ * changes — passing an inline literal each render is safe.
+ *
+ * Effects cleanly: when the hook unmounts, the disposer runs; when
+ * no other subscribers are live, the native layer pauses FFT
+ * processing.
+ */
+export function useVisualizerState(
+  config: VisualizerConfig,
+  sampleRateHz: number = 30,
+): VisualizerState {
+  const [state, setState] = useState<VisualizerState>(INITIAL);
+  // Pull primitive config fields into local scope so the effect dep
+  // array can list them directly — passing an inline `config` object
+  // each render would re-fire the effect on every parent re-render.
+  const { fftSize, updateIntervalMs, includeSamples } = config;
+
+  // Latest frame held in a ref so the audio-thread bridge callback
+  // doesn't trigger a React re-render per frame. The throttle
+  // interval below pulls from the ref. `frameEpochRef` increments
+  // once per native frame so the throttle can detect "no new frame
+  // since last setState" and skip the re-render entirely.
+  const latestFrameRef = useRef<BridgeVisualizerFrame | null>(null);
+  const latestReasonRef = useRef<VisualizerErrorReason | null>(null);
+  const frameEpochRef = useRef(0);
+
+  useEffect(() => {
+    const viz = getVisualizer();
+    const dispose = viz.subscribe(
+      { fftSize, updateIntervalMs, includeSamples },
+      (frame) => {
+        latestFrameRef.current = frame;
+        latestReasonRef.current = null;
+        frameEpochRef.current += 1;
+      },
+      (reason) => {
+        latestReasonRef.current = reason;
+      },
+    );
+
+    const intervalMs = Math.max(16, Math.round(1000 / sampleRateHz));
+    let lastSeenEpoch = 0;
+    let lastSeenReason: VisualizerErrorReason | null = null;
+    const timer = setInterval(() => {
+      const frame = latestFrameRef.current;
+      const reason = latestReasonRef.current;
+      const epoch = frameEpochRef.current;
+      if (frame && epoch !== lastSeenEpoch) {
+        lastSeenEpoch = epoch;
+        lastSeenReason = reason;
+        setState({
+          fft: new Float32Array(frame.fft),
+          samples: frame.samples ? new Float32Array(frame.samples) : null,
+          sampleRate: frame.sampleRate,
+          available: reason === null,
+          reason,
+        });
+      } else if (reason && reason !== lastSeenReason) {
+        lastSeenReason = reason;
+        setState((prev) => ({ ...prev, reason, available: false }));
+      }
+    }, intervalMs);
+
+    return () => {
+      clearInterval(timer);
+      dispose();
+      latestFrameRef.current = null;
+      latestReasonRef.current = null;
+      frameEpochRef.current = 0;
+    };
+  }, [fftSize, updateIntervalMs, includeSamples, sampleRateHz]);
+
+  return state;
+}