react-native-queue-player 1.0.0

package/src/Visualizer.nitro.ts

@@ -0,0 +1,48 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type {
+  VisualizerConfig,
+  VisualizerErrorReason,
+  VisualizerFrame,
+} from './types';
+
+// FFT-magnitude (and optional time-domain PCM) streaming HybridObject.
+// When subscriber count hits 0 the native layer pauses FFT processing —
+// zero idle CPU cost. Single subscribe-with-disposer pattern (not a
+// sub-HybridObject) for consistency with TrackPlayer events.
+
+export interface Visualizer
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  /**
+   * Subscribe to FFT (and optionally raw PCM) frames.
+   *
+   * `onFrame` fires every `config.updateIntervalMs` while the engine is
+   * actively producing audio:
+   *   - `frame.fft`: Float32 magnitudes, length = `fftSize / 2`.
+   *     Underlying storage is shared zero-copy with the native buffer
+   *     for the lifetime of the call.
+   *   - `frame.samples`: Float32 raw pre-window time-domain PCM,
+   *     length = `fftSize`. The Hann window applied for the FFT
+   *     does NOT touch this payload — consumers receive the same
+   *     mono-mixed samples that fed the FFT, suitable for
+   *     oscilloscope / Lissajous / waveform displays. Present iff
+   *     `config.includeSamples === true`.
+   *   - `frame.sampleRate`: stream sample rate in Hz.
+   *
+   * `onError` fires when a subscription cannot deliver frames — see
+   * VisualizerErrorReason for the cases. The lib does not request the
+   * Android `RECORD_AUDIO` permission: the FFT runs against the app's
+   * own decoded PCM via Media3's TeeAudioProcessor (Android) and an
+   * MTAudioProcessingTap on the AVAudioMix (iOS).
+   *
+   * Call the returned disposer to unsubscribe; when the last subscriber
+   * disposes, native FFT processing stops.
+   */
+  subscribe(
+    config: VisualizerConfig,
+    onFrame: (frame: VisualizerFrame) => void,
+    onError: (reason: VisualizerErrorReason) => void
+  ): () => void;
+
+  /** How many active subscriptions exist right now. Useful for diagnostics. */
+  getSubscriberCount(): number;
+}

package/src/cast/index.ts

@@ -0,0 +1,224 @@
+import { getCastManager } from '../clients';
+import type {
+  CastConnectOptions,
+  CastDeviceKind,
+  CastDiscoveryState,
+  CastLocalNetworkPermission,
+  CastLocalNetworkPermissionEvent,
+  CastProtocol,
+  CastReceiver,
+  CastReceiverCapabilities,
+  CastRoute,
+  CastSessionDiedEvent,
+  CastSessionEndReason,
+  CastStreamingModel,
+} from '../types';
+
+export type {
+  CastConnectOptions,
+  CastDeviceKind,
+  CastDiscoveryState,
+  CastLocalNetworkPermission,
+  CastLocalNetworkPermissionEvent,
+  CastProtocol,
+  CastReceiver,
+  CastReceiverCapabilities,
+  CastRoute,
+  CastSessionDiedEvent,
+  CastSessionEndReason,
+  CastStreamingModel,
+};
+
+/**
+ * Subscription handle returned by every `add*Listener` function. Call
+ * [remove] to unsubscribe — idempotent + safe inside the listener body.
+ */
+export interface CastSubscription {
+  remove(): void;
+}
+
+/**
+ * Native error codes surfaced on rejected `connect()` promises. Use these
+ * to detect specific failure modes — e.g. `AUTH_REQUIRED` indicates the
+ * receiver wants a password and the JS layer should prompt the user then
+ * retry with `connect(id, { password })`.
+ */
+export const CastErrorCodes = {
+  CONNECT_FAILED: 'cast_connect_failed',
+  AUTH_REQUIRED: 'cast_auth_required',
+} as const;
+
+export type CastErrorCode = (typeof CastErrorCodes)[keyof typeof CastErrorCodes];
+
+/** Synthesised local route used when no remote session is active. */
+const LOCAL_ROUTE: CastRoute = {
+  castProtocol: 'local',
+  receiverId: '',
+  name: 'Phone speaker',
+  iconHint: 'phone',
+  capabilities: {
+    supportsRemoteVolume: false,
+    streamingModel: 'pushPcm',
+    requiresPairing: false,
+  },
+  protocolVersion: '',
+};
+
+// === Capability
+
+/** Protocols the current build actually supports (AirPlay, Chromecast, both). */
+export function getSupportedProtocols(): CastProtocol[] {
+  return getCastManager().getSupportedProtocols();
+}
+
+/** Convenience: true when at least one cast protocol is available. */
+export function isCastAvailable(): boolean {
+  return getSupportedProtocols().length > 0;
+}
+
+// === Configuration
+
+export interface CastConfig {
+  /** Name advertised to receivers — shown on approval dialogs / now-playing. */
+  deviceName: string;
+  /**
+   * Hide AirPlay receivers running on Mac computers from the device list.
+   * macOS AirPlay Receiver only accepts Apple senders on the same Apple ID,
+   * so it can't be cast to from here — hidden by default. Set `false` to
+   * surface them anyway. Android-only (iOS AirPlay is OS-managed).
+   */
+  hideAirPlayComputers?: boolean;
+}
+
+export function configure(config: CastConfig): Promise<void> {
+  return getCastManager().configure({
+    deviceName: config.deviceName,
+    hideAirPlayComputers: config.hideAirPlayComputers,
+  });
+}
+
+// === Discovery
+
+export function startDiscovery(): Promise<void> {
+  return getCastManager().startDiscovery();
+}
+
+export function stopDiscovery(): Promise<void> {
+  return getCastManager().stopDiscovery();
+}
+
+export function isDiscovering(): boolean {
+  return getCastManager().isDiscovering();
+}
+
+// === Receivers + Route
+
+export function getReceivers(): CastReceiver[] {
+  return getCastManager().getReceivers();
+}
+
+export function getCurrentRoute(): CastRoute {
+  return getCastManager().getCurrentRoute();
+}
+
+// === Session
+
+export function connect(
+  receiverId: string,
+  options?: { password?: string }
+): Promise<void> {
+  const payload: CastConnectOptions = { password: options?.password ?? '' };
+  return getCastManager().connect(receiverId, payload);
+}
+
+export function disconnect(): Promise<void> {
+  return getCastManager().disconnect();
+}
+
+/**
+ * Show the system route picker (iOS AVRoutePickerView). On Android there
+ * is no native system Cast picker — render the bundled `RoutePicker`
+ * component instead.
+ */
+export function showSystemPicker(): Promise<void> {
+  return getCastManager().showSystemPicker();
+}
+
+// === Volume
+
+/** Read the active receiver's volume (`0.0..1.0`), or `NaN` when unknown. */
+export function getRouteVolume(): number {
+  return getCastManager().getRouteVolume();
+}
+
+export function setRouteVolume(value: number): Promise<void> {
+  return getCastManager().setRouteVolume(value);
+}
+
+// === AirPlay pairing
+
+export function submitPairingPin(pin: string): Promise<void> {
+  return getCastManager().submitPairingPin(pin);
+}
+
+// === Local Network permission
+
+export function getLocalNetworkPermissionState(): CastLocalNetworkPermission {
+  return getCastManager().getLocalNetworkPermissionState();
+}
+
+export function requestLocalNetworkPermission(): Promise<CastLocalNetworkPermission> {
+  return getCastManager().requestLocalNetworkPermission();
+}
+
+// === Listeners
+
+function toSubscription(dispose: () => void): CastSubscription {
+  let removed = false;
+  return {
+    remove() {
+      if (removed) return;
+      removed = true;
+      dispose();
+    },
+  };
+}
+
+export function addRouteListener(
+  listener: (route: CastRoute) => void
+): CastSubscription {
+  return toSubscription(getCastManager().onRouteChange(listener));
+}
+
+export function addReceiversListener(
+  listener: (receivers: CastReceiver[]) => void
+): CastSubscription {
+  return toSubscription(getCastManager().onReceiversChange(listener));
+}
+
+export function addDiscoveryStateListener(
+  listener: (state: CastDiscoveryState) => void
+): CastSubscription {
+  return toSubscription(getCastManager().onDiscoveryStateChange(listener));
+}
+
+export function addSessionDiedListener(
+  listener: (event: CastSessionDiedEvent) => void
+): CastSubscription {
+  return toSubscription(getCastManager().onSessionDied(listener));
+}
+
+export function addLocalNetworkPermissionListener(
+  listener: (event: CastLocalNetworkPermissionEvent) => void
+): CastSubscription {
+  return toSubscription(
+    getCastManager().onLocalNetworkPermissionChange(listener)
+  );
+}
+
+// === Helpers
+
+/** Local fallback route. Useful for picker UI before discovery starts. */
+export function localRoute(): CastRoute {
+  return LOCAL_ROUTE;
+}

package/src/clients.ts

@@ -0,0 +1,50 @@
+import { NitroModules } from 'react-native-nitro-modules';
+
+import type { CastManager } from './CastManager.nitro';
+import type { Equalizer } from './Equalizer.nitro';
+import type { TrackPlayer } from './TrackPlayer.nitro';
+import type { Visualizer } from './Visualizer.nitro';
+
+/**
+ * HybridObject accessors. Lives in its own module so the public
+ * `index.ts` barrel and the React hooks under `hooks/` can both
+ * import from here without forming a require cycle through the
+ * barrel.
+ *
+ * Each accessor is a memoised singleton — Nitro is happy to vend
+ * the same hybrid instance on repeated `createHybridObject` calls,
+ * but caching avoids the round-trip through the JSI bridge.
+ */
+
+let _player: TrackPlayer | null = null;
+let _equalizer: Equalizer | null = null;
+let _visualizer: Visualizer | null = null;
+let _castManager: CastManager | null = null;
+
+export function getTrackPlayer(): TrackPlayer {
+  if (_player == null) {
+    _player = NitroModules.createHybridObject<TrackPlayer>('TrackPlayer');
+  }
+  return _player;
+}
+
+export function getEqualizer(): Equalizer {
+  if (_equalizer == null) {
+    _equalizer = NitroModules.createHybridObject<Equalizer>('Equalizer');
+  }
+  return _equalizer;
+}
+
+export function getVisualizer(): Visualizer {
+  if (_visualizer == null) {
+    _visualizer = NitroModules.createHybridObject<Visualizer>('Visualizer');
+  }
+  return _visualizer;
+}
+
+export function getCastManager(): CastManager {
+  if (_castManager == null) {
+    _castManager = NitroModules.createHybridObject<CastManager>('CastManager');
+  }
+  return _castManager;
+}

package/src/equalizer.ts

@@ -0,0 +1,86 @@
+import type { EqualizerBand, EqualizerPreset } from './types';
+
+/**
+ * Pure-function helper utilities for the equalizer surface. The
+ * imperative API lives on `getEqualizer()` and the React hook
+ * lives in `hooks/useEqualizer`; this module gives consumers
+ * format / range / lookup helpers that don't require a Hybrid call.
+ */
+
+/** Project-wide gain range. Matches the native clamp on both platforms. */
+export const EQ_GAIN_MIN_DB = -12;
+export const EQ_GAIN_MAX_DB = 12;
+
+/** ISO-standard centre frequencies (Hz) the cascade processes. */
+export const EQ_BAND_FREQUENCIES_HZ: readonly number[] = [
+  31, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000,
+];
+
+/** Number of bands in the cascade (pinned to 10). */
+export const EQ_BAND_COUNT = 10;
+
+/**
+ * Clamp a gain (dB) to the project-wide spec range. Values
+ * outside the range round to the nearest endpoint rather than
+ * throwing — JS callers can pass slider values without explicit
+ * pre-validation.
+ */
+export function clampGain(dB: number): number {
+  if (Number.isNaN(dB)) return 0;
+  if (dB < EQ_GAIN_MIN_DB) return EQ_GAIN_MIN_DB;
+  if (dB > EQ_GAIN_MAX_DB) return EQ_GAIN_MAX_DB;
+  return dB;
+}
+
+/** Sentinel name used by both platforms for the no-EQ identity preset. */
+export const EQ_FLAT_PRESET_NAME = 'Flat';
+
+/** Returns true when [name] is one of the 16 built-in presets. */
+export function isBuiltinPreset(presets: readonly EqualizerPreset[], name: string): boolean {
+  return presets.some((p) => p.name === name && p.builtin);
+}
+
+/**
+ * Build a 10-element gain array from a partial map keyed by
+ * band index. Missing entries default to 0; out-of-range indices
+ * are silently dropped. Useful when the consumer's UI tracks
+ * gains as a sparse `{ [index]: gainDb }` shape.
+ */
+export function gainsFromMap(map: Readonly<Record<number, number>>): number[] {
+  const out = new Array<number>(EQ_BAND_COUNT).fill(0);
+  for (const [k, v] of Object.entries(map)) {
+    const idx = Number(k);
+    if (Number.isInteger(idx) && idx >= 0 && idx < EQ_BAND_COUNT) {
+      out[idx] = clampGain(v);
+    }
+  }
+  return out;
+}
+
+/**
+ * Find the band whose centre frequency is closest to [hz]. Used
+ * by visualisations that need to map an arbitrary frequency
+ * (e.g. an FFT bin) to the nearest cascade band.
+ */
+export function nearestBandIndex(hz: number): number {
+  let bestIdx = 0;
+  let bestDist = Infinity;
+  for (let i = 0; i < EQ_BAND_FREQUENCIES_HZ.length; i++) {
+    const freq = EQ_BAND_FREQUENCIES_HZ[i] ?? 0;
+    const d = Math.abs(freq - hz);
+    if (d < bestDist) {
+      bestDist = d;
+      bestIdx = i;
+    }
+  }
+  return bestIdx;
+}
+
+/**
+ * Snapshot a band array down to a plain `number[]` of gains in
+ * cascade order. Useful when feeding [setAllBandGains] from a
+ * UI that tracks `EqualizerBand[]` shape internally.
+ */
+export function gainsFromBands(bands: readonly EqualizerBand[]): number[] {
+  return bands.map((b) => clampGain(b.gainDb));
+}

package/src/hooks/index.ts

@@ -0,0 +1,33 @@
+export { useProgress } from './useProgress';
+export type { ProgressState } from './useProgress';
+
+export { usePlaybackState } from './usePlaybackState';
+export type { PlaybackStateSnapshot } from './usePlaybackState';
+
+export { useActiveTrack } from './useActiveTrack';
+export type { ActiveTrackSnapshot } from './useActiveTrack';
+
+export { useCanSkip } from './useCanSkip';
+export type { CanSkipSnapshot } from './useCanSkip';
+
+export { useSleepTimer } from './useSleepTimer';
+
+export { useBufferState } from './useBufferState';
+
+export { useFullyBuffered } from './useFullyBuffered';
+
+export { useEqualizer } from './useEqualizer';
+export type { UseEqualizerResult } from './useEqualizer';
+
+export { useVisualizerState } from './useVisualizerState';
+export type { VisualizerState } from './useVisualizerState';
+
+export { useLookaheadCache } from './useLookaheadCache';
+export type { UseLookaheadCacheResult } from './useLookaheadCache';
+
+export { useNowPlayingFormat } from './useNowPlayingFormat';
+
+export { useCast } from './useCast';
+export type { CastSnapshot } from './useCast';
+
+export { useAudioRoute } from './useAudioRoute';

package/src/hooks/useActiveTrack.ts

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+import type { TrackItem, TrackChangeReason } from '../types';
+
+export interface ActiveTrackSnapshot {
+  track: TrackItem | undefined;
+  /** -1 when the queue is empty. */
+  index: number;
+  /** Why the track last changed. `'queue-replaced'` for the initial render. */
+  reason: TrackChangeReason;
+}
+
+const INITIAL: ActiveTrackSnapshot = {
+  track: undefined,
+  index: -1,
+  reason: 'queue-replaced',
+};
+
+/**
+ * Subscribes to native `onTrackChange` updates.
+ *
+ * The first-render seed reads `getQueue()` and `getCurrentTrackIndex()`
+ * separately — the pair is not atomic against a concurrent queue
+ * mutation on either platform, so the seed can briefly observe the
+ * new list with the old index (or vice versa). Self-healing: the
+ * next `onTrackChange` event delivers a consistent
+ * `(track, index, reason)` triple. Consumers needing an atomic
+ * snapshot should wait for the first listener fire.
+ */
+export function useActiveTrack(): ActiveTrackSnapshot {
+  const [snapshot, setSnapshot] = useState<ActiveTrackSnapshot>(() => {
+    try {
+      const player = getTrackPlayer();
+      const queue = player.getQueue();
+      const index = player.getCurrentTrackIndex();
+      return {
+        track: index >= 0 && index < queue.length ? queue[index] : undefined,
+        index,
+        reason: 'queue-replaced',
+      };
+    } catch {
+      return INITIAL;
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    const dispose = player.onTrackChange((track, index, reason) => {
+      setSnapshot({ track, index, reason });
+    });
+    return dispose;
+  }, []);
+
+  return snapshot;
+}

package/src/hooks/useAudioRoute.ts

@@ -0,0 +1,69 @@
+import { useEffect, useRef, useState } from 'react';
+import { getCastManager } from '../clients';
+import type { AudioRoute } from '../types';
+
+const LOCAL_FALLBACK: AudioRoute = {
+  kind: 'speaker',
+  name: 'Phone speaker',
+  identifier: '',
+  isExternal: false,
+  isSystemManaged: true,
+};
+
+/**
+ * Subscribe to the active audio output. Returns the current `AudioRoute`
+ * (kind + name + identifier + isExternal + isSystemManaged) and updates
+ * on every system route change — BT pair/unpair, wired plug/unplug,
+ * AirPlay route swap, Chromecast session activate/deactivate.
+ *
+ * Independent of cast discovery: reading does not trigger a scan. The
+ * picker can show "currently playing on AirPods (Bluetooth)" while
+ * cast discovery is idle.
+ */
+export function useAudioRoute(): AudioRoute {
+  const initialRef = useRef<AudioRoute | null>(null);
+  const [route, setRoute] = useState<AudioRoute>(() => {
+    const initial = readInitialRoute();
+    initialRef.current = initial;
+    return initial;
+  });
+
+  useEffect(() => {
+    const dispose = getCastManager().onAudioRouteChange((next) => {
+      // The native side replays the current route synchronously on
+      // subscribe. The `useState` initializer already captured an
+      // initial value; skip the replay only when it matches that
+      // value. If the route changed in the gap between mount and
+      // subscribe (e.g. BT pair raced the render), the replay
+      // delivers the new state instead of being silently dropped.
+      const initial = initialRef.current;
+      if (initial != null && audioRouteEquals(initial, next)) {
+        initialRef.current = null;
+        return;
+      }
+      initialRef.current = null;
+      setRoute(next);
+    });
+    return dispose;
+  }, []);
+
+  return route;
+}
+
+function readInitialRoute(): AudioRoute {
+  try {
+    return getCastManager().getCurrentAudioRoute();
+  } catch {
+    return LOCAL_FALLBACK;
+  }
+}
+
+function audioRouteEquals(a: AudioRoute, b: AudioRoute): boolean {
+  return (
+    a.kind === b.kind &&
+    a.name === b.name &&
+    a.identifier === b.identifier &&
+    a.isExternal === b.isExternal &&
+    a.isSystemManaged === b.isSystemManaged
+  );
+}

package/src/hooks/useBufferState.ts

@@ -0,0 +1,35 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+import type { BufferState } from '../types';
+
+/**
+ * Subscribes to native `onBufferStateChange` and exposes the current discrete
+ * buffer state for the active track (`'empty' | 'buffering' | 'stalled' | 'full'`). Driven by
+ * the platform's native buffer signals rather than the progress tick, so a
+ * loading / stall indicator reacts immediately.
+ *
+ * ```tsx
+ * const buffer = useBufferState();
+ * {buffer !== 'full' && <Spinner />}
+ * ```
+ *
+ * `'full'` means playback can proceed smoothly from the current position, not
+ * that the whole track is downloaded — for buffered-ahead seconds read
+ * `useProgress().buffered`.
+ */
+export function useBufferState(): BufferState {
+  const [state, setState] = useState<BufferState>(() => {
+    try {
+      return getTrackPlayer().getBufferState();
+    } catch {
+      return 'empty';
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    return player.onBufferStateChange(setState);
+  }, []);
+
+  return state;
+}

package/src/hooks/useCanSkip.ts

@@ -0,0 +1,92 @@
+import { useEffect, useRef, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+
+export interface CanSkipSnapshot {
+  /**
+   * Whether the user-facing Next button should be enabled. True when
+   * there's a next track to skip to under the current repeat mode:
+   * false at the last track in `'off'` and `'track'` (no wrap), always
+   * true under `'queue'` (wraps). `'track'` (repeat-one) navigates
+   * exactly like `'off'`; only natural auto-advance replays the
+   * current track.
+   */
+  canSkipNext: boolean;
+  /**
+   * Whether the user-facing Previous button should be enabled.
+   * Symmetric with `canSkipNext` — true when there's a previous track
+   * to skip to under the current repeat mode (false at index 0 in
+   * `'off'` and `'track'` — no wrap; true under `'queue'` since it
+   * wraps). Apps that want the Apple-Music-style "tap Previous
+   * restarts current when position > 3s" UX implement that themselves
+   * in their button handler.
+   */
+  canSkipPrevious: boolean;
+}
+
+const INITIAL: CanSkipSnapshot = {
+  canSkipNext: false,
+  canSkipPrevious: false,
+};
+
+/**
+ * Subscribes to native `onSkipCapabilityChange` updates. Bind the
+ * returned booleans to the `disabled` prop of skip-next / skip-prev
+ * buttons:
+ *
+ * ```tsx
+ * const { canSkipNext, canSkipPrevious } = useCanSkip();
+ * <Button disabled={!canSkipPrevious} onPress={() => player.skipToPrevious()} />
+ * <Button disabled={!canSkipNext} onPress={() => player.skipToNext()} />
+ * ```
+ *
+ * The native side recomputes whenever queue, current index, repeat
+ * mode, or shuffle changes, with dedup so the listener fires only on
+ * actual flips. The first render seeds synchronously via
+ * `getCanSkipNext` / `getCanSkipPrevious` to avoid the "buttons flash
+ * disabled then enabled" UX on mount; the listener also auto-fires
+ * on subscribe (Media3 `onAvailableCommandsChanged` semantic). When
+ * the auto-fire payload matches the seed, the dedup ref below
+ * suppresses the redundant re-render.
+ */
+export function useCanSkip(): CanSkipSnapshot {
+  const [snapshot, setSnapshot] = useState<CanSkipSnapshot>(() => {
+    try {
+      const player = getTrackPlayer();
+      return {
+        canSkipNext: player.getCanSkipNext(),
+        canSkipPrevious: player.getCanSkipPrevious(),
+      };
+    } catch {
+      return INITIAL;
+    }
+  });
+
+  // Mirror state in a ref so the listener can dedup against the
+  // current value without taking a dep on `snapshot` (which would
+  // re-subscribe the listener on every change). Updated alongside
+  // `setSnapshot` inside the listener so the ref + state stay in
+  // lockstep across back-to-back fires within a single render.
+  const snapshotRef = useRef(snapshot);
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    const dispose = player.onSkipCapabilityChange((capability) => {
+      const curr = snapshotRef.current;
+      if (
+        curr.canSkipNext === capability.canSkipNext &&
+        curr.canSkipPrevious === capability.canSkipPrevious
+      ) {
+        return;
+      }
+      const next = {
+        canSkipPrevious: capability.canSkipPrevious,
+        canSkipNext: capability.canSkipNext,
+      };
+      snapshotRef.current = next;
+      setSnapshot(next);
+    });
+    return dispose;
+  }, []);
+
+  return snapshot;
+}