react-native-queue-player 1.2.0 → 2.0.0

package/src/hooks/useQueue.ts

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { getTrackPlayer } from '../clients';
 import type { TrackItem } from '../types';
+import { applyQueueDelta } from '../queueDelta';
 
 export interface QueueSnapshot {
   /** The current queue, in play order. */
@@ -17,28 +18,75 @@ const INITIAL: QueueSnapshot = { queue: [], currentIndex: -1 };
  * `onTrackChange` so `currentIndex` stays live on auto-advance / skip,
  * which move the active position without changing the queue contents.
  *
- * The first-render seed reads `getQueue()` + `getCurrentTrackIndex()`
- * separately — the pair is not atomic against a concurrent mutation, so
- * it can briefly skew. Self-healing: the first `onQueueChange` /
- * `onTrackChange` fire delivers a consistent snapshot.
+ * Renders empty for the first frame, then fills in: the seed reads
+ * `getQueue()`, which resolves asynchronously. A mutation landing in that gap
+ * is not lost: a delta that arrives before the seed lands cannot be applied —
+ * there is nothing correct to apply it to — so the queue is re-read instead.
  */
 export function useQueue(): QueueSnapshot {
-  const [snapshot, setSnapshot] = useState<QueueSnapshot>(() => {
-    try {
-      const player = getTrackPlayer();
-      return {
-        queue: player.getQueue(),
-        currentIndex: player.getCurrentTrackIndex(),
-      };
-    } catch {
-      return INITIAL;
-    }
-  });
+  const [snapshot, setSnapshot] = useState<QueueSnapshot>(INITIAL);
 
   useEffect(() => {
     const player = getTrackPlayer();
-    const offQueue = player.onQueueChange((queue, currentIndex) => {
-      setSnapshot({ queue, currentIndex });
+    let disposed = false;
+    // `haveBase` is what makes a delta applicable: without a queue to apply it
+    // to, applying one silently produces a wrong mirror — and for `shuffle`, an
+    // array of holes. `seenEvent` separately stops a slow seed overwriting
+    // newer state.
+    let haveBase = false;
+    let seenEvent = false;
+    let revision = 0;
+    // Guards against two overlapping re-reads resolving out of order.
+    let readTicket = 0;
+
+    const reread = () => {
+      const ticket = ++readTicket;
+      // Until this read lands there is no base a delta can be applied to:
+      // an event arriving meanwhile re-reads too, and the ticket keeps the
+      // last read's answer.
+      haveBase = false;
+      void player
+        .getQueue()
+        .then((queue) => {
+          if (disposed || ticket !== readTicket) return;
+          haveBase = true;
+          // Re-read the index too: the queue just came from a fresh read, and
+          // the index captured when the event fired may already be stale.
+          setSnapshot({ queue, currentIndex: player.getCurrentTrackIndex() });
+        })
+        .catch(() => {
+          // Player not configured yet; a later event re-reads.
+        });
+    };
+
+    void (async () => {
+      try {
+        const ticket = ++readTicket;
+        const queue = await player.getQueue();
+        const currentIndex = player.getCurrentTrackIndex();
+        if (disposed || seenEvent || ticket !== readTicket) return;
+        haveBase = true;
+        setSnapshot({ queue, currentIndex });
+      } catch {
+        // Player not configured yet; the first event re-reads instead.
+      }
+    })();
+
+    // A delta only makes sense against the copy it was computed from, so a
+    // missed event — or one that beats the seed — is recovered by re-reading
+    // rather than patched over.
+    const offQueue = player.onQueueChange((delta, currentIndex, reason) => {
+      seenEvent = true;
+      const missed = revision !== 0 && delta.revision !== revision + 1;
+      revision = delta.revision;
+      if (!haveBase || missed) {
+        reread();
+        return;
+      }
+      setSnapshot((prev) => ({
+        queue: applyQueueDelta(prev.queue, delta, reason),
+        currentIndex,
+      }));
     });
     // Keep `currentIndex` live when the active track changes without a
     // queue-content change (auto-advance, skip). Preserves the queue from
@@ -47,6 +95,7 @@ export function useQueue(): QueueSnapshot {
       setSnapshot((prev) => ({ queue: prev.queue, currentIndex: index }));
     });
     return () => {
+      disposed = true;
       offQueue();
       offTrack();
     };

package/src/index.ts

@@ -9,6 +9,9 @@ export type {
   // Player
   TrackItem,
   PlayerConfig,
+  AudioContentType,
+  AudioCategoryOptions,
+  VoiceVocabulary,
   PlayerState,
   BufferState,
   PlaybackMode,
@@ -20,6 +23,7 @@ export type {
   StateChangeReason,
   TrackChangeReason,
   QueueChangeReason,
+  QueueChangeDelta,
   TrackSource,
   PlayerProgress,
   PlaybackError,
@@ -28,6 +32,8 @@ export type {
   SkipCapability,
   SleepTimerState,
   NowPlayingFormat,
+  NowPlayingFormatIosExtras,
+  NowPlayingFormatAndroidExtras,
   AudioCodec,
   AudioContainer,
   // Lookahead cache
@@ -71,6 +77,7 @@ export type {
   CastSessionDiedEvent,
   CastLocalNetworkPermissionEvent,
   CastConnectOptions,
+  CastConfigureOptions,
   // Audio route (cast + on-device)
   AudioRouteKind,
   AudioRoute,
@@ -118,10 +125,13 @@ export {
   nearestBandIndex,
 } from './equalizer';
 
+// Pure helper for applying an onQueueChange delta to a queue copy.
+export { applyQueueDelta } from './queueDelta';
+
 // React hooks — thin observers over the HybridObject event surface.
 export * from './hooks';
 
-// Cast — Promise-based wrappers + listener subscriptions around the
-// `CastManager` HybridObject. Consumers can either reach in via
-// `getCastManager()` directly or import from `react-native-queue-player/cast`.
+// Cast — `Cast.*`: thin functions over the `CastManager` HybridObject
+// (optional-argument shapes, `CastSubscription` handles, `CastErrorCodes`,
+// `localRoute()`); `getCastManager()` returns the HybridObject itself.
 export * as Cast from './cast';

package/src/queueDelta.ts

@@ -0,0 +1,41 @@
+import type { QueueChangeDelta, QueueChangeReason, TrackItem } from './types';
+
+/**
+ * Rebuild the queue from the previous copy plus one change.
+ *
+ * Exported from the package root as the reference for what a consumer must do
+ * with a delta; `useQueue` applies it too. The shapes it reads are documented
+ * on [QueueChangeDelta].
+ */
+export function applyQueueDelta(
+  previous: TrackItem[],
+  delta: QueueChangeDelta,
+  reason: QueueChangeReason
+): TrackItem[] {
+  switch (reason) {
+    case 'set-queue':
+      return delta.inserted.slice();
+    case 'clear':
+      return [];
+    case 'add': {
+      const next = previous.slice();
+      next.splice(delta.insertedAt, 0, ...delta.inserted);
+      return next;
+    }
+    case 'remove': {
+      const drop = new Set(delta.removed);
+      return previous.filter((_, i) => !drop.has(i));
+    }
+    case 'move': {
+      const next = previous.slice();
+      const [moved] = next.splice(delta.movedFrom, 1);
+      if (moved) next.splice(delta.movedTo, 0, moved);
+      return next;
+    }
+    case 'shuffle':
+      // `order[i]` is where the track now at `i` used to be.
+      return delta.order.map((from) => previous[from]!);
+    default:
+      return previous;
+  }
+}

package/src/types.ts

@@ -44,6 +44,32 @@ export interface TrackItem {
   artworkUrl?: string;
   /** Opaque passthrough the consuming app can attach; the module does not read it. */
   extras?: Record<string, string>;
+  /**
+   * Consumer-supplied `REPLAYGAIN_TRACK_GAIN` in dB.
+   *
+   * The four ReplayGain fields are all-or-nothing per track: supplying
+   * ANY of them makes this track's ReplayGain come solely from these
+   * values, and whatever the file itself carries is discarded in full —
+   * including for the mode nothing was supplied for. Supplying a value
+   * is the statement of intent; a track that should use the file's own
+   * tags carries none of these fields.
+   *
+   * Presence is what claims the track, not validity: a lone
+   * out-of-range peak still discards the file's tags and leaves the
+   * track playing at unity.
+   */
+  replayGainTrackGain?: number;
+  /**
+   * Consumer-supplied `REPLAYGAIN_TRACK_PEAK`, linear. Accepted in the
+   * `0.001 ... 2.0` band — `1.0` is digital full scale and caps a boost
+   * at unity. A gain with no usable peak has its boost clamped to unity
+   * and reports a `null` peak.
+   */
+  replayGainTrackPeak?: number;
+  /** Consumer-supplied `REPLAYGAIN_ALBUM_GAIN` in dB. */
+  replayGainAlbumGain?: number;
+  /** Consumer-supplied `REPLAYGAIN_ALBUM_PEAK`, linear. */
+  replayGainAlbumPeak?: number;
 }
 
 /**
@@ -89,7 +115,7 @@ export interface PlayerConfig {
   /**
    * Auto-retry attempts on transient errors (TIMEOUT / CONNECTION_LOST /
    * NETWORK_UNREACHABLE / SOURCE_UNREACHABLE / CANNOT_OPEN). Clamped
-   * to [0, 5]; default 3. Fatal errors (codec / format / auth) are
+   * to [0, 5]; default 1. Fatal errors (codec / format / auth) are
    * never retried regardless of this setting.
    */
   autoRetries?: number;
@@ -133,6 +159,30 @@ export interface PlayerConfig {
    * configure rule as `audioContentType`.
    */
   audioCategoryOptions?: AudioCategoryOptions;
+  /**
+   * Opt in to donating the consumer's catalog to Siri's vocabulary, so voice
+   * queries like "Play Pearl Jam" resolve against the app's own artist and
+   * playlist names. Enables `donateVoiceVocabulary`, which is inert without
+   * it. Default `false`.
+   *
+   * **iOS only.** Android ignores this field: Google Assistant has no in-app
+   * vocabulary donation API, and `donateVoiceVocabulary` is already a no-op
+   * there.
+   *
+   * **Enabling it requires the `com.apple.developer.siri` entitlement** —
+   * Xcode's Siri capability — not just `NSSiriUsageDescription` in
+   * Info.plist. `INVocabulary` checks for the entitlement at runtime and
+   * raises an Objective-C exception without it, which cannot be caught from
+   * Swift and terminates the app. iOS gives a process no way to read its own
+   * entitlements, so the library cannot verify this on your behalf: leave the
+   * flag `false` unless the Siri capability is on the target.
+   *
+   * **Pinned at the first `configure()` for the life of the process.** The
+   * entitlement it depends on is fixed when the app is signed, so there is
+   * nothing for a later change to mean; a re-`configure()` with a different
+   * value is ignored rather than silently re-arming a crash path.
+   */
+  voiceVocabularyDonationEnabled?: boolean;
   /**
    * Disable the visualization pipeline at engine construction. When
    * `false`, the lib skips the viz-side audio chain entirely:
@@ -195,6 +245,16 @@ export interface PlayerConfig {
    * `100`. Control actual runtime usage via `setLookaheadCache`'s `enabled` +
    * `lookaheadCount`; read the active ceiling back from
    * `getLookaheadCacheStatus().maxSizeMb`.
+   *
+   * Where the playing track is protected from eviction, this is a budget rather
+   * than a hard cap — that is both policies on iOS, and `'fifo'` on Android
+   * (see `EvictionPolicy`). Eviction never takes the playing track or its
+   * immediate neighbours, so when those alone exceed the budget nothing is
+   * evictable and usage can exceed it —
+   * `getLookaheadCacheStatus().currentSizeMb` may read above `maxSizeMb` until
+   * the window moves. Reachable with lossless sources and a large
+   * `lookaheadCount`; size the budget for `2 + lookaheadCount` tracks to avoid
+   * it. The alternative would be evicting the track being played.
    */
   lookaheadCacheMaxSizeMb?: number;
   /**
@@ -471,6 +531,53 @@ export type QueueChangeReason =
   | 'clear' // clearQueue emptied the queue
   | 'shuffle'; // shuffleQueue reordered the queue
 
+/**
+ * What a queue mutation did, delivered by `onQueueChange` alongside the reason.
+ *
+ * Describes the change rather than re-sending the queue, so a reorder costs two
+ * numbers instead of one `TrackItem` per entry. Which fields carry meaning
+ * depends on the reason; the rest are empty or `-1`.
+ *
+ * Apply it to your own copy of the queue, or call `getQueue()` if you would
+ * rather re-read than track it. `useQueue()` does the former for you.
+ *
+ * **Not every emptying of the queue is reported.** `destroy()` and `configure()`
+ * clear it without an event, and `configure()` runs that teardown on every call,
+ * so a mirror held across one is stale with nothing to signal it.
+ */
+export interface QueueChangeDelta {
+  /**
+   * Increments once per emit. A jump of more than one means an event was missed
+   * and the mirror should be rebuilt from `getQueue()`. Length alone cannot
+   * detect that — `move`, `shuffle` and a same-size `set-queue` all preserve it.
+   */
+  revision: number;
+  /** Queue length after the mutation. */
+  length: number;
+  /**
+   * Tracks now occupying `[insertedAt, insertedAt + inserted.length)`.
+   * Populated for `add` and `set-queue`; empty otherwise.
+   *
+   * `set-queue` carries the whole queue because the subscriber is not
+   * necessarily whoever called `setQueue` — and on Android an assistant or
+   * Android Auto request replaces the queue with tracks the app never passed in.
+   */
+  inserted: TrackItem[];
+  /** Where `inserted` begins, or `-1` when nothing was inserted. */
+  insertedAt: number;
+  /** Positions removed, ascending, as they were before the removal. */
+  removed: number[];
+  /** Position a `move` came from, else `-1`. */
+  movedFrom: number;
+  /** Position a `move` went to, else `-1`. */
+  movedTo: number;
+  /**
+   * For `shuffle`: `order[i]` is the position the track now at `i` held before
+   * the shuffle. Empty for every other reason.
+   */
+  order: number[];
+}
+
 /**
  * How the active track is being played:
  * - `'local'` — `track.url` is a `file://` URL.
@@ -556,10 +663,21 @@ export interface NowPlayingFormat {
   /** Channel count (1 = mono, 2 = stereo, 6 = 5.1, etc.), or `null`. */
   channelCount: number | null;
   /**
-   * Average / nominal bitrate in bits-per-second. `null` when not
-   * detectable. Reliable for `file://` + progressive HTTP MP3/M4A/FLAC;
-   * for HLS, returns the variant's nominal bandwidth from the
-   * manifest.
+   * Average encoded bitrate in bits-per-second, or `null` when the source
+   * does not declare one and it cannot be measured.
+   *
+   * Available for `file://` sources of any codec, and for progressive HTTP
+   * and HLS sources whose stream or manifest declares a rate — which MP3,
+   * M4A/AAC and HLS variants do.
+   *
+   * **Not available for remote FLAC.** The FLAC header carries no bitrate
+   * — the format does not declare one — so it can only be derived from the
+   * file's size over its duration. That works for a local file and needs a
+   * request the library does not make for a remote one.
+   *
+   * A derived figure is the whole-file average, so it includes container
+   * headers and embedded artwork: typically a few kbps above the audio-only
+   * rate.
    */
   bitrate: number | null;
   /** Track duration in seconds, or `null` when not yet known. */
@@ -685,8 +803,8 @@ export interface PlaybackError {
   /**
    * Raw native message — typically `localizedDescription` on iOS or
    * `PlaybackException.message` on Android. URL query strings are
-   * stripped before emission to avoid leaking auth tokens (e.g.
-   * Subsonic `s=…&t=…` salt+token in stream URLs).
+   * stripped before emission to avoid leaking auth tokens carried in
+   * query strings (e.g. `?token=…`).
    */
   nativeMessage: string;
   /**
@@ -718,9 +836,8 @@ export interface PlaybackError {
  * (no skip-next on the last track, no skip-previous on the first).
  *
  * Wrapped in a struct (rather than two separate boolean callback
- * args) so future capability flags can be added without a breaking
- * API change. Also works around a Nitrogen 0.35.4 codegen bug for
- * `(bool, bool) → void` callback signatures specifically.
+ * args) so further capability flags can be added without a breaking
+ * API change.
  */
 export interface SkipCapability {
   /** Reflects queue length + current index + repeat mode (symmetric with `canSkipNext`). */
@@ -739,8 +856,7 @@ export interface SkipCapability {
  * converts to a concrete deadline near the track's end.
  *
  * Wrapped in a struct (rather than positional callback args) so fields can be
- * added without a breaking change, and to avoid a Nitrogen 0.35.4 codegen bug
- * for multi-primitive callback signatures.
+ * added without a breaking change.
  */
 export interface SleepTimerState {
   /** `true` while a sleep timer is armed (duration or end-of-track). */
@@ -772,13 +888,54 @@ export interface SleepTimerState {
  *
  * Construction-fixed like the cache size: changing it at `configure()` clears
  * the cache and rebuilds with the new policy.
+ *
+ * **Protecting the playing track differs by platform.** Eviction runs on every
+ * download commit, so without protection the entry backing the track being
+ * played can be deleted while it plays.
+ *
+ * - **iOS** protects under both policies.
+ * - **Android** protects under `'fifo'` only. Media3's LRU evictor has no
+ *   protected-key concept, and its recency bump is per byte-range span rather
+ *   than per track, so a long track's already-played spans stay evictable while
+ *   it is still playing. Choose `'fifo'` if that matters to you.
  */
 export type EvictionPolicy = 'lru' | 'fifo';
 
 export interface LookaheadCacheConfig {
+  /**
+   * Whether the cache is in use. Enabled, playback of a track the cache holds
+   * in full is served from disk with no request, a track it does not hold is
+   * fetched from the origin and written as it plays, and the tracks ahead are
+   * prefetched. Disabled, every read goes to the origin and nothing is written,
+   * whatever the disk already holds; the item already loading keeps the source
+   * it opened. The on-disk entries survive a disable and serve again on enable.
+   */
   enabled: boolean;
   /** Tracks ahead of the current index to proactively cache. 0 disables lookahead; eviction still runs. */
   lookaheadCount: number;
+  /**
+   * Whether prefetching may use cellular data. Defaults to `true`.
+   *
+   * The lookahead cache downloads whole upcoming tracks before playback
+   * reaches them, so on a metered connection it can spend a lot of data on
+   * tracks the listener skips past. Set `false` to back a "download over
+   * Wi-Fi only" setting.
+   *
+   * Applies at runtime — no `configure()` cycle — and gates prefetch only.
+   * Playback is never blocked by it, so the track being played carries on
+   * either way.
+   *
+   * The enforcement point differs, because the platforms offer different
+   * primitives:
+   * - **iOS** sets it on each prefetch request, and the OS refuses to run that
+   *   request over cellular. A download already on the wire keeps the value it
+   *   started with and runs to completion.
+   * - **Android** has no per-request equivalent, so prefetch stops being
+   *   scheduled while the default network is cellular. That also cancels the
+   *   download in flight, whose partial data stays in the cache and resumes
+   *   when prefetch is permitted again.
+   */
+  allowsCellularAccess?: boolean;
 }
 
 export interface CacheStatus {

package/android/src/main/java/com/margelo/nitro/queueplayer/PendingIntentBuffer.kt

@@ -1,82 +0,0 @@
-package com.margelo.nitro.queueplayer
-
-import java.util.concurrent.atomic.AtomicReference
-
-/**
- * Single-slot buffer for a voice intent that arrived before the JS
- * resolver had registered. Holds at most one request per instance; a
- * subsequent [push] replaces any prior entry (latest-wins).
- *
- * Entries carry a `bufferedAtMillis` timestamp and expire after
- * [ttlMillis]. Expired entries are dropped on the next [peek] /
- * [drain] without producing a result, so a stale cold-launch intent
- * never reaches a JS resolver that registers minutes later.
- *
- * Cross-platform parity primitive: iOS's `CarPlayBridge` holds an
- * analogous `PendingIntentBuffer` for `INPlayMediaIntent` cold-start
- * dispatches because Swift Concurrency lacks Kotlin's
- * `MutableStateFlow.filterNotNull().first()` suspend-until-non-null
- * pattern. On Android the lib's existing `BrowseCallbackRegistry`
- * slots + `PlaybackService.dispatchAssistantPlay` already provide the
- * same cold-start-race coverage via coroutine suspension, so this
- * class is a reusable primitive without a load-bearing Android call
- * site today. Kept for symmetry + future single-flight use cases.
- *
- * Thread-safety: every method is safe to call from any thread —
- * [AtomicReference] guards the slot via CAS.
- *
- * Clock contract: callers must supply a monotonically non-decreasing
- * clock. Negative-skew elapsed values are clamped to zero so a
- * backwards-moving clock can't extend an entry's effective TTL.
- */
-internal class PendingIntentBuffer<Request : Any>(
-  private val ttlMillis: Long = 20_000L,
-  private val clock: () -> Long = System::currentTimeMillis,
-) {
-
-  private data class Entry<Request : Any>(val request: Request, val bufferedAtMillis: Long)
-
-  private val cell = AtomicReference<Entry<Request>?>(null)
-
-  /** Store [request], replacing any prior entry. */
-  fun push(request: Request) {
-    cell.set(Entry(request, clock()))
-  }
-
-  /**
-   * Remove and return the buffered request, or `null` if empty or
-   * expired. Drains the slot in both cases — an expired entry is not
-   * retained for a later non-expired read.
-   */
-  fun drain(): Request? {
-    val current = cell.getAndSet(null) ?: return null
-    val elapsed = (clock() - current.bufferedAtMillis).coerceAtLeast(0L)
-    if (elapsed > ttlMillis) return null
-    return current.request
-  }
-
-  /**
-   * Inspect the buffered request without removing it. Auto-clears an
-   * expired entry as a side effect so a stale request can't be
-   * inspected indefinitely.
-   */
-  fun peek(): Request? {
-    while (true) {
-      val current = cell.get() ?: return null
-      val elapsed = (clock() - current.bufferedAtMillis).coerceAtLeast(0L)
-      if (elapsed > ttlMillis) {
-        if (cell.compareAndSet(current, null)) return null
-        continue
-      }
-      return current.request
-    }
-  }
-
-  /** Drop any buffered request without returning it. */
-  fun clear() {
-    cell.set(null)
-  }
-
-  /** True when the slot is empty (or holds only an expired entry). */
-  fun isEmpty(): Boolean = peek() == null
-}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/http/LocalMediaServerLifecycle.kt

@@ -1,15 +0,0 @@
-package com.margelo.nitro.queueplayer.cast.http
-
-/**
- * Single-callback contract by which the host service learns whether
- * the local HTTP server has any live sessions. While `active` is true
- * the host must keep itself foregrounded so Android doesn't kill the
- * process out from under the server.
- *
- * Cast-core stays unaware of foreground-service mechanics; the
- * implementer translates this signal into `startForeground` /
- * `stopForeground` etc.
- */
-fun interface LocalMediaServerLifecycle {
-  fun onActiveStateChanged(active: Boolean)
-}