react-native-queue-player 1.0.8 → 1.1.0

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

@@ -40,7 +40,7 @@ class PlaceholderFallbackBitmapLoaderTest {
 
   @Test
   fun `loadBitmapFromMetadata returns placeholder when artwork URI and data are absent`() {
-    val loader = PlaceholderFallbackBitmapLoader(NeverCalledLoader, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(NeverCalledLoader, { placeholder })
     val metadata = MediaMetadata.Builder().setTitle("no artwork").build()
 
     val future = loader.loadBitmapFromMetadata(metadata)
@@ -49,10 +49,22 @@ class PlaceholderFallbackBitmapLoaderTest {
     assertSame(placeholder, future!!.get())
   }
 
+  @Test
+  fun `loadBitmapFromMetadata reads the placeholder provider on every call so a live swap is reflected`() {
+    val swapped = Bitmap.createBitmap(4, 4, Bitmap.Config.ARGB_8888)
+    var current = placeholder
+    val loader = PlaceholderFallbackBitmapLoader(NeverCalledLoader) { current }
+    val metadata = MediaMetadata.Builder().setTitle("no artwork").build()
+
+    assertSame(placeholder, loader.loadBitmapFromMetadata(metadata)!!.get())
+    current = swapped
+    assertSame(swapped, loader.loadBitmapFromMetadata(metadata)!!.get())
+  }
+
   @Test
   fun `loadBitmapFromMetadata returns delegate result when artwork URI is present`() {
     val delegate = StubLoader(metadataResult = Futures.immediateFuture(delegateBitmap))
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
     val metadata = MediaMetadata.Builder()
       .setArtworkUri(Uri.parse("https://example.com/cover.jpg"))
       .build()
@@ -68,7 +80,7 @@ class PlaceholderFallbackBitmapLoaderTest {
     val delegate = StubLoader(
       metadataResult = Futures.immediateFailedFuture(RuntimeException("decode failed"))
     )
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
     val metadata = MediaMetadata.Builder()
       .setArtworkUri(Uri.parse("https://example.com/broken.jpg"))
       .build()
@@ -82,7 +94,7 @@ class PlaceholderFallbackBitmapLoaderTest {
   @Test
   fun `loadBitmapFromMetadata returns placeholder when delegate returns null future`() {
     val delegate = StubLoader(metadataResult = null)
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
     val metadata = MediaMetadata.Builder()
       .setArtworkUri(Uri.parse("https://example.com/cover.jpg"))
       .build()
@@ -98,7 +110,7 @@ class PlaceholderFallbackBitmapLoaderTest {
     val delegate = StubLoader(
       uriResult = Futures.immediateFailedFuture(RuntimeException("network error"))
     )
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
 
     val result = loader.loadBitmap(Uri.parse("https://example.com/cover.jpg")).get()
 
@@ -108,7 +120,7 @@ class PlaceholderFallbackBitmapLoaderTest {
   @Test
   fun `loadBitmap returns delegate result on success`() {
     val delegate = StubLoader(uriResult = Futures.immediateFuture(delegateBitmap))
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
 
     val result = loader.loadBitmap(Uri.parse("https://example.com/cover.jpg")).get()
 
@@ -120,7 +132,7 @@ class PlaceholderFallbackBitmapLoaderTest {
     val delegate = StubLoader(
       bytesResult = Futures.immediateFailedFuture(RuntimeException("malformed bytes"))
     )
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
 
     val result = loader.decodeBitmap(byteArrayOf(0x00, 0x01)).get()
 
@@ -130,7 +142,7 @@ class PlaceholderFallbackBitmapLoaderTest {
   @Test
   fun `decodeBitmap returns delegate result on success`() {
     val delegate = StubLoader(bytesResult = Futures.immediateFuture(delegateBitmap))
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
 
     val result = loader.decodeBitmap(byteArrayOf(0x00, 0x01)).get()
 
@@ -140,7 +152,7 @@ class PlaceholderFallbackBitmapLoaderTest {
   @Test
   fun `supportsMimeType proxies through to delegate`() {
     val delegate = StubLoader(supportedMimeTypes = setOf("image/jpeg"))
-    val loader = PlaceholderFallbackBitmapLoader(delegate, placeholder)
+    val loader = PlaceholderFallbackBitmapLoader(delegate, { placeholder })
 
     assertTrue(loader.supportsMimeType("image/jpeg"))
     assertFalse(loader.supportsMimeType("image/heic"))

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

@@ -80,16 +80,16 @@ class PlaybackServiceArtworkLoaderTest {
 
   @Test
   fun `repeat builds reuse the same placeholder bitmap`() {
-    // PlaceholderArtwork is process-cached after first read so the
-    // ~10 KB JPEG decode runs once — service-recreate cycles +
-    // multiple consumer-side reconfigures should not multiply the
-    // memory cost.
+    // The loader holds a placeholder *provider* closure; invoking it
+    // reads the process-cached PlaceholderArtwork bitmap so the ~10 KB
+    // JPEG decode runs once — service-recreate cycles + multiple
+    // consumer-side reconfigures do not multiply the memory cost.
     val first = service.buildBitmapLoader()
     val second = service.buildBitmapLoader()
-    val firstPlaceholder = first.javaClass.getDeclaredField("placeholder")
-      .apply { isAccessible = true }.get(first)
-    val secondPlaceholder = second.javaClass.getDeclaredField("placeholder")
-      .apply { isAccessible = true }.get(second)
-    assertSame(firstPlaceholder, secondPlaceholder)
+    val firstProvider = first.javaClass.getDeclaredField("placeholder")
+      .apply { isAccessible = true }.get(first) as kotlin.jvm.functions.Function0<*>
+    val secondProvider = second.javaClass.getDeclaredField("placeholder")
+      .apply { isAccessible = true }.get(second) as kotlin.jvm.functions.Function0<*>
+    assertSame(firstProvider.invoke(), secondProvider.invoke())
   }
 }

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,
+      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,
+      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), 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), 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), 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), 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
+    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)
+    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
+    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
+    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
+    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), 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)
+    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
+        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
+    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),
+      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),
+      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)
+    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)
+  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), 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), 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
+    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), 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), 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/TrackPlayerReadersTest.kt

@@ -42,7 +42,7 @@ class TrackPlayerReadersTest {
         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
+        lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
       ),
       context()
     )

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

@@ -53,7 +53,7 @@ class TrackPlayerSkipCapabilityTest {
     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), 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()
     )
   }
 
@@ -318,7 +318,46 @@ class TrackPlayerSkipCapabilityTest {
     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), 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()
+    )
+  }
+
+  // --- skipToPreviousBehavior = restart-or-previous forces canSkipPrevious true
+
+  private fun configureRestart() {
+    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, skipToPreviousBehavior = SkipToPreviousBehavior.RESTART_OR_PREVIOUS), context()
+    )
+  }
+
+  @Test
+  fun `restart mode forces canSkipPrevious true at index 0`() {
+    configureRestart()
+    player.setQueueInternal((1..5).map { track("t$it") })
+    // At index 0 under OFF the default mode reports false (no previous);
+    // restart mode forces it true so Previous never greys out.
+    assertEquals(true, player.getCanSkipPrevious())
+    assertEquals(true, player.getCanSkipNext())
+  }
+
+  @Test
+  fun `default previous mode leaves canSkipPrevious false at index 0`() {
+    // setUp configured skipToPreviousBehavior = null (= 'previous').
+    player.setQueueInternal((1..5).map { track("t$it") })
+    assertEquals(false, player.getCanSkipPrevious())
+  }
+
+  @Test
+  fun `restart mode emits canSkipPrevious true via onSkipCapabilityChange`() {
+    configureRestart()
+    val emissions = mutableListOf<SkipCapability>()
+    player.onSkipCapabilityChange { cap -> emissions.add(cap) }
+    flushMain() // auto-fire: empty queue → (false, false)
+    player.setQueueInternal((1..5).map { track("t$it") })
+    flushMain()
+    assertTrue(
+      "restart mode makes canSkipPrevious true once a track is loaded",
+      emissions.last().canSkipPrevious
     )
   }
 }

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

@@ -51,7 +51,7 @@ class TrackPlayerSkipTest {
     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), 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.tracks = (1..5).map { track("t$it") }
     player.currentTrackIndex = 2 // mid-queue default for most cases
@@ -284,4 +284,37 @@ class TrackPlayerSkipTest {
       0, fresh.currentTrackIndex
     )
   }
+
+  // --- skipToPreviousInternal with skipToPreviousBehavior = restart-or-previous
+  //
+  // The test harness leaves the ExoPlayer timeline empty, so engine position
+  // reads 0 (<= the 3s threshold). Past-threshold restart with a real position
+  // is covered by the pure `QueueSkipArithmeticTest` matrix + the demo suite.
+
+  private fun configureSkipBehavior(behavior: SkipToPreviousBehavior?) {
+    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, skipToPreviousBehavior = behavior), context()
+    )
+    player.tracks = (1..5).map { track("t$it") }
+  }
+
+  @Test
+  fun `skipToPreviousInternal restart mode under threshold goes to previous track`() {
+    configureSkipBehavior(SkipToPreviousBehavior.RESTART_OR_PREVIOUS)
+    player.repeatModeState = RepeatMode.OFF
+    player.currentTrackIndex = 3
+    player.skipToPreviousInternal()
+    assertEquals("position 0 <= threshold → previous track", 2, player.currentTrackIndex)
+  }
+
+  @Test
+  fun `skipToPreviousInternal restart mode at first track restarts, index unchanged`() {
+    configureSkipBehavior(SkipToPreviousBehavior.RESTART_OR_PREVIOUS)
+    player.repeatModeState = RepeatMode.OFF
+    player.currentTrackIndex = 0
+    // No previous track → restart current; the restart branch seeks to 0 and
+    // leaves currentTrackIndex put (a seek, not a skip).
+    player.skipToPreviousInternal()
+    assertEquals("restart leaves the index unchanged", 0, player.currentTrackIndex)
+  }
 }

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

@@ -50,7 +50,7 @@ class TrackPlayerTransportTest {
     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), 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/ios/Cast/Core/CastNowPlayingController.swift

@@ -35,12 +35,15 @@ final class CastNowPlayingController {
   /// `TrackPlayer.configure` via `configureArtwork`.
   private let artworkResolver = ArtworkResolver()
 
-  /// Bundled placeholder shown until the real cover resolves, so the
-  /// lockscreen never renders artwork-less during the network fetch.
-  private static let placeholderArtwork: MPMediaItemArtwork = {
+  /// Placeholder shown until the real cover resolves, so the lockscreen
+  /// never renders artwork-less during the network fetch. Read live —
+  /// `PlaceholderArtwork.image` is the consumer-configured image when one
+  /// is set (`PlayerConfig.placeholderArtworkUri`), else the bundled one —
+  /// so a per-refresh write here never clobbers it back to the built-in.
+  private static var placeholderArtwork: MPMediaItemArtwork {
     let image = PlaceholderArtwork.image
     return MPMediaItemArtwork(boundsSize: image.size) { _ in image }
-  }()
+  }
 
   /// Snapshot of the active receiver track for the lockscreen surface.
   /// Pushed by `TrackPlayer` when the receiver's current track (resolved