react-native-queue-player 1.2.0 → 2.0.0

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

@@ -5,6 +5,7 @@ import android.os.Build
 import android.util.Log
 import androidx.annotation.RequiresApi
 import androidx.media3.common.C
+import java.util.concurrent.ConcurrentHashMap
 
 /**
  * 10-band pre-EQ for API 28+ backed by [DynamicsProcessing].
@@ -29,11 +30,16 @@ import androidx.media3.common.C
  * [attach] `channelCount` parameter is therefore ignored on this
  * backend — retained on the interface for future per-track engines.
  *
- * Threading: callers serialize externally — [attach] / [detach] /
- * [setBandGain] / [setEnabled] run from the playback engine's
- * audio-session-id listener executor, which delivers events single-
- * threaded. The [DynamicsProcessing] instance is not guarded by an
- * internal lock; cross-thread mutation is the caller's concern.
+ * Threading: not serialised. [attachAll] / [detachAll] run on the
+ * service main looper from the audio-session-id listener, and on the
+ * thread constructing an [Equalizer] (its init wires the engine, and
+ * the listener registration replays the current session ids
+ * synchronously). [setBandGain] / [setAllBandGains] / [setEnabled] run
+ * on the `Promise.async` pool, so two JS calls may run concurrently;
+ * [isEnabled] / [getBandGains] run synchronously on the JS thread.
+ * `instances` is a `ConcurrentHashMap` and the flags are `@Volatile`,
+ * which rules out structural corruption and stale reads. What remains
+ * is documented on the fields.
  * [release] briefly blocks while the native effect tears down (a
  * few ms typical, longer on slow devices) — callers may dispatch
  * off-thread if a teardown burst risks a UI hitch.
@@ -54,16 +60,26 @@ class EqualizerEngine : IEqualizerEngine {
     private const val LOG_TAG = "EqualizerEngine"
   }
 
+  // Written by the setters and by attach, all on the main looper:
+  // `Equalizer` hops every JS-facing mutation there, and the playback
+  // engine's session-id listener drives attach there. Nothing touches
+  // this off the looper.
   private val gainsDb: FloatArray = FloatArray(BAND_COUNT)
-  private var enabled: Boolean = false
+  @Volatile private var enabled: Boolean = false
   /**
    * One [DynamicsProcessing] instance per attached audio session.
    * Crossfade-window callers can hold two simultaneously
    * (outgoing + incoming legs) so EQ continuity is preserved
    * across the fade. Single-session callers see exactly one entry.
+   * Iteration order is never relied on: the attach diff is set
+   * arithmetic and every other loop applies one operation per entry.
+   * Inserts use `putIfAbsent` and removals go through `remove`, so two
+   * attaches racing on one session release the loser instead of
+   * leaking it, and a detach cannot drop an instance inserted between
+   * its iteration and its clear.
    */
-  private val instances: MutableMap<Int, DynamicsProcessing> = LinkedHashMap()
-  private var released: Boolean = false
+  private val instances: MutableMap<Int, DynamicsProcessing> = ConcurrentHashMap()
+  @Volatile private var released: Boolean = false
 
   /**
    * Diff [sessionIds] against the current per-session map:
@@ -104,6 +120,7 @@ class EqualizerEngine : IEqualizerEngine {
         results[id] = true
         continue
       }
+      var instance: DynamicsProcessing? = null
       results[id] = try {
         val config = DynamicsProcessing.Config.Builder(
           DynamicsProcessing.VARIANT_FAVOR_FREQUENCY_RESOLUTION,
@@ -113,13 +130,18 @@ class EqualizerEngine : IEqualizerEngine {
           /* postEqInUse = */ false, /* postEqBandCount = */ 0,
           /* limiterInUse = */ false,
         ).build()
-        val instance = DynamicsProcessing(PRIORITY, id, config)
-        instances[id] = instance
+        instance = DynamicsProcessing(PRIORITY, id, config)
         applyAllBandsToInstance(instance)
         instance.setEnabled(enabled)
+        // Insert only once the instance is fully configured, so a throw
+        // above leaves no entry for isAttached() to report. A concurrent
+        // attach that got here first keeps its instance; ours is released.
+        val existing = instances.putIfAbsent(id, instance)
+        if (existing != null) instance.release()
         true
       } catch (e: RuntimeException) {
         Log.w(LOG_TAG, "DynamicsProcessing attach failed for session $id", e)
+        instance?.release()
         false
       }
     }
@@ -131,8 +153,7 @@ class EqualizerEngine : IEqualizerEngine {
    * gains + enabled state survive for the next [attachAll].
    */
   override fun detachAll() {
-    for (instance in instances.values) instance.release()
-    instances.clear()
+    for (id in instances.keys) instances.remove(id)?.release()
   }
 
   /** True when the engine is attached to at least one audio session. */

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

@@ -3,6 +3,7 @@ package com.margelo.nitro.queueplayer
 import android.media.audiofx.Equalizer
 import android.util.Log
 import androidx.media3.common.C
+import java.util.concurrent.ConcurrentHashMap
 import kotlin.math.abs
 import kotlin.math.roundToInt
 
@@ -27,7 +28,16 @@ import kotlin.math.roundToInt
  * also clamped to the device's reported `getBandLevelRange()` to
  * avoid IllegalArgumentException on aggressive devices.
  *
- * Threading: methods are called from the service main looper.
+ * Threading: not serialised. [attachAll] / [detachAll] run on the
+ * service main looper from the audio-session-id listener, and on the
+ * thread constructing an [Equalizer] (its init wires the engine, and
+ * the listener registration replays the current session ids
+ * synchronously). [setBandGain] / [setAllBandGains] / [setEnabled] run
+ * on the `Promise.async` pool, so two JS calls may run concurrently;
+ * [isEnabled] / [getBandGains] run synchronously on the JS thread.
+ * `instances` is a `ConcurrentHashMap` and the flags are `@Volatile`,
+ * which rules out structural corruption and stale reads. What remains
+ * is documented on the fields.
  * [release] briefly blocks while the native effect tears down.
  */
 class EqualizerLegacyEngine : IEqualizerEngine {
@@ -70,7 +80,7 @@ class EqualizerLegacyEngine : IEqualizerEngine {
 
   /**
    * Per-session equalizer instance + the per-device-derived
-   * mapping & gain bounds latched at attach time. Each session
+   * mapping & gain bounds read once at attach time. Each session
    * derives independently so AOSP-fork variance across sessions
    * is handled correctly.
    */
@@ -81,10 +91,19 @@ class EqualizerLegacyEngine : IEqualizerEngine {
     val deviceMaxMb: Short,
   )
 
+  // Written by the setters and by attach, all on the main looper:
+  // `Equalizer` hops every JS-facing mutation there, and the playback
+  // engine's session-id listener drives attach there. Nothing touches
+  // this off the looper.
   private val gainsDb: FloatArray = FloatArray(BAND_COUNT)
-  private var enabled: Boolean = false
-  private val instances: MutableMap<Int, Slot> = LinkedHashMap()
-  private var released: Boolean = false
+  @Volatile private var enabled: Boolean = false
+  // Iteration order is never relied on: the attach diff is set arithmetic
+  // and every other loop applies one operation per entry. Inserts use
+  // `putIfAbsent` and removals go through `remove`, so two attaches
+  // racing on one session release the loser instead of leaking it, and a
+  // detach cannot drop a slot inserted between its iteration and clear.
+  private val instances: MutableMap<Int, Slot> = ConcurrentHashMap()
+  @Volatile private var released: Boolean = false
 
   /**
    * Diff [sessionIds] against the current per-session map.
@@ -138,9 +157,14 @@ class EqualizerLegacyEngine : IEqualizerEngine {
         deviceMinMb = range[0],
         deviceMaxMb = range[1],
       )
-      instances[audioSessionId] = slot
       applyAllBandsToSlot(slot)
       instance.enabled = enabled
+      // Insert only once the slot is fully configured, so a throw above
+      // leaves no entry for isAttached() to report against a released
+      // native handle. A concurrent attach that got here first keeps its
+      // slot; ours is released.
+      val existing = instances.putIfAbsent(audioSessionId, slot)
+      if (existing != null) instance.release()
       true
     } catch (e: RuntimeException) {
       Log.w(LOG_TAG, "Equalizer attach failed for session $audioSessionId", e)
@@ -150,8 +174,7 @@ class EqualizerLegacyEngine : IEqualizerEngine {
   }
 
   override fun detachAll() {
-    for (slot in instances.values) slot.equalizer.release()
-    instances.clear()
+    for (id in instances.keys) instances.remove(id)?.equalizer?.release()
   }
 
   override fun isAttached(): Boolean = instances.isNotEmpty()

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

@@ -38,10 +38,9 @@ internal class FFTProcessorTee(
   }
 
   // 2× ring so we can copy the latest fftSize-sample window without
-  // worrying about mid-window wraparound. AudioBufferSink callbacks
-  // are synchronous on the audio render thread — single-writer,
-  // single-reader, no synchronization needed. Length is a power of
-  // two so wrap is a free bitmask.
+  // worrying about mid-window wraparound. handleBuffer is the only
+  // writer and reader of the ring, and it runs on the audio render
+  // thread. Length is a power of two so wrap is a free bitmask.
   private val ring = FloatArray(fftSize * 2)
   private val ringMask: Int = ring.size - 1
   private var writeIdx = 0L
@@ -57,21 +56,33 @@ internal class FFTProcessorTee(
   private val magsOut = FloatArray(fftSize / 2)
   private val samplesOut: FloatArray? = if (includeSamples) FloatArray(fftSize) else null
 
-  private var sampleRate: Int = 44100
-  private var channelCount: Int = 2
-  private var encoding: Int = C.ENCODING_PCM_16BIT
-  private var bytesPerFrame: Int = 4 // 2 channels × 2 bytes
-  private var bytesPerSampleCached: Int = 2
+  /**
+   * The stream format a buffer is decoded under. Immutable and published
+   * as a whole through the single [format] reference, so a decode never
+   * mixes one flush's channel count with another's encoding.
+   */
+  private class Format(val sampleRate: Int, val channelCount: Int, val encoding: Int) {
+    val bytesPerSample: Int = bytesPerSample(encoding)
+    val bytesPerFrame: Int = bytesPerSample * channelCount
+  }
 
+  // flush() runs on whichever thread attaches the sink (see
+  // MultiplexingAudioBufferSink.primeNewSink) and on the render thread;
+  // handleBuffer runs on the render thread and reads this once per call.
+  @Volatile private var format = Format(44100, 2, C.ENCODING_PCM_16BIT)
+
+  // `writeIdx` (above) and `lastEmitNs` are written by handleBuffer and
+  // reset by flush, with no ordering between the two. A flush racing a
+  // handleBuffer can lose the `writeIdx` reset, so exactly one emitted
+  // frame carries up to fftSize pre-flush samples — comparable to the
+  // delayed first frame MultiplexingAudioBufferSink documents for a
+  // double flush. A lost `lastEmitNs` reset delays the first post-flush
+  // frame by at most intervalMs. On a 32-bit ABI the Long resets can
+  // tear; the outcomes are the same one frame.
   private var lastEmitNs: Long = 0L
 
   override fun flush(sampleRateHz: Int, channelCount: Int, encoding: Int) {
-    this.sampleRate = sampleRateHz
-    this.channelCount = channelCount.coerceAtLeast(1)
-    this.encoding = encoding
-    val sampleSize = bytesPerSample(encoding)
-    this.bytesPerSampleCached = sampleSize
-    this.bytesPerFrame = sampleSize * this.channelCount
+    format = Format(sampleRateHz, channelCount.coerceAtLeast(1), encoding)
     // Reset write index on stream change so the ring doesn't carry
     // samples from the previous track / sample-rate config across.
     writeIdx = 0L
@@ -79,17 +90,19 @@ internal class FFTProcessorTee(
   }
 
   override fun handleBuffer(buffer: ByteBuffer) {
-    if (bytesPerFrame == 0 || bytesPerSampleCached == 0) return // unsupported encoding
+    // One read: every field this call uses comes from the same flush.
+    val fmt = format
+    if (fmt.bytesPerFrame == 0 || fmt.bytesPerSample == 0) return // unsupported encoding
     // Read via a duplicated view so the source buffer's position +
     // byte order are not mutated. Media3 documents the input as a
     // duplicated read-only buffer, but local-mutating it would
     // surprise any future consumer that relied on the contract.
     val view = buffer.duplicate().order(ByteOrder.nativeOrder())
-    val frameCount = view.remaining() / bytesPerFrame
+    val frameCount = view.remaining() / fmt.bytesPerFrame
     var idxLo = (writeIdx and ringMask.toLong()).toInt()
     var i = 0
     while (i < frameCount) {
-      ring[idxLo] = readMonoSample(view)
+      ring[idxLo] = readMonoSample(view, fmt)
       idxLo = (idxLo + 1) and ringMask
       i++
     }
@@ -100,10 +113,10 @@ internal class FFTProcessorTee(
     if (nowNs - lastEmitNs < intervalMs * 1_000_000L) return
     lastEmitNs = nowNs
 
-    emitFrame()
+    emitFrame(fmt.sampleRate)
   }
 
-  private fun emitFrame() {
+  private fun emitFrame(sampleRate: Int) {
     // Latest fftSize samples ending at writeIdx - 1.
     val startLo = ((writeIdx - fftSize) and ringMask.toLong()).toInt()
     var i = 0
@@ -134,24 +147,24 @@ internal class FFTProcessorTee(
    * a sample (returns 0); the audio chain doesn't typically deliver
    * those to AudioSink.
    */
-  private fun readMonoSample(buffer: ByteBuffer): Float {
+  private fun readMonoSample(buffer: ByteBuffer, fmt: Format): Float {
     var sum = 0f
     var ch = 0
-    while (ch < channelCount) {
-      sum += when (encoding) {
+    while (ch < fmt.channelCount) {
+      sum += when (fmt.encoding) {
         C.ENCODING_PCM_16BIT -> buffer.short.toFloat() / Short.MAX_VALUE.toFloat()
         C.ENCODING_PCM_FLOAT -> buffer.float
         C.ENCODING_PCM_32BIT -> buffer.int.toFloat() / Int.MAX_VALUE.toFloat()
         C.ENCODING_PCM_24BIT -> read24BitPacked(buffer)
         else -> {
           // Skip unknown encoding: advance position by sample size guess.
-          buffer.position(buffer.position() + bytesPerSample(encoding))
+          buffer.position(buffer.position() + fmt.bytesPerSample)
           0f
         }
       }
       ch++
     }
-    return sum / channelCount
+    return sum / fmt.channelCount
   }
 
   private fun read24BitPacked(buffer: ByteBuffer): Float {
@@ -164,10 +177,12 @@ internal class FFTProcessorTee(
     return v.toFloat() / 8_388_608f // 2^23
   }
 
-  private fun bytesPerSample(encoding: Int): Int = when (encoding) {
-    C.ENCODING_PCM_16BIT -> 2
-    C.ENCODING_PCM_24BIT -> 3
-    C.ENCODING_PCM_32BIT, C.ENCODING_PCM_FLOAT -> 4
-    else -> 0
+  private companion object {
+    fun bytesPerSample(encoding: Int): Int = when (encoding) {
+      C.ENCODING_PCM_16BIT -> 2
+      C.ENCODING_PCM_24BIT -> 3
+      C.ENCODING_PCM_32BIT, C.ENCODING_PCM_FLOAT -> 4
+      else -> 0
+    }
   }
 }

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

@@ -26,17 +26,48 @@ import java.util.TreeSet
  * only to force the recency-bump rewrite.)
  *
  * Callbacks are invoked under the [Cache]'s lock, so the plain fields below need
- * no additional synchronization — mirrors Media3's own evictor.
+ * no additional synchronization — mirrors Media3's own evictor. [protectedKeys]
+ * is the exception: it is written from outside those callbacks.
+ *
+ * [setProtectedKeys] names urls eviction must leave alone. Only this evictor
+ * honours them — Media3's LRU evictor has no such concept, and LRU is the
+ * default policy, so protection ships off unless a consumer selects FIFO. LRU
+ * is not equivalent: it bumps the recency of the span just read, not the whole
+ * resource, so a long track's already-played spans stay evictable while it is
+ * still playing.
  */
 @UnstableApi
 class FifoCacheEvictor(private val maxBytes: Long) : CacheEvictor {
 
   private var insertionCounter: Long = 0
+
+  /**
+   * Bytes held by the spans this evictor tracks — not the cache's on-disk total.
+   *
+   * The two differ when the cache notifies an add whose span [fifo] rejects: the
+   * bytes land on disk but no removal is ever notified for them, so counting
+   * them here would push the evictor permanently over budget and make it evict
+   * everything on every add. Untracked bytes are reclaimed when their resource
+   * is removed as a whole.
+   */
   private var currentSize: Long = 0
 
   /** Insertion order per resource key (the track URL); stamped once, never bumped. */
   private val insertionOrderByKey = HashMap<String, Long>()
 
+  /**
+   * Live span count per resource key, maintained from the [fifo] mutations
+   * themselves rather than from the callback count.
+   *
+   * [CacheSpan] defines no `equals`/`hashCode`, and [Cache] notifies an add even
+   * when the set rejects it as a duplicate, so a count derived from callbacks
+   * drifts from the set. A drifted count drops an [insertionOrderByKey] entry
+   * while spans for that key are still live, which changes the comparator's
+   * verdict for elements already in [fifo]; removals then silently fail and
+   * [evictToFit] cannot make progress.
+   */
+  private val spanCountByKey = HashMap<String, Int>()
+
   /** Spans ordered oldest-first by (resource insertion order, byte position). */
   private val fifo = TreeSet<CacheSpan> { a, b ->
     val oa = insertionOrderByKey[a.key] ?: Long.MAX_VALUE
@@ -48,6 +79,26 @@ class FifoCacheEvictor(private val maxBytes: Long) : CacheEvictor {
     }
   }
 
+  /**
+   * Urls eviction must not take. Written from the main thread while callbacks
+   * run under the [Cache] lock on whichever thread touched the cache, hence
+   * volatile. The setter copies because a Kotlin `Set` is read-only rather than
+   * immutable: without the copy a caller could keep mutating the set it handed
+   * over and change what is protected behind this evictor's back.
+   */
+  @Volatile
+  private var protectedKeys: Set<String> = emptySet()
+
+  /**
+   * Name the urls eviction must leave alone — the playing track and the ones
+   * around it. Without this, FIFO evicts the track being played the moment the
+   * cache is over budget: [requiresCacheSpanTouches] is false, so a read never
+   * bumps a resource's order and the playing track cannot protect itself.
+   */
+  fun setProtectedKeys(keys: Set<String>) {
+    protectedKeys = keys.toSet()
+  }
+
   override fun requiresCacheSpanTouches(): Boolean = false
 
   override fun onCacheInitialized() {
@@ -61,36 +112,81 @@ class FifoCacheEvictor(private val maxBytes: Long) : CacheEvictor {
   }
 
   override fun onSpanAdded(cache: Cache, span: CacheSpan) {
+    // Stamp the order before inserting: the comparator reads it for every
+    // element it touches during the insert.
     insertionOrderByKey.getOrPut(span.key) { insertionCounter++ }
-    fifo.add(span)
-    currentSize += span.length
+    if (fifo.add(span)) {
+      spanCountByKey.merge(span.key, 1, Int::plus)
+      currentSize += span.length
+    }
     evictToFit(cache, 0)
   }
 
   override fun onSpanRemoved(cache: Cache, span: CacheSpan) {
-    fifo.remove(span)
+    if (!fifo.remove(span)) return
     currentSize -= span.length
-    // Once a resource's last span is gone, forget its insertion order so a
-    // later re-fetch of the same URL is treated as newly inserted.
-    if (fifo.none { it.key == span.key }) {
-      insertionOrderByKey.remove(span.key)
+    spanCountByKey.merge(span.key, -1, Int::plus)
+    retireIfEmpty(span.key)
+  }
+
+  /**
+   * Forget a resource's insertion order once it holds no spans, so a later
+   * re-fetch of the same URL is treated as newly inserted.
+   *
+   * Retires on `<= 0` rather than `== 0`: `HashMap.merge` stores the value
+   * directly for an absent key, so a decrement that outruns an increment lands
+   * at -1, and an equality test would pin the entry in place permanently.
+   */
+  private fun retireIfEmpty(key: String) {
+    if ((spanCountByKey[key] ?: 0) <= 0) {
+      spanCountByKey.remove(key)
+      insertionOrderByKey.remove(key)
     }
   }
 
   override fun onSpanTouched(cache: Cache, oldSpan: CacheSpan, newSpan: CacheSpan) {
     // Not called while requiresCacheSpanTouches() is false. Handled defensively:
-    // swap the span in place, preserving the resource's insertion order.
-    fifo.remove(oldSpan)
-    currentSize -= oldSpan.length
-    fifo.add(newSpan)
-    currentSize += newSpan.length
+    // swap the span in place, preserving the resource's insertion order —
+    // re-stamping it here would move the resource to the back of the queue on a
+    // mere access. The count tracks each mutation separately so a swap that
+    // only half-applies cannot retire an order whose spans are still live.
+    if (fifo.remove(oldSpan)) {
+      currentSize -= oldSpan.length
+      spanCountByKey.merge(oldSpan.key, -1, Int::plus)
+    }
+    insertionOrderByKey.getOrPut(newSpan.key) { insertionCounter++ }
+    if (fifo.add(newSpan)) {
+      currentSize += newSpan.length
+      spanCountByKey.merge(newSpan.key, 1, Int::plus)
+    }
+    // Settle both keys only after both mutations: a same-key swap dips to zero
+    // in between, and retiring there would re-stamp the resource as newest.
+    retireIfEmpty(oldSpan.key)
+    retireIfEmpty(newSpan.key)
   }
 
   private fun evictToFit(cache: Cache, requiredSpace: Long) {
-    while (currentSize + requiredSpace > maxBytes && fifo.isNotEmpty()) {
+    // One volatile read, so the whole scan sees a single consistent set.
+    val shielded = protectedKeys
+    while (currentSize + requiredSpace > maxBytes) {
+      // Oldest first, skipping what must survive. Nothing evictable left means
+      // over budget is the outcome — the alternative is spinning here.
+      val victim = fifo.firstOrNull { it.key !in shielded } ?: return
       // removeSpan synchronously calls back onSpanRemoved, which updates
       // currentSize + fifo, so the loop re-checks against the new total.
-      cache.removeSpan(fifo.first())
+      cache.removeSpan(victim)
+      if (fifo.contains(victim)) {
+        // The cache index no longer holds this span, so removeSpan notified
+        // nothing. Drop our own record: its bytes are unreclaimable, but
+        // leaving it in place would make it the victim of every future
+        // eviction and stop the cache evicting at all. Membership, not the
+        // head, is the test — a protected span can sit ahead of the victim.
+        // Membership stays exact because a span still in the tree always has a
+        // live order entry: the entry is retired only after its last successful
+        // removal. Once retired, the span sorts at the Long.MAX_VALUE sentinel,
+        // past every live element, so `contains` reports false.
+        onSpanRemoved(cache, victim)
+      }
     }
   }
 }

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

@@ -70,9 +70,10 @@ internal class GaplessEngine(
   /**
    * Per-engine ReplayGain audio processor. Always present in the
    * pipeline; the processor's own [ReplayGainAudioProcessor.isActive]
-   * gates the per-sample multiply on encoding (Float32) + gain
-   * (`!= 1.0f`). The [Player.Listener.onTracksChanged] listener
-   * reads container-level tags out of the active audio track's
+   * gates only on encoding, so a gain pushed mid-stream reaches the
+   * audio without a sink reconfigure. The
+   * [Player.Listener.onTracksChanged] listener reads container-level
+   * tags out of the active audio track's
    * `Format.metadata` and pushes a fresh gain;
    * [Player.Listener.onMediaItemTransition] resets to unity until
    * the next track's tracks become available. The
@@ -135,10 +136,13 @@ internal class GaplessEngine(
 
   private val playerListener = object : Player.Listener {
     override fun onPlaybackStateChanged(playbackState: Int) {
-      delegate?.onStateMaybeChanged(this@GaplessEngine, playWhenReadyReason = null)
+      // The end signal goes first: the queue-end path emits ENDED with its
+      // own reason, and a plain state emit before it would take that slot
+      // with SYSTEM and leave the queue-end emit deduplicated.
       if (playbackState == Player.STATE_ENDED) {
         delegate?.onPlaybackEnded(this@GaplessEngine)
       }
+      delegate?.onStateMaybeChanged(this@GaplessEngine, playWhenReadyReason = null)
     }
 
     override fun onPlayWhenReadyChanged(playWhenReady: Boolean, reason: Int) {
@@ -199,7 +203,7 @@ internal class GaplessEngine(
     }
 
     override fun onPlayerError(error: PlaybackException) {
-      delegate?.onError(this@GaplessEngine, error)
+      delegate?.onError(this@GaplessEngine, error, failedIndex = exoPlayer.currentMediaItemIndex)
     }
   }
 
@@ -225,15 +229,6 @@ internal class GaplessEngine(
 
   // --- PlaybackEngine — lifecycle ---
 
-  override suspend fun prepare(
-    mediaItems: List<MediaItem>,
-    startIndex: Int,
-    startPositionMs: Long,
-  ) {
-    exoPlayer.setMediaItems(mediaItems, startIndex, startPositionMs)
-    exoPlayer.prepare()
-  }
-
   override fun release() {
     if (released) return
     released = true
@@ -257,6 +252,11 @@ internal class GaplessEngine(
     startIndex: Int,
     startPositionMs: Long,
   ) {
+    if (items.isEmpty()) {
+      // Draining is not pausing: `playWhenReady` survives an empty playlist,
+      // so the next queue seated on this player would start on contact.
+      exoPlayer.pause()
+    }
     exoPlayer.setMediaItems(items, startIndex, startPositionMs)
     // ExoPlayer is in STATE_IDLE after construction + after stop().
     // setMediaItems alone doesn't transition out of IDLE — prepare()
@@ -425,12 +425,47 @@ internal class GaplessEngine(
   // --- ReplayGain — engine-internal accessors ---
 
   /**
-   * Recompute the processor's linear gain from [cachedReplayGainData]
+   * Resolves the consumer's ReplayGain claim over the queue entry at a
+   * given index. Installed by [TrackPlayer] at engine construction and
+   * invoked on every read rather than cached: a `setQueue` carrying
+   * corrected values then takes effect at the next recompute, with no
+   * cache to invalidate at the wrong moment.
+   *
+   * A `null` return means the consumer supplied nothing for that entry
+   * and the file's own tags stand. A non-null result with a `null`
+   * [SuppliedReplayGain.data] means the consumer claimed the track and
+   * gave nothing usable — a different state, and one the merge has to
+   * be able to tell apart.
+   */
+  internal var suppliedReplayGainResolver: ((Int) -> SuppliedReplayGain?)? = null
+
+  /**
+   * The ReplayGain the active item actually plays with: the consumer's
+   * claim where there is one, [cachedReplayGainData] otherwise. Every
+   * read of ReplayGain on this engine goes through here, so the merge
+   * lands before the first value reaches the audio or a listener.
+   */
+  private fun effectiveReplayGainData(): ReplayGainData? {
+    // An empty timeline reports index 0, which would name the first
+    // queue entry for a player holding no items at all — so nothing is
+    // claimed until there is an item for the index to mean something.
+    val supplied = if (exoPlayer.mediaItemCount == 0) null
+                   else suppliedReplayGainResolver?.invoke(exoPlayer.currentMediaItemIndex)
+    return ReplayGainData.merge(
+      suppliedClaimed = supplied != null,
+      supplied = supplied?.data,
+      detected = cachedReplayGainData,
+    )
+  }
+
+  /**
+   * Recompute the processor's linear gain from [effectiveReplayGainData]
    * + the current [ReplayGainConfig.getMode]. Called from
    * [Player.Listener.onTracksChanged] / [Player.Listener.onMetadata]
    * via [handleReplayGainParse] when fresh tags arrive and from
    * [TrackPlayer.setReplayGainMode] when the user flips mode
-   * mid-track. With no cached data the processor stays at unity.
+   * mid-track. With nothing supplied and nothing cached the processor
+   * stays at unity.
    *
    * Main thread only — the listener bodies dispatch on the
    * application looper and [TrackPlayer.setReplayGainMode] hops to
@@ -438,7 +473,7 @@ internal class GaplessEngine(
    */
   @MainThread
   internal fun recomputeReplayGainFromConfig() {
-    val gain = computeLinearGain(cachedReplayGainData, ReplayGainConfig.getMode())
+    val gain = computeLinearGain(effectiveReplayGainData(), ReplayGainConfig.getMode())
     replayGainProcessor.setLinearGain(gain)
   }
 
@@ -465,20 +500,21 @@ internal class GaplessEngine(
   }
 
   /**
-   * Snapshot the active item's cached [ReplayGainData] for the
-   * [NowPlayingFormatExtractor] surface. Returns `null` when no
-   * usable RG tags have been parsed yet for the current track.
+   * Snapshot the ReplayGain the active item plays with, for the
+   * [NowPlayingFormatExtractor] surface. Returns `null` when nothing is
+   * supplied for the current track and no usable RG tags have been
+   * parsed for it either.
    */
-  override fun currentReplayGainData(): ReplayGainData? = cachedReplayGainData
+  override fun currentReplayGainData(): ReplayGainData? = effectiveReplayGainData()
 
   /**
-   * `true` when [cachedReplayGainData] carries a tag for the active
-   * mode (i.e. the gain push lands at non-unity). Used by the
+   * `true` when the active item's ReplayGain carries a tag for the
+   * active mode (i.e. the gain push lands at non-unity). Used by the
    * NowPlayingFormat path to populate `replayGainActive` without
    * recomputing the linear gain itself.
    */
   override fun currentReplayGainActive(): Boolean {
-    val data = cachedReplayGainData ?: return false
+    val data = effectiveReplayGainData() ?: return false
     val (gainDb, _) = data.selectGain(ReplayGainConfig.getMode())
     return gainDb != null
   }
@@ -532,15 +568,6 @@ internal class GaplessEngine(
     }
     return null
   }
-
-  // --- PlaybackEngine — handoff ---
-
-  override suspend fun handoff(to: PlaybackEngine, atTrackBoundary: Boolean) {
-    // Wired alongside CrossfadeEngine; with only the gapless engine
-    // available there is no swap target.
-    throw NotImplementedError("PlaybackEngine.handoff is not yet implemented")
-  }
-
 }
 
 /**