react-native-queue-player 1.1.2 → 2.0.0

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

@@ -2,8 +2,10 @@ package com.margelo.nitro.queueplayer
 
 import androidx.media3.common.util.UnstableApi
 import androidx.test.core.app.ApplicationProvider
+import kotlinx.coroutines.runBlocking
 import org.junit.After
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNotEquals
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertNull
@@ -70,7 +72,7 @@ class TrackPlayerLookaheadConfigTest {
     // Size is configure-time (PlayerConfig.lookaheadCacheMaxSizeMb), not a
     // runtime dimension. Unset → 100 MB default; set → reflected read-only.
     player.configureInternal(emptyConfig(), context())
-    assertEquals(100.0, player.getLookaheadCacheStatus().maxSizeMb, 0.001)
+    assertEquals(100.0, player.buildCacheStatusSnapshot().maxSizeMb, 0.001)
 
     player.destroyInternal()
     serviceHandle.destroy()
@@ -79,12 +81,14 @@ class TrackPlayerLookaheadConfigTest {
       PlayerConfig(
         httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
         networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
-        visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = 250.0, lookaheadCacheEvictionPolicy = null,
+        voiceVocabularyDonationEnabled = null,
+        visualizationEnabled = null, clampSeekToBuffered = null,
+        lookaheadCacheMaxSizeMb = 250.0, lookaheadCacheEvictionPolicy = null,
         progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
       ),
       context()
     )
-    assertEquals(250.0, player.getLookaheadCacheStatus().maxSizeMb, 0.001)
+    assertEquals(250.0, player.buildCacheStatusSnapshot().maxSizeMb, 0.001)
   }
 
   @Test
@@ -115,39 +119,263 @@ class TrackPlayerLookaheadConfigTest {
     assertNotNull(player.lookaheadCache)
   }
 
-  private fun configWithPolicy(policy: EvictionPolicy) = PlayerConfig(
+  private fun configWithPolicy(policy: EvictionPolicy, maxSizeMb: Double? = null) = PlayerConfig(
     httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
     networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
-    visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null,
+    voiceVocabularyDonationEnabled = null,
+    visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = maxSizeMb,
     lookaheadCacheEvictionPolicy = policy,
     progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
   )
 
+  @Test
+  fun `re-configuring with an unchanged policy keeps the cache`() {
+    // The policy comparison reads what the live cache was built with, not the
+    // in-memory config, which starts at the LRU default on every player.
+    player.configureInternal(configWithPolicy(EvictionPolicy.FIFO), context())
+    val first = player.lookaheadCache?.simpleCache
+    assertNotNull(first)
+
+    player.destroyInternal()
+    serviceHandle.destroy()
+    player = TrackPlayer()
+    serviceHandle = bindPlaybackServiceForTest(player, context())
+    player.configureInternal(configWithPolicy(EvictionPolicy.FIFO), context())
+
+    assertSame(
+      "an unchanged policy must not discard the shared cache",
+      first, player.lookaheadCache?.simpleCache
+    )
+  }
+
+  /**
+   * With no live cache in the process, the policy the directory was built
+   * with is read from prefs. A previous process is stood in for by a cache
+   * built and populated here, then released from the process-wide map; the
+   * span it holds is what a discard removes and a kept cache still serves.
+   */
+  @Test
+  fun `a policy recorded by a previous process is read from disk`() {
+    val ctx = context()
+    val url = "https://example.com/previous.m4a"
+    seedCacheFromAPreviousProcess(url, EvictionPolicy.FIFO)
+
+    player.configureInternal(configWithPolicy(EvictionPolicy.LRU), ctx)
+
+    assertTrue(
+      "the recorded policy differs from the requested one, so the old cache is discarded",
+      player.lookaheadCache!!.simpleCache.getCachedSpans(url).isEmpty())
+  }
+
+  @Test
+  fun `a policy recorded by a previous process that matches keeps the cache`() {
+    val ctx = context()
+    val url = "https://example.com/previous.m4a"
+    seedCacheFromAPreviousProcess(url, EvictionPolicy.FIFO)
+
+    player.configureInternal(configWithPolicy(EvictionPolicy.FIFO), ctx)
+
+    assertFalse(
+      "an unchanged policy keeps the cache and its spans",
+      player.lookaheadCache!!.simpleCache.getCachedSpans(url).isEmpty())
+  }
+
+  /**
+   * Build a cache under [policy], commit one span for [url], then leave the
+   * process with no live instance and prefs recording [policy] — the state
+   * the next launch finds.
+   */
+  private fun seedCacheFromAPreviousProcess(url: String, policy: EvictionPolicy) {
+    val ctx = context()
+    player.configureInternal(configWithPolicy(policy), ctx)
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(enabled = false, lookaheadCount = 0.0, allowsCellularAccess = null)
+    )
+    writeSpansAndListSurvivors(listOf(url))
+    val dir = player.lookaheadCache!!.cacheDir
+    player.destroyInternal()
+    serviceHandle.destroy()
+    LookaheadCache.releaseSharedInstance(dir)
+    ctx.getSharedPreferences("rnqp_lookahead_cache", android.content.Context.MODE_PRIVATE)
+      .edit().putString("eviction_policy", policy.name).commit()
+    player = TrackPlayer()
+    serviceHandle = bindPlaybackServiceForTest(player, ctx)
+  }
+
+  private fun track(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
+  )
+
+  // --- cache protection window
+
+  /**
+   * The window is observed through the evictor: five 400 KB tracks against a
+   * 1 MB budget under FIFO leave exactly the protected ones — the one behind the
+   * playhead, the playing one and `lookaheadCount` ahead — on disk.
+   */
+  @Test
+  fun `the protection window keeps the playing track and its neighbours through eviction`() {
+    player.configureInternal(configWithPolicy(EvictionPolicy.FIFO, maxSizeMb = 1.0), context())
+    // The window is refreshed whether or not prefetch is enabled; disabled,
+    // the writer fetches nothing and the evictor is the only thing that
+    // decides which spans survive.
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(enabled = false, lookaheadCount = 1.0, allowsCellularAccess = null)
+    )
+    player.setQueueInternal((1..5).map { track("t$it") }, startAtIndex = 2)
+
+    val survivors = writeSpansAndListSurvivors((1..5).map { "https://example.com/t$it.m4a" })
+
+    assertEquals(
+      "t1 is the oldest unprotected entry and t5 lands over budget with nothing else to take",
+      listOf("https://example.com/t2.m4a", "https://example.com/t3.m4a", "https://example.com/t4.m4a"),
+      survivors)
+  }
+
+  @Test
+  fun `an out-of-range lookahead count clamps the protection window`() {
+    // lookaheadCount crosses from JS as a Double. The window drops non-finite
+    // values before any `toInt()`, and clamps a finite one to the queue and
+    // the protected-ahead ceiling before it is added to the index — so every
+    // one of these yields a well-formed set rather than a thrown subList.
+    player.configureInternal(configWithPolicy(EvictionPolicy.FIFO, maxSizeMb = 1.0), context())
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(enabled = false, lookaheadCount = 0.0, allowsCellularAccess = null)
+    )
+    player.setQueueInternal((1..5).map { track("t$it") }, startAtIndex = 2)
+
+    listOf(Double.POSITIVE_INFINITY, Double.NaN, Double.MAX_VALUE, -1.0).forEach { count ->
+      player.setLookaheadCacheInternal(
+        LookaheadCacheConfig(enabled = false, lookaheadCount = count, allowsCellularAccess = null)
+      )
+    }
+    // -1.0 was applied last: a count of zero ahead protects t2 and t3 only.
+    val survivors = writeSpansAndListSurvivors((1..5).map { "https://example.com/t$it.m4a" })
+
+    assertEquals(listOf("https://example.com/t2.m4a", "https://example.com/t3.m4a"), survivors)
+  }
+
+  /** Commit one 400 KB span per url in order and return the urls still cached. */
+  private fun writeSpansAndListSurvivors(urls: List<String>): List<String> {
+    val cache = player.lookaheadCache!!.simpleCache
+    val spanBytes = 400L * 1024
+    for (url in urls) {
+      // The write lock a CacheDataSink would hold: startFile requires it.
+      val hole = cache.startReadWrite(url, 0, spanBytes)
+      val file = cache.startFile(url, 0, spanBytes)
+      file.writeBytes(ByteArray(spanBytes.toInt()))
+      cache.commitFile(file, spanBytes)
+      cache.releaseHoleSpan(hole)
+    }
+    return urls.filter { cache.getCachedSpans(it).isNotEmpty() }
+  }
+
   // --- setLookaheadCacheInternal
 
   @Test
-  fun `setLookaheadCacheInternal disable tears down writer but keeps cache`() {
-    // Deferred-rebuild contract: disabling stops new prefetches but
-    // leaves the cache instance alive so the player's MediaSource.Factory
-    // can still read existing entries. Cache is fully released on the
-    // next destroy() / configure() cycle.
+  fun `setLookaheadCacheInternal disable tears down writer and stops serving reads`() {
+    // Disabling stops new prefetches and routes the player's reads to the
+    // origin; the cache instance stays alive (one per directory) and is
+    // released on the next destroy() / configure() cycle.
     player.configureInternal(emptyConfig(), context())
     val cacheBeforeDisable = player.lookaheadCache
     assertNotNull(cacheBeforeDisable)
     assertNotNull(player.lookaheadCacheWriter)
+    assertTrue("enabled: playback reads go through the cache", cacheBeforeDisable!!.servesPlayback)
 
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = false, lookaheadCount = 3.0
+        enabled = false, lookaheadCount = 3.0,
+        allowsCellularAccess = null
       )
     )
 
-    assertSame(
-      "cache must stay alive — player's MediaSource.Factory still reads it",
-      cacheBeforeDisable, player.lookaheadCache
-    )
+    assertSame("the cache instance stays alive", cacheBeforeDisable, player.lookaheadCache)
     assertNull("writer torn down — no new prefetches", player.lookaheadCacheWriter)
+    assertFalse("disabled: playback reads go to the origin", cacheBeforeDisable.servesPlayback)
     assertEquals(false, player.lookaheadConfig.enabled)
+
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(enabled = true, lookaheadCount = 3.0, allowsCellularAccess = null)
+    )
+    assertTrue("re-enabled: reads go through the cache again", cacheBeforeDisable.servesPlayback)
+  }
+
+  // --- allowsCellularAccess
+
+  @Test
+  fun `configure builds the writer permitting cellular by default`() {
+    player.configureInternal(emptyConfig(), context())
+
+    assertEquals(true, player.lookaheadCacheWriter?.allowsCellularAccess)
+  }
+
+  @Test
+  fun `configure carries a non-default cellular policy into the writer`() {
+    player.lookaheadConfig = LookaheadCacheConfig(
+      enabled = true, lookaheadCount = 3.0, allowsCellularAccess = false
+    )
+
+    player.configureInternal(emptyConfig(), context())
+
+    assertEquals(false, player.lookaheadCacheWriter?.allowsCellularAccess)
+  }
+
+  @Test
+  fun `configure starts a transport monitor and destroy stops it`() {
+    player.configureInternal(emptyConfig(), context())
+    assertNotNull(player.cellularTransportMonitor)
+
+    player.destroyInternal()
+
+    assertNull(player.cellularTransportMonitor)
+  }
+
+  @Test
+  fun `setLookaheadCacheInternal applies allowsCellularAccess to the live writer`() {
+    player.configureInternal(emptyConfig(), context())
+    val writer = player.lookaheadCacheWriter
+    assertNotNull(writer)
+
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(
+        enabled = true, lookaheadCount = 3.0, allowsCellularAccess = false
+      )
+    )
+
+    assertSame("the writer is reused — only its policy changes", writer, player.lookaheadCacheWriter)
+    assertEquals(false, writer?.allowsCellularAccess)
+
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(
+        enabled = true, lookaheadCount = 3.0, allowsCellularAccess = true
+      )
+    )
+
+    assertEquals(true, writer?.allowsCellularAccess)
+  }
+
+  @Test
+  fun `a writer rebuilt by an enable flip carries the current cellular policy`() {
+    player.configureInternal(emptyConfig(), context())
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(
+        enabled = false, lookaheadCount = 3.0, allowsCellularAccess = false
+      )
+    )
+    assertNull(player.lookaheadCacheWriter)
+
+    player.setLookaheadCacheInternal(
+      LookaheadCacheConfig(
+        enabled = true, lookaheadCount = 3.0, allowsCellularAccess = false
+      )
+    )
+
+    assertEquals(false, player.lookaheadCacheWriter?.allowsCellularAccess)
   }
 
   @Test
@@ -164,7 +392,8 @@ class TrackPlayerLookaheadConfigTest {
     // Disable → writer released, cache kept for reads.
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = false, lookaheadCount = 3.0
+        enabled = false, lookaheadCount = 3.0,
+        allowsCellularAccess = null
       )
     )
     assertNull("disable releases the writer", player.lookaheadCacheWriter)
@@ -173,7 +402,8 @@ class TrackPlayerLookaheadConfigTest {
     // Re-enable → writer rebuilt at runtime, same cache, no configure().
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = true, lookaheadCount = 5.0
+        enabled = true, lookaheadCount = 5.0,
+        allowsCellularAccess = null
       )
     )
     assertNotNull(
@@ -190,7 +420,8 @@ class TrackPlayerLookaheadConfigTest {
     // Toggle off again → writer released once more (clean repeatable switch).
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = false, lookaheadCount = 5.0
+        enabled = false, lookaheadCount = 5.0,
+        allowsCellularAccess = null
       )
     )
     assertNull("second disable releases the writer again", player.lookaheadCacheWriter)
@@ -203,16 +434,21 @@ class TrackPlayerLookaheadConfigTest {
     // (built even when disabled) so the runtime enable can attach a writer.
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = false, lookaheadCount = 3.0
+        enabled = false, lookaheadCount = 3.0,
+        allowsCellularAccess = null
       )
     )
     player.configureInternal(emptyConfig(), context())
     assertNotNull("cache is built even when disabled at configure", player.lookaheadCache)
     assertNull("no writer while disabled", player.lookaheadCacheWriter)
+    assertFalse(
+      "built disabled: the player's reads go to the origin",
+      player.lookaheadCache!!.servesPlayback)
 
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = true, lookaheadCount = 4.0
+        enabled = true, lookaheadCount = 4.0,
+        allowsCellularAccess = null
       )
     )
     assertNotNull(
@@ -230,7 +466,8 @@ class TrackPlayerLookaheadConfigTest {
 
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = true, lookaheadCount = 7.0
+        enabled = true, lookaheadCount = 7.0,
+        allowsCellularAccess = null
       )
     )
 
@@ -253,7 +490,7 @@ class TrackPlayerLookaheadConfigTest {
     val writer = player.lookaheadCacheWriter
     assertNotNull(writer)
 
-    player.clearLookaheadCacheInternal()
+    runBlocking { player.clearLookaheadCacheInternal()?.join() }
 
     assertNotNull("cache stays — clear is wipe, not destroy", player.lookaheadCache)
     assertNotNull("writer stays — clear is wipe, not destroy", player.lookaheadCacheWriter)
@@ -269,7 +506,7 @@ class TrackPlayerLookaheadConfigTest {
   @Test
   fun `getLookaheadCacheStatus on a fresh player reports defaults`() {
     player.configureInternal(emptyConfig(), context())
-    val status = player.getLookaheadCacheStatus()
+    val status = player.buildCacheStatusSnapshot()
     assertEquals(true, status.enabled)
     assertEquals(0.0, status.currentSizeMb, 0.001)
     assertEquals(100.0, status.maxSizeMb, 0.001)
@@ -282,10 +519,11 @@ class TrackPlayerLookaheadConfigTest {
     player.configureInternal(emptyConfig(), context())
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = false, lookaheadCount = 0.0
+        enabled = false, lookaheadCount = 0.0,
+        allowsCellularAccess = null
       )
     )
-    val status = player.getLookaheadCacheStatus()
+    val status = player.buildCacheStatusSnapshot()
     assertEquals(false, status.enabled)
     assertEquals(0.0, status.currentSizeMb, 0.001)
     // maxSizeMb is the configure-time budget (100 MB default), reported
@@ -298,7 +536,7 @@ class TrackPlayerLookaheadConfigTest {
   @Test
   fun `re-configure with changed httpHeaders rebuilds the player (writer + cache)`() {
     player.configureInternal(
-      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-1"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null),
+      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-1"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null),
       context()
     )
     val firstWriter = player.lookaheadCacheWriter
@@ -307,15 +545,14 @@ class TrackPlayerLookaheadConfigTest {
     assertNotNull(firstCache)
 
     player.configureInternal(
-      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-2"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null),
+      PlayerConfig(httpHeaders = mapOf("X-Auth" to "token-2"), userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null),
       context()
     )
 
-    // previously only the writer was
-    // rebuilt, leaving the player's MediaSource.Factory bound to
-    // the OLD headers. Now we rebuild the entire player (and the
-    // cache + writer with it) so subsequent playback requests
-    // carry the new auth. The on-disk cache directory is
+    // A header change on re-configure rebuilds the entire player (and
+    // the cache + writer with it), not just the writer, so the player's
+    // MediaSource.Factory and every subsequent playback request carry
+    // the new auth. The on-disk cache directory is
     // preserved across the rebuild — `SimpleCache.release()` only
     // frees the in-memory instance + file lock; entries stay on
     // disk and the next `LookaheadCache(...)` constructor reads
@@ -339,7 +576,7 @@ class TrackPlayerLookaheadConfigTest {
     // simulated here by `destroyInternal` between
     // `configureInternal` calls) yields a fresh writer instance,
     // even when headers are unchanged.
-    val cfg = PlayerConfig(httpHeaders = mapOf("X-Auth" to "token"), userAgent = "rnqp/test", autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
+    val cfg = PlayerConfig(httpHeaders = mapOf("X-Auth" to "token"), userAgent = "rnqp/test", autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
     player.configureInternal(cfg, context())
     val firstWriter = player.lookaheadCacheWriter
 
@@ -369,7 +606,8 @@ class TrackPlayerLookaheadConfigTest {
     // Step 1: disable. Writer torn down, cache stays.
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = false, lookaheadCount = 3.0
+        enabled = false, lookaheadCount = 3.0,
+        allowsCellularAccess = null
       )
     )
     assertSame(firstCache, player.lookaheadCache)
@@ -379,7 +617,8 @@ class TrackPlayerLookaheadConfigTest {
     // same cache instance.
     player.setLookaheadCacheInternal(
       LookaheadCacheConfig(
-        enabled = true, lookaheadCount = 7.0
+        enabled = true, lookaheadCount = 7.0,
+        allowsCellularAccess = null
       )
     )
     assertSame("re-enable reuses the same cache instance", firstCache, player.lookaheadCache)
@@ -402,9 +641,9 @@ class TrackPlayerLookaheadConfigTest {
   @Test
   fun `clearLookaheadCacheInternal then status snapshot reports zero size + empty currentlyCaching`() {
     player.configureInternal(emptyConfig(), context())
-    player.clearLookaheadCacheInternal()
+    runBlocking { player.clearLookaheadCacheInternal()?.join() }
 
-    val status = player.getLookaheadCacheStatus()
+    val status = player.buildCacheStatusSnapshot()
     assertEquals(true, status.enabled)
     assertEquals(0.0, status.currentSizeMb, 0.001)
     assertEquals(0.0, status.tracksFullyCached, 0.001)
@@ -413,5 +652,5 @@ class TrackPlayerLookaheadConfigTest {
 
   // --- Helpers
 
-  private fun emptyConfig() = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
+  private fun emptyConfig() = PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null)
 }

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

@@ -35,7 +35,9 @@ class TrackPlayerMutationTest {
   private fun track(id: String) = TrackItem(
     id = id, url = "https://example.com/$id.m4a",
     title = null, artist = null, album = null,
-    duration = null, artworkUrl = null, extras = null
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null
   )
 
   private lateinit var serviceHandle: PlaybackServiceTestHandle
@@ -45,7 +47,7 @@ class TrackPlayerMutationTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     player.setQueueInternal((1..5).map { track("t$it") })
     // cur defaults to 0 after setQueue; tests needing mid-queue
@@ -127,7 +129,7 @@ class TrackPlayerMutationTest {
     val freshHandle = bindPlaybackServiceForTest(fresh, context())
     try {
       fresh.configureInternal(
-        PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+        PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
       )
       assertEquals(-1, fresh.currentTrackIndex)
       assertEquals(Player.STATE_IDLE, fresh.player!!.playbackState)

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

@@ -34,7 +34,8 @@ class TrackPlayerProgressThrottleTest {
   private fun config(foregroundMs: Double?, backgroundMs: Double? = null) = PlayerConfig(
     httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
     networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
-    visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
+    voiceVocabularyDonationEnabled = null,
+      visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
     progressUpdateIntervalMs = foregroundMs, backgroundProgressUpdateIntervalMs = backgroundMs, placeholderArtworkUri = null, skipToPreviousBehavior = null
   )
 

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

@@ -28,9 +28,11 @@ class TrackPlayerQueueChangeTest {
   private lateinit var serviceHandle: PlaybackServiceTestHandle
 
   private data class QueueEvent(
+    /** The mirror after applying this event's delta. */
     val queue: List<TrackItem>,
     val index: Int,
     val reason: QueueChangeReason,
+    val delta: QueueChangeDelta,
   )
 
   private fun context() =
@@ -40,6 +42,8 @@ class TrackPlayerQueueChangeTest {
     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,
   )
 
   @Before
@@ -47,7 +51,7 @@ class TrackPlayerQueueChangeTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     player.setQueueInternal((1..5).map { track("t$it") })
   }
@@ -62,12 +66,90 @@ class TrackPlayerQueueChangeTest {
    *  therefore not captured — onQueueChange does not auto-fire). */
   private fun capture(): Pair<MutableList<QueueEvent>, () -> Unit> {
     val events = mutableListOf<QueueEvent>()
-    val dispose = player.onQueueChange { queue, idx, reason ->
-      events.add(QueueEvent(queue.toList(), idx.toInt(), reason))
+    // Mirror the queue by applying each delta, the way a consumer must. Every
+    // assertion below reads that mirror, so it doubles as proof the delta
+    // carries enough to reconstruct the queue.
+    var mirror = player.tracks.toList()
+    val dispose = player.onQueueChange { delta, idx, reason ->
+      mirror = applyDelta(mirror, delta, reason)
+      events.add(QueueEvent(mirror, idx.toInt(), reason, delta))
     }
     return events to dispose
   }
 
+  /** The reference delta application, mirroring what `useQueue()` does in JS. */
+  private fun applyDelta(
+    previous: List<TrackItem>,
+    delta: QueueChangeDelta,
+    reason: QueueChangeReason
+  ): List<TrackItem> = when (reason) {
+    QueueChangeReason.SET_QUEUE -> delta.inserted.toList()
+    QueueChangeReason.CLEAR -> emptyList()
+    QueueChangeReason.ADD -> previous.toMutableList().apply {
+      addAll(delta.insertedAt.toInt(), delta.inserted.toList())
+    }
+    QueueChangeReason.REMOVE -> {
+      val drop = delta.removed.map { it.toInt() }.toSet()
+      previous.filterIndexed { i, _ -> i !in drop }
+    }
+    QueueChangeReason.MOVE -> previous.toMutableList().apply {
+      add(delta.movedTo.toInt(), removeAt(delta.movedFrom.toInt()))
+    }
+    QueueChangeReason.SHUFFLE -> delta.order.map { previous[it.toInt()] }
+  }
+
+  @Test
+  fun `a mirror built only from deltas matches the live queue`() {
+    val (events, dispose) = capture()
+    player.setQueueInternal((1..6).map { track("s$it") }, startAtIndex = 0)
+    player.addToQueueInternal(listOf(track("added")), insertBefore = 2)
+    player.removeFromQueueInternal(listOf(4, 0))
+    player.moveInQueueInternal(3, 1)
+    dispose()
+
+    assertEquals(
+      "the delta stream must reconstruct the queue exactly",
+      player.tracks.map { it.id },
+      events.last().queue.map { it.id }
+    )
+  }
+
+  @Test
+  fun `each emit advances the revision by one`() {
+    val (events, dispose) = capture()
+    player.setQueueInternal((1..3).map { track("r$it") })
+    player.addToQueueInternal(listOf(track("r4")), insertBefore = null)
+    player.clearQueueInternal()
+    dispose()
+
+    val revisions = events.map { it.delta.revision.toInt() }
+    val first = revisions.first()
+    assertEquals(revisions.indices.map { first + it }, revisions)
+  }
+
+  /**
+   * `destroy` and `configure` clear the queue without an emit; the revision
+   * the next emit carries skips one, which is the signal a delta mirror
+   * re-reads on.
+   */
+  @Test
+  fun `a silent clear leaves a revision gap for the next emit`() {
+    val (events, dispose) = capture()
+    player.setQueueInternal((1..3).map { track("g$it") })
+    val before = events.last().delta.revision.toInt()
+
+    player.destroyInternal()
+    serviceHandle.destroy()
+    serviceHandle = bindPlaybackServiceForTest(player, context())
+    player.configureInternal(
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+    )
+    player.setQueueInternal(listOf(track("after")))
+    dispose()
+
+    assertEquals(before + 2, events.last().delta.revision.toInt())
+  }
+
   // --- one emission per mutation, with the post-mutation snapshot
 
   @Test