react-native-queue-player 1.2.0 → 2.0.1

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

@@ -0,0 +1,115 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import android.media.AudioManager
+import androidx.media3.common.MediaItem
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
+import org.robolectric.annotation.Config
+
+/**
+ * A crossfade engine owns audio focus itself, so the pause a focus loss
+ * makes reaches the delegate carrying the audio-focus reason, not the
+ * user-request reason `pause()` stamps by default.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class CrossfadeEngineFocusLossTest {
+
+  private val context: Context = ApplicationProvider.getApplicationContext()
+
+  /** Records every play-when-ready reason the engine reports. */
+  private class RecordingDelegate : PlaybackEngineDelegate {
+    val reasons = mutableListOf<Int?>()
+    override fun onStateMaybeChanged(engine: PlaybackEngine, playWhenReadyReason: Int?) {
+      reasons.add(playWhenReadyReason)
+    }
+    override fun onIsPlayingChanged(engine: PlaybackEngine, isPlaying: Boolean) {}
+    override fun onTrackTransition(engine: PlaybackEngine, platformReason: Int) {}
+    override fun onActiveItemFormatChanged(engine: PlaybackEngine) {}
+    override fun onError(engine: PlaybackEngine, exception: PlaybackException, failedIndex: Int) {}
+    override fun onPlaybackEnded(engine: PlaybackEngine) {}
+    override fun onAutoTransitionDiscontinuity(engine: PlaybackEngine) {}
+    override fun onCrossfadeBegin(engine: PlaybackEngine, incomingIndex: Int) {}
+    override fun onCrossfadeCancel(engine: PlaybackEngine, revertedIndex: Int) {}
+  }
+
+  private fun playingEngine(delegate: RecordingDelegate): CrossfadeEngine {
+    val engine = CrossfadeEngine(context = context, crossfadeDurationMs = 3_000L)
+    engine.delegate = delegate
+    engine.setMediaItems(listOf(MediaItem.fromUri("https://example.com/a.mp3")), 0, 0L)
+    engine.play()
+    shadowOf(android.os.Looper.getMainLooper()).idle()
+    return engine
+  }
+
+  private fun focusListener(): AudioManager.OnAudioFocusChangeListener {
+    val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+    val request = shadowOf(audioManager).lastAudioFocusRequest
+    assertNotNull("play() must request focus", request)
+    return request.listener
+  }
+
+  @Test
+  fun `a focus loss pauses with the audio-focus reason`() {
+    val delegate = RecordingDelegate()
+    val engine = playingEngine(delegate)
+    delegate.reasons.clear()
+
+    focusListener().onAudioFocusChange(AudioManager.AUDIOFOCUS_LOSS)
+    shadowOf(android.os.Looper.getMainLooper()).idle()
+
+    assertEquals(
+      "the delegate stamps the last reason it is handed; a USER_REQUEST after the loss would label the pause a user pause",
+      Player.PLAY_WHEN_READY_CHANGE_REASON_AUDIO_FOCUS_LOSS,
+      delegate.reasons.last { it != null },
+    )
+    engine.release()
+  }
+
+  @Test
+  fun `a transient focus loss pauses with the audio-focus reason too`() {
+    val delegate = RecordingDelegate()
+    val engine = playingEngine(delegate)
+    delegate.reasons.clear()
+
+    focusListener().onAudioFocusChange(AudioManager.AUDIOFOCUS_LOSS_TRANSIENT)
+    shadowOf(android.os.Looper.getMainLooper()).idle()
+
+    assertEquals(
+      Player.PLAY_WHEN_READY_CHANGE_REASON_AUDIO_FOCUS_LOSS,
+      delegate.reasons.last { it != null },
+    )
+    engine.release()
+  }
+
+  @Test
+  fun `a user pause after the loss keeps its own reason`() {
+    val delegate = RecordingDelegate()
+    val engine = playingEngine(delegate)
+    focusListener().onAudioFocusChange(AudioManager.AUDIOFOCUS_LOSS_TRANSIENT)
+    focusListener().onAudioFocusChange(AudioManager.AUDIOFOCUS_GAIN)
+    engine.play()
+    shadowOf(android.os.Looper.getMainLooper()).idle()
+    delegate.reasons.clear()
+
+    engine.pause()
+    shadowOf(android.os.Looper.getMainLooper()).idle()
+
+    assertEquals(
+      "the substitution lasts only for the loss's own pauses",
+      Player.PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST,
+      delegate.reasons.last { it != null },
+    )
+    engine.release()
+  }
+}

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

@@ -1,5 +1,6 @@
 package com.margelo.nitro.queueplayer
 
+import androidx.media3.common.MediaItem
 import androidx.media3.common.util.UnstableApi
 import androidx.test.core.app.ApplicationProvider
 import org.junit.Assert.assertEquals
@@ -31,6 +32,49 @@ class CrossfadeEngineLifecycleTest {
       crossfadeDurationMs = crossfadeDurationMs,
     )
 
+  /**
+   * Settling leaves the standby leg holding nothing.
+   *
+   * An armed standby carries the queue as it stood when it was armed. A caller
+   * that mutates the queue through a path the engine does not see — Media3
+   * setting resolved assistant items on the session player — needs that
+   * snapshot gone, or promoting it drops whatever the caller added.
+   */
+  @Test
+  fun `settling a pending fade leaves nothing staged on the standby leg`() {
+    val engine = makeEngine()
+    engine.standbyPlayer.setMediaItems(
+      listOf(MediaItem.fromUri("http://example.com/next.mp3")))
+    engine.standbyPlayer.prepare()
+    assertEquals(1, engine.standbyPlayer.mediaItemCount)
+
+    engine.settlePendingFade()
+
+    assertEquals(0, engine.standbyPlayer.mediaItemCount)
+    engine.release()
+  }
+
+  /**
+   * A settle with nothing to settle leaves the legs as they are: a caller
+   * settling defensively must not swap them. Promotion itself needs a live
+   * fade, which needs real playback with duration metadata, so that half is
+   * covered by the crossfade demo suites.
+   */
+  @Test
+  fun `settling by promotion leaves the roles alone when no fade is in flight`() {
+    val engine = makeEngine()
+    val leading = engine.leadingPlayer
+    val standby = engine.standbyPlayer
+
+    engine.settlePendingFadeByPromoting()
+    engine.settlePendingFadeByPromoting()
+
+    assertSame(leading, engine.leadingPlayer)
+    assertSame(standby, engine.standbyPlayer)
+    assertTrue(engine.currentRoleIsA)
+    engine.release()
+  }
+
   @Test
   fun `constructor accepts a non-negative crossfade duration`() {
     val engine = makeEngine()
@@ -204,6 +248,7 @@ class CrossfadeEngineLifecycleTest {
     override fun onError(
       engine: PlaybackEngine,
       exception: androidx.media3.common.PlaybackException,
+      failedIndex: Int,
     ) = Unit
     override fun onPlaybackEnded(engine: PlaybackEngine) = Unit
     override fun onAutoTransitionDiscontinuity(engine: PlaybackEngine) = Unit

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

@@ -0,0 +1,70 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Context
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
+import org.robolectric.annotation.Config
+
+/**
+ * When a player reaches STATE_ENDED the engines hand the delegate the end
+ * signal before the generic state callback, so the queue-end path owns the
+ * ENDED emit and its reason.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class EngineEndSignalOrderTest {
+
+  private val context: Context = ApplicationProvider.getApplicationContext()
+
+  private class OrderingDelegate : PlaybackEngineDelegate {
+    val calls = mutableListOf<String>()
+    override fun onStateMaybeChanged(engine: PlaybackEngine, playWhenReadyReason: Int?) { calls.add("state") }
+    override fun onPlaybackEnded(engine: PlaybackEngine) { calls.add("ended") }
+    override fun onIsPlayingChanged(engine: PlaybackEngine, isPlaying: Boolean) {}
+    override fun onTrackTransition(engine: PlaybackEngine, platformReason: Int) {}
+    override fun onActiveItemFormatChanged(engine: PlaybackEngine) {}
+    override fun onError(engine: PlaybackEngine, exception: PlaybackException, failedIndex: Int) {}
+    override fun onAutoTransitionDiscontinuity(engine: PlaybackEngine) {}
+    override fun onCrossfadeBegin(engine: PlaybackEngine, incomingIndex: Int) {}
+    override fun onCrossfadeCancel(engine: PlaybackEngine, revertedIndex: Int) {}
+  }
+
+  /** An empty playlist prepared is STATE_ENDED at once. */
+  private fun assertEndedBeforeState(engine: PlaybackEngine, delegate: OrderingDelegate) {
+    engine.setMediaItems(emptyList(), 0, 0L)
+    shadowOf(android.os.Looper.getMainLooper()).idle()
+    val ended = delegate.calls.indexOf("ended")
+    val stateAfter = delegate.calls.withIndex().any { it.value == "state" && it.index > ended }
+    assertEquals("the end signal must be delivered", true, ended >= 0)
+    assertEquals(
+      "the generic state callback follows the end signal: ${delegate.calls}",
+      true, stateAfter)
+    assertEquals(
+      "no state callback precedes the end signal for this transition: ${delegate.calls}",
+      -1, delegate.calls.subList(0, ended).lastIndexOf("state"))
+    engine.release()
+  }
+
+  @Test
+  fun `gapless reports the end before the state`() {
+    val delegate = OrderingDelegate()
+    val engine = GaplessEngine(context = context)
+    engine.delegate = delegate
+    assertEndedBeforeState(engine, delegate)
+  }
+
+  @Test
+  fun `crossfade reports the end before the state`() {
+    val delegate = OrderingDelegate()
+    val engine = CrossfadeEngine(context = context, crossfadeDurationMs = 3_000L)
+    engine.delegate = delegate
+    assertEndedBeforeState(engine, delegate)
+  }
+}

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

@@ -213,4 +213,21 @@ class EqualizerEngineTest {
     engine.setBandGain(3, 4f)
     assertEquals(4f, engine.getBandGains()[3])
   }
+
+  /** A failed attach leaves no trace: nothing attached, and a retry is possible. */
+  @Test
+  @Config(sdk = [34], shadows = [ShadowDynamicsProcessingRejectingEnable::class])
+  fun `attach that fails while configuring leaves the engine detached`() {
+    val engine = EqualizerEngine()
+
+    val attached = engine.attach(audioSessionId = 801, channelCount = 2)
+
+    assertFalse("the attach reports its failure", attached)
+    assertFalse("nothing is attached after a failed configure", engine.isAttached())
+    assertEquals(
+      "the failed session is not carried as attached on the next diff",
+      mapOf(801 to false),
+      engine.attachAll(intArrayOf(801))
+    )
+  }
 }

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

@@ -232,11 +232,6 @@ private class FakePlaybackEngine : PlaybackEngine {
   override val mediaSessionPlayer: androidx.media3.exoplayer.ExoPlayer
     get() = error("not used in test")
 
-  override suspend fun prepare(
-    mediaItems: List<androidx.media3.common.MediaItem>,
-    startIndex: Int,
-    startPositionMs: Long,
-  ) = error("not used in test")
   override fun release() = error("not used in test")
   override fun setMediaItems(items: List<androidx.media3.common.MediaItem>, startIndex: Int, startPositionMs: Long) = error("not used in test")
   override fun addMediaItems(items: List<androidx.media3.common.MediaItem>, insertBefore: Int) = error("not used in test")
@@ -268,6 +263,5 @@ private class FakePlaybackEngine : PlaybackEngine {
   }
   override fun attachAudioBufferSink(sink: androidx.media3.exoplayer.audio.TeeAudioProcessor.AudioBufferSink) = error("not used in test")
   override fun detachAudioBufferSink(sink: androidx.media3.exoplayer.audio.TeeAudioProcessor.AudioBufferSink) = error("not used in test")
-  override suspend fun handoff(to: PlaybackEngine, atTrackBoundary: Boolean) = error("not used in test")
   override var delegate: PlaybackEngineDelegate? = null
 }

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

@@ -221,4 +221,21 @@ class EqualizerLegacyEngineTest {
     } ?: error("no equalizer attached for session $sessionId")
     return (effect as Equalizer).getBandLevel(band).toInt()
   }
+
+  /** A failed attach leaves no trace: nothing attached, and a retry is possible. */
+  @Test
+  @Config(sdk = [27], shadows = [ShadowEqualizerRejectingBandWrites::class])
+  fun `attach that fails while configuring leaves the engine detached`() {
+    val engine = EqualizerLegacyEngine()
+
+    val attached = engine.attach(audioSessionId = 801, channelCount = 2)
+
+    assertFalse("the attach reports its failure", attached)
+    assertFalse("nothing is attached after a failed configure", engine.isAttached())
+    assertEquals(
+      "the failed session is not carried as attached on the next diff",
+      mapOf(801 to false),
+      engine.attachAll(intArrayOf(801))
+    )
+  }
 }

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

@@ -181,4 +181,19 @@ class FFTProcessorTeeTest {
     assertEquals(expectedPosition, original.position())
     assertEquals(expectedOrder, original.order())
   }
+
+  /** A flush resets the emit throttle, so the first frame of a new stream is not delayed. */
+  @Test
+  fun `flush resets the emit throttle`() {
+    val reported = mutableListOf<Int>()
+    val tee = makeTee(fftSize = 256, intervalMs = 1000) { _, _, sampleRate -> reported += sampleRate }
+    tee.flush(48000, 1, C.ENCODING_PCM_16BIT)
+    tee.handleBuffer(pcm16Buffer(ShortArray(256) { 1000 }))
+    assertEquals(listOf(48000), reported)
+
+    // Well inside the 1000 ms window: without the reset this emit is throttled.
+    tee.flush(96000, 1, C.ENCODING_PCM_16BIT)
+    tee.handleBuffer(pcm16Buffer(ShortArray(256) { 1000 }))
+    assertEquals(listOf(48000, 96000), reported)
+  }
 }

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

@@ -13,8 +13,10 @@ import java.io.File
 /**
  * Unit tests for [FifoCacheEvictor]'s eviction ordering. Drives the evictor's
  * [CacheEvictor] callbacks directly against a minimal fake [Cache] whose only
- * live method is `removeSpan` (delegates back to `onSpanRemoved`), so the tests
- * assert insertion-order eviction without a real SimpleCache or filesystem.
+ * live method is `removeSpan`, so the tests assert insertion-order eviction
+ * without a real SimpleCache or filesystem. The fake normally delegates back to
+ * `onSpanRemoved`; `callsBack = false` models a span the cache index has already
+ * dropped, which notifies nothing.
  */
 @UnstableApi
 class FifoCacheEvictorTest {
@@ -72,11 +74,140 @@ class FifoCacheEvictorTest {
     assertEquals(listOf("b"), removed.map { it.key })
   }
 
+  @Test
+  fun `a url retires its insertion order once its last span is gone`() {
+    // The cache notifies an add even when the evictor's own set rejects the
+    // span, so a count taken from the callbacks over-counts. Here both adds are
+    // the same span, so one entry exists and one removal empties the url.
+    val evictor = FifoCacheEvictor(maxBytes = 1000)
+    val cache = FakeCache(evictor)
+    val only = CacheSpan("a", 0, 100, 1L, File("/tmp/a"))
+    evictor.onSpanAdded(cache, only)
+    evictor.onSpanAdded(cache, only)
+    evictor.onSpanAdded(cache, span("b", length = 100))
+    evictor.onSpanRemoved(cache, only)
+    removed.clear()
+
+    // `a` is empty, so re-adding it stamps a fresh newest order and `b` — now
+    // the oldest — is the victim. An over-count leaves `a` on its old order and
+    // evicts `a` instead.
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("c", length = 900)) // 1100 > maxBytes
+    assertEquals(listOf("b"), removed.map { it.key })
+  }
+
+  @Test
+  fun `a url keeps its insertion order while any of its spans remain`() {
+    val evictor = FifoCacheEvictor(maxBytes = 1000)
+    val cache = FakeCache(evictor)
+    val first = CacheSpan("a", 0, 100, 1L, File("/tmp/a-1"))
+    val second = CacheSpan("a", 100, 100, 1L, File("/tmp/a-2"))
+    evictor.onSpanAdded(cache, first)
+    evictor.onSpanAdded(cache, second)
+    evictor.onSpanAdded(cache, second) // rejected by the set, still notified
+    evictor.onSpanAdded(cache, span("b", length = 100))
+    evictor.onSpanRemoved(cache, first)
+    removed.clear()
+
+    // `a` still holds `second`, so it keeps its original (oldest) order and is
+    // still the first victim. A retired order would sort it newest and evict b.
+    evictor.onSpanAdded(cache, span("c", length = 900))
+    assertEquals("a", removed.first().key)
+    removed.clear()
+
+    // With `a` now empty, a re-add stamps a fresh newest order. An over-count
+    // from the rejected add leaves `a` on its old order and evicts it again.
+    evictor.onSpanRemoved(cache, second)
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("d", length = 900))
+    assertEquals("b", removed.first().key)
+  }
+
+  @Test(timeout = 5_000)
+  fun `eviction advances past a span the cache no longer holds`() {
+    // removeSpan is a no-op here, modelling a span the cache index has already
+    // dropped: no onSpanRemoved callback, so the head does not move on its own.
+    // The evictor must retire its own record and carry on — spinning wedges the
+    // cache's lock, and giving up makes that span the victim of every later
+    // eviction, which stops eviction permanently.
+    val evictor = FifoCacheEvictor(maxBytes = 150)
+    val deaf = FakeCache(evictor, callsBack = false)
+    evictor.onSpanAdded(deaf, span("a", length = 100))
+    evictor.onSpanAdded(deaf, span("b", length = 100))
+    evictor.onSpanAdded(deaf, span("c", length = 100))
+    assertEquals(listOf("a", "b"), removed.map { it.key })
+  }
+
+  @Test
+  fun `a protected url survives eviction and the next-oldest goes instead`() {
+    val evictor = FifoCacheEvictor(maxBytes = 250)
+    val cache = FakeCache(evictor)
+    evictor.setProtectedKeys(setOf("a"))
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("b", length = 100))
+    evictor.onSpanAdded(cache, span("c", length = 100)) // 300 > 250
+    assertEquals(listOf("b"), removed.map { it.key })
+  }
+
+  @Test(timeout = 5_000)
+  fun `eviction gives up when every remaining url is protected`() {
+    // Over budget with nothing evictable is a real state: the protected window
+    // can outgrow the budget. Staying over budget is the outcome; spinning
+    // under the cache's lock is not.
+    val evictor = FifoCacheEvictor(maxBytes = 150)
+    val cache = FakeCache(evictor)
+    evictor.setProtectedKeys(setOf("a", "b"))
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("b", length = 100)) // 200 > 150, both shielded
+    assertEquals(emptyList<String>(), removed.map { it.key })
+  }
+
+  @Test(timeout = 5_000)
+  fun `a protected span ahead of the victim does not stall the self-heal`() {
+    // The victim is not the head here: `a` is protected and sorts first, so a
+    // progress check that compared the head would never see the removal fail
+    // and would spin under the cache's lock.
+    val evictor = FifoCacheEvictor(maxBytes = 150)
+    val deaf = FakeCache(evictor, callsBack = false)
+    evictor.setProtectedKeys(setOf("a"))
+    evictor.onSpanAdded(deaf, span("a", length = 100))
+    evictor.onSpanAdded(deaf, span("b", length = 100)) // 200 > 150; a shielded
+    assertEquals(listOf("b"), removed.map { it.key })
+  }
+
+  @Test
+  fun `dropping protection makes the url evictable again`() {
+    val evictor = FifoCacheEvictor(maxBytes = 250)
+    val cache = FakeCache(evictor)
+    evictor.setProtectedKeys(setOf("a"))
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("b", length = 100))
+    evictor.setProtectedKeys(emptySet())
+    evictor.onSpanAdded(cache, span("c", length = 100)) // 300 > 250
+    assertEquals(listOf("a"), removed.map { it.key })
+  }
+
+  @Test
+  fun `the protected set is copied so a caller's later mutation cannot leak in`() {
+    val evictor = FifoCacheEvictor(maxBytes = 250)
+    val cache = FakeCache(evictor)
+    val live = mutableSetOf("a")
+    evictor.setProtectedKeys(live)
+    live.add("b") // must not reach the evictor
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("b", length = 100))
+    evictor.onSpanAdded(cache, span("c", length = 100)) // 300 > 250
+    assertEquals(listOf("b"), removed.map { it.key })
+  }
+
   /** Minimal [Cache]: only `removeSpan` is live (records + calls back the evictor). */
-  private inner class FakeCache(private val evictor: FifoCacheEvictor) : Cache {
+  private inner class FakeCache(
+    private val evictor: FifoCacheEvictor,
+    private val callsBack: Boolean = true
+  ) : Cache {
     override fun removeSpan(span: CacheSpan) {
       removed.add(span)
-      evictor.onSpanRemoved(this, span)
+      if (callsBack) evictor.onSpanRemoved(this, span)
     }
 
     override fun getUid(): Long = throw UnsupportedOperationException()

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

@@ -45,6 +45,7 @@ class GaplessEngineLifecycleTest {
       override fun onError(
         engine: PlaybackEngine,
         exception: androidx.media3.common.PlaybackException,
+        failedIndex: Int,
       ) = Unit
       override fun onPlaybackEnded(engine: PlaybackEngine) = Unit
       override fun onAutoTransitionDiscontinuity(engine: PlaybackEngine) = Unit

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

@@ -21,8 +21,9 @@ import org.robolectric.annotation.Config
  * the engine-internal `handleReplayGainParse` helper which these
  * tests drive directly with synthetic [ReplayGainData].
  * This file covers the no-data baseline,
- * mode-change-without-data behaviour, and the
- * `handleReplayGainParse` cache + recompute contract.
+ * mode-change-without-data behaviour, the
+ * `handleReplayGainParse` cache + recompute contract, and the
+ * consumer's supplied claim outranking the parsed tags.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])
@@ -81,6 +82,39 @@ class GaplessEngineReplayGainTest {
     engine.release()
   }
 
+  /**
+   * The consumer's claim over the active item outranks the file's tags: a
+   * supplied value replaces detection in full, and a claim whose values were
+   * all rejected still discards detection and plays at unity.
+   */
+  @Test
+  fun `a supplied claim on the active item replaces the detected tags`() {
+    val engine = makeEngine()
+    ReplayGainConfig.setMode(ReplayGainMode.TRACK)
+    engine.setMediaItems(listOf(androidx.media3.common.MediaItem.fromUri("https://example.com/a.mp3")), 0, 0L)
+    val detected = ReplayGainData(trackGainDb = -6.0f, trackPeak = 0.5f, albumGainDb = null, albumPeak = null)
+    engine.handleReplayGainParse(detected)
+    assertEquals(detected, engine.currentReplayGainData())
+
+    var claim: TrackItem = suppliedTrack(trackGain = -3.0)
+    engine.suppliedReplayGainResolver = { SuppliedReplayGain.from(claim) }
+    assertEquals(
+      ReplayGainData(trackGainDb = -3.0f, trackPeak = null, albumGainDb = null, albumPeak = null),
+      engine.currentReplayGainData())
+    assertTrue(engine.currentReplayGainActive())
+
+    claim = suppliedTrack(trackGain = Double.NaN)
+    assertNull("a claim with no usable value discards the detection too", engine.currentReplayGainData())
+    assertFalse(engine.currentReplayGainActive())
+    engine.release()
+  }
+
+  private fun suppliedTrack(trackGain: Double) = TrackItem(
+    id = null, url = "https://example.com/a.mp3", title = null, artist = null, album = null,
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = trackGain, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null)
+
   @Test
   fun `handleReplayGainParse with album-only data is inactive in track mode`() {
     val engine = makeEngine()