react-native-queue-player 1.0.7 → 1.0.9

package/nitrogen/generated/shared/c++/QueueChangeReason.hpp

@@ -0,0 +1,92 @@
+///
+/// QueueChangeReason.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::queueplayer {
+
+  /**
+   * An enum which can be represented as a JavaScript union (QueueChangeReason).
+   */
+  enum class QueueChangeReason {
+    SET_QUEUE      SWIFT_NAME(setQueue) = 0,
+    ADD      SWIFT_NAME(add) = 1,
+    REMOVE      SWIFT_NAME(remove) = 2,
+    MOVE      SWIFT_NAME(move) = 3,
+    CLEAR      SWIFT_NAME(clear) = 4,
+    SHUFFLE      SWIFT_NAME(shuffle) = 5,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::queueplayer
+
+namespace margelo::nitro {
+
+  // C++ QueueChangeReason <> JS QueueChangeReason (union)
+  template <>
+  struct JSIConverter<margelo::nitro::queueplayer::QueueChangeReason> final {
+    static inline margelo::nitro::queueplayer::QueueChangeReason fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("set-queue"): return margelo::nitro::queueplayer::QueueChangeReason::SET_QUEUE;
+        case hashString("add"): return margelo::nitro::queueplayer::QueueChangeReason::ADD;
+        case hashString("remove"): return margelo::nitro::queueplayer::QueueChangeReason::REMOVE;
+        case hashString("move"): return margelo::nitro::queueplayer::QueueChangeReason::MOVE;
+        case hashString("clear"): return margelo::nitro::queueplayer::QueueChangeReason::CLEAR;
+        case hashString("shuffle"): return margelo::nitro::queueplayer::QueueChangeReason::SHUFFLE;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum QueueChangeReason - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::queueplayer::QueueChangeReason arg) {
+      switch (arg) {
+        case margelo::nitro::queueplayer::QueueChangeReason::SET_QUEUE: return JSIConverter<std::string>::toJSI(runtime, "set-queue");
+        case margelo::nitro::queueplayer::QueueChangeReason::ADD: return JSIConverter<std::string>::toJSI(runtime, "add");
+        case margelo::nitro::queueplayer::QueueChangeReason::REMOVE: return JSIConverter<std::string>::toJSI(runtime, "remove");
+        case margelo::nitro::queueplayer::QueueChangeReason::MOVE: return JSIConverter<std::string>::toJSI(runtime, "move");
+        case margelo::nitro::queueplayer::QueueChangeReason::CLEAR: return JSIConverter<std::string>::toJSI(runtime, "clear");
+        case margelo::nitro::queueplayer::QueueChangeReason::SHUFFLE: return JSIConverter<std::string>::toJSI(runtime, "shuffle");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert QueueChangeReason to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("set-queue"):
+        case hashString("add"):
+        case hashString("remove"):
+        case hashString("move"):
+        case hashString("clear"):
+        case hashString("shuffle"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-queue-player",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Nitro Modules audio playback library for React Native — gapless, EQ, crossfade, automotive, voice, casting",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/index.d.ts",

package/src/TrackPlayer.nitro.ts

@@ -9,6 +9,7 @@ import type {
   RemoteControlOptions,
   StateChangeReason,
   TrackChangeReason,
+  QueueChangeReason,
   TrackSource,
   PlaybackError,
   PlayerProgress,
@@ -372,6 +373,38 @@ export interface TrackPlayer
       transitionGapMs: number | undefined
     ) => void
   ): () => void;
+  /**
+   * Fires when the queue **contents or order** change — `setQueue`,
+   * `addToQueue`, `removeFromQueue`, `moveInQueue`, `clearQueue`,
+   * `shuffleQueue`. Unlike `onTrackChange` (which fires only when the
+   * active *track* changes), this fires on queue-preserving mutations —
+   * e.g. inserting a "play next" item or removing an upcoming track — so
+   * a reactive queue UI stays in sync.
+   *
+   * The `(queue, currentIndex)` pair is delivered **atomically**: it is
+   * the post-mutation snapshot captured on the native side under the same
+   * mutation, so it never exhibits the one-tick skew of reading
+   * `getQueue()` + `getCurrentTrackIndex()` back-to-back. `currentIndex`
+   * is `-1` when the queue is empty; note it can shift without the active
+   * track changing (e.g. an insert before the current item), which is the
+   * case `onTrackChange` does not cover.
+   *
+   * Fires only when the queue actually changes — a no-op mutation (empty
+   * `addToQueue`, out-of-range `removeFromQueue`, `moveInQueue` with
+   * `from === to`) does not fire, and neither do current-index-only
+   * changes from auto-advance / skip (those are `onTrackChange`). Does not
+   * auto-fire on subscribe; seed initial state from `getQueue()` (the
+   * `useQueue()` hook does this). For a mutation that also changes the
+   * active track (`set-queue` / `clear` / `shuffle`) this fires first,
+   * then `onTrackChange` follows.
+   */
+  onQueueChange(
+    callback: (
+      queue: TrackItem[],
+      currentIndex: number,
+      reason: QueueChangeReason
+    ) => void
+  ): () => void;
   /**
    * Subscribes to playback-progress ticks. Native side fires at ~2 Hz
    * via `addPeriodicTimeObserver` (iOS) / a coroutine-driven handler

package/src/hooks/index.ts

@@ -7,6 +7,9 @@ export type { PlaybackStateSnapshot } from './usePlaybackState';
 export { useActiveTrack } from './useActiveTrack';
 export type { ActiveTrackSnapshot } from './useActiveTrack';
 
+export { useQueue } from './useQueue';
+export type { QueueSnapshot } from './useQueue';
+
 export { useCanSkip } from './useCanSkip';
 export type { CanSkipSnapshot } from './useCanSkip';
 

package/src/hooks/useQueue.ts

@@ -0,0 +1,56 @@
+import { useEffect, useState } from 'react';
+import { getTrackPlayer } from '../clients';
+import type { TrackItem } from '../types';
+
+export interface QueueSnapshot {
+  /** The current queue, in play order. */
+  queue: TrackItem[];
+  /** Index of the active track. `-1` when the queue is empty. */
+  currentIndex: number;
+}
+
+const INITIAL: QueueSnapshot = { queue: [], currentIndex: -1 };
+
+/**
+ * Subscribes to native `onQueueChange` for the live queue + current
+ * index, delivered as one atomic snapshot. Also subscribes to
+ * `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.
+ */
+export function useQueue(): QueueSnapshot {
+  const [snapshot, setSnapshot] = useState<QueueSnapshot>(() => {
+    try {
+      const player = getTrackPlayer();
+      return {
+        queue: player.getQueue(),
+        currentIndex: player.getCurrentTrackIndex(),
+      };
+    } catch {
+      return INITIAL;
+    }
+  });
+
+  useEffect(() => {
+    const player = getTrackPlayer();
+    const offQueue = player.onQueueChange((queue, currentIndex) => {
+      setSnapshot({ queue, currentIndex });
+    });
+    // Keep `currentIndex` live when the active track changes without a
+    // queue-content change (auto-advance, skip). Preserves the queue from
+    // the last `onQueueChange`.
+    const offTrack = player.onTrackChange((_track, index) => {
+      setSnapshot((prev) => ({ queue: prev.queue, currentIndex: index }));
+    });
+    return () => {
+      offQueue();
+      offTrack();
+    };
+  }, []);
+
+  return snapshot;
+}

package/src/index.ts

@@ -18,6 +18,7 @@ export type {
   RemoteControlOptions,
   StateChangeReason,
   TrackChangeReason,
+  QueueChangeReason,
   TrackSource,
   PlayerProgress,
   PlaybackError,

package/src/types.ts

@@ -69,6 +69,23 @@ export interface PlayerConfig {
   httpHeaders?: Record<string, string>;
   /** Overrides the default UA on network requests. */
   userAgent?: string;
+  /**
+   * Replacement for the built-in RNQP cover-art placeholder (the image
+   * shown before real artwork loads and when a track has no artwork).
+   * MUST be a **local `file://` URI** — the built-in placeholder is a
+   * local file, so this must be too; remote URLs are not loaded (they
+   * would break offline playback and change behaviour). When set, this
+   * image is used in place of the built-in everywhere the built-in is
+   * used; unset, non-`file://`, or unloadable falls back to the built-in.
+   * Resolve a bundled asset to a `file://` path with expo-asset —
+   * `const a = Asset.fromModule(require('./logo.png')); await
+   * a.downloadAsync();` then pass `a.localUri` — which copies the packaged
+   * image onto the filesystem across dev and release.
+   * (`Image.resolveAssetSource(...).uri` is not suitable: it is an
+   * `http://` Metro URL in dev and a drawable resource name on Android
+   * release, neither of which is a `file://` path.)
+   */
+  placeholderArtworkUri?: string;
   /**
    * Auto-retry attempts on transient errors (TIMEOUT / CONNECTION_LOST /
    * NETWORK_UNREACHABLE / SOURCE_UNREACHABLE / CANNOT_OPEN). Clamped
@@ -417,6 +434,18 @@ export type TrackChangeReason =
    */
   | 'crossfade-cancelled';
 
+/**
+ * Why the queue contents or order changed, reported by `onQueueChange`.
+ * Each value maps 1:1 to the public mutation that produced it.
+ */
+export type QueueChangeReason =
+  | 'set-queue' // setQueue replaced the whole queue
+  | 'add' // addToQueue inserted track(s)
+  | 'remove' // removeFromQueue removed track(s)
+  | 'move' // moveInQueue reordered a track
+  | 'clear' // clearQueue emptied the queue
+  | 'shuffle'; // shuffleQueue reordered the queue
+
 /**
  * How the active track is being played:
  * - `'local'` — `track.url` is a `file://` URL.