react-native-queue-player 1.0.8 → 1.1.0

package/README.md

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

package/android/src/main/java/com/margelo/nitro/queueplayer/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/QueueSkipArithmetic.kt

@@ -59,9 +59,9 @@ internal object QueueSkipArithmetic {
    * Previous-track index. Same early-bail rules as [computeNext].
    *
    * OFF and TRACK both return null at index 0 (no previous track, no
-   * wrap). Apps that want the Apple-Music-style "tap Previous at
-   * track 0 restarts current" UX implement that in their button
-   * handler.
+   * wrap). The "restart current when past the threshold" model is
+   * available via `PlayerConfig.skipToPreviousBehavior` (resolved by
+   * [resolveSkipToPrevious]).
    */
   fun computePrevious(
     trackCount: Int,
@@ -99,15 +99,62 @@ internal object QueueSkipArithmetic {
    * OFF and TRACK are false at index 0 (no wrap); QUEUE is always
    * true with an active track (wraps).
    *
-   * **Apps that want the Apple-Music-style "tap Previous restarts
-   * when position > 3s" UX** should implement that in their button
-   * handler: read playback position, branch to `seekTo(0)` vs
-   * `skipToPrevious()` themselves. Lib intentionally ships the
-   * primitive (skip if there's a track to skip to), not the policy.
+   * When [restartEnabled] is true (`PlayerConfig.skipToPreviousBehavior
+   * == RESTART_OR_PREVIOUS`), Previous is enabled whenever a track is
+   * loaded — even at index 0, where past the threshold it restarts the
+   * current track — so the control never greys out.
    */
   fun canSkipPrevious(
     trackCount: Int,
     currentIndex: Int,
-    repeatMode: QueueSkipRepeatMode
-  ): Boolean = computePrevious(trackCount, currentIndex, repeatMode) != null
+    repeatMode: QueueSkipRepeatMode,
+    restartEnabled: Boolean = false
+  ): Boolean =
+    if (restartEnabled) trackCount > 0
+    else computePrevious(trackCount, currentIndex, repeatMode) != null
+
+  /**
+   * Position (ms) at or below which a restart-or-previous skip-back goes
+   * to the previous track; past it, the current track restarts. Matches
+   * Media3's default `maxSeekToPreviousPosition` (industry-standard 3 s).
+   */
+  const val RESTART_THRESHOLD_MS: Long = 3000L
+
+  /** What a skip-to-previous should do, resolved from position + behavior. */
+  sealed interface SkipToPreviousAction {
+    /** Navigate to this queue index (a real track change). */
+    data class Previous(val index: Int) : SkipToPreviousAction
+    /** Restart the current track (seek to 0) — not a track change. */
+    object RestartCurrent : SkipToPreviousAction
+    /** Nothing to do (empty queue). */
+    object NoOp : SkipToPreviousAction
+  }
+
+  /**
+   * Resolves a skip-to-previous. When [restartEnabled] is false this is
+   * exactly [computePrevious] (previous track, or nothing). When true it
+   * applies the threshold model, matching Media3 `BasePlayer.seekToPrevious`:
+   * a previous track exists AND `positionMs <= thresholdMs` -> previous;
+   * otherwise (past threshold, or first track with no previous) -> restart
+   * the current track.
+   */
+  fun resolveSkipToPrevious(
+    trackCount: Int,
+    currentIndex: Int,
+    repeatMode: QueueSkipRepeatMode,
+    restartEnabled: Boolean,
+    positionMs: Long,
+    thresholdMs: Long = RESTART_THRESHOLD_MS
+  ): SkipToPreviousAction {
+    if (trackCount <= 0 || currentIndex < 0) return SkipToPreviousAction.NoOp
+    val prev = computePrevious(trackCount, currentIndex, repeatMode)
+    if (!restartEnabled) {
+      return if (prev != null) SkipToPreviousAction.Previous(prev) else SkipToPreviousAction.NoOp
+    }
+    return if (prev != null && positionMs <= thresholdMs) {
+      SkipToPreviousAction.Previous(prev)
+    } else {
+      SkipToPreviousAction.RestartCurrent
+    }
+  }
 }

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

@@ -201,7 +201,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       visualizationEnabled = null,
       clampSeekToBuffered = null,
       lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
-      progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null
+      progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
     )
 
   @Volatile
@@ -880,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
@@ -1480,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)
   }
 
   /**
@@ -1578,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).
@@ -2167,25 +2171,46 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     }
 
   /**
-   * Standard skip-previous: go to the previous track if there is one
-   * (per the arithmetic helper; OFF/TRACK don't wrap, QUEUE wraps).
-   * Under TRACK this navigates like OFF and repeat-one persists. Apps
-   * that want the Apple-Music-style "tap Previous restarts when
-   * position > 3s" UX implement that in their button handler — the
-   * lib provides the primitive (skip if there's a track to skip to),
-   * not the policy.
+   * Skip-previous, resolved by [QueueSkipArithmetic.resolveSkipToPrevious]
+   * from `PlayerConfig.skipToPreviousBehavior`. With the default PREVIOUS this
+   * goes to the previous track if there is one (OFF/TRACK don't wrap, QUEUE
+   * wraps; TRACK navigates like OFF and repeat-one persists). With
+   * RESTART_OR_PREVIOUS it restarts the current track (seek to 0) when past
+   * the threshold, otherwise goes to the previous track.
    */
   @VisibleForTesting
   internal fun skipToPreviousInternal() {
     val p = player ?: return
-    val prev = computePreviousIndex() ?: return
-    currentTrackIndex = prev
-    pendingTrackChangeReason = TrackChangeReason.USER_SKIP_PREVIOUS
-    if (prev < p.mediaItemCount) {
-      serviceBinder?.engine?.seekTo(prev, 0L)
+    val action = QueueSkipArithmetic.resolveSkipToPrevious(
+      trackCount = tracks.size,
+      currentIndex = currentTrackIndex,
+      repeatMode = repeatModeAsSkipMode(),
+      restartEnabled = skipRestartEnabled(),
+      positionMs = serviceBinder?.engine?.currentPositionMs ?: 0L
+    )
+    when (action) {
+      is QueueSkipArithmetic.SkipToPreviousAction.Previous -> {
+        val prev = action.index
+        currentTrackIndex = prev
+        pendingTrackChangeReason = TrackChangeReason.USER_SKIP_PREVIOUS
+        if (prev < p.mediaItemCount) {
+          serviceBinder?.engine?.seekTo(prev, 0L)
+        }
+        rescheduleLookahead()
+        recomputeCapabilities()
+      }
+      QueueSkipArithmetic.SkipToPreviousAction.RestartCurrent -> {
+        // Restart the current track from 0 — a seek, not a track change.
+        // A same-index seek emits no onMediaItemTransition, so no
+        // onTrackChange; leave currentTrackIndex + pendingTrackChangeReason
+        // untouched (stashing a reason no transition consumes would leak
+        // into the next real skip).
+        if (currentTrackIndex in 0 until p.mediaItemCount) {
+          serviceBinder?.engine?.seekTo(currentTrackIndex, 0L)
+        }
+      }
+      QueueSkipArithmetic.SkipToPreviousAction.NoOp -> return
     }
-    rescheduleLookahead()
-    recomputeCapabilities()
   }
 
   /**
@@ -2217,6 +2242,14 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     RepeatMode.QUEUE -> QueueSkipRepeatMode.QUEUE
   }
 
+  /**
+   * Whether skip-to-previous restarts the current track past the threshold
+   * (`PlayerConfig.skipToPreviousBehavior == RESTART_OR_PREVIOUS`). Read live
+   * from the current config at each skip + capability recompute.
+   */
+  private fun skipRestartEnabled(): Boolean =
+    config.skipToPreviousBehavior == SkipToPreviousBehavior.RESTART_OR_PREVIOUS
+
   /**
    * Recompute [cachedSkipCapability] from
    * authoritative state and fire [onSkipCapabilityChange] if either
@@ -2241,7 +2274,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val mode = repeatModeAsSkipMode()
     val count = tracks.size
     val cur = currentTrackIndex
-    val newPrev = QueueSkipArithmetic.canSkipPrevious(count, cur, mode)
+    val newPrev = QueueSkipArithmetic.canSkipPrevious(count, cur, mode, skipRestartEnabled())
     val newNext = QueueSkipArithmetic.canSkipNext(count, cur, mode)
     val current = cachedSkipCapability
     val capChanged =
@@ -2404,7 +2437,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,
@@ -2806,7 +2839,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))

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?
+}