react-native-queue-player 1.0.7 → 1.0.9

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

@@ -57,7 +57,8 @@ object MediaItemBuilder {
   fun buildMediaItems(
     context: Context,
     tracks: List<TrackItem>,
-    lookaheadCache: LookaheadCache? = null
+    lookaheadCache: LookaheadCache? = null,
+    customPlaceholderUri: String? = null
   ): List<MediaItem> {
     return tracks.map { track ->
       val builder = MediaItem.Builder()
@@ -68,7 +69,7 @@ object MediaItemBuilder {
         // Media3's documented default when track.id is omitted.
         .setMediaId(track.id ?: "")
         .setUri(Uri.parse(track.url))
-        .setMediaMetadata(buildMetadata(context, track))
+        .setMediaMetadata(buildMetadata(context, track, customPlaceholderUri))
       val mime = resolveMimeTypeForBuild(track.url, lookaheadCache)
       if (mime != null) builder.setMimeType(mime)
       builder.build()
@@ -86,13 +87,26 @@ object MediaItemBuilder {
    * so Media3's BitmapLoader resolves it once per process rather than
    * cloning a byte[] into every MediaMetadata.
    */
-  private fun buildMetadata(context: Context, track: TrackItem): MediaMetadata {
+  private fun buildMetadata(
+    context: Context,
+    track: TrackItem,
+    customPlaceholderUri: String?
+  ): MediaMetadata {
     val builder = MediaMetadata.Builder()
       .setTitle(track.title.orEmpty())
       .setArtist(track.artist.orEmpty())
       .setAlbumTitle(track.album.orEmpty())
 
     val artworkUrl = track.artworkUrl?.trim()
+    // Only a local `file://` placeholder is honoured (the built-in is a
+    // local file; a remote URL would break offline + change behaviour).
+    // Scheme match is case-insensitive to mirror iOS's `URL.isFileURL`;
+    // normalize to a lowercase `file` scheme so the case-sensitive
+    // `content://` rewrite below applies to an uppercase `FILE://` too.
+    val customFileUri = customPlaceholderUri
+      ?.let { Uri.parse(it) }
+      ?.takeIf { it.scheme.equals("file", ignoreCase = true) }
+      ?.buildUpon()?.scheme("file")?.build()
     val artworkUri = if (!artworkUrl.isNullOrEmpty()) {
       // Rewrite private `file://` paths through the lib's exported
       // `ArtworkContentProvider` so cross-process controllers (Android
@@ -100,6 +114,10 @@ object MediaItemBuilder {
       // their own process. `http(s)://` and `content://` URIs pass
       // through unchanged.
       ArtworkContentProvider.mapFileUri(Uri.parse(artworkUrl))
+    } else if (customFileUri != null) {
+      // Consumer-supplied placeholder in place of the built-in — same
+      // cross-process file-URI rewrite as the real-art branch.
+      ArtworkContentProvider.mapFileUri(customFileUri)
     } else {
       placeholderArtworkUri(context)
     }

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

@@ -3,6 +3,7 @@ package com.margelo.nitro.queueplayer
 import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.BitmapFactory
+import android.net.Uri
 
 /**
  * Bundled fallback artwork used by the MediaSession + notification
@@ -26,8 +27,10 @@ internal object PlaceholderArtwork {
    * to call from any thread (the bitmap is immutable once decoded).
    */
   fun bitmap(context: Context): Bitmap {
+    customBitmap?.let { return it }
     cached?.let { return it }
     synchronized(this) {
+      customBitmap?.let { return it }
       cached?.let { return it }
       val decoded = decode(context)
       cached = decoded
@@ -35,6 +38,32 @@ internal object PlaceholderArtwork {
     }
   }
 
+  /**
+   * Set (or clear) the consumer-supplied placeholder from
+   * `PlayerConfig.placeholderArtworkUri`. Decoded once from the local
+   * `file://` path via `BitmapFactory.decodeFile` (scheme match is
+   * case-insensitive); a non-`file://` URI, an unset URI, or a decode
+   * failure leaves the bundled placeholder as the floor. Decode is
+   * synchronous, so a very large consumer image briefly blocks the
+   * `configure` call. Called from configure.
+   */
+  fun setCustom(uri: String?) {
+    synchronized(this) {
+      // Local file:// only — remote URLs would break offline + change
+      // behaviour, so anything else leaves the built-in as the floor.
+      customBitmap = uri
+        ?.takeIf { Uri.parse(it).scheme.equals("file", ignoreCase = true) }
+        ?.let { decodeUri(it) }
+    }
+  }
+
+  private fun decodeUri(uri: String): Bitmap? =
+    try {
+      Uri.parse(uri).path?.let { BitmapFactory.decodeFile(it) }
+    } catch (e: Exception) {
+      null
+    }
+
   /**
    * Returns the placeholder bytes (raw JPEG payload). Useful for
    * paths that want to write the bytes into a `MediaMetadata`
@@ -53,6 +82,7 @@ internal object PlaceholderArtwork {
 
   @Volatile private var cached: Bitmap? = null
   @Volatile private var cachedBytes: ByteArray? = null
+  @Volatile private var customBitmap: Bitmap? = null
 
   private fun decode(context: Context): Bitmap {
     val stream = context.resources.openRawResource(R.raw.rnqp_placeholder)

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

@@ -37,7 +37,10 @@ import com.google.common.util.concurrent.MoreExecutors
 @UnstableApi
 internal class PlaceholderFallbackBitmapLoader(
   private val delegate: BitmapLoader,
-  private val placeholder: Bitmap,
+  // Read on each fallback (not captured at construction) so a placeholder
+  // swapped at `configure` — after the session/loader was built in
+  // `onCreate` — is reflected without rebuilding the loader.
+  private val placeholder: () -> Bitmap,
 ) : BitmapLoader {
 
   override fun supportsMimeType(mimeType: String): Boolean =
@@ -47,7 +50,7 @@ internal class PlaceholderFallbackBitmapLoader(
     Futures.catching(
       delegate.decodeBitmap(data),
       Throwable::class.java,
-      { placeholder },
+      { placeholder() },
       MoreExecutors.directExecutor(),
     )
 
@@ -55,20 +58,20 @@ internal class PlaceholderFallbackBitmapLoader(
     Futures.catching(
       delegate.loadBitmap(uri),
       Throwable::class.java,
-      { placeholder },
+      { placeholder() },
       MoreExecutors.directExecutor(),
     )
 
   override fun loadBitmapFromMetadata(metadata: MediaMetadata): ListenableFuture<Bitmap>? {
     if (metadata.artworkUri == null && metadata.artworkData == null) {
-      return Futures.immediateFuture(placeholder)
+      return Futures.immediateFuture(placeholder())
     }
     val delegated = delegate.loadBitmapFromMetadata(metadata)
-      ?: return Futures.immediateFuture(placeholder)
+      ?: return Futures.immediateFuture(placeholder())
     return Futures.catching(
       delegated,
       Throwable::class.java,
-      { placeholder },
+      { placeholder() },
       MoreExecutors.directExecutor(),
     )
   }

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

@@ -777,7 +777,10 @@ class PlaybackService : HeadlessJsMediaService() {
   internal fun buildBitmapLoader(): PlaceholderFallbackBitmapLoader =
     PlaceholderFallbackBitmapLoader(
       delegate = CacheBitmapLoader(DataSourceBitmapLoader.Builder(this).build()),
-      placeholder = PlaceholderArtwork.bitmap(this),
+      // 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.
+      placeholder = { PlaceholderArtwork.bitmap(applicationContext) },
     )
 
   /**

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
+      progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null
     )
 
   @Volatile
@@ -544,6 +544,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   // simultaneously without clobbering each other.
   private val stateChangeListeners = ListenerRegistry<(PlayerState, StateChangeReason) -> Unit>()
   private val trackChangeListeners = ListenerRegistry<(TrackItem?, Double, TrackChangeReason, Double?) -> Unit>()
+  private val queueChangeListeners = ListenerRegistry<(Array<TrackItem>, Double, QueueChangeReason) -> Unit>()
   private val progressListeners = ListenerRegistry<(PlayerProgress) -> Unit>()
   // Buffer state — discrete empty/buffering/stalled/full for the active track, derived
   // from Media3's playback state + buffered-ahead. Recomputed on the engine
@@ -879,6 +880,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // shared instance is released and its directory deleted below.
     val previousEvictionPolicy = evictionPolicyFrom(this.config)
     this.config = newConfig
+    // Swap the cover-art placeholder bitmap to the consumer-supplied image
+    // (or back to the built-in when unset). The no-art metadata URI is
+    // threaded separately at each buildMediaItems call.
+    PlaceholderArtwork.setCustom(newConfig.placeholderArtworkUri)
     if (evictionPolicyFrom(newConfig) != previousEvictionPolicy) {
       lookaheadCacheWriter?.release()
       lookaheadCacheWriter = null
@@ -1445,6 +1450,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(newTracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    emitQueueChange(QueueChangeReason.SET_QUEUE)
   }
 
   /**
@@ -1478,7 +1484,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining =
       (newTracks.indices.associateWith { attempts }).toMutableMap()
-    return MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache)
+    return MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache, config.placeholderArtworkUri)
   }
 
   /**
@@ -1503,6 +1509,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(newTracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    emitQueueChange(QueueChangeReason.SET_QUEUE)
     return items
   }
 
@@ -1575,7 +1582,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     for (newIdx in at until at + shift) {
       retryAttemptsRemaining[newIdx] = attempts
     }
-    val items = MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache)
+    val items = MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache, config.placeholderArtworkUri)
     serviceBinder?.engine?.addMediaItems(items, insertBefore = at)
     // Diverges from iOS: add-into-empty-queue on iOS leaves the
     // AVQueuePlayer empty until the consumer calls skipToIndex(0).
@@ -1595,6 +1602,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(this.tracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    emitQueueChange(QueueChangeReason.ADD)
     return at
   }
 
@@ -1688,6 +1696,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(this.tracks))
     rescheduleLookahead()
     recomputeCapabilities()
+    // Reached only past the `sanitised.isEmpty()` guard, so ≥1 track was
+    // removed; tracks + index are final.
+    emitQueueChange(QueueChangeReason.REMOVE)
     return sanitised
   }
 
@@ -1753,6 +1764,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     for (i in this.tracks.indices) retryAttemptsRemaining[i] = attempts
     rescheduleLookahead()
     recomputeCapabilities()
+    // Reached only past the invalid / `from == to` / pinned-current
+    // guards, so the order actually changed.
+    emitQueueChange(QueueChangeReason.MOVE)
     return true
   }
 
@@ -1771,6 +1785,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   @VisibleForTesting
   internal fun clearQueueInternal() {
     val p = player ?: return
+    val queueWasNonEmpty = tracks.isNotEmpty()
     // Reset authoritative state BEFORE the ExoPlayer mutation.
     // `clearMediaItems()` fires `onMediaItemTransition(null,
     // REASON_PLAYLIST_CHANGED)` synchronously, which routes through
@@ -1788,6 +1803,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     retryAttemptsRemaining.clear()
     tracks = emptyList()
     currentTrackIndex = -1
+    // Fire queue-change BEFORE setMediaItems (which synchronously fires
+    // onTrackChange via onMediaItemTransition) so a `useQueue()` consumer
+    // sees the empty queue + index -1 together. Only when the queue was
+    // actually non-empty — clearing an empty queue is a no-op.
+    if (queueWasNonEmpty) emitQueueChange(QueueChangeReason.CLEAR)
     // Route through the engine surface (not directly through the
     // leading leg) so CrossfadeEngine can also tear down the
     // standby leg's preroll'd items + cancel any in-flight fade.
@@ -2388,7 +2408,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // playback continues from the current track / position. The
     // post-swap engine starts empty by construction.
     if (resumeIndex >= 0 && resumeIndex < tracks.count()) {
-      val media = MediaItemBuilder.buildMediaItems(service, tracks, lookaheadCache)
+      val media = MediaItemBuilder.buildMediaItems(service, tracks, lookaheadCache, config.placeholderArtworkUri)
       newEngine.setMediaItems(
         items = media,
         startIndex = resumeIndex,
@@ -2790,7 +2810,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     retryAttemptsRemaining.clear()
     for (i in newTracks.indices) retryAttemptsRemaining[i] = attempts
 
-    val items = MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache)
+    val items = MediaItemBuilder.buildMediaItems(ctx, newTracks, lookaheadCache, config.placeholderArtworkUri)
     serviceBinder?.engine?.setMediaItems(items, startIndex = 0, startPositionMs = 0L)
     p.prepare()
     serviceBinder?.engine?.setWakeMode(pickWakeMode(newTracks))
@@ -2802,6 +2822,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
     rescheduleLookahead()
     recomputeCapabilities()
+    // Skip a single-track shuffle — the order can't change.
+    if (newTracks.size > 1) emitQueueChange(QueueChangeReason.SHUFFLE)
 
     return ShuffleResult(
       tracks = newTracks.toTypedArray(),
@@ -2892,6 +2914,27 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     return { trackChangeListeners.remove(id) }
   }
 
+  override fun onQueueChange(
+    callback: (queue: Array<TrackItem>, currentIndex: Double, reason: QueueChangeReason) -> Unit
+  ): () -> Unit {
+    val id = queueChangeListeners.add(callback)
+    return { queueChangeListeners.remove(id) }
+  }
+
+  /**
+   * Fire onQueueChange with an atomic snapshot of the post-mutation
+   * queue + current index. Main-thread only — every queue mutation
+   * commits on main, so [tracks] / [currentTrackIndex] are settled here.
+   * Callers gate this on an actual content/order change so a no-op
+   * mutation never emits.
+   */
+  @MainThread
+  private fun emitQueueChange(reason: QueueChangeReason) {
+    val snapshot = tracks.toTypedArray()
+    val index = currentTrackIndex.toDouble()
+    queueChangeListeners.forEach { it(snapshot, index, reason) }
+  }
+
   override fun onProgress(
     callback: (progress: PlayerProgress) -> Unit
   ): () -> Unit {

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

@@ -1,6 +1,7 @@
 package com.margelo.nitro.queueplayer
 
 import android.content.Context
+import android.net.Uri
 import androidx.media3.common.C
 import androidx.media3.common.MediaMetadata
 import androidx.media3.common.util.UnstableApi
@@ -277,6 +278,60 @@ class MediaItemBuilderTest {
     assertEquals(expected, metadata.artworkUri?.toString())
   }
 
+  @Test
+  fun `MediaMetadata uses the custom placeholder URI when artworkUrl is null and a file URI is configured`() {
+    val customUri = "file:///data/user/0/com.example/files/logo.png"
+    val metadata = MediaItemBuilder.buildMediaItems(
+      context,
+      listOf(makeTrack(id = "t", url = "https://example.com/s.mp3")),
+      customPlaceholderUri = customUri
+    )[0].mediaMetadata
+    val expected = ArtworkContentProvider.mapFileUri(Uri.parse(customUri)).toString()
+    assertEquals(expected, metadata.artworkUri?.toString())
+  }
+
+  @Test
+  fun `MediaMetadata ignores a non-file custom placeholder URI and uses the built-in`() {
+    val metadata = MediaItemBuilder.buildMediaItems(
+      context,
+      listOf(makeTrack(id = "t", url = "https://example.com/s.mp3")),
+      customPlaceholderUri = "https://example.com/logo.png"
+    )[0].mediaMetadata
+    val expected =
+      "android.resource://${context.packageName}/${R.raw.rnqp_placeholder}"
+    assertEquals(expected, metadata.artworkUri?.toString())
+  }
+
+  @Test
+  fun `MediaMetadata prefers the real artworkUrl over a configured custom placeholder`() {
+    val metadata = MediaItemBuilder.buildMediaItems(
+      context,
+      listOf(
+        makeTrack(
+          id = "t",
+          url = "https://example.com/s.mp3",
+          artworkUrl = "https://example.com/cover.jpg"
+        )
+      ),
+      customPlaceholderUri = "file:///data/user/0/com.example/files/logo.png"
+    )[0].mediaMetadata
+    assertEquals("https://example.com/cover.jpg", metadata.artworkUri?.toString())
+  }
+
+  @Test
+  fun `MediaMetadata normalizes an uppercase FILE scheme custom placeholder to lowercase file`() {
+    val customUri = "FILE:///data/user/0/com.example/files/logo.png"
+    val metadata = MediaItemBuilder.buildMediaItems(
+      context,
+      listOf(makeTrack(id = "t", url = "https://example.com/s.mp3")),
+      customPlaceholderUri = customUri
+    )[0].mediaMetadata
+    val normalized = Uri.parse(customUri).buildUpon().scheme("file").build()
+    val expected = ArtworkContentProvider.mapFileUri(normalized).toString()
+    assertEquals(expected, metadata.artworkUri?.toString())
+    assertEquals("file", metadata.artworkUri?.scheme)
+  }
+
   @Test
   fun `MediaMetadata sets durationMs from positive seconds`() {
     val track = makeTrack(

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

@@ -0,0 +1,72 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import android.graphics.Bitmap
+import androidx.test.core.app.ApplicationProvider
+import org.junit.After
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertSame
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Coverage for [PlaceholderArtwork.setCustom] — the consumer-supplied
+ * cover-art placeholder from `PlayerConfig.placeholderArtworkUri`. Only a
+ * local `file://` URI is honoured; a remote or unset URI leaves the
+ * bundled placeholder as the floor.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class PlaceholderArtworkTest {
+
+  private val context: Context
+    get() = ApplicationProvider.getApplicationContext()
+
+  @After
+  fun tearDown() {
+    // Process-wide singleton — reset so a set custom bitmap does not
+    // leak into other suites that read the built-in placeholder.
+    PlaceholderArtwork.setCustom(null)
+  }
+
+  @Test
+  fun `setCustom with a file URI installs a custom bitmap that bitmap returns`() {
+    PlaceholderArtwork.setCustom("file:///data/user/0/com.example/files/logo.png")
+    val custom = customBitmap()
+    assertNotNull(custom)
+    assertSame(custom, PlaceholderArtwork.bitmap(context))
+  }
+
+  @Test
+  fun `setCustom ignores a non-file URI and leaves the built-in placeholder`() {
+    PlaceholderArtwork.setCustom("https://example.com/logo.png")
+    assertNull(customBitmap())
+  }
+
+  @Test
+  fun `setCustom ignores an empty string and leaves the built-in placeholder`() {
+    PlaceholderArtwork.setCustom("")
+    assertNull(customBitmap())
+  }
+
+  @Test
+  fun `setCustom accepts an uppercase FILE scheme (case-insensitive)`() {
+    PlaceholderArtwork.setCustom("FILE:///data/user/0/com.example/files/logo.png")
+    assertNotNull(customBitmap())
+  }
+
+  @Test
+  fun `setCustom with null clears a previously-installed custom bitmap`() {
+    PlaceholderArtwork.setCustom("file:///data/user/0/com.example/files/logo.png")
+    PlaceholderArtwork.setCustom(null)
+    assertNull(customBitmap())
+  }
+
+  private fun customBitmap(): Bitmap? =
+    PlaceholderArtwork.javaClass.getDeclaredField("customBitmap")
+      .apply { isAccessible = true }
+      .get(PlaceholderArtwork) as Bitmap?
+}

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

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,
       ),
       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), 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), 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), 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), context()
     )
     // No listener is bound to the new ExoPlayer's actual STATE_ENDED
     // path in a Robolectric test, but the callback slot itself is