react-native-queue-player 1.0.0

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

@@ -0,0 +1,166 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.annotation.MainThread
+import androidx.media3.common.C
+import androidx.media3.common.Format
+import androidx.media3.common.Player
+import androidx.media3.common.Tracks
+import androidx.media3.common.util.UnstableApi
+import com.margelo.nitro.core.NullType
+
+/**
+ * Resolves the active item's runtime audio format from a Media3 [Player].
+ * Pure object — no shared state. Caller owns invocation cadence + emit
+ * dedup.
+ *
+ * Codec maps from `Format.sampleMimeType`; container maps from
+ * `Format.containerMimeType`, with a URL-extension fallback for path-only
+ * MediaItems whose container MIME isn't populated by the demuxer. Each
+ * field falls back to its `null` sentinel when Media3 hasn't determined
+ * it (`Format.NO_VALUE`).
+ *
+ * The optional `engine` parameter surfaces the four ReplayGain data
+ * fields + `replayGainActive` from the engine's per-leg cached
+ * [ReplayGainData]. When `engine` is null (off-engine call paths,
+ * tests that don't construct an engine) all four data fields surface
+ * null and `replayGainActive` is false.
+ */
+@UnstableApi
+internal object NowPlayingFormatExtractor {
+
+  /**
+   * Extract the format snapshot from `player`'s currently selected
+   * audio track. Returns `null` only when no audio track exists in the
+   * timeline; otherwise every field is best-effort with per-field null
+   * fallback.
+   *
+   * `engine` is the currently-active [PlaybackEngine]. When non-null
+   * the extractor reads ReplayGain data + active flag from the
+   * engine's per-leg cache (see [GaplessEngine.currentReplayGainData]
+   * / [CrossfadeEngine.currentReplayGainData]).
+   */
+  @MainThread
+  fun extract(player: Player, engine: PlaybackEngine? = null): NowPlayingFormat? {
+    val (group, trackIndex) = pickAudioTrack(player.currentTracks) ?: return null
+    val format = group.getTrackFormat(trackIndex)
+    val codec = mapCodec(format.sampleMimeType)
+    val urlExtension = player.currentMediaItem
+      ?.localConfiguration?.uri?.toString()
+      ?.substringAfterLast('.', missingDelimiterValue = "")
+      ?.lowercase()
+      ?.takeIf { it.isNotEmpty() }
+    val container = mapContainer(format, urlExtension)
+    val mimeType = format.sampleMimeType
+    val sampleRate = format.sampleRate.takeIf { it != Format.NO_VALUE }?.toDouble()
+    val channelCount = format.channelCount.takeIf { it != Format.NO_VALUE }?.toDouble()
+    val bitrate = format.bitrate.takeIf { it != Format.NO_VALUE }?.toDouble()
+    val peakBitrate = format.peakBitrate.takeIf { it != Format.NO_VALUE }?.toDouble()
+    val pcmEncoding = format.pcmEncoding.takeIf { it != Format.NO_VALUE }?.toDouble()
+    val codecsString = format.codecs
+    val durationMs = player.duration
+    val durationSec = if (durationMs == C.TIME_UNSET || durationMs <= 0) null
+                      else durationMs / 1000.0
+
+    val rgData = engine?.currentReplayGainData()
+    val rgActive = engine?.currentReplayGainActive() ?: false
+
+    return NowPlayingFormat(
+      codec = codec,
+      container = container,
+      mimeType = stringOrNullVariant(mimeType),
+      sampleRate = doubleOrNullVariant(sampleRate),
+      channelCount = doubleOrNullVariant(channelCount),
+      bitrate = doubleOrNullVariant(bitrate),
+      durationSec = doubleOrNullVariant(durationSec),
+      replayGainTrackDb = doubleOrNullVariant(rgData?.trackGainDb?.toDouble()),
+      replayGainTrackPeak = doubleOrNullVariant(rgData?.trackPeak?.toDouble()),
+      replayGainAlbumDb = doubleOrNullVariant(rgData?.albumGainDb?.toDouble()),
+      replayGainAlbumPeak = doubleOrNullVariant(rgData?.albumPeak?.toDouble()),
+      replayGainActive = rgActive,
+      ios = null,
+      android = NowPlayingFormatAndroidExtras(
+        peakBitrate = doubleOrNullVariant(peakBitrate),
+        codecs = stringOrNullVariant(codecsString),
+        pcmEncoding = doubleOrNullVariant(pcmEncoding)
+      )
+    )
+  }
+
+  private fun pickAudioTrack(tracks: Tracks): Pair<Tracks.Group, Int>? {
+    var firstAudioMatch: Pair<Tracks.Group, Int>? = null
+    for (group in tracks.groups) {
+      if (group.type != C.TRACK_TYPE_AUDIO) continue
+      val mediaGroup = group.mediaTrackGroup
+      for (i in 0 until mediaGroup.length) {
+        if (firstAudioMatch == null) firstAudioMatch = group to i
+        if (group.isTrackSelected(i)) return group to i
+      }
+    }
+    return firstAudioMatch
+  }
+
+  internal fun mapCodec(mime: String?): AudioCodec {
+    if (mime == null) return AudioCodec.UNKNOWN
+    // Compare against lowercase string literals so the matcher tolerates
+    // case variation in upstream MimeTypes constants (Media3 names some
+    // constants like `audio/mpeg-L1` with mixed case).
+    return when (mime.lowercase()) {
+      "audio/aac", "audio/mp4a-latm" -> AudioCodec.AAC
+      "audio/mpeg", "audio/mpeg-l1", "audio/mpeg-l2" -> AudioCodec.MP3
+      "audio/flac", "audio/x-flac" -> AudioCodec.FLAC
+      "audio/alac" -> AudioCodec.ALAC
+      "audio/opus" -> AudioCodec.OPUS
+      "audio/raw", "audio/wav", "audio/wave", "audio/x-wav" -> AudioCodec.PCM
+      else -> AudioCodec.UNKNOWN
+    }
+  }
+
+  internal fun mapContainer(
+    format: Format,
+    urlExtension: String? = null
+  ): AudioContainer {
+    val container = format.containerMimeType?.lowercase()
+    when (container) {
+      "application/x-mpegurl", "application/vnd.apple.mpegurl" -> return AudioContainer.HLS
+      "audio/mpeg" -> return AudioContainer.MP3
+      "audio/mp4", "video/mp4" -> return AudioContainer.MP4
+      "audio/flac", "audio/x-flac" -> return AudioContainer.FLAC
+      "audio/ogg", "application/ogg" -> return AudioContainer.OGG
+      "audio/wav", "audio/wave", "audio/x-wav" -> return AudioContainer.WAV
+      "audio/aac" -> return AudioContainer.AAC_ADTS
+      else -> {}
+    }
+    // Container MIME may be null for path-only MediaItems (the demuxer
+    // sets sampleMimeType reliably but not containerMimeType). Prefer
+    // the URL extension when available — distinguishes AAC-in-MP4
+    // (`.m4a`) from AAC-in-ADTS (`.aac`) where the codec alone can't.
+    when (urlExtension) {
+      "mp3" -> return AudioContainer.MP3
+      "m4a", "m4b", "m4r", "mp4" -> return AudioContainer.MP4
+      "flac" -> return AudioContainer.FLAC
+      "ogg", "opus" -> return AudioContainer.OGG
+      "wav", "wave" -> return AudioContainer.WAV
+      "aac" -> return AudioContainer.AAC_ADTS
+      "m3u8" -> return AudioContainer.HLS
+      else -> {}
+    }
+    // Final fallback: codec → most-common container.
+    return when (mapCodec(format.sampleMimeType)) {
+      AudioCodec.AAC -> AudioContainer.MP4
+      AudioCodec.MP3 -> AudioContainer.MP3
+      AudioCodec.FLAC -> AudioContainer.FLAC
+      AudioCodec.ALAC -> AudioContainer.MP4
+      AudioCodec.OPUS -> AudioContainer.OGG
+      AudioCodec.PCM -> AudioContainer.WAV
+      AudioCodec.UNKNOWN -> AudioContainer.UNKNOWN
+    }
+  }
+
+  private fun stringOrNullVariant(s: String?): Variant_NullType_String =
+    if (s == null) Variant_NullType_String.create(NullType.NULL)
+    else Variant_NullType_String.create(s)
+
+  private fun doubleOrNullVariant(d: Double?): Variant_NullType_Double =
+    if (d == null) Variant_NullType_Double.create(NullType.NULL)
+    else Variant_NullType_Double.create(d)
+}

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

@@ -0,0 +1,70 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Native-side queue of `parentId`s a controller asked the
+ * MediaLibrarySession to enumerate before the consumer's JS bridge
+ * had pushed a [BrowseSnapshot] into [BrowseDataProvider]. The empty
+ * `onGetChildren` response is the "still loading" UX hint to the
+ * controller; once a snapshot lands, [PlaybackService] drains the
+ * queue and fires `notifyChildrenChanged` for each pending parent
+ * so the controller re-fetches with real data.
+ *
+ * The cold-start race the queue closes:
+ *
+ *  1. Android Auto / Google Assistant binds to [PlaybackService]
+ *     before any Activity has booted React.
+ *  2. The session's `onConnect` triggers
+ *     [PlaybackService.selfWakeForHeadlessClient] which spawns the
+ *     JS task — but the bridge boot + bundle evaluation +
+ *     `registerPlaybackService` call take ~1-3 s.
+ *  3. Mid-boot the controller calls `getChildren(rootId)`.
+ *     [BrowseDataProvider.getSnapshot] returns `null` because no JS
+ *     consumer has called `setBrowseSnapshot` yet.
+ *  4. Without this queue, the callback would return
+ *     `RESULT_ERROR_NOT_SUPPORTED` and the controller would display
+ *     a hard error. With this queue, the callback returns an empty
+ *     list (controller paints a skeleton) and registers the parent
+ *     for replay once the snapshot lands.
+ *
+ * Threading: every method is safe to call from any thread —
+ * [AtomicReference] guards the underlying set.
+ */
+@UnstableApi
+internal class PendingBrowseRequests {
+
+  private val cell = AtomicReference<Set<String>>(emptySet())
+
+  /**
+   * Record [parentId] as a pending request. Idempotent — duplicate
+   * enqueues collapse, so a single [drainAll] yields one
+   * `notifyChildrenChanged` per unique parent regardless of how many
+   * controllers asked for it before the snapshot landed.
+   */
+  fun enqueue(parentId: String) {
+    while (true) {
+      val current = cell.get()
+      if (parentId in current) return
+      val next = current + parentId
+      if (cell.compareAndSet(current, next)) return
+    }
+  }
+
+  /** Atomically take + clear the pending set. Subsequent calls return
+   *  empty until the next [enqueue]. */
+  fun drainAll(): Set<String> = cell.getAndSet(emptySet())
+
+  /** Discard every pending entry without firing any notification.
+   *  Invoked from [PlaybackService.onDestroy] so a service teardown
+   *  during a cold-start stall doesn't strand a stale entry across
+   *  the next service spin-up. */
+  fun clear() {
+    cell.set(emptySet())
+  }
+
+  /** Snapshot the pending parents without consuming. Mainly for
+   *  tests — production code drains via [drainAll]. */
+  internal fun snapshotForTest(): Set<String> = cell.get()
+}

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

@@ -0,0 +1,82 @@
+package com.margelo.nitro.queueplayer
+
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Single-slot buffer for a voice intent that arrived before the JS
+ * resolver had registered. Holds at most one request per instance; a
+ * subsequent [push] replaces any prior entry (latest-wins).
+ *
+ * Entries carry a `bufferedAtMillis` timestamp and expire after
+ * [ttlMillis]. Expired entries are dropped on the next [peek] /
+ * [drain] without producing a result, so a stale cold-launch intent
+ * never reaches a JS resolver that registers minutes later.
+ *
+ * Cross-platform parity primitive: iOS's `CarPlayBridge` holds an
+ * analogous `PendingIntentBuffer` for `INPlayMediaIntent` cold-start
+ * dispatches because Swift Concurrency lacks Kotlin's
+ * `MutableStateFlow.filterNotNull().first()` suspend-until-non-null
+ * pattern. On Android the lib's existing `BrowseCallbackRegistry`
+ * slots + `PlaybackService.dispatchAssistantPlay` already provide the
+ * same cold-start-race coverage via coroutine suspension, so this
+ * class is a reusable primitive without a load-bearing Android call
+ * site today. Kept for symmetry + future single-flight use cases.
+ *
+ * Thread-safety: every method is safe to call from any thread —
+ * [AtomicReference] guards the slot via CAS.
+ *
+ * Clock contract: callers must supply a monotonically non-decreasing
+ * clock. Negative-skew elapsed values are clamped to zero so a
+ * backwards-moving clock can't extend an entry's effective TTL.
+ */
+internal class PendingIntentBuffer<Request : Any>(
+  private val ttlMillis: Long = 20_000L,
+  private val clock: () -> Long = System::currentTimeMillis,
+) {
+
+  private data class Entry<Request : Any>(val request: Request, val bufferedAtMillis: Long)
+
+  private val cell = AtomicReference<Entry<Request>?>(null)
+
+  /** Store [request], replacing any prior entry. */
+  fun push(request: Request) {
+    cell.set(Entry(request, clock()))
+  }
+
+  /**
+   * Remove and return the buffered request, or `null` if empty or
+   * expired. Drains the slot in both cases — an expired entry is not
+   * retained for a later non-expired read.
+   */
+  fun drain(): Request? {
+    val current = cell.getAndSet(null) ?: return null
+    val elapsed = (clock() - current.bufferedAtMillis).coerceAtLeast(0L)
+    if (elapsed > ttlMillis) return null
+    return current.request
+  }
+
+  /**
+   * Inspect the buffered request without removing it. Auto-clears an
+   * expired entry as a side effect so a stale request can't be
+   * inspected indefinitely.
+   */
+  fun peek(): Request? {
+    while (true) {
+      val current = cell.get() ?: return null
+      val elapsed = (clock() - current.bufferedAtMillis).coerceAtLeast(0L)
+      if (elapsed > ttlMillis) {
+        if (cell.compareAndSet(current, null)) return null
+        continue
+      }
+      return current.request
+    }
+  }
+
+  /** Drop any buffered request without returning it. */
+  fun clear() {
+    cell.set(null)
+  }
+
+  /** True when the slot is empty (or holds only an expired entry). */
+  fun isEmpty(): Boolean = peek() == null
+}

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

@@ -0,0 +1,69 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.PlaybackParameters
+import androidx.media3.common.audio.AudioProcessor
+import androidx.media3.common.audio.AudioProcessorChain
+import androidx.media3.common.audio.SonicAudioProcessor
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * Custom [AudioProcessorChain] that gates the pitch-correction time-stretch on
+ * the active [PitchCorrectionMode]. It holds BOTH Media3's built-in
+ * [SonicAudioProcessor] (none/voice) and the [SignalsmithStretchAudioProcessor]
+ * (music) in one chain, so switching modes at runtime never rebuilds the sink.
+ * Exactly one stretcher is ever active: the owning engine pushes the mode via
+ * [setMode], and [applyPlaybackParameters] routes the speed to the matching one
+ * and neutralizes the other (speed == 1 ⇒ inactive). none/voice are
+ * indistinguishable in [PlaybackParameters] alone, which is why the mode is
+ * pushed explicitly rather than inferred.
+ *
+ * Supplied to `DefaultAudioSink.Builder.setAudioProcessorChain`, which — unlike
+ * `setAudioProcessors` — does NOT auto-append Sonic + silence-skipping. This
+ * chain owns the full composition: [preProcessors] (ReplayGain, visualizer Tee)
+ * run first, then the two stretchers. Silence-skipping is intentionally absent
+ * (unused on this path), so [applySkipSilenceEnabled] returns false.
+ */
+@UnstableApi
+internal class PitchAwareAudioProcessorChain(
+  preProcessors: Array<AudioProcessor>,
+) : AudioProcessorChain {
+
+  private val sonic = SonicAudioProcessor()
+  private val signalsmith = SignalsmithStretchAudioProcessor()
+  private val processors: Array<AudioProcessor> =
+    preProcessors + arrayOf<AudioProcessor>(sonic, signalsmith)
+
+  @Volatile
+  private var mode: PitchCorrectionMode = PitchCorrectionMode.VOICE
+
+  fun setMode(value: PitchCorrectionMode) {
+    mode = value
+  }
+
+  override fun getAudioProcessors(): Array<AudioProcessor> = processors
+
+  override fun applyPlaybackParameters(playbackParameters: PlaybackParameters): PlaybackParameters {
+    if (mode == PitchCorrectionMode.MUSIC) {
+      // Signalsmith does the music-grade stretch; Sonic neutralized.
+      signalsmith.setSpeed(playbackParameters.speed)
+      sonic.setSpeed(1f)
+      sonic.setPitch(1f)
+    } else {
+      // none/voice → Sonic applies speed (+ pitch); Signalsmith idle.
+      sonic.setSpeed(playbackParameters.speed)
+      sonic.setPitch(playbackParameters.pitch)
+      signalsmith.setSpeed(1f)
+    }
+    return playbackParameters
+  }
+
+  override fun applySkipSilenceEnabled(skipSilenceEnabled: Boolean): Boolean = false
+
+  override fun getMediaDuration(playoutDuration: Long): Long = when {
+    signalsmith.isStretching() -> signalsmith.getMediaDuration(playoutDuration)
+    sonic.isActive -> sonic.getMediaDuration(playoutDuration)
+    else -> playoutDuration
+  }
+
+  override fun getSkippedOutputFrameCount(): Long = 0L
+}

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

@@ -0,0 +1,27 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.PlaybackParameters
+
+/**
+ * Maps the public [PitchCorrectionMode] to Media3 [PlaybackParameters].
+ *
+ * - `none` → pitch follows rate (`pitch == speed`): Media3's built-in
+ *   time-stretch resamples, so pitch shifts with speed.
+ * - `voice` → pitch preserved (`pitch == 1`): the built-in (speech-tuned)
+ *   time-stretch holds pitch while changing speed.
+ * - `music` → currently the same pitch-preserving path as `voice`; a
+ *   dedicated music-grade engine is a separate effort.
+ *
+ * At `speed == 1.0` every mode yields `(1.0, 1.0)`, so the built-in
+ * stretch is inactive — the auto-bypass at unity rate.
+ */
+internal object PitchCorrection {
+  fun playbackParameters(mode: PitchCorrectionMode, speed: Float): PlaybackParameters {
+    val pitch = when (mode) {
+      PitchCorrectionMode.NONE -> speed
+      PitchCorrectionMode.VOICE -> 1.0f
+      PitchCorrectionMode.MUSIC -> 1.0f
+    }
+    return PlaybackParameters(speed, pitch)
+  }
+}

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

@@ -0,0 +1,65 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+
+/**
+ * Bundled fallback artwork used by the MediaSession + notification
+ * surface when the consumer-supplied `track.artworkUrl` is missing
+ * or unreachable. Lazy-loaded once per process; cached for lifetime.
+ *
+ * Real-world failure mode this guards against: passing `null` artwork
+ * makes some Android OEM skins (Xiaomi, Oppo, Realme) drop the
+ * notification controls entirely. By always handing a bitmap to the
+ * `MediaNotification.Provider` BitmapLoader, the lib forces the OEM
+ * skin into the well-tested artwork-present render path.
+ *
+ * The asset lives at `res/raw/rnqp_placeholder.jpg` so it bypasses
+ * Android's drawable DPI scaling (it's a fixed 256×256 JPEG; we never
+ * want it scaled or themed).
+ */
+internal object PlaceholderArtwork {
+
+  /**
+   * Returns the placeholder bitmap. Cached after first call; safe
+   * to call from any thread (the bitmap is immutable once decoded).
+   */
+  fun bitmap(context: Context): Bitmap {
+    cached?.let { return it }
+    synchronized(this) {
+      cached?.let { return it }
+      val decoded = decode(context)
+      cached = decoded
+      return decoded
+    }
+  }
+
+  /**
+   * Returns the placeholder bytes (raw JPEG payload). Useful for
+   * paths that want to write the bytes into a `MediaMetadata`
+   * artworkData field rather than decoding to bitmap upfront.
+   */
+  fun bytes(context: Context): ByteArray {
+    cachedBytes?.let { return it }
+    synchronized(this) {
+      cachedBytes?.let { return it }
+      val stream = context.resources.openRawResource(R.raw.rnqp_placeholder)
+      val out = stream.use { it.readBytes() }
+      cachedBytes = out
+      return out
+    }
+  }
+
+  @Volatile private var cached: Bitmap? = null
+  @Volatile private var cachedBytes: ByteArray? = null
+
+  private fun decode(context: Context): Bitmap {
+    val stream = context.resources.openRawResource(R.raw.rnqp_placeholder)
+    return stream.use { BitmapFactory.decodeStream(it) }
+      ?: throw IllegalStateException(
+        "RNQP placeholder asset missing or undecodable at res/raw/rnqp_placeholder.jpg — " +
+          "verify the JPEG was packaged into the lib AAR"
+      )
+  }
+}

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

@@ -0,0 +1,75 @@
+package com.margelo.nitro.queueplayer
+
+import android.graphics.Bitmap
+import android.net.Uri
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.util.BitmapLoader
+import androidx.media3.common.util.UnstableApi
+import com.google.common.util.concurrent.Futures
+import com.google.common.util.concurrent.ListenableFuture
+import com.google.common.util.concurrent.MoreExecutors
+
+/**
+ * Decorates a [BitmapLoader] so the notification + lock-screen
+ * surface always receives a bitmap, never the system "music note"
+ * generic. Some Android OEM skins (Xiaomi/Oppo/Realme) drop the
+ * notification controls entirely when the loader returns no bitmap;
+ * the placeholder fallback keeps them on the artwork-present render
+ * path.
+ *
+ * Three failure modes the decorator covers:
+ *  - `MediaMetadata` carries neither an artwork URI nor artwork
+ *    bytes — answered synchronously with the placeholder.
+ *  - The delegate's `loadBitmapFromMetadata` returns null
+ *    (older delegate impls) — answered synchronously with the
+ *    placeholder.
+ *  - The delegate's future fails (network error, decode failure,
+ *    4xx/5xx response) — caught via [Futures.catching] and remapped
+ *    to the placeholder.
+ *
+ * `loadBitmap` and `decodeBitmap` are also wrapped because Media3
+ * consults them directly when `MediaMetadata#artworkUri` or
+ * `MediaMetadata#artworkData` is set; without the wrap, a failing
+ * delegate at those boundaries propagates an exception into the
+ * notification render and reproduces the controls-drop OEM
+ * behaviour the wrapper is here to prevent.
+ */
+@UnstableApi
+internal class PlaceholderFallbackBitmapLoader(
+  private val delegate: BitmapLoader,
+  private val placeholder: Bitmap,
+) : BitmapLoader {
+
+  override fun supportsMimeType(mimeType: String): Boolean =
+    delegate.supportsMimeType(mimeType)
+
+  override fun decodeBitmap(data: ByteArray): ListenableFuture<Bitmap> =
+    Futures.catching(
+      delegate.decodeBitmap(data),
+      Throwable::class.java,
+      { placeholder },
+      MoreExecutors.directExecutor(),
+    )
+
+  override fun loadBitmap(uri: Uri): ListenableFuture<Bitmap> =
+    Futures.catching(
+      delegate.loadBitmap(uri),
+      Throwable::class.java,
+      { placeholder },
+      MoreExecutors.directExecutor(),
+    )
+
+  override fun loadBitmapFromMetadata(metadata: MediaMetadata): ListenableFuture<Bitmap>? {
+    if (metadata.artworkUri == null && metadata.artworkData == null) {
+      return Futures.immediateFuture(placeholder)
+    }
+    val delegated = delegate.loadBitmapFromMetadata(metadata)
+      ?: return Futures.immediateFuture(placeholder)
+    return Futures.catching(
+      delegated,
+      Throwable::class.java,
+      { placeholder },
+      MoreExecutors.directExecutor(),
+    )
+  }
+}