react-native-queue-player 1.0.6 → 1.0.8

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

@@ -41,6 +41,8 @@ namespace margelo::nitro::queueplayer { struct SleepTimerState; }
 namespace margelo::nitro::queueplayer { enum class StateChangeReason; }
 // Forward declaration of `TrackChangeReason` to properly resolve imports.
 namespace margelo::nitro::queueplayer { enum class TrackChangeReason; }
+// Forward declaration of `QueueChangeReason` to properly resolve imports.
+namespace margelo::nitro::queueplayer { enum class QueueChangeReason; }
 // Forward declaration of `PlayerProgress` to properly resolve imports.
 namespace margelo::nitro::queueplayer { struct PlayerProgress; }
 // Forward declaration of `PlaybackError` to properly resolve imports.
@@ -82,6 +84,7 @@ namespace margelo::nitro::queueplayer { struct NowPlayingFormat; }
 #include <functional>
 #include "StateChangeReason.hpp"
 #include "TrackChangeReason.hpp"
+#include "QueueChangeReason.hpp"
 #include "PlayerProgress.hpp"
 #include "PlaybackError.hpp"
 #include "BrowseSnapshot.hpp"
@@ -171,6 +174,7 @@ namespace margelo::nitro::queueplayer {
       virtual SleepTimerState getSleepTimer() = 0;
       virtual std::function<void()> onStateChange(const std::function<void(PlayerState /* state */, StateChangeReason /* reason */)>& callback) = 0;
       virtual std::function<void()> onTrackChange(const std::function<void(const std::optional<TrackItem>& /* track */, double /* index */, TrackChangeReason /* reason */, std::optional<double> /* transitionGapMs */)>& callback) = 0;
+      virtual std::function<void()> onQueueChange(const std::function<void(const std::vector<TrackItem>& /* queue */, double /* currentIndex */, QueueChangeReason /* reason */)>& callback) = 0;
       virtual std::function<void()> onProgress(const std::function<void(const PlayerProgress& /* progress */)>& callback) = 0;
       virtual std::function<void()> onPlaybackMilestone(const std::function<void(double /* milestone */, double /* trackIndex */)>& callback) = 0;
       virtual std::function<void()> onError(const std::function<void(const PlaybackError& /* error */)>& callback) = 0;

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.6",
+  "version": "1.0.8",
   "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

@@ -417,6 +417,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.