react-native-queue-player 1.0.9 → 1.1.1

package/README.md

@@ -140,9 +140,17 @@ Lock-screen / Now Playing controls and remote commands work automatically once t
 
 ## Common UX patterns
 
-### Apple-Music-style "tap Previous restarts when position > 3s"
+### Restart-or-previous skip-back (the "tap Previous restarts, then goes back" model)
 
-The library ships the **primitive** (`canSkipPrevious` = "is there a previous track under the current repeat mode") and leaves the **policy** (rewind-vs-skip threshold) to your app:
+The standard music-player behaviour — a skip-back restarts the current track when it's past a few seconds, otherwise goes to the previous track — is built in. Enable it with `skipToPreviousBehavior`:
+
+```ts
+await player.configure({ skipToPreviousBehavior: 'restart-or-previous' });
+```
+
+Now every `skipToPrevious()` — from your UI, the lock screen, Bluetooth, Android Auto, or CarPlay — restarts the current track (seeks to 0) when the position is past ~3 s, and goes to the previous track under it. Because it's native, it stays consistent across every surface (a JS handler can't cleanly intercept the OS Previous button), and the restart is a seek so it does **not** fire `onTrackChange`. With the option enabled, `canSkipPrevious` stays `true` while a track is loaded, so the Previous control never greys out — even on the first track. The default `'previous'` keeps skip-back always going to the previous track. (Local playback only; during cast, Previous routes to the receiver.)
+
+For a different threshold or bespoke logic on **your own** in-app button (the OS controls follow `skipToPreviousBehavior`), leave the option at its default and branch on the live position:
 
 ```tsx
 import { getTrackPlayer, useProgress } from 'react-native-queue-player';
@@ -151,18 +159,16 @@ function PreviousButton() {
   const { position } = useProgress();
   const onPress = async () => {
     const player = getTrackPlayer();
-    if (position > 3) await player.seekTo(0);
+    if (position > 5) await player.seekTo(0);
     else await player.skipToPrevious();
   };
   return /* your <Button> here */;
 }
 ```
 
-The 3-second threshold is the Apple Music default; tune to taste.
-
 ### Skip-button enable/disable from `useCanSkip`
 
-`canSkipNext` / `canSkipPrevious` already account for repeat mode: under `off` they go false at queue boundaries; under `queue` they wrap and stay true; under `track` they stay true.
+`canSkipNext` / `canSkipPrevious` account for repeat mode: under `off` they go false at queue boundaries; under `queue` they wrap and stay true; under `track` they stay true. With `skipToPreviousBehavior: 'restart-or-previous'`, `canSkipPrevious` stays true whenever a track is loaded (the Previous control never greys out).
 
 ```tsx
 const { canSkipNext, canSkipPrevious } = useCanSkip();

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

@@ -762,8 +762,15 @@ class PlaybackService : HeadlessJsMediaService() {
    * (the same one ExoPlayer drives for HTTP playback), so consumer
    * `userAgent` + custom HTTP headers configured on the player's
    * `MediaSource.Factory` propagate into artwork fetches without a
-   * second HTTP client. `CacheBitmapLoader` deduplicates repeat
-   * requests for the same URI inside a single foreground session.
+   * second HTTP client. It mirrors Media3's own default loader config:
+   * `setMaximumOutputDimension(MediaSession.getBitmapDimensionLimit(...))`
+   * downsamples an oversized consumer image during decode (device-adaptive
+   * cap; no full-resolution bitmap for a small control), and
+   * `setMakeShared(true)` puts the bitmap in shared memory so the System UI
+   * process reuses it instead of copying. Supplying our own loader (for the
+   * placeholder guarantee below) had otherwise dropped both defaults, which
+   * is what left artwork decoding unbounded. `CacheBitmapLoader` deduplicates
+   * repeat requests for the same URI inside a single foreground session.
    * The outer [PlaceholderFallbackBitmapLoader] guarantees a bitmap
    * always reaches the notification — the OEM-skin failure mode
    * where a null bitmap drops the transport controls is closed.
@@ -776,7 +783,12 @@ class PlaybackService : HeadlessJsMediaService() {
   @VisibleForTesting
   internal fun buildBitmapLoader(): PlaceholderFallbackBitmapLoader =
     PlaceholderFallbackBitmapLoader(
-      delegate = CacheBitmapLoader(DataSourceBitmapLoader.Builder(this).build()),
+      delegate = CacheBitmapLoader(
+        DataSourceBitmapLoader.Builder(this)
+          .setMaximumOutputDimension(MediaSession.getBitmapDimensionLimit(this))
+          .setMakeShared(true)
+          .build()
+      ),
       // Read on each fallback so a placeholder set at `configure` (after
       // this loader was built in onCreate) is reflected — `PlaceholderArtwork`
       // returns the consumer image when one is configured, else the built-in.

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

@@ -59,9 +59,9 @@ internal object QueueSkipArithmetic {
    * Previous-track index. Same early-bail rules as [computeNext].
    *
    * OFF and TRACK both return null at index 0 (no previous track, no
-   * wrap). Apps that want the Apple-Music-style "tap Previous at
-   * track 0 restarts current" UX implement that in their button
-   * handler.
+   * wrap). The "restart current when past the threshold" model is
+   * available via `PlayerConfig.skipToPreviousBehavior` (resolved by
+   * [resolveSkipToPrevious]).
    */
   fun computePrevious(
     trackCount: Int,
@@ -99,15 +99,62 @@ internal object 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
+   * == RESTART_OR_PREVIOUS`), 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.
    */
   fun canSkipPrevious(
     trackCount: Int,
     currentIndex: Int,
-    repeatMode: QueueSkipRepeatMode
-  ): Boolean = computePrevious(trackCount, currentIndex, repeatMode) != null
+    repeatMode: QueueSkipRepeatMode,
+    restartEnabled: Boolean = false
+  ): Boolean =
+    if (restartEnabled) trackCount > 0
+    else computePrevious(trackCount, currentIndex, repeatMode) != null
+
+  /**
+   * Position (ms) at or below which a restart-or-previous skip-back goes
+   * to the previous track; past it, the current track restarts. Matches
+   * Media3's default `maxSeekToPreviousPosition` (industry-standard 3 s).
+   */
+  const val RESTART_THRESHOLD_MS: Long = 3000L
+
+  /** What a skip-to-previous should do, resolved from position + behavior. */
+  sealed interface SkipToPreviousAction {
+    /** Navigate to this queue index (a real track change). */
+    data class Previous(val index: Int) : SkipToPreviousAction
+    /** Restart the current track (seek to 0) — not a track change. */
+    object RestartCurrent : SkipToPreviousAction
+    /** Nothing to do (empty queue). */
+    object NoOp : SkipToPreviousAction
+  }
+
+  /**
+   * 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.
+   */
+  fun resolveSkipToPrevious(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode,
+    restartEnabled: Boolean,
+    positionMs: Long,
+    thresholdMs: Long = RESTART_THRESHOLD_MS
+  ): SkipToPreviousAction {
+    if (trackCount <= 0 || currentIndex < 0) return SkipToPreviousAction.NoOp
+    val prev = computePrevious(trackCount, currentIndex, repeatMode)
+    if (!restartEnabled) {
+      return if (prev != null) SkipToPreviousAction.Previous(prev) else SkipToPreviousAction.NoOp
+    }
+    return if (prev != null && positionMs <= thresholdMs) {
+      SkipToPreviousAction.Previous(prev)
+    } else {
+      SkipToPreviousAction.RestartCurrent
+    }
+  }
 }

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

@@ -201,7 +201,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       visualizationEnabled = null,
       clampSeekToBuffered = null,
       lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
-      progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
+      progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
     )
 
   @Volatile
@@ -2171,25 +2171,46 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     }
 
   /**
-   * 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
+   * RESTART_OR_PREVIOUS it restarts the current track (seek to 0) when past
+   * the threshold, otherwise goes to the previous track.
    */
   @VisibleForTesting
   internal fun skipToPreviousInternal() {
     val p = player ?: return
-    val prev = computePreviousIndex() ?: return
-    currentTrackIndex = prev
-    pendingTrackChangeReason = TrackChangeReason.USER_SKIP_PREVIOUS
-    if (prev < p.mediaItemCount) {
-      serviceBinder?.engine?.seekTo(prev, 0L)
+    val action = QueueSkipArithmetic.resolveSkipToPrevious(
+      trackCount = tracks.size,
+      currentIndex = currentTrackIndex,
+      repeatMode = repeatModeAsSkipMode(),
+      restartEnabled = skipRestartEnabled(),
+      positionMs = serviceBinder?.engine?.currentPositionMs ?: 0L
+    )
+    when (action) {
+      is QueueSkipArithmetic.SkipToPreviousAction.Previous -> {
+        val prev = action.index
+        currentTrackIndex = prev
+        pendingTrackChangeReason = TrackChangeReason.USER_SKIP_PREVIOUS
+        if (prev < p.mediaItemCount) {
+          serviceBinder?.engine?.seekTo(prev, 0L)
+        }
+        rescheduleLookahead()
+        recomputeCapabilities()
+      }
+      QueueSkipArithmetic.SkipToPreviousAction.RestartCurrent -> {
+        // Restart the current track from 0 — a seek, not a track change.
+        // A same-index seek emits no onMediaItemTransition, so no
+        // onTrackChange; leave currentTrackIndex + pendingTrackChangeReason
+        // untouched (stashing a reason no transition consumes would leak
+        // into the next real skip).
+        if (currentTrackIndex in 0 until p.mediaItemCount) {
+          serviceBinder?.engine?.seekTo(currentTrackIndex, 0L)
+        }
+      }
+      QueueSkipArithmetic.SkipToPreviousAction.NoOp -> return
     }
-    rescheduleLookahead()
-    recomputeCapabilities()
   }
 
   /**
@@ -2221,6 +2242,14 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     RepeatMode.QUEUE -> QueueSkipRepeatMode.QUEUE
   }
 
+  /**
+   * Whether skip-to-previous restarts the current track past the threshold
+   * (`PlayerConfig.skipToPreviousBehavior == RESTART_OR_PREVIOUS`). Read live
+   * from the current config at each skip + capability recompute.
+   */
+  private fun skipRestartEnabled(): Boolean =
+    config.skipToPreviousBehavior == SkipToPreviousBehavior.RESTART_OR_PREVIOUS
+
   /**
    * Recompute [cachedSkipCapability] from
    * authoritative state and fire [onSkipCapabilityChange] if either
@@ -2245,7 +2274,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val mode = repeatModeAsSkipMode()
     val count = tracks.size
     val cur = currentTrackIndex
-    val newPrev = QueueSkipArithmetic.canSkipPrevious(count, cur, mode)
+    val newPrev = QueueSkipArithmetic.canSkipPrevious(count, cur, mode, skipRestartEnabled())
     val newNext = QueueSkipArithmetic.canSkipNext(count, cur, mode)
     val current = cachedSkipCapability
     val capChanged =

package/android/src/test/java/com/margelo/nitro/queueplayer/PlaybackServiceArtworkLoaderTest.kt

@@ -3,7 +3,9 @@ package com.margelo.nitro.queueplayer
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.datasource.DataSourceBitmapLoader
 import androidx.media3.session.CacheBitmapLoader
+import androidx.media3.session.MediaSession
 import org.junit.After
+import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertSame
 import org.junit.Assert.assertTrue
@@ -78,6 +80,32 @@ class PlaybackServiceArtworkLoaderTest {
     )
   }
 
+  @Test
+  fun `DataSourceBitmapLoader mirrors Media3's default cap + shared-memory bitmap`() {
+    val loader = service.buildBitmapLoader()
+    val cached = loader.javaClass.getDeclaredField("delegate")
+      .apply { isAccessible = true }.get(loader) as CacheBitmapLoader
+    val backing = cached.javaClass.getDeclaredField("bitmapLoader")
+      .apply { isAccessible = true }.get(cached) as DataSourceBitmapLoader
+    val maxDim = DataSourceBitmapLoader::class.java
+      .getDeclaredField("maximumOutputDimension")
+      .apply { isAccessible = true }
+      .getInt(backing)
+    assertEquals(
+      "artwork decode is capped to Media3's device-adaptive limit (no full-res allocation)",
+      MediaSession.getBitmapDimensionLimit(service),
+      maxDim
+    )
+    val makeShared = DataSourceBitmapLoader::class.java
+      .getDeclaredField("makeShared")
+      .apply { isAccessible = true }
+      .getBoolean(backing)
+    assertTrue(
+      "decoded bitmap is shared-memory so the System UI process reuses it instead of copying",
+      makeShared
+    )
+  }
+
   @Test
   fun `repeat builds reuse the same placeholder bitmap`() {
     // The loader holds a placeholder *provider* closure; invoking it

package/android/src/test/java/com/margelo/nitro/queueplayer/PlaybackServiceCallbackTest.kt

@@ -785,7 +785,7 @@ class PlaybackServiceCallbackTest {
         audioCategoryOptions = null,
         visualizationEnabled = null,
         clampSeekToBuffered = null,
-      lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null,
+      lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null,
       ),
       context,
     )

package/android/src/test/java/com/margelo/nitro/queueplayer/QueueSkipArithmeticTest.kt

@@ -340,4 +340,107 @@ class QueueSkipArithmeticTest {
     assertFalse(QueueSkipArithmetic.canSkipNext(1, 0, QueueSkipRepeatMode.TRACK))
     assertFalse(QueueSkipArithmetic.canSkipPrevious(1, 0, QueueSkipRepeatMode.TRACK))
   }
+
+  // --- resolveSkipToPrevious — mode OFF (position ignored, current behavior)
+
+  private fun resolve(
+    count: Int = 3, index: Int, mode: QueueSkipRepeatMode,
+    restart: Boolean, positionMs: Long
+  ) = QueueSkipArithmetic.resolveSkipToPrevious(count, index, mode, restart, positionMs)
+
+  private val previous1 = QueueSkipArithmetic.SkipToPreviousAction.Previous(1)
+  private val previous2 = QueueSkipArithmetic.SkipToPreviousAction.Previous(2)
+  private val restart = QueueSkipArithmetic.SkipToPreviousAction.RestartCurrent
+  private val noOp = QueueSkipArithmetic.SkipToPreviousAction.NoOp
+
+  @Test
+  fun `resolve mode OFF ignores position and goes previous`() {
+    assertEquals(previous1, resolve(index = 2, mode = QueueSkipRepeatMode.OFF, restart = false, positionMs = 99_000L))
+  }
+
+  @Test
+  fun `resolve mode OFF first track is noop`() {
+    assertEquals(noOp, resolve(index = 0, mode = QueueSkipRepeatMode.OFF, restart = false, positionMs = 99_000L))
+  }
+
+  @Test
+  fun `resolve mode OFF queue wraps`() {
+    assertEquals(previous2, resolve(index = 0, mode = QueueSkipRepeatMode.QUEUE, restart = false, positionMs = 0L))
+  }
+
+  @Test
+  fun `resolve mode OFF empty queue is noop`() {
+    assertEquals(noOp, resolve(count = 0, index = -1, mode = QueueSkipRepeatMode.OFF, restart = false, positionMs = 0L))
+  }
+
+  // --- resolveSkipToPrevious — mode ON (3s threshold model)
+
+  @Test
+  fun `resolve past threshold restarts even with a previous`() {
+    for (pos in listOf(3001L, 5000L, 600_000L)) {
+      assertEquals("position $pos > 3000 restarts", restart,
+        resolve(index = 2, mode = QueueSkipRepeatMode.OFF, restart = true, positionMs = pos))
+    }
+  }
+
+  @Test
+  fun `resolve threshold boundary goes previous, one past restarts`() {
+    assertEquals(previous1, resolve(index = 2, mode = QueueSkipRepeatMode.OFF, restart = true, positionMs = 3000L))
+    assertEquals(restart, resolve(index = 2, mode = QueueSkipRepeatMode.OFF, restart = true, positionMs = 3001L))
+  }
+
+  @Test
+  fun `resolve under threshold goes previous`() {
+    for (pos in listOf(0L, 1L, 2999L)) {
+      assertEquals("position $pos <= 3000 goes previous", previous1,
+        resolve(index = 2, mode = QueueSkipRepeatMode.OFF, restart = true, positionMs = pos))
+    }
+  }
+
+  @Test
+  fun `resolve first track under threshold restarts when no previous`() {
+    assertEquals(restart, resolve(index = 0, mode = QueueSkipRepeatMode.OFF, restart = true, positionMs = 1000L))
+    assertEquals(restart, resolve(index = 0, mode = QueueSkipRepeatMode.TRACK, restart = true, positionMs = 1000L))
+  }
+
+  @Test
+  fun `resolve first track under threshold queue wraps`() {
+    assertEquals(previous2, resolve(index = 0, mode = QueueSkipRepeatMode.QUEUE, restart = true, positionMs = 1000L))
+  }
+
+  @Test
+  fun `resolve first track past threshold restarts under every mode`() {
+    for (mode in QueueSkipRepeatMode.values()) {
+      assertEquals("first track past threshold restarts under $mode", restart,
+        resolve(index = 0, mode = mode, restart = true, positionMs = 9000L))
+    }
+  }
+
+  @Test
+  fun `resolve mode ON empty queue is noop`() {
+    assertEquals(noOp, resolve(count = 0, index = -1, mode = QueueSkipRepeatMode.OFF, restart = true, positionMs = 9000L))
+  }
+
+  // --- canSkipPrevious with restartEnabled (forced true)
+
+  @Test
+  fun `canSkipPrevious forced true at every index and mode`() {
+    for (mode in QueueSkipRepeatMode.values()) {
+      for (index in 0 until 3) {
+        assertTrue("restart mode forces canSkipPrevious true at index $index under $mode",
+          QueueSkipArithmetic.canSkipPrevious(3, index, mode, restartEnabled = true))
+      }
+    }
+  }
+
+  @Test
+  fun `canSkipPrevious restartEnabled false for empty queue`() {
+    assertFalse(QueueSkipArithmetic.canSkipPrevious(0, -1, QueueSkipRepeatMode.OFF, restartEnabled = true))
+  }
+
+  @Test
+  fun `canSkipPrevious restart disabled matches existing`() {
+    assertFalse(QueueSkipArithmetic.canSkipPrevious(3, 0, QueueSkipRepeatMode.OFF, restartEnabled = false))
+    assertTrue(QueueSkipArithmetic.canSkipPrevious(3, 1, QueueSkipRepeatMode.OFF, restartEnabled = false))
+  }
 }

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerAirPlayMetadataWiringTest.kt

@@ -66,7 +66,7 @@ class TrackPlayerAirPlayMetadataWiringTest {
         retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null,
         audioCategoryOptions = null, visualizationEnabled = null,
         clampSeekToBuffered = null,
-      lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null,
+      lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null,
       ),
       context(),
     )

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerAudioFocusTest.kt

@@ -44,7 +44,7 @@ class TrackPlayerAudioFocusTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerEventsTest.kt

@@ -51,7 +51,7 @@ class TrackPlayerEventsTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 
@@ -230,7 +230,7 @@ class TrackPlayerEventsTest {
     // the public effects — a new configure + getStateInternal
     // should return NONE.
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     assertEquals(PlayerState.NONE, player.getStateInternal())
   }
@@ -479,7 +479,7 @@ class TrackPlayerEventsTest {
     serviceHandle.destroy()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     // No listener is bound to the new ExoPlayer's actual STATE_ENDED
     // path in a Robolectric test, but the callback slot itself is

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerLifecycleTest.kt

@@ -68,7 +68,7 @@ class TrackPlayerLifecycleTest {
       autoRetries = null,
       retryBackoffMs = null,
       networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
+    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
     )
     player.configureInternal(config, context())
 
@@ -92,7 +92,7 @@ class TrackPlayerLifecycleTest {
     // public path owns the destroy step. This test drives the
     // destroy + reconstruct shape directly to mirror what
     // `configure()` does end-to-end.
-    val empty = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null)
+    val empty = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
 
     player.configureInternal(empty, context())
     val firstInstance = player.player
@@ -125,12 +125,12 @@ class TrackPlayerLifecycleTest {
     val first = PlayerConfig(
       httpHeaders = mapOf("A" to "1"), userAgent = "ua-1",
       autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
+    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
     )
     val second = PlayerConfig(
       httpHeaders = mapOf("B" to "2"), userAgent = "ua-2",
       autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
+    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
     )
 
     player.configureInternal(first, context())
@@ -144,7 +144,7 @@ class TrackPlayerLifecycleTest {
     val configured = PlayerConfig(
       httpHeaders = mapOf("h" to "v"), userAgent = "ua",
       autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null,
-    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
+    lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
     )
     player.configureInternal(configured, context())
     // Non-default playback state the consumer set post-configure.
@@ -180,7 +180,7 @@ class TrackPlayerLifecycleTest {
   @Test
   fun `destroyInternal is safe to call twice`() {
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     player.destroyInternal()
     player.destroyInternal()
@@ -189,7 +189,7 @@ class TrackPlayerLifecycleTest {
 
   @Test
   fun `configureInternal after destroyInternal rebuilds the ExoPlayer`() {
-    val cfg = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null)
+    val cfg = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
 
     player.configureInternal(cfg, context())
     val first = player.player

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerLookaheadConfigTest.kt

@@ -80,7 +80,7 @@ class TrackPlayerLookaheadConfigTest {
         httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
         networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
         visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = 250.0, lookaheadCacheEvictionPolicy = null,
-        progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
+        progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
       ),
       context()
     )
@@ -120,7 +120,7 @@ class TrackPlayerLookaheadConfigTest {
     networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
     visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null,
     lookaheadCacheEvictionPolicy = policy,
-    progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
+    progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
   )
 
   // --- setLookaheadCacheInternal
@@ -298,7 +298,7 @@ class TrackPlayerLookaheadConfigTest {
   @Test
   fun `re-configure with changed httpHeaders rebuilds the player (writer + cache)`() {
     player.configureInternal(
-      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-1"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null),
+      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-1"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null),
       context()
     )
     val firstWriter = player.lookaheadCacheWriter
@@ -307,7 +307,7 @@ class TrackPlayerLookaheadConfigTest {
     assertNotNull(firstCache)
 
     player.configureInternal(
-      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-2"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null),
+      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-2"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null),
       context()
     )
 
@@ -339,7 +339,7 @@ class TrackPlayerLookaheadConfigTest {
     // simulated here by `destroyInternal` between
     // `configureInternal` calls) yields a fresh writer instance,
     // even when headers are unchanged.
-    val cfg = PlayerConfig(httpHeaders = mapOf("X-Auth" to "token"), userAgent = "rnqp/test", autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null)
+    val cfg = PlayerConfig(httpHeaders = mapOf("X-Auth" to "token"), userAgent = "rnqp/test", autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
     player.configureInternal(cfg, context())
     val firstWriter = player.lookaheadCacheWriter
 
@@ -413,5 +413,5 @@ class TrackPlayerLookaheadConfigTest {
 
   // --- Helpers
 
-  private fun emptyConfig() = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null)
+  private fun emptyConfig() = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
 }

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerMutationTest.kt

@@ -45,7 +45,7 @@ class TrackPlayerMutationTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     player.setQueueInternal((1..5).map { track("t$it") })
     // cur defaults to 0 after setQueue; tests needing mid-queue
@@ -127,7 +127,7 @@ class TrackPlayerMutationTest {
     val freshHandle = bindPlaybackServiceForTest(fresh, context())
     try {
       fresh.configureInternal(
-        PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+        PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
       )
       assertEquals(-1, fresh.currentTrackIndex)
       assertEquals(Player.STATE_IDLE, fresh.player!!.playbackState)

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerProgressThrottleTest.kt

@@ -35,7 +35,7 @@ class TrackPlayerProgressThrottleTest {
     httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
     networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
     visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
-    progressUpdateIntervalMs = foregroundMs, backgroundProgressUpdateIntervalMs = backgroundMs, placeholderArtworkUri = null
+    progressUpdateIntervalMs = foregroundMs, backgroundProgressUpdateIntervalMs = backgroundMs, placeholderArtworkUri = null, skipToPreviousBehavior = null
   )
 
   @Before

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerQueueChangeTest.kt

@@ -47,7 +47,7 @@ class TrackPlayerQueueChangeTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     player.setQueueInternal((1..5).map { track("t$it") })
   }

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerQueueTest.kt

@@ -55,7 +55,7 @@ class TrackPlayerQueueTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }