react-native-queue-player 1.1.2 → 2.0.0

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

@@ -4,7 +4,6 @@ import org.junit.Assert.assertArrayEquals
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertTrue
-import org.junit.Assume.assumeTrue
 import org.junit.Test
 import org.junit.runner.RunWith
 import org.robolectric.RobolectricTestRunner
@@ -168,7 +167,7 @@ class EqualizerEngineTest {
   fun `reattach on same session is idempotent`() {
     val engine = EqualizerEngine()
     val first = engine.attach(audioSessionId = 123, channelCount = 2)
-    assumeTrue("Robolectric audio-effect shadow refused first attach", first)
+    assertTrue("first attach succeeds", first)
     val second = engine.attach(audioSessionId = 123, channelCount = 6)
     assertTrue("repeat attach on the same session succeeds", second)
     assertTrue(
@@ -181,7 +180,7 @@ class EqualizerEngineTest {
   fun `attachAll holds multiple sessions simultaneously for crossfade`() {
     val engine = EqualizerEngine()
     val results = engine.attachAll(intArrayOf(101, 102))
-    assumeTrue("Robolectric audio-effect shadow refused attach", results[101] == true)
+    assertTrue("session attaches", results[101] == true)
     assertTrue("incoming session also attached", results[102] == true)
     assertTrue("at least one session held", engine.isAttached())
   }
@@ -190,7 +189,7 @@ class EqualizerEngineTest {
   fun `attachAll diff releases sessions no longer in the input array`() {
     val engine = EqualizerEngine()
     val first = engine.attachAll(intArrayOf(201, 202))
-    assumeTrue("Robolectric audio-effect shadow refused attach", first[201] == true)
+    assertTrue("session attaches", first[201] == true)
     val second = engine.attachAll(intArrayOf(202))
     // 201 dropped, 202 retained.
     assertTrue("retained session marked succeeded", second[202] == true)
@@ -201,22 +200,34 @@ class EqualizerEngineTest {
   fun `detachAll releases every per-session instance`() {
     val engine = EqualizerEngine()
     val results = engine.attachAll(intArrayOf(301, 302))
-    assumeTrue("Robolectric audio-effect shadow refused attach", results[301] == true)
+    assertTrue("session attaches", results[301] == true)
     engine.detachAll()
     assertTrue("no sessions held after detachAll", !engine.isAttached())
   }
 
   @Test
-  fun `setBandGain fans gain across all attached sessions`() {
+  fun `setBandGain buffers the gain while sessions are attached`() {
     val engine = EqualizerEngine()
     val results = engine.attachAll(intArrayOf(401, 402))
-    assumeTrue("Robolectric audio-effect shadow refused attach", results[401] == true)
+    assertTrue("session attaches", results[401] == true)
     engine.setBandGain(3, 4f)
     assertEquals(4f, engine.getBandGains()[3])
-    // The buffered gain mirrors what each per-session instance
-    // received via setPreEqBandAllChannelsTo. Direct hardware
-    // verification requires a real device — Robolectric's audio-
-    // effect shadow doesn't expose the per-band gain readback —
-    // so this asserts the lib-side state mirrors the call.
+  }
+
+  /** 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

@@ -4,20 +4,22 @@ import org.junit.Assert.assertArrayEquals
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertTrue
+import android.media.audiofx.Equalizer
 import org.junit.Test
 import org.junit.runner.RunWith
 import org.robolectric.RobolectricTestRunner
+import org.robolectric.shadow.api.Shadow
 import org.robolectric.annotation.Config
+import org.robolectric.shadows.ShadowAudioEffect
 
 /**
- * State-mirror coverage for [EqualizerLegacyEngine] on the API <28 path.
- * Robolectric's audio-effect shadow doesn't model the hardware-side
- * band centre frequencies + gain range; the band-mapping + dB↔mB
- * conversion are the invariants this covers. Legacy AudioEffect
- * behaviour varies per OEM.
+ * State-mirror coverage for [EqualizerLegacyEngine] on the API <28 path:
+ * the band mapping, the dB↔mB conversion, and what reaches each attached
+ * session. [ShadowEqualizer] supplies the hardware-side band count, centre
+ * frequencies and gain range that legacy AudioEffect varies per OEM.
  */
 @RunWith(RobolectricTestRunner::class)
-@Config(sdk = [27])
+@Config(sdk = [27], shadows = [ShadowEqualizer::class])
 class EqualizerLegacyEngineTest {
 
   @Test
@@ -181,9 +183,7 @@ class EqualizerLegacyEngineTest {
   fun `attachAll on empty array detaches every active instance`() {
     val engine = EqualizerLegacyEngine()
     val first = engine.attachAll(intArrayOf(501, 502))
-    org.junit.Assume.assumeTrue(
-      "Robolectric audio-effect shadow refused first attach", first[501] == true,
-    )
+    assertEquals("both sessions attach", mapOf(501 to true, 502 to true), first)
     val second = engine.attachAll(intArrayOf())
     assertEquals("empty array clears the map", 0, second.size)
     assertFalse("no sessions held after empty attachAll", engine.isAttached())
@@ -193,9 +193,7 @@ class EqualizerLegacyEngineTest {
   fun `detachAll releases every per-session instance`() {
     val engine = EqualizerLegacyEngine()
     val results = engine.attachAll(intArrayOf(601, 602))
-    org.junit.Assume.assumeTrue(
-      "Robolectric audio-effect shadow refused attach", results[601] == true,
-    )
+    assertEquals("both sessions attach", mapOf(601 to true, 602 to true), results)
     engine.detachAll()
     assertFalse("no sessions held after detachAll", engine.isAttached())
   }
@@ -204,10 +202,40 @@ class EqualizerLegacyEngineTest {
   fun `setBandGain fans gain across every attached session`() {
     val engine = EqualizerLegacyEngine()
     val results = engine.attachAll(intArrayOf(701, 702))
-    org.junit.Assume.assumeTrue(
-      "Robolectric audio-effect shadow refused attach", results[701] == true,
-    )
+    assertEquals("both sessions attach", mapOf(701 to true, 702 to true), results)
+
     engine.setBandGain(4, 5f)
+
     assertEquals("buffered band gain mirrors the call", 5f, engine.getBandGains()[4])
+    // Our 500 Hz band maps onto the shadow's 230 Hz legacy band, and +5 dB
+    // is 500 mB against a ±1500 mB device range.
+    val legacyBand: Short = 1
+    assertEquals("session 701 receives the gain", 500, levelFor(701, legacyBand))
+    assertEquals("session 702 receives the gain", 500, levelFor(702, legacyBand))
+  }
+
+  /** Band level the session's own equalizer reports, in millibels. */
+  private fun levelFor(sessionId: Int, band: Short): Int {
+    val effect = ShadowAudioEffect.getAudioEffects().firstOrNull {
+      Shadow.extract<ShadowEqualizer>(it).audioSession == sessionId
+    } ?: 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()

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

@@ -20,8 +20,8 @@ import java.io.File
  *
  * Exercises the cache directly without going through ExoPlayer:
  * - Constructor creates the cache directory under `context.cacheDir`.
- * - `wrapDataSourceFactory` returns a [CacheDataSource.Factory]-shaped
- *   factory rooted at this cache.
+ * - `wrapDataSourceFactory` hands out a [CacheDataSource] while the cache
+ *   serves playback and the bare upstream source while it does not.
  * - `release()` is idempotent, and a fresh cache can be constructed
  *   at the same directory afterwards (the SimpleCache one-instance-
  *   per-directory invariant is restored on release).
@@ -69,25 +69,33 @@ class LookaheadCacheTest {
   }
 
   @Test
-  fun `wrapDataSourceFactory returns a CacheDataSource Factory`() {
+  fun `the wrapped factory reads through the cache while it serves playback`() {
     val upstream = DefaultHttpDataSource.Factory()
     val wrapped = cache.wrapDataSourceFactory(upstream)
-    assertNotNull(wrapped)
+    val source = wrapped.createDataSource()
     assertTrue(
-      "wrapped factory must produce a CacheDataSource so reads check the LRU first",
-      wrapped is CacheDataSource.Factory
+      "a data source opened while the cache is enabled checks the disk first",
+      source is CacheDataSource
     )
   }
 
+  /**
+   * Disabled means every read goes to the origin and nothing is written,
+   * whatever the disk holds — the wrapper hands out the bare upstream source.
+   * Decided per data source, so a change reaches the next item load.
+   */
   @Test
-  fun `wrapped factory creates DataSources rooted at the same SimpleCache`() {
+  fun `the wrapped factory bypasses the cache while it does not serve playback`() {
     val upstream = DefaultHttpDataSource.Factory()
     val wrapped = cache.wrapDataSourceFactory(upstream)
-    val source = wrapped.createDataSource()
-    assertTrue(
-      "createDataSource must produce a CacheDataSource — the cache check happens at read time",
-      source is androidx.media3.datasource.cache.CacheDataSource
-    )
+
+    cache.servesPlayback = false
+    val bypassed = wrapped.createDataSource()
+    cache.servesPlayback = true
+    val served = wrapped.createDataSource()
+
+    assertTrue("disabled: the upstream source, no cache in front", bypassed !is CacheDataSource)
+    assertTrue("re-enabled: the next source goes through the cache again", served is CacheDataSource)
   }
 
   @Test
@@ -125,13 +133,11 @@ class LookaheadCacheTest {
   }
 
   @Test
-  fun `default max size constant matches the documented bootstrap budget`() {
-    // Guards against an accidental tweak — the bootstrap budget is
-    // load-bearing for the 1.24-1.27 interim (consumers see the
-    // library's automatic disk usage before the runtime config API
-    // ships).
+  fun `default max size is 100 MB`() {
+    // The default is what a consumer that omits `lookaheadCacheMaxSizeMb`
+    // from `configure()` gets, so it is part of the public contract.
     assertEquals(
-      "bootstrap budget should be 100 MB the runtime config",
+      "default disk budget",
       100L * 1024L * 1024L,
       LookaheadCache.DEFAULT_MAX_SIZE_BYTES
     )

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

@@ -0,0 +1,85 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+/**
+ * Cancelling a prefetch stops the write that is running, not only the
+ * coroutine around it.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class LookaheadCacheWriterCancelTest {
+
+  private fun httpTrack(id: String) = TrackItem(
+    id = id, url = "https://example.com/$id.m4a", title = null, artist = null, album = null,
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null)
+
+  /**
+   * `CacheWriter.cache()` blocks and polls only its own cancelled flag, so a
+   * cancelled coroutine alone would leave it writing. The download body
+   * relays the cancellation onto the writer; `CacheWriter` then closes its
+   * source, which is what this observes.
+   */
+  @Test
+  fun `cancel stops the running download, not just its coroutine`() {
+    val cache = LookaheadCache(
+      context = ApplicationProvider.getApplicationContext(),
+      maxSizeBytes = 4L * 1024L * 1024L,
+      cacheDirName = "writer-cancel-${System.nanoTime()}"
+    )
+    val source = TricklingDataSource()
+    val writer = LookaheadCacheWriter.create(
+      cache = cache,
+      httpFactory = androidx.media3.datasource.DataSource.Factory { source },
+      isOnCellular = { false }
+    )
+    try {
+      // The window is the tracks ahead of the current one.
+      writer.reschedule(listOf(httpTrack("current"), httpTrack("slow")), currentIndex = 0, lookaheadCount = 1)
+      assertTrue("the download must have opened its source", source.opened.await(5, TimeUnit.SECONDS))
+
+      writer.cancel()
+
+      assertTrue("a cancelled write closes its source", source.closed.await(5, TimeUnit.SECONDS))
+    } finally {
+      writer.release()
+      cache.release()
+    }
+  }
+
+  /** A source that hands out one byte at a time, forever, until closed. */
+  private class TricklingDataSource : androidx.media3.datasource.DataSource {
+    val opened = CountDownLatch(1)
+    val closed = CountDownLatch(1)
+    private var uri: android.net.Uri? = null
+
+    override fun addTransferListener(transferListener: androidx.media3.datasource.TransferListener) {}
+    override fun open(dataSpec: androidx.media3.datasource.DataSpec): Long {
+      uri = dataSpec.uri
+      opened.countDown()
+      return androidx.media3.common.C.LENGTH_UNSET.toLong()
+    }
+    override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+      if (length == 0) return 0
+      Thread.sleep(2)
+      buffer[offset] = 0
+      return 1
+    }
+    override fun getUri(): android.net.Uri? = uri
+    override fun close() {
+      closed.countDown()
+    }
+  }
+
+}