react-native-queue-player 1.1.2 → 2.0.0

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

@@ -45,7 +45,9 @@ class TrackPlayerQueueTest {
   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
@@ -55,7 +57,7 @@ class TrackPlayerQueueTest {
     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()
     )
   }
 
@@ -128,13 +130,15 @@ class TrackPlayerQueueTest {
   // --- getQueue / getCurrentTrackIndex
 
   @Test
-  fun `getQueue returns the track list as an array`() {
+  fun `setQueueInternal stores the tracks in order`() {
+    // `getQueue()` itself returns a Nitro Promise, which cannot be resolved
+    // from Robolectric; it reads this list on main, and the demo cycle covers
+    // the bridged call.
     val tracks = (1..3).map { track("t$it") }
     player.setQueueInternal(tracks)
 
-    val result = player.getQueue()
-    assertEquals(3, result.size)
-    assertEquals("t1", result[0].id)
+    assertEquals(3, player.tracks.size)
+    assertEquals("t1", player.tracks[0].id)
   }
 
   @Test
@@ -275,7 +279,7 @@ class TrackPlayerQueueTest {
   fun `skipToIndex after setQueue issues the ExoPlayer seek`() {
     // After setQueue the MediaItem timeline has 3 entries, so the
     // `target < mediaItemCount` guard in skipToIndexInternal no
-    // longer short-circuits — confirms the skip → seek plumbing
+    // longer short-circuits — confirms the skip → seek path
     // survives once the timeline is populated.
     player.setQueueInternal((1..3).map { track("t$it") })
 

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

@@ -41,7 +41,8 @@ class TrackPlayerReadersTest {
       PlayerConfig(
         httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
         networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
-        visualizationEnabled = null, clampSeekToBuffered = null,
+        voiceVocabularyDonationEnabled = null,
+      visualizationEnabled = null, clampSeekToBuffered = null,
         lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
       ),
       context()

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

@@ -40,7 +40,9 @@ class TrackPlayerSkipCapabilityTest {
   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
   )
 
   /** Drain main-looper posts so the auto-fire-on-subscribe lands. */
@@ -53,7 +55,7 @@ class TrackPlayerSkipCapabilityTest {
     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()
     )
   }
 
@@ -318,7 +320,7 @@ class TrackPlayerSkipCapabilityTest {
     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()
     )
   }
 
@@ -326,10 +328,25 @@ class TrackPlayerSkipCapabilityTest {
 
   private fun configureRestart() {
     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 = SkipToPreviousBehavior.RESTART_OR_PREVIOUS), 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 = SkipToPreviousBehavior.RESTART_OR_PREVIOUS), context()
     )
   }
 
+  @Test
+  fun `restart mode — addToQueueInternal into empty queue keeps Previous false (cur stays -1)`() {
+    configureRestart()
+    val emissions = mutableListOf<SkipCapability>()
+    player.onSkipCapabilityChange { cap -> emissions.add(cap) }
+    flushMain()
+    emissions.clear()
+
+    player.addToQueueInternal((1..3).map { track("t$it") }, insertBefore = null)
+    // No loaded track: nothing to restart and nothing before it, so the
+    // lock-screen Previous control stays disabled until skipToIndex.
+    assertEquals(false, player.getCanSkipPrevious())
+    assertEquals(emptyList<SkipCapability>(), emissions)
+  }
+
   @Test
   fun `restart mode forces canSkipPrevious true at index 0`() {
     configureRestart()
@@ -360,4 +377,73 @@ class TrackPlayerSkipCapabilityTest {
       emissions.last().canSkipPrevious
     )
   }
+
+  // --- cast index writes keep the capability current
+
+  @Test
+  fun `emitRemoteTrackChange to the last index disables Next`() {
+    player.setQueueInternal((1..3).map { track("t$it") })
+    assertEquals(true, player.getCanSkipNext())
+
+    // The receiver advanced to the last track; the lock-screen Next
+    // control must grey out exactly as it does for a local advance.
+    player.emitRemoteTrackChange(2)
+    assertEquals(2, player.currentTrackIndex)
+    assertEquals(false, player.getCanSkipNext())
+    assertEquals(true, player.getCanSkipPrevious())
+  }
+
+  @Test
+  fun `emitRemoteTrackChange emits the capability change`() {
+    player.setQueueInternal((1..3).map { track("t$it") })
+    val emissions = mutableListOf<SkipCapability>()
+    player.onSkipCapabilityChange { cap -> emissions.add(cap) }
+    flushMain()
+    emissions.clear()
+
+    player.emitRemoteTrackChange(2)
+    flushMain()
+    assertEquals(
+      listOf(SkipCapability(canSkipPrevious = true, canSkipNext = false)),
+      emissions
+    )
+  }
+
+  @Test
+  fun `emitRemoteTrackChange classifies the new track's source`() {
+    // A local file at index 2, streaming tracks elsewhere: the source the
+    // JS side reads must follow the index the receiver moved to.
+    val local = TrackItem(
+      id = "local", url = "file:///tmp/local.m4a",
+      title = null, artist = null, album = null,
+      duration = null, artworkUrl = null, extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
+    )
+    player.setQueueInternal(listOf(track("t1"), track("t2"), local))
+    assertEquals(TrackSource.STREAMING, player.getCurrentTrackSource())
+
+    player.emitRemoteTrackChange(2)
+    assertEquals(TrackSource.LOCAL, player.getCurrentTrackSource())
+  }
+
+  @Test
+  fun `resumeLocalAfterCast lands on the handback index with its capability and source`() {
+    val local = TrackItem(
+      id = "local", url = "file:///tmp/local.m4a",
+      title = null, artist = null, album = null,
+      duration = null, artworkUrl = null, extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
+    )
+    player.setQueueInternal(listOf(track("t1"), track("t2"), local))
+    assertEquals(true, player.getCanSkipNext())
+    assertEquals(TrackSource.STREAMING, player.getCurrentTrackSource())
+
+    player.resumeLocalAfterCast(trackIndex = 2, positionMs = 0L)
+    flushMain()
+    assertEquals(2, player.currentTrackIndex)
+    assertEquals(false, player.getCanSkipNext())
+    assertEquals(TrackSource.LOCAL, player.getCurrentTrackSource())
+  }
 }

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

@@ -15,9 +15,8 @@ import org.robolectric.annotation.Config
  * [TrackPlayer]. `QueueSkipArithmeticTest` covers the raw
  * arithmetic; these tests cover the adapter layer:
  *
- * - `computeNextIndex` / `computePreviousIndex` — read
- *   `repeatModeState` + `currentTrackIndex` + `tracks.size` and
- *   delegate to [QueueSkipArithmetic].
+ * - `computeNextIndex` — reads `repeatModeState` + `currentTrackIndex`
+ *   + `tracks.size` and delegates to [QueueSkipArithmetic].
  * - `skipToNextInternal` / `skipToPreviousInternal` /
  *   `skipToIndexInternal` — advance `currentTrackIndex` when the
  *   arithmetic returns a target, no-op when it returns null. Under
@@ -41,7 +40,9 @@ class TrackPlayerSkipTest {
   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
@@ -51,7 +52,7 @@ class TrackPlayerSkipTest {
     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.tracks = (1..5).map { track("t$it") }
     player.currentTrackIndex = 2 // mid-queue default for most cases
@@ -63,7 +64,7 @@ class TrackPlayerSkipTest {
     serviceHandle.destroy()
   }
 
-  // --- computeNextIndex / computePreviousIndex (adapter)
+  // --- computeNextIndex (adapter)
 
   @Test
   fun `computeNextIndex reads repeatModeState`() {
@@ -77,18 +78,6 @@ class TrackPlayerSkipTest {
     assertEquals(3, player.computeNextIndex())
   }
 
-  @Test
-  fun `computePreviousIndex reads repeatModeState`() {
-    player.repeatModeState = RepeatMode.OFF
-    assertEquals(1, player.computePreviousIndex())
-
-    player.repeatModeState = RepeatMode.TRACK
-    assertEquals(1, player.computePreviousIndex())
-
-    player.repeatModeState = RepeatMode.QUEUE
-    assertEquals(1, player.computePreviousIndex())
-  }
-
   @Test
   fun `computeNextIndex returns null at end under REPEAT OFF`() {
     player.repeatModeState = RepeatMode.OFF
@@ -103,13 +92,6 @@ class TrackPlayerSkipTest {
     assertEquals(0, player.computeNextIndex())
   }
 
-  @Test
-  fun `computePreviousIndex wraps to last under REPEAT QUEUE at index 0`() {
-    player.repeatModeState = RepeatMode.QUEUE
-    player.currentTrackIndex = 0
-    assertEquals(4, player.computePreviousIndex())
-  }
-
   // --- skipToNextInternal / skipToPreviousInternal
 
   @Test
@@ -293,7 +275,7 @@ class TrackPlayerSkipTest {
 
   private fun configureSkipBehavior(behavior: SkipToPreviousBehavior?) {
     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 = behavior), 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 = behavior), context()
     )
     player.tracks = (1..5).map { track("t$it") }
   }

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

@@ -50,7 +50,7 @@ class TrackPlayerTransportTest {
     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()
     )
   }
 
@@ -80,7 +80,7 @@ class TrackPlayerTransportTest {
     // currentTrackIndex while the ExoPlayer is still IDLE.
     // iOS parity: paused-with-queue returns PAUSED, not NONE.
     player.tracks = listOf(
-      TrackItem("t1", "https://example.com/1.m4a", null, null, null, null, null, null)
+      TrackItem("t1", "https://example.com/1.m4a", null, null, null, null, null, null, null, null, null, null)
     )
     player.currentTrackIndex = 0
 
@@ -104,7 +104,7 @@ class TrackPlayerTransportTest {
     // on eventually-seekable content still lands. The reset-to-start protection
     // applies once the item is loaded (STATE_READY) and confirmed unseekable.
     player.setQueueInternal(
-      (1..3).map { TrackItem("t$it", "https://example.com/$it.m4a", null, null, null, null, null, null) }
+      (1..3).map { TrackItem("t$it", "https://example.com/$it.m4a", null, null, null, null, null, null, null, null, null, null) }
     )
     player.currentTrackIndex = 0
 

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

@@ -162,9 +162,6 @@ private class FakePlaybackEngineWithSinks : 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")
@@ -197,6 +194,5 @@ private class FakePlaybackEngineWithSinks : PlaybackEngine {
   override fun detachAudioBufferSink(sink: TeeAudioProcessor.AudioBufferSink) {
     if (attachedSinks.remove(sink)) detachCount++
   }
-  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/cast/FakeRemotePlayer.kt

@@ -9,10 +9,11 @@ import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.flow.asStateFlow
 
 /**
- * Test double for [CastSession.RemotePlayer]. Transport calls are no-ops;
- * the StateFlows are driveable via the public `_`-prefixed backing
- * fields; [mediaSessionPlayer] is injectable so bind tests can assert the
- * MediaSession swaps to it.
+ * Test double for [CastSession.RemotePlayer]. Transport calls record their
+ * name in [transportCalls]; the StateFlows are driveable via the public
+ * backing fields, or via [reportState] to mirror the real session's
+ * [hasReportedState] flag; [mediaSessionPlayer] is injectable so bind tests
+ * can assert the MediaSession swaps to it.
  */
 internal class FakeRemotePlayer(
   private val player: Player? = null,
@@ -36,15 +37,30 @@ internal class FakeRemotePlayer(
   override val mediaError: SharedFlow<RemoteMediaError> = backingError.asSharedFlow()
   override val seekCompleted: SharedFlow<Long> = backingSeek.asSharedFlow()
 
+  /** Transport calls in the order they arrived, for routing assertions. */
+  val transportCalls = mutableListOf<String>()
+
+  override var hasReportedState: Boolean = false
+
+  /**
+   * Drive the receiver state the way a live session does: a non-idle report
+   * sets [hasReportedState]. Set [backingState] directly to stage a state
+   * the receiver has not reported yet.
+   */
+  fun reportState(state: RemotePlaybackState) {
+    if (state != RemotePlaybackState.IDLE) hasReportedState = true
+    backingState.value = state
+  }
+
   override fun setVolume(value: Float) {}
   override fun close() {}
-  override fun play() {}
-  override fun pause() {}
-  override fun stop() {}
-  override fun seekTo(positionMs: Long) {}
-  override fun queueNext() {}
-  override fun queuePrev() {}
-  override fun skipToQueueIndex(index: Int) {}
+  override fun play() { transportCalls += "play" }
+  override fun pause() { transportCalls += "pause" }
+  override fun stop() { transportCalls += "stop" }
+  override fun seekTo(positionMs: Long) { transportCalls += "seekTo:$positionMs" }
+  override fun queueNext() { transportCalls += "queueNext" }
+  override fun queuePrev() { transportCalls += "queuePrev" }
+  override fun skipToQueueIndex(index: Int) { transportCalls += "skipToQueueIndex:$index" }
   override fun setPlaybackRate(rate: Float) {}
   override fun setRepeatMode(mode: RemoteRepeatMode) {}
 

package/android/src/test/java/com/margelo/nitro/queueplayer/cast/airplay/AirPlayMetadataSyncTest.kt

@@ -0,0 +1,303 @@
+package com.margelo.nitro.queueplayer.cast.airplay
+
+import android.net.Uri
+import android.os.Looper
+import androidx.media3.common.MediaItem
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Player
+import androidx.media3.common.SimpleBasePlayer
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import com.google.common.collect.ImmutableList
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.cancel
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
+import org.robolectric.annotation.Config
+import java.io.File
+import java.util.Base64
+import java.time.Duration
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+
+/**
+ * Receiver-display sync lifecycle: what reaches the receiver while a sync is
+ * running, and that nothing reaches it once the session has been torn down.
+ *
+ * The teardown cases drive `stop()` from a non-looper thread, which is where
+ * it comes from in production — the JS thread on a user disconnect, the
+ * native drain thread on receiver death.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class AirPlayMetadataSyncTest {
+
+  private lateinit var player: FakePlayer
+  private lateinit var target: RecordingTarget
+  private lateinit var sync: AirPlayMetadataSync
+  private val scope = CoroutineScope(Dispatchers.Main.immediate)
+
+  private fun context() = ApplicationProvider.getApplicationContext<android.content.Context>()
+
+  private fun idle() = shadowOf(Looper.getMainLooper()).idle()
+
+  private fun idleFor(ms: Long) =
+    shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(ms))
+
+  /** Runs [block] off the looper and waits for it, as a real teardown does. */
+  private fun offLooper(block: () -> Unit) {
+    val executor = Executors.newSingleThreadExecutor()
+    try {
+      executor.submit(block).get(5, TimeUnit.SECONDS)
+    } finally {
+      executor.shutdownNow()
+    }
+  }
+
+  /** Waits for work dispatched off the looper, e.g. the artwork fetch. */
+  private fun awaitTrue(timeoutMs: Long = 5_000, condition: () -> Boolean): Boolean {
+    val deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(timeoutMs)
+    while (System.nanoTime() < deadline) {
+      idle()
+      if (condition()) return true
+      Thread.sleep(20)
+    }
+    return condition()
+  }
+
+  @Before
+  fun setUp() {
+    player = FakePlayer(Looper.getMainLooper())
+    target = RecordingTarget()
+    sync = AirPlayMetadataSync(context(), target, player, scope)
+  }
+
+  @After
+  fun tearDown() {
+    sync.stop()
+    idle()
+    scope.cancel()
+  }
+
+  @Test
+  fun `start sends the current track metadata`() {
+    sync.start()
+    idle()
+
+    assertEquals(
+      listOf(Triple("Everlong", "Foo Fighters", "The Colour and the Shape")),
+      target.metadata,
+    )
+  }
+
+  @Test
+  fun `progress is pushed while playing`() {
+    sync.start()
+    idle()
+    val afterStart = target.progress.size
+
+    idleFor(11_000)
+
+    assertTrue(
+      "expected progress pushes while playing, got ${target.progress.size - afterStart}",
+      target.progress.size - afterStart >= 2,
+    )
+  }
+
+  @Test
+  fun `stop from another thread halts the progress loop`() {
+    sync.start()
+    idle()
+    idleFor(6_000)
+    assertTrue(target.progress.isNotEmpty())
+
+    offLooper { sync.stop() }
+    idle()
+    val atStop = target.progress.size
+
+    idleFor(30_000)
+
+    assertEquals(atStop, target.progress.size)
+  }
+
+  @Test
+  fun `a resume callback arriving after stop starts no progress loop`() {
+    sync.start()
+    idle()
+    player.emitPlayWhenReady(false)
+    idle()
+
+    // The resume lands while listener removal is still queued behind the
+    // off-looper stop, so it reaches startProgressTimer on a spent sync.
+    offLooper { sync.stop() }
+    player.emitPlayWhenReady(true)
+    idle()
+    val atStop = target.progress.size
+
+    idleFor(30_000)
+
+    assertEquals(atStop, target.progress.size)
+  }
+
+  @Test
+  fun `a track change arriving after stop pushes nothing`() {
+    sync.start()
+    idle()
+    val atStop = target.metadata.size
+
+    offLooper { sync.stop() }
+    player.emitTrackChange(trackMediaItem("Monkey Wrench", "Foo Fighters", "TCATS"))
+    idle()
+
+    assertEquals(atStop, target.metadata.size)
+  }
+
+  @Test
+  fun `artwork from a local file reaches the receiver while running`() {
+    player.emitTrackChange(
+      trackMediaItem("Everlong", "Foo Fighters", "TCATS", artworkUri = artworkFile())
+    )
+
+    sync.start()
+
+    assertTrue("artwork never arrived", awaitTrue { target.artwork.isNotEmpty() })
+  }
+
+  @Test
+  fun `artwork is not fetched after stop`() {
+    sync.start()
+    idle()
+
+    // Fired while listener removal is still queued behind the off-looper
+    // stop, so the fetch is reached on a spent sync.
+    offLooper { sync.stop() }
+    player.emitTrackChange(
+      trackMediaItem("Monkey Wrench", "Foo Fighters", "TCATS", artworkUri = artworkFile())
+    )
+
+    // Real elapsed time, not looper time: the fetch runs on Dispatchers.IO,
+    // so advancing the looper clock proves nothing about whether it ran.
+    assertFalse(
+      "artwork reached the receiver after stop",
+      awaitTrue(2_000) { target.artwork.isNotEmpty() },
+    )
+  }
+
+  @Test
+  fun `start after stop does nothing`() {
+    sync.start()
+    idle()
+    offLooper { sync.stop() }
+    idle()
+    val atStop = target.progress.size + target.metadata.size
+
+    sync.start()
+    idle()
+    idleFor(30_000)
+
+    assertEquals(atStop, target.progress.size + target.metadata.size)
+  }
+
+  private fun artworkFile(): Uri {
+    val file = File(context().cacheDir, "artwork.png")
+    if (!file.exists()) file.writeBytes(PNG_1X1)
+    return Uri.fromFile(file)
+  }
+
+  private class RecordingTarget : MetadataSyncTarget {
+    // The artwork fetch runs on Dispatchers.IO while the test thread reads
+    // these, so plain ArrayLists would be shared unsynchronised.
+    val metadata = CopyOnWriteArrayList<Triple<String?, String?, String?>>()
+    val progress = CopyOnWriteArrayList<Pair<Int, Int>>()
+    val artwork = CopyOnWriteArrayList<Int>()
+
+    override fun setMetadata(title: String?, artist: String?, album: String?) {
+      metadata += Triple(title, artist, album)
+    }
+
+    override fun setProgress(elapsedMs: Int, durationMs: Int) {
+      progress += elapsedMs to durationMs
+    }
+
+    override fun setArtwork(imageData: ByteArray, contentType: String) {
+      artwork += imageData.size
+    }
+  }
+
+  /**
+   * Player double exposing exactly what the sync reads: the current item's
+   * metadata, position, duration and whether playback is running. Each item
+   * carries its own period uid, so replacing it is delivered as a media-item
+   * transition rather than a timeline change.
+   */
+  private class FakePlayer(looper: Looper) : SimpleBasePlayer(looper) {
+    private var item: MediaItem =
+      trackMediaItem("Everlong", "Foo Fighters", "The Colour and the Shape")
+    private var playing = true
+
+    fun emitTrackChange(next: MediaItem) {
+      item = next
+      invalidateState()
+    }
+
+    fun emitPlayWhenReady(value: Boolean) {
+      playing = value
+      invalidateState()
+    }
+
+    override fun getState(): State =
+      State.Builder()
+        .setAvailableCommands(Player.Commands.Builder().addAllCommands().build())
+        .setPlaybackState(Player.STATE_READY)
+        .setPlayWhenReady(playing, Player.PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
+        .setPlaylist(
+          ImmutableList.of(
+            MediaItemData.Builder(item)
+              .setMediaItem(item)
+              .setDurationUs(300_000_000L)
+              .build()
+          )
+        )
+        .setCurrentMediaItemIndex(0)
+        .setContentPositionMs(1_000L)
+        .build()
+  }
+
+  private companion object {
+    /**
+     * A real 1x1 PNG — Robolectric decodes artwork through ImageIO, so a
+     * stub header fails to decode and the fetch reports no artwork.
+     */
+    val PNG_1X1: ByteArray = Base64.getDecoder().decode(
+      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+    )
+
+    fun trackMediaItem(
+      title: String,
+      artist: String,
+      album: String,
+      artworkUri: Uri? = null,
+    ): MediaItem =
+      MediaItem.Builder()
+        .setUri("https://example.invalid/${title.replace(' ', '-')}.mp3")
+        .setMediaMetadata(
+          MediaMetadata.Builder()
+            .setTitle(title)
+            .setArtist(artist)
+            .setAlbumTitle(album)
+            .apply { artworkUri?.let { setArtworkUri(it) } }
+            .build()
+        )
+        .build()
+  }
+}