react-native-queue-player 1.0.7 → 1.0.9

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
     )
     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)
 
     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
     )
     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
     )
 
     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
     )
     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), 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)
 
     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
       ),
       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
   )
 
   // --- 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),
       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),
       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)
     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)
 }

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), 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), 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
   )
 
   @Before

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

@@ -0,0 +1,180 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * `onQueueChange` emission coverage against a live ExoPlayer via
+ * Robolectric. Every queue-content/order mutation fires exactly one
+ * event carrying the post-mutation `(queue, index, reason)`; a no-op
+ * mutation fires nothing. `emitQueueChange` runs synchronously inside
+ * the mutation on the test (main) thread, so no looper idle is needed to
+ * observe the fire.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class TrackPlayerQueueChangeTest {
+
+  private lateinit var player: TrackPlayer
+  private lateinit var serviceHandle: PlaybackServiceTestHandle
+
+  private data class QueueEvent(
+    val queue: List<TrackItem>,
+    val index: Int,
+    val reason: QueueChangeReason,
+  )
+
+  private fun context() =
+    ApplicationProvider.getApplicationContext<android.content.Context>()
+
+  private fun track(id: String) = TrackItem(
+    id = id, url = "https://example.com/$id.m4a",
+    title = null, artist = null, album = null,
+    duration = null, artworkUrl = null, extras = null,
+  )
+
+  @Before
+  fun setUp() {
+    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()
+    )
+    player.setQueueInternal((1..5).map { track("t$it") })
+  }
+
+  @After
+  fun tearDown() {
+    player.destroyInternal()
+    serviceHandle.destroy()
+  }
+
+  /** Register a capturing listener AFTER the @Before setQueue (which is
+   *  therefore not captured — onQueueChange does not auto-fire). */
+  private fun capture(): Pair<MutableList<QueueEvent>, () -> Unit> {
+    val events = mutableListOf<QueueEvent>()
+    val dispose = player.onQueueChange { queue, idx, reason ->
+      events.add(QueueEvent(queue.toList(), idx.toInt(), reason))
+    }
+    return events to dispose
+  }
+
+  // --- one emission per mutation, with the post-mutation snapshot
+
+  @Test
+  fun `setQueue fires SET_QUEUE with the new queue + resolved index`() {
+    val (events, dispose) = capture()
+    player.setQueueInternal((1..3).map { track("n$it") }, startAtIndex = 1)
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.SET_QUEUE, events[0].reason)
+    assertEquals(3, events[0].queue.size)
+    assertEquals(1, events[0].index)
+  }
+
+  @Test
+  fun `addToQueue fires ADD with the grown queue`() {
+    val (events, dispose) = capture()
+    player.addToQueueInternal(listOf(track("n1")), insertBefore = null)
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.ADD, events[0].reason)
+    assertEquals(6, events[0].queue.size)
+    assertEquals("n1", events[0].queue[5].id)
+  }
+
+  @Test
+  fun `removeFromQueue fires REMOVE with the shrunk queue`() {
+    val (events, dispose) = capture()
+    player.removeFromQueueInternal(listOf(3)) // remove t4; cur=0 pinned
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.REMOVE, events[0].reason)
+    assertEquals(listOf("t1", "t2", "t3", "t5"), events[0].queue.map { it.id })
+  }
+
+  @Test
+  fun `moveInQueue fires MOVE`() {
+    val (events, dispose) = capture()
+    player.moveInQueueInternal(from = 3, to = 1) // cur=0 not moved
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.MOVE, events[0].reason)
+    // t4 (index 3) removed + reinserted at 1 → t1,t4,t2,t3,t5.
+    assertEquals(listOf("t1", "t4", "t2", "t3", "t5"), events[0].queue.map { it.id })
+  }
+
+  @Test
+  fun `clearQueue fires CLEAR with an empty queue + index -1`() {
+    val (events, dispose) = capture()
+    player.clearQueueInternal()
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.CLEAR, events[0].reason)
+    assertEquals(0, events[0].queue.size)
+    assertEquals(-1, events[0].index)
+  }
+
+  @Test
+  fun `shuffleQueue fires SHUFFLE with a full queue at index 0`() {
+    val (events, dispose) = capture()
+    player.shuffleQueueInternal()
+    dispose()
+    assertEquals(1, events.size)
+    assertEquals(QueueChangeReason.SHUFFLE, events[0].reason)
+    assertEquals(5, events[0].queue.size)
+    assertEquals(0, events[0].index)
+  }
+
+  // --- no-op mutations do not fire
+
+  @Test
+  fun `empty addToQueue does not fire`() {
+    val (events, dispose) = capture()
+    player.addToQueueInternal(emptyList(), insertBefore = null)
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `no-op move (from == to) does not fire`() {
+    val (events, dispose) = capture()
+    player.moveInQueueInternal(from = 2, to = 2)
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `out-of-range remove does not fire`() {
+    val (events, dispose) = capture()
+    player.removeFromQueueInternal(listOf(99))
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `clearing an already-empty queue does not fire`() {
+    player.clearQueueInternal() // empties (fires; no listener yet)
+    val (events, dispose) = capture()
+    player.clearQueueInternal() // already empty → no-op
+    dispose()
+    assertTrue(events.isEmpty())
+  }
+
+  @Test
+  fun `unsubscribe stops emissions`() {
+    val (events, dispose) = capture()
+    dispose()
+    player.addToQueueInternal(listOf(track("n1")), insertBefore = null)
+    assertTrue(events.isEmpty())
+  }
+}

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), 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
       ),
       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), context()
     )
   }
 
@@ -318,7 +318,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), context()
     )
   }
 }

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), context()
     )
     player.tracks = (1..5).map { track("t$it") }
     player.currentTrackIndex = 2 // mid-queue default for most cases

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), context()
     )
   }
 

package/ios/AVQueueBuilder.swift

@@ -55,6 +55,35 @@ public enum AVQueueBuilder {
     }
   }
 
+  /// Best-effort warm-up of a freshly-built item's asset BEFORE it is
+  /// inserted into a live `AVQueuePlayer`. When the insert lands in the
+  /// immediate-next slot of a playing queue, `AVQueuePlayer` prerolls the
+  /// new item on the shared decode/render pipeline while the current item
+  /// is still rendering; faulting the asset's `tracks` / `duration` /
+  /// `playable` keys in synchronously at that moment briefly disturbs the
+  /// currently-playing item. Loading them here first makes that preroll
+  /// cheap.
+  ///
+  /// Best-effort: the load races a [timeout] deadline and the caller
+  /// proceeds as soon as either wins. `AVAsset`'s async loader honours
+  /// task cancellation, so `cancelAll` caps a slow / unreachable remote
+  /// asset at [timeout] and the item is inserted unwarmed rather than
+  /// deferring the enqueue. Load errors are ignored for the same reason.
+  @MainActor
+  static func preloadAssetForInsert(_ item: AVPlayerItem, timeout: TimeInterval = 2.0) async {
+    let asset = item.asset
+    await withTaskGroup(of: Void.self) { group in
+      group.addTask { @MainActor in
+        _ = try? await asset.load(.tracks, .duration, .isPlayable)
+      }
+      group.addTask {
+        try? await Task.sleep(nanoseconds: UInt64(timeout * 1_000_000_000))
+      }
+      _ = await group.next()
+      group.cancelAll()
+    }
+  }
+
   /// Single-item builder. Used by addToQueue. Honours the cache
   /// lookup when a cache instance is supplied.
   ///

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

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/QueueState.swift

@@ -23,11 +23,23 @@ internal struct QueueState {
   /// Returns the freshly-generated IDs for the inserted slice.
   mutating func insert(_ newTracks: [TrackItem], at index: Int) -> [String] {
     let newIds = newTracks.map { _ in UUID().uuidString }
-    tracks.insert(contentsOf: newTracks, at: index)
-    queueItemIds.insert(contentsOf: newIds, at: index)
+    insert(newTracks, at: index, ids: newIds)
     return newIds
   }
 
+  /// Insert with caller-supplied IDs — used when the AVPlayerItems were
+  /// built (and their assets preloaded) ahead of the state mutation, so
+  /// the same lib-generated `queueItemId` that was stamped on each item
+  /// stays 1:1 with `queueItemIds`. `ids` must parallel `newTracks`.
+  mutating func insert(_ newTracks: [TrackItem], at index: Int, ids: [String]) {
+    precondition(
+      ids.count == newTracks.count,
+      "QueueState.insert requires ids parallel to newTracks (1:1)"
+    )
+    tracks.insert(contentsOf: newTracks, at: index)
+    queueItemIds.insert(contentsOf: ids, at: index)
+  }
+
   /// Returns the removed `queueItemId`.
   mutating func remove(at index: Int) -> String {
     let removedId = queueItemIds.remove(at: index)