react-native-queue-player 1.0.8 → 1.1.0

package/ios/NowPlayingInfo.swift

@@ -43,7 +43,6 @@ final class NowPlayingInfo {
   var snapshotProvider: (() -> Snapshot)?
 
   private var periodicTimer: Timer?
-  private var cachedPlaceholderArtwork: MPMediaItemArtwork?
   /// Subscription to the global cast active-session router. When a
   /// remote session is active, `CastNowPlayingController` owns the
   /// lockscreen surface and this writer becomes a no-op — every
@@ -176,15 +175,14 @@ final class NowPlayingInfo {
     info[MPNowPlayingInfoPropertyPlaybackRate] = rate
   }
 
-  /// Lazy MPMediaItemArtwork wrapper around the bundled placeholder
-  /// UIImage. Built once per process; the closure that the system
-  /// invokes for size requests just returns the same image (the system
-  /// handles its own scaling).
+  /// MPMediaItemArtwork wrapper around the active placeholder image —
+  /// `PlaceholderArtwork.image` is the consumer-configured image when one
+  /// is set (`PlayerConfig.placeholderArtworkUri`), else the bundled one.
+  /// Rebuilt per call (cheap: the closure just returns the image, the
+  /// system handles scaling) so a placeholder set at `configure` is
+  /// reflected rather than serving a stale wrapper.
   private func placeholderArtwork() -> MPMediaItemArtwork {
-    if let cached = cachedPlaceholderArtwork { return cached }
     let image = PlaceholderArtwork.image
-    let mp = MPMediaItemArtwork(boundsSize: image.size) { _ in image }
-    cachedPlaceholderArtwork = mp
-    return mp
+    return MPMediaItemArtwork(boundsSize: image.size) { _ in image }
   }
 }

package/ios/PlaceholderArtwork.swift

@@ -15,7 +15,30 @@ import UIKit
 /// Android skins (mirror that defence on iOS too).
 enum PlaceholderArtwork {
 
-  static let image: UIImage = loadImage()
+  /// The active placeholder: the consumer-supplied image when one is
+  /// configured + loadable, otherwise the bundled RNQP placeholder.
+  static var image: UIImage { customImage ?? bundledImage }
+
+  /// Set (or clear) the consumer-supplied placeholder from
+  /// `PlayerConfig.placeholderArtworkUri`. Loaded from a local `file://`
+  /// image the same way the bundled placeholder is (`UIImage(contentsOfFile:)`).
+  /// Only `file://` is honoured (scheme match is case-insensitive) — the
+  /// built-in is a local file, and a remote URL would break offline +
+  /// change behaviour; anything else (or an unloadable file) leaves the
+  /// bundled placeholder in effect. Decode is synchronous, so a very large
+  /// consumer image briefly blocks the `configure` call. Main-thread only
+  /// (called from `configure`).
+  static func setCustom(uri: String?) {
+    guard let uri = uri, !uri.isEmpty,
+          let url = URL(string: uri), url.scheme?.lowercased() == "file" else {
+      customImage = nil
+      return
+    }
+    customImage = UIImage(contentsOfFile: url.path)
+  }
+
+  private static var customImage: UIImage?
+  private static let bundledImage: UIImage = loadImage()
 
   private static func loadImage() -> UIImage {
     let frameworkBundle = Bundle(for: BundleToken.self)

package/ios/QueueSkipArithmetic.swift

@@ -48,9 +48,10 @@ public enum QueueSkipArithmetic {
 
   /// Previous-track index. Same early-bail rules as `computeNext`.
   ///
-  /// `.off` and `.track` both return nil at index 0 (no previous
-  /// track, no wrap). Apps that want the "tap Previous at track 0
-  /// restarts current" UX implement that in their button handler.
+  /// `.off` and `.track` both return nil at index 0 (no previous track,
+  /// no wrap). The "restart current when past the threshold" model is
+  /// available via `PlayerConfig.skipToPreviousBehavior` (resolved by
+  /// `resolveSkipToPrevious`).
   public static func computePrevious(
     trackCount: Int,
     currentIndex: Int,
@@ -87,19 +88,64 @@ public enum QueueSkipArithmetic {
   /// `.off` and `.track` are false at index 0 (no wrap); `.queue` is
   /// always true with an active track (wraps).
   ///
-  /// **Apps that want the Apple-Music-style "tap Previous restarts
-  /// when position > 3s" UX** should implement that in their button
-  /// handler: read playback position, branch to `seekTo(0)` vs
-  /// `skipToPrevious()` themselves. Lib intentionally ships the
-  /// primitive (skip if there's a track to skip to), not the policy.
+  /// When `restartEnabled` is true (`PlayerConfig.skipToPreviousBehavior
+  /// == .restartOrPrevious`), Previous is enabled whenever a track is
+  /// loaded — even at index 0, where past the threshold it restarts the
+  /// current track — so the control never greys out.
   public static func canSkipPrevious(
     trackCount: Int,
     currentIndex: Int,
-    repeatMode: QueueSkipRepeatMode
+    repeatMode: QueueSkipRepeatMode,
+    restartEnabled: Bool = false
   ) -> Bool {
+    if restartEnabled { return trackCount > 0 }
     return computePrevious(
       trackCount: trackCount,
       currentIndex: currentIndex,
       repeatMode: repeatMode) != nil
   }
+
+  /// Position (ms) at or below which a `.restartOrPrevious` skip-back goes
+  /// to the previous track; past it, the current track restarts. Matches
+  /// Media3's default `maxSeekToPreviousPosition` (the industry-standard 3 s).
+  public static let restartThresholdMs: Int = 3000
+
+  /// What a skip-to-previous should do, resolved from queue position + the
+  /// configured behavior.
+  public enum SkipToPreviousAction: Equatable {
+    /// Navigate to this queue index (a real track change).
+    case previous(Int)
+    /// Restart the current track (seek to 0) — not a track change.
+    case restartCurrent
+    /// Nothing to do (empty queue).
+    case noOp
+  }
+
+  /// Resolves a skip-to-previous. When `restartEnabled` is false this is
+  /// exactly `computePrevious` (previous track, or nothing). When true it
+  /// applies the threshold model, matching Media3 `BasePlayer.seekToPrevious`:
+  /// a previous track exists AND `positionMs <= thresholdMs` → previous;
+  /// otherwise (past threshold, or first track with no previous) → restart
+  /// the current track.
+  public static func resolveSkipToPrevious(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode,
+    restartEnabled: Bool,
+    positionMs: Int,
+    thresholdMs: Int = restartThresholdMs
+  ) -> SkipToPreviousAction {
+    guard trackCount > 0, currentIndex >= 0 else { return .noOp }
+    let prev = computePrevious(
+      trackCount: trackCount,
+      currentIndex: currentIndex,
+      repeatMode: repeatMode)
+    if !restartEnabled {
+      return prev.map { .previous($0) } ?? .noOp
+    }
+    if let prev, positionMs <= thresholdMs {
+      return .previous(prev)
+    }
+    return .restartCurrent
+  }
 }

package/ios/Tests/AVQueueBuilderTests.swift

@@ -169,7 +169,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let item = AVQueueBuilder.makeItem(
       for: track,
       queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertNotNil(item)
@@ -186,7 +186,7 @@ final class AVQueueBuilderTests: XCTestCase {
   func testMakeItemFallsBackToRemoteWhenCacheMisses() {
     // No cache provided → behaves identically to the no-cache path.
     let track = makeTrack(id: "t1", url: "https://example.com/track.m4a")
-    let config = PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
+    let config = PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: UUID().uuidString, config: config, cache: nil)
     XCTAssertNotNil(item)
@@ -214,7 +214,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let item = AVQueueBuilder.makeItem(
       for: track,
       queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertNotNil(item)
@@ -260,7 +260,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let item = AVQueueBuilder.makeItem(
       for: track,
       queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertNotNil(item)
@@ -296,7 +296,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let items = AVQueueBuilder.buildPlayerItems(
       tracks: [trackA, trackB],
       queueItemIds: [UUID().uuidString, UUID().uuidString],
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertEqual(items.count, 2)
@@ -371,12 +371,12 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemIdB = UUID().uuidString
     let itemA = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemIdA,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     let itemB = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemIdB,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     XCTAssertNotNil(itemA)
@@ -401,7 +401,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemId = UUID().uuidString
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemId,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     XCTAssertNotNil(item)
@@ -417,7 +417,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemId = UUID().uuidString
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemId,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     XCTAssertNotNil(item)

package/ios/Tests/CastNowPlayingControllerTests.swift

@@ -132,6 +132,39 @@ final class CastNowPlayingControllerTests: XCTestCase {
       "activation renders the most recent cached metadata"
     )
   }
+
+  func testSeededPlaceholderReflectsConfiguredCustomImage() throws {
+    let tmp = FileManager.default.temporaryDirectory
+      .appendingPathComponent("rnqp-cast-placeholder-\(UUID().uuidString).jpg")
+    try makeTinyJpeg().write(to: tmp)
+    defer {
+      try? FileManager.default.removeItem(at: tmp)
+      PlaceholderArtwork.setCustom(uri: nil)
+    }
+    let builtInSize = PlaceholderArtwork.image.size
+    PlaceholderArtwork.setCustom(uri: tmp.absoluteString)
+    let customSize = PlaceholderArtwork.image.size
+    // Precondition: the fixture is a different size from the built-in,
+    // else the size check below can't tell them apart.
+    XCTAssertNotEqual(customSize, builtInSize)
+
+    try router.setActive(ControllableRemoteSession())
+
+    let artwork = info?[MPMediaItemPropertyArtwork] as? MPMediaItemArtwork
+    XCTAssertEqual(
+      artwork?.image(at: customSize)?.size, customSize,
+      "the cast lockscreen seeds the live custom placeholder, not a frozen built-in"
+    )
+  }
+
+  private func makeTinyJpeg() -> Data {
+    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 1, height: 1))
+    let image = renderer.image { ctx in
+      UIColor.green.setFill()
+      ctx.fill(CGRect(x: 0, y: 0, width: 1, height: 1))
+    }
+    return image.jpegData(compressionQuality: 1.0) ?? Data()
+  }
 }
 
 // MARK: - Listener-firing fake

package/ios/Tests/PlaceholderArtworkTests.swift

@@ -0,0 +1,81 @@
+import XCTest
+@testable import QueuePlayer
+import UIKit
+
+/// `PlaceholderArtwork` swaps in a consumer-supplied cover-art placeholder
+/// (`PlayerConfig.placeholderArtworkUri`) in place of the bundled RNQP
+/// image. Only a local `file://` image is honoured; a remote or unset URI,
+/// or an unloadable file, keeps the bundled placeholder.
+@MainActor
+final class PlaceholderArtworkTests: XCTestCase {
+
+  override func tearDown() {
+    // Process-wide singleton — reset so a set custom image does not leak
+    // into other suites that read the bundled placeholder.
+    PlaceholderArtwork.setCustom(uri: nil)
+    super.tearDown()
+  }
+
+  func testCustomFileUriReplacesTheBundledPlaceholder() throws {
+    let bundled = PlaceholderArtwork.image
+    let tmp = FileManager.default.temporaryDirectory
+      .appendingPathComponent("rnqp-placeholder-\(UUID().uuidString).jpg")
+    try makeJpegBytes().write(to: tmp)
+    defer { try? FileManager.default.removeItem(at: tmp) }
+
+    PlaceholderArtwork.setCustom(uri: tmp.absoluteString)
+
+    let image = PlaceholderArtwork.image
+    XCTAssertFalse(image === bundled,
+                   "a loadable file:// image replaces the bundled placeholder")
+    XCTAssertTrue(image === PlaceholderArtwork.image,
+                  "the custom image is stable across reads")
+  }
+
+  func testUnsetUriKeepsTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: nil)
+    XCTAssertTrue(PlaceholderArtwork.image === bundled)
+  }
+
+  func testNonFileUriIsRejectedAndKeepsTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: "https://example.com/logo.png")
+    XCTAssertTrue(PlaceholderArtwork.image === bundled,
+                  "a remote URI is rejected — offline-only file:// contract")
+  }
+
+  func testUnloadableFileUriFallsBackToTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: "file:///nonexistent/path/missing.jpg")
+    XCTAssertTrue(PlaceholderArtwork.image === bundled)
+  }
+
+  func testEmptyUriKeepsTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: "")
+    XCTAssertTrue(PlaceholderArtwork.image === bundled)
+  }
+
+  func testUppercaseFileSchemeIsHonoured() throws {
+    let bundled = PlaceholderArtwork.image
+    let tmp = FileManager.default.temporaryDirectory
+      .appendingPathComponent("rnqp-placeholder-\(UUID().uuidString).jpg")
+    try makeJpegBytes().write(to: tmp)
+    defer { try? FileManager.default.removeItem(at: tmp) }
+
+    PlaceholderArtwork.setCustom(uri: "FILE://" + tmp.path)
+
+    XCTAssertFalse(PlaceholderArtwork.image === bundled,
+                   "an uppercase FILE:// scheme is honoured (case-insensitive)")
+  }
+
+  private func makeJpegBytes() -> Data {
+    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 1, height: 1))
+    let image = renderer.image { ctx in
+      UIColor.blue.setFill()
+      ctx.fill(CGRect(x: 0, y: 0, width: 1, height: 1))
+    }
+    return image.jpegData(compressionQuality: 1.0) ?? Data()
+  }
+}

package/ios/Tests/SkipIndexTests.swift

@@ -256,4 +256,101 @@ final class SkipIndexTests: XCTestCase {
     XCTAssertFalse(QueueSkipArithmetic.canSkipPrevious(
       trackCount: 1, currentIndex: 0, repeatMode: .track))
   }
+
+  // MARK: - resolveSkipToPrevious — mode OFF (position ignored, current behavior)
+
+  private func resolve(
+    count: Int = 3, index: Int, mode: QueueSkipRepeatMode,
+    restart: Bool, positionMs: Int
+  ) -> QueueSkipArithmetic.SkipToPreviousAction {
+    QueueSkipArithmetic.resolveSkipToPrevious(
+      trackCount: count, currentIndex: index, repeatMode: mode,
+      restartEnabled: restart, positionMs: positionMs)
+  }
+
+  func testResolveModeOffIgnoresPositionAndGoesPrevious() {
+    // Past-threshold position must NOT restart when the option is off.
+    XCTAssertEqual(resolve(index: 2, mode: .off, restart: false, positionMs: 99_000),
+                   .previous(1))
+  }
+
+  func testResolveModeOffFirstTrackIsNoOp() {
+    XCTAssertEqual(resolve(index: 0, mode: .off, restart: false, positionMs: 99_000), .noOp)
+  }
+
+  func testResolveModeOffQueueWraps() {
+    XCTAssertEqual(resolve(index: 0, mode: .queue, restart: false, positionMs: 0), .previous(2))
+  }
+
+  func testResolveModeOffEmptyQueueIsNoOp() {
+    XCTAssertEqual(resolve(count: 0, index: -1, mode: .off, restart: false, positionMs: 0), .noOp)
+  }
+
+  // MARK: - resolveSkipToPrevious — mode ON (3s threshold model)
+
+  func testResolvePastThresholdRestartsEvenWithPrevious() {
+    for pos in [3001, 5000, 600_000] {
+      XCTAssertEqual(resolve(index: 2, mode: .off, restart: true, positionMs: pos),
+                     .restartCurrent, "position \(pos) > 3000 should restart")
+    }
+  }
+
+  func testResolveThresholdBoundaryGoesPrevious() {
+    // <= threshold → previous; one ms past → restart.
+    XCTAssertEqual(resolve(index: 2, mode: .off, restart: true, positionMs: 3000), .previous(1))
+    XCTAssertEqual(resolve(index: 2, mode: .off, restart: true, positionMs: 3001), .restartCurrent)
+  }
+
+  func testResolveUnderThresholdGoesPrevious() {
+    for pos in [0, 1, 2999] {
+      XCTAssertEqual(resolve(index: 2, mode: .off, restart: true, positionMs: pos),
+                     .previous(1), "position \(pos) <= 3000 should go previous")
+    }
+  }
+
+  func testResolveFirstTrackUnderThresholdRestartsWhenNoPrevious() {
+    XCTAssertEqual(resolve(index: 0, mode: .off, restart: true, positionMs: 1000), .restartCurrent)
+    XCTAssertEqual(resolve(index: 0, mode: .track, restart: true, positionMs: 1000), .restartCurrent)
+  }
+
+  func testResolveFirstTrackUnderThresholdQueueWraps() {
+    // queue mode has a previous (wraps), so under threshold goes to the last track.
+    XCTAssertEqual(resolve(index: 0, mode: .queue, restart: true, positionMs: 1000), .previous(2))
+  }
+
+  func testResolveFirstTrackPastThresholdRestarts() {
+    for mode in [QueueSkipRepeatMode.off, .track, .queue] {
+      XCTAssertEqual(resolve(index: 0, mode: mode, restart: true, positionMs: 9000),
+                     .restartCurrent, "first track past threshold restarts under \(mode)")
+    }
+  }
+
+  func testResolveModeOnEmptyQueueIsNoOp() {
+    XCTAssertEqual(resolve(count: 0, index: -1, mode: .off, restart: true, positionMs: 9000), .noOp)
+  }
+
+  // MARK: - canSkipPrevious with restartEnabled (forced true)
+
+  func testCanSkipPreviousForcedTrueAtEveryIndexAndMode() {
+    for mode in [QueueSkipRepeatMode.off, .track, .queue] {
+      for index in 0..<3 {
+        XCTAssertTrue(QueueSkipArithmetic.canSkipPrevious(
+          trackCount: 3, currentIndex: index, repeatMode: mode, restartEnabled: true),
+          "restart mode forces canSkipPrevious true at index \(index) under \(mode)")
+      }
+    }
+  }
+
+  func testCanSkipPreviousRestartEnabledFalseForEmptyQueue() {
+    XCTAssertFalse(QueueSkipArithmetic.canSkipPrevious(
+      trackCount: 0, currentIndex: -1, repeatMode: .off, restartEnabled: true))
+  }
+
+  func testCanSkipPreviousRestartDisabledMatchesExisting() {
+    // Default restartEnabled=false path is unchanged: false at index 0 under .off.
+    XCTAssertFalse(QueueSkipArithmetic.canSkipPrevious(
+      trackCount: 3, currentIndex: 0, repeatMode: .off, restartEnabled: false))
+    XCTAssertTrue(QueueSkipArithmetic.canSkipPrevious(
+      trackCount: 3, currentIndex: 1, repeatMode: .off, restartEnabled: false))
+  }
 }

package/ios/TrackPlayer.swift

@@ -97,14 +97,14 @@ class TrackPlayer: HybridTrackPlayerSpec {
     PlayerConfig(
       httpHeaders: nil,
       userAgent: nil,
-      autoRetries: nil,
+      placeholderArtworkUri: nil, autoRetries: nil,
       retryBackoffMs: nil,
       networkTimeoutMs: nil,
       audioContentType: nil,
       audioCategoryOptions: nil,
       visualizationEnabled: nil,
       clampSeekToBuffered: nil,
-      lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil,
+      skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil,
       progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil
     )
 
@@ -609,6 +609,10 @@ class TrackPlayer: HybridTrackPlayerSpec {
         // each track-change resolve.
         self.artworkResolver.configHeaders = config.httpHeaders
         self.artworkResolver.configUserAgent = config.userAgent
+        // Swap the cover-art placeholder to the consumer-supplied image
+        // (or back to the built-in when unset). Every placeholder site
+        // reads `PlaceholderArtwork.image`, so this is the only hook needed.
+        PlaceholderArtwork.setCustom(uri: config.placeholderArtworkUri)
         // Same live config for the cast lockscreen's own artwork
         // resolver so authenticated covers resolve during cast.
         CastNowPlayingController.shared.configureArtwork(
@@ -2115,21 +2119,37 @@ class TrackPlayer: HybridTrackPlayerSpec {
     }
   }
 
-  /// Standard skip-previous: go to the previous track if there is one
-  /// (per the arithmetic helper; `.off`/`.track` don't wrap, `.queue`
-  /// wraps). Under `.track` this navigates like `.off` and repeat-one
-  /// persists. Apps that want the Apple-Music-style "tap Previous
-  /// restarts when position > 3s" UX implement that in their button
-  /// handler — the lib provides the primitive (skip if there's a
-  /// track to skip to), not the policy.
+  /// Skip-previous, resolved by `QueueSkipArithmetic.resolveSkipToPrevious`
+  /// from `PlayerConfig.skipToPreviousBehavior`. With the default `.previous`
+  /// this goes to the previous track if there is one (`.off`/`.track` don't
+  /// wrap, `.queue` wraps; `.track` navigates like `.off` and repeat-one
+  /// persists). With `.restartOrPrevious` it restarts the current track (seek
+  /// to 0) when past the threshold, otherwise goes to the previous track.
   func skipToPrevious() throws -> Promise<Void> {
     return Promise<Void>.async {
       if CastTransportRouter.routeSkipToPrevious() { return }
       await self.onMain {
-        guard self.engine != nil else { return }
-        guard let prev = self.computePreviousIndex() else { return }
-        self.applyNewCurrentIndex(
-          newIndex: prev, reason: .userSkipPrevious)
+        guard let engine = self.engine else { return }
+        let positionMs = Int(max(0, engine.currentPositionSeconds) * 1000)
+        let action = QueueSkipArithmetic.resolveSkipToPrevious(
+          trackCount: self.tracks.count,
+          currentIndex: self.currentTrackIndex,
+          repeatMode: self.repeatModeAsSkipMode(),
+          restartEnabled: self.skipRestartEnabled(),
+          positionMs: positionMs)
+        switch action {
+        case .previous(let idx):
+          self.applyNewCurrentIndex(newIndex: idx, reason: .userSkipPrevious)
+        case .restartCurrent:
+          // Restart the current track from 0 — a seek, not a track change.
+          // Same-index `applyNewCurrentIndex` takes its restart branch
+          // (currentItem unchanged → no `onTrackChange`), engine-aware across
+          // gapless (live / drained-rebuild) + crossfade.
+          self.applyNewCurrentIndex(
+            newIndex: self.currentTrackIndex, reason: .userSkipPrevious)
+        case .noOp:
+          return
+        }
       }
     }
   }
@@ -2156,6 +2176,13 @@ class TrackPlayer: HybridTrackPlayerSpec {
   /// Map the Nitrogen-generated `RepeatMode` enum onto the pure-Swift
   /// `QueueSkipRepeatMode` so `QueueSkipArithmetic` can stay off the
   /// Swift ↔ C++ interop path.
+  /// Whether skip-to-previous restarts the current track past the threshold
+  /// (`PlayerConfig.skipToPreviousBehavior == .restartOrPrevious`). Read live
+  /// from the current config at each skip + capability recompute.
+  private func skipRestartEnabled() -> Bool {
+    return self.config.skipToPreviousBehavior == .restartOrPrevious
+  }
+
   private func repeatModeAsSkipMode() -> QueueSkipRepeatMode {
     switch self.repeatModeState {
     case .off: return .off
@@ -2203,7 +2230,8 @@ class TrackPlayer: HybridTrackPlayerSpec {
     let count = tracks.count
     let cur = currentTrackIndex
     let newPrev = QueueSkipArithmetic.canSkipPrevious(
-      trackCount: count, currentIndex: cur, repeatMode: mode)
+      trackCount: count, currentIndex: cur, repeatMode: mode,
+      restartEnabled: skipRestartEnabled())
     let newNext = QueueSkipArithmetic.canSkipNext(
       trackCount: count, currentIndex: cur, repeatMode: mode)
     let current = cachedSkipCapability

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["getCastManager","getEqualizer","getTrackPlayer","getVisualizer","registerPlaybackService","unregisterPlaybackService","crossfadeDurationBounds","SectionIcon","EQ_BAND_COUNT","EQ_BAND_FREQUENCIES_HZ","EQ_FLAT_PRESET_NAME","EQ_GAIN_MAX_DB","EQ_GAIN_MIN_DB","clampGain","gainsFromBands","gainsFromMap","isBuiltinPreset","nearestBandIndex","Cast"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA;;AAMA;;AAuEA;AACA;AACA;AACA,SAASA,cAAc,EAAEC,YAAY,EAAEC,cAAc,EAAEC,aAAa,QAAQ,cAAW;;AAEvF;AACA;AACA;AACA,SACEC,uBAAuB,EACvBC,yBAAyB,QACpB,sBAAmB;AAM1B;AACA;AACA,SAASC,uBAAuB,QAAQ,YAAS;;AAEjD;AACA;AACA;AACA,SAASC,WAAW,QAAQ,YAAS;;AAErC;AACA;AACA;AACA,SACEC,aAAa,EACbC,sBAAsB,EACtBC,mBAAmB,EACnBC,cAAc,EACdC,cAAc,EACdC,SAAS,EACTC,cAAc,EACdC,YAAY,EACZC,eAAe,EACfC,gBAAgB,QACX,gBAAa;;AAEpB;AACA,cAAc,kBAAS;;AAEvB;AACA;AACA;AACA,OAAO,KAAKC,IAAI,MAAM,iBAAQ","ignoreList":[]}
+{"version":3,"names":["getCastManager","getEqualizer","getTrackPlayer","getVisualizer","registerPlaybackService","unregisterPlaybackService","crossfadeDurationBounds","SectionIcon","EQ_BAND_COUNT","EQ_BAND_FREQUENCIES_HZ","EQ_FLAT_PRESET_NAME","EQ_GAIN_MAX_DB","EQ_GAIN_MIN_DB","clampGain","gainsFromBands","gainsFromMap","isBuiltinPreset","nearestBandIndex","Cast"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA;;AAMA;;AAwEA;AACA;AACA;AACA,SAASA,cAAc,EAAEC,YAAY,EAAEC,cAAc,EAAEC,aAAa,QAAQ,cAAW;;AAEvF;AACA;AACA;AACA,SACEC,uBAAuB,EACvBC,yBAAyB,QACpB,sBAAmB;AAM1B;AACA;AACA,SAASC,uBAAuB,QAAQ,YAAS;;AAEjD;AACA;AACA;AACA,SAASC,WAAW,QAAQ,YAAS;;AAErC;AACA;AACA;AACA,SACEC,aAAa,EACbC,sBAAsB,EACtBC,mBAAmB,EACnBC,cAAc,EACdC,cAAc,EACdC,SAAS,EACTC,cAAc,EACdC,YAAY,EACZC,eAAe,EACfC,gBAAgB,QACX,gBAAa;;AAEpB;AACA,cAAc,kBAAS;;AAEvB;AACA;AACA;AACA,OAAO,KAAKC,IAAI,MAAM,iBAAQ","ignoreList":[]}

package/lib/module/types.js

@@ -99,6 +99,15 @@ export const crossfadeDurationBounds = {
  *   one that loops.
  */
 
+/**
+ * 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`.
+ */
+
 /**
  * How the lock-screen / notification skip controls behave: skip between queue
  * tracks (`'track'`) or jump forward/back within the current track by a fixed

package/lib/module/types.js.map

@@ -1 +1 @@
-{"version":3,"names":["crossfadeDurationBounds","minMs","maxMs","stepMs","SectionIcon"],"sourceRoot":"../../src","sources":["types.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;;AA2BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmJA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AA+BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;;AAyBA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,uBAAuB,GAAG;EACrC;EACAC,KAAK,EAAE,KAAK;EACZ;EACAC,KAAK,EAAE,MAAM;EACb;EACAC,MAAM,EAAE;AACV,CAAU;;AAEV;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;;AA0BA;AACA;AACA;AACA;;AAOe;;AAEf;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;;AAWA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA6EA;;AAMA;;AAcA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA+DA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA0BA;AACA;AACA;;AASA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA4FA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,WAAYC,WAAW,0BAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAA,OAAXA,WAAW;AAAA;;AAgBvB;AACA;AACA;AACA;AACA;AACA;AACA;;AAuBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAOA;AACA;AACA;;AAcA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAuDA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;;AASA;AACA;AACA;AACA;;AAWA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAaA;AACA;AACA;AACA;AACA;;AA0BA;AACA;AACA;AACA;AACA;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA","ignoreList":[]}
+{"version":3,"names":["crossfadeDurationBounds","minMs","maxMs","stepMs","SectionIcon"],"sourceRoot":"../../src","sources":["types.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;;AA2BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmLA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AA+BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;;AAyBA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,uBAAuB,GAAG;EACrC;EACAC,KAAK,EAAE,KAAK;EACZ;EACAC,KAAK,EAAE,MAAM;EACb;EACAC,MAAM,EAAE;AACV,CAAU;;AAEV;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;;AA0BA;AACA;AACA;AACA;;AAOe;;AAEf;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;;AAWA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA6EA;;AAMA;;AAcA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA+DA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA0BA;AACA;AACA;;AASA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA4FA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,WAAYC,WAAW,0BAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAA,OAAXA,WAAW;AAAA;;AAgBvB;AACA;AACA;AACA;AACA;AACA;AACA;;AAuBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAOA;AACA;AACA;;AAcA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAuDA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;;AASA;AACA;AACA;AACA;;AAWA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAaA;AACA;AACA;AACA;AACA;;AA0BA;AACA;AACA;AACA;AACA;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA","ignoreList":[]}

package/lib/typescript/TrackPlayer.nitro.d.ts

@@ -266,17 +266,17 @@ export interface TrackPlayer extends HybridObject<{
     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/lib/typescript/index.d.ts

@@ -2,7 +2,7 @@ export type { TrackPlayer } from './TrackPlayer.nitro';
 export type { Equalizer } from './Equalizer.nitro';
 export type { Visualizer } from './Visualizer.nitro';
 export type { CastManager } from './CastManager.nitro';
-export type { TrackItem, PlayerConfig, PlayerState, BufferState, PlaybackMode, PlaybackModeKind, RepeatMode, RemoteSkipMode, RemoteControlOptions, StateChangeReason, TrackChangeReason, QueueChangeReason, TrackSource, PlayerProgress, PlaybackError, PlaybackErrorCode, ShuffleResult, SkipCapability, SleepTimerState, NowPlayingFormat, AudioCodec, AudioContainer, LookaheadCacheConfig, EvictionPolicy, CacheStatus, MediaSearchRequest, MediaSearchType, MediaSearchOrigin, MediaSearchReference, MediaSearchRepeatMode, MediaSearchReleaseDateRange, MediaSearchQueueLocation, BrowseItem, BrowseSection, BrowseSnapshot, ServiceReadyReason, EqualizerBand, EqualizerPreset, ReplayGainMode, PitchCorrectionMode, VisualizerConfig, VisualizerFftSize, VisualizerFrame, VisualizerErrorReason, CastProtocol, CastStreamingModel, CastDeviceKind, CastSessionEndReason, CastLocalNetworkPermission, CastReceiverCapabilities, CastReceiver, CastRoute, CastDiscoveryState, CastSessionDiedEvent, CastLocalNetworkPermissionEvent, CastConnectOptions, AudioRouteKind, AudioRoute, } from './types';
+export type { TrackItem, PlayerConfig, PlayerState, BufferState, PlaybackMode, PlaybackModeKind, RepeatMode, SkipToPreviousBehavior, RemoteSkipMode, RemoteControlOptions, StateChangeReason, TrackChangeReason, QueueChangeReason, TrackSource, PlayerProgress, PlaybackError, PlaybackErrorCode, ShuffleResult, SkipCapability, SleepTimerState, NowPlayingFormat, AudioCodec, AudioContainer, LookaheadCacheConfig, EvictionPolicy, CacheStatus, MediaSearchRequest, MediaSearchType, MediaSearchOrigin, MediaSearchReference, MediaSearchRepeatMode, MediaSearchReleaseDateRange, MediaSearchQueueLocation, BrowseItem, BrowseSection, BrowseSnapshot, ServiceReadyReason, EqualizerBand, EqualizerPreset, ReplayGainMode, PitchCorrectionMode, VisualizerConfig, VisualizerFftSize, VisualizerFrame, VisualizerErrorReason, CastProtocol, CastStreamingModel, CastDeviceKind, CastSessionEndReason, CastLocalNetworkPermission, CastReceiverCapabilities, CastReceiver, CastRoute, CastDiscoveryState, CastSessionDiedEvent, CastLocalNetworkPermissionEvent, CastConnectOptions, AudioRouteKind, AudioRoute, } from './types';
 export { getCastManager, getEqualizer, getTrackPlayer, getVisualizer } from './clients';
 export { registerPlaybackService, unregisterPlaybackService, } from './playbackService';
 export type { PlaybackServiceHandler, PlaybackServiceFactory, } from './playbackService';