react-native-queue-player 1.0.8 → 1.1.0

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

@@ -0,0 +1,76 @@
+///
+/// SkipToPreviousBehavior.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 (SkipToPreviousBehavior).
+   */
+  enum class SkipToPreviousBehavior {
+    PREVIOUS      SWIFT_NAME(previous) = 0,
+    RESTART_OR_PREVIOUS      SWIFT_NAME(restartOrPrevious) = 1,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::queueplayer
+
+namespace margelo::nitro {
+
+  // C++ SkipToPreviousBehavior <> JS SkipToPreviousBehavior (union)
+  template <>
+  struct JSIConverter<margelo::nitro::queueplayer::SkipToPreviousBehavior> final {
+    static inline margelo::nitro::queueplayer::SkipToPreviousBehavior 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("previous"): return margelo::nitro::queueplayer::SkipToPreviousBehavior::PREVIOUS;
+        case hashString("restart-or-previous"): return margelo::nitro::queueplayer::SkipToPreviousBehavior::RESTART_OR_PREVIOUS;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum SkipToPreviousBehavior - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::queueplayer::SkipToPreviousBehavior arg) {
+      switch (arg) {
+        case margelo::nitro::queueplayer::SkipToPreviousBehavior::PREVIOUS: return JSIConverter<std::string>::toJSI(runtime, "previous");
+        case margelo::nitro::queueplayer::SkipToPreviousBehavior::RESTART_OR_PREVIOUS: return JSIConverter<std::string>::toJSI(runtime, "restart-or-previous");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert SkipToPreviousBehavior 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("previous"):
+        case hashString("restart-or-previous"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-queue-player",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "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

@@ -306,17 +306,17 @@ export interface TrackPlayer
   getCanSkipNext(): boolean;
   /**
    * Whether the user-facing Previous button should be enabled.
-   * Symmetric with `getCanSkipNext` — true when there's a previous
+   * Symmetric with `getCanSkipNext` — with the default
+   * `skipToPreviousBehavior: 'previous'`, true when there's a previous
    * track to skip to under the current repeat mode:
    * - `'off'` and `'track'` at index 0: false (no previous, no wrap)
    * - `'queue'`: true with an active track (wraps)
    *
-   * **Apps that want the Apple-Music-style "tap Previous restarts
-   * current when position > 3s" UX** should implement that
-   * themselves in their button handler — branch on the live
-   * `useProgress().position` value to either `seekTo(0)` or
-   * `skipToPrevious()`. The lib intentionally ships the primitive,
-   * not the policy.
+   * With `PlayerConfig.skipToPreviousBehavior: 'restart-or-previous'` the
+   * lib applies the standard music-player "restart when past ~3 s, else
+   * previous" model natively, and this reports `true` whenever a track is
+   * loaded (even at index 0, where past the threshold Previous restarts the
+   * current track) so the control never greys out.
    */
   getCanSkipPrevious(): boolean;
   /**

package/src/index.ts

@@ -14,6 +14,7 @@ export type {
   PlaybackMode,
   PlaybackModeKind,
   RepeatMode,
+  SkipToPreviousBehavior,
   RemoteSkipMode,
   RemoteControlOptions,
   StateChangeReason,

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
@@ -155,6 +172,21 @@ export interface PlayerConfig {
    * Default: `false` (targets pass through unclamped).
    */
   clampSeekToBuffered?: boolean;
+  /**
+   * How skip-to-previous behaves. `'previous'` (default) always goes to the
+   * previous track. `'restart-or-previous'` restarts the current track
+   * (seeks to 0) when it is past ~3 s, otherwise goes to the previous track
+   * — the standard music-player model. Applies
+   * to local playback; during cast, Previous routes to the receiver. When
+   * `'restart-or-previous'`, the Previous control is always enabled
+   * (`canSkipPrevious` reports `true` whenever a track is loaded, so the
+   * control never greys out — even on the first track, where past the
+   * threshold it restarts).
+   *
+   * Pinned per `configure()` (a fixed behavior, not a live toggle);
+   * changing it re-runs `configure()`. Default: `'previous'`.
+   */
+  skipToPreviousBehavior?: SkipToPreviousBehavior;
   /**
    * Disk budget for the lookahead cache, in megabytes. Fixed at `configure()`
    * time and cannot change at runtime — Android's Media3 `SimpleCache` fixes
@@ -322,6 +354,16 @@ export const crossfadeDurationBounds = {
  */
 export type RepeatMode = 'off' | 'queue' | 'track';
 
+/**
+ * How `skipToPrevious` (and the OS Previous control) behaves.
+ * - `'previous'` — always go to the previous track (the default; current
+ *   behavior).
+ * - `'restart-or-previous'` — restart the current track (seek to 0) when it
+ *   is past ~3 s, otherwise go to the previous track. The standard
+ *   music-player model. See `PlayerConfig.skipToPreviousBehavior`.
+ */
+export type SkipToPreviousBehavior = 'previous' | 'restart-or-previous';
+
 /**
  * How the lock-screen / notification skip controls behave: skip between queue
  * tracks (`'track'`) or jump forward/back within the current track by a fixed