react-native-queue-player 1.1.1 → 1.2.0

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/AirPlaySession.kt

@@ -6,6 +6,7 @@ import androidx.media3.exoplayer.audio.AudioSink
 import com.margelo.nitro.queueplayer.cast.CastSession
 import com.margelo.nitro.queueplayer.cast.MetadataAwareSession
 import kotlinx.coroutines.CoroutineScope
+import java.util.concurrent.atomic.AtomicReference
 
 /**
  * A live AirPlay 1 streaming session backed by libraop via [AirplayJNI].
@@ -25,15 +26,22 @@ class AirPlaySession(
     private val handle: Long,
     private val host: String,
     private val port: Int,
-) : CastSession.PcmStream(), MetadataAwareSession {
+) : CastSession.PcmStream(), MetadataAwareSession, MetadataSyncTarget {
 
     companion object {
         private const val TAG = "AirPlaySession"
     }
 
     private val sink = AirPlaySink(handle)
+
+    // Read by every sender, set by close() on whichever thread disconnected.
+    @Volatile
     private var closed = false
-    private var metadataSync: AirPlayMetadataSync? = null
+
+    // Swapped on the player's looper by onActivated, read and cleared on the
+    // disconnecting thread — the exchange has to be atomic or a teardown can
+    // read a stale null and leave the previous sync running.
+    private val metadataSync = AtomicReference<AirPlayMetadataSync?>()
 
     override fun audioSink(): AudioSink = sink
 
@@ -46,22 +54,29 @@ class AirPlaySession(
     }
 
     override fun onActivated(player: Player, scope: CoroutineScope) {
-        // Re-entrant safe: stop any prior sync before rebinding so a repeat
+        if (closed) return
+        // Stop any prior sync before starting the replacement, so a repeat
         // activation (the player swaps under a still-connected session) never
         // leaves an orphaned sync running against the previous player.
-        metadataSync?.stop()
-        metadataSync = AirPlayMetadataSync(context, this, player, scope).also { it.start() }
+        val next = AirPlayMetadataSync(context, this, player, scope)
+        metadataSync.getAndSet(next)?.stop()
+        next.start()
+        // A close() that ran while this was publishing exchanged out a null
+        // and tore down without seeing `next`, so re-check: otherwise a live
+        // sync stays bound to a closed session for the process lifetime.
+        if (closed) metadataSync.getAndSet(null)?.stop()
     }
 
     override fun onDeactivated() {
-        metadataSync?.stop()
-        metadataSync = null
+        metadataSync.getAndSet(null)?.stop()
     }
 
     override fun close() {
         if (closed) return
-        onDeactivated()
+        // Closed before the sync is torn down so an in-flight sender bails at
+        // its own guard rather than reaching a handle nativeDestroy has freed.
         closed = true
+        onDeactivated()
         Log.i(TAG, "Closing AirPlay session to $host:$port")
         // Release the sink BEFORE the native handle is torn down: this sets
         // the sink's volatile `released` flag so the renderer thread stops
@@ -73,20 +88,17 @@ class AirPlaySession(
         AirplayJNI.nativeDestroy(handle)
     }
 
-    /** Send DAAP metadata (title/artist/album) to the receiver. */
-    fun setMetadata(title: String?, artist: String?, album: String?) {
+    override fun setMetadata(title: String?, artist: String?, album: String?) {
         if (closed) return
         AirplayJNI.nativeSetDaap(handle, title, artist, album)
     }
 
-    /** Send artwork image to the receiver. */
-    fun setArtwork(imageData: ByteArray, contentType: String = "image/jpeg") {
+    override fun setArtwork(imageData: ByteArray, contentType: String) {
         if (closed) return
         AirplayJNI.nativeSetArtwork(handle, imageData, imageData.size, contentType)
     }
 
-    /** Update the progress bar on the receiver. */
-    fun setProgress(elapsedMs: Int, durationMs: Int) {
+    override fun setProgress(elapsedMs: Int, durationMs: Int) {
         if (closed) return
         AirplayJNI.nativeSetProgressMs(handle, elapsedMs, durationMs)
     }

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/airplay/MetadataSyncTarget.kt

@@ -0,0 +1,20 @@
+package com.margelo.nitro.queueplayer.cast.airplay
+
+/**
+ * What an AirPlay session accepts for the receiver's own display while it
+ * streams. [AirPlayMetadataSync] pushes into this; AirPlay 1 and AirPlay 2
+ * sessions implement it over their respective native senders.
+ */
+interface MetadataSyncTarget {
+    /** Send track metadata (title/artist/album) to the receiver. */
+    fun setMetadata(title: String?, artist: String?, album: String?)
+
+    /** Update the progress bar on the receiver. */
+    fun setProgress(elapsedMs: Int, durationMs: Int)
+
+    /**
+     * Send artwork image bytes to the receiver. A receiver whose sender
+     * protocol carries no content type ignores [contentType].
+     */
+    fun setArtwork(imageData: ByteArray, contentType: String)
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/chromecast/ChromecastSession.kt

@@ -14,6 +14,8 @@ import com.google.android.gms.cast.MediaQueueItem
 import com.google.android.gms.cast.MediaSeekOptions
 import com.google.android.gms.cast.MediaStatus
 import com.google.android.gms.cast.framework.media.RemoteMediaClient
+import com.google.android.gms.common.api.PendingResult
+import com.margelo.nitro.queueplayer.BuildConfig
 import com.margelo.nitro.queueplayer.cast.CastBackends
 import com.margelo.nitro.queueplayer.cast.CastMediaItem
 import com.margelo.nitro.queueplayer.cast.CastSession
@@ -88,6 +90,10 @@ internal class ChromecastSession(
   private val _seekCompleted = MutableSharedFlow<Long>(extraBufferCapacity = 4)
 
   override val state: StateFlow<RemotePlaybackState> = _state.asStateFlow()
+
+  @Volatile
+  override var hasReportedState: Boolean = false
+    private set
   override val positionMs: StateFlow<Long> = _positionMs.asStateFlow()
   override val durationMs: StateFlow<Long> = _durationMs.asStateFlow()
   override val currentTrackIndex: StateFlow<Int> = _currentTrackIndex.asStateFlow()
@@ -110,7 +116,13 @@ internal class ChromecastSession(
   private var serverHandle: MediaServerHandle? = null
 
   private val remoteMediaCallbacks = RemoteMediaCallbacks(
-    onStateChanged = { _state.value = it },
+    onStateChanged = { next ->
+      if (BuildConfig.DEBUG && _state.value != next) {
+        Log.d(TAG, "receiver state ${_state.value} -> $next")
+      }
+      if (next != RemotePlaybackState.IDLE) hasReportedState = true
+      _state.value = next
+    },
     onPositionChanged = { _positionMs.value = it },
     onDurationChanged = { _durationMs.value = it },
     onEndedReason = { _endedReason.tryEmit(it) },
@@ -264,12 +276,13 @@ internal class ChromecastSession(
     _currentTrackIndex.value = clampedStart
   }
 
+  // No bitmask flag gates `play` — the mask models pause, not resume.
   override fun play() {
     fireRemote("play") { it.play() }
   }
 
   override fun pause() {
-    fireRemote("pause") { it.pause() }
+    fireRemote("pause", requires = MediaStatus.COMMAND_PAUSE) { it.pause() }
   }
 
   override fun stop() {
@@ -277,11 +290,11 @@ internal class ChromecastSession(
   }
 
   override fun queueNext() {
-    fireRemote("queueNext") { it.queueNext(null) }
+    fireRemote("queueNext", requires = MediaStatus.COMMAND_QUEUE_NEXT) { it.queueNext(null) }
   }
 
   override fun queuePrev() {
-    fireRemote("queuePrev") { it.queuePrev(null) }
+    fireRemote("queuePrev", requires = MediaStatus.COMMAND_QUEUE_PREVIOUS) { it.queuePrev(null) }
   }
 
   override fun skipToQueueIndex(index: Int) {
@@ -292,8 +305,8 @@ internal class ChromecastSession(
     // synced that slot yet; skip rather than jump blind.
     fireRemote("skipToQueueIndex") { client ->
       val itemId = receiverItemIdAtIndex(index)
-      if (itemId == MediaQueueItem.INVALID_ITEM_ID) return@fireRemote
-      client.queueJumpToItem(itemId, null)
+      if (itemId == MediaQueueItem.INVALID_ITEM_ID) null
+      else client.queueJumpToItem(itemId, null)
     }
   }
 
@@ -367,7 +380,9 @@ internal class ChromecastSession(
   }
 
   override fun setPlaybackRate(rate: Float) {
-    fireRemote("setPlaybackRate") { it.setPlaybackRate(rate.toDouble()) }
+    fireRemote("setPlaybackRate", requires = MediaStatus.COMMAND_PLAYBACK_RATE) {
+      it.setPlaybackRate(rate.toDouble())
+    }
   }
 
   override fun setRepeatMode(mode: RemoteRepeatMode) {
@@ -435,11 +450,26 @@ internal class ChromecastSession(
   }
 
   /**
-   * Post [block] to main and invoke it with the current remote media
-   * client. Silently skips when the session is closed or the client
-   * is unavailable (log only — transport calls are fire-and-forget).
+   * Post [block] to main and invoke it with the current [RemoteMediaClient].
+   * Silently skips when the session is closed or the client is unavailable
+   * (log only — transport calls are fire-and-forget).
+   *
+   * [block] returns the [PendingResult] the SDK scheduled, or `null` when it
+   * declined to issue one. A returned result gets a callback so a
+   * receiver-side rejection is reported instead of vanishing — without it a
+   * refused command is indistinguishable from one the receiver honoured.
+   *
+   * [requires] names the [MediaStatus] command bitmask flag the receiver must
+   * advertise for this command (`null` for commands not gated by the mask).
+   * The receiver publishes support per media item, so an item can accept queue
+   * commands while refusing `pause` — worth a warning, since the command is
+   * otherwise dropped in silence.
    */
-  private fun fireRemote(label: String, block: (RemoteMediaClient) -> Unit) {
+  private fun fireRemote(
+    label: String,
+    requires: Long? = null,
+    block: (RemoteMediaClient) -> PendingResult<RemoteMediaClient.MediaChannelResult>?,
+  ) {
     if (closed) return
     runOnMain {
       if (closed) return@runOnMain
@@ -448,8 +478,38 @@ internal class ChromecastSession(
         Log.w(TAG, "$label: no RemoteMediaClient — session not fully live?")
         return@runOnMain
       }
-      runCatching { block(client) }
-        .onFailure { Log.w(TAG, "$label failed", it) }
+      val status = client.mediaStatus
+      if (requires != null && status != null && !status.isMediaCommandSupported(requires)) {
+        Log.w(
+          TAG,
+          "$label: receiver does not advertise support for this command " +
+            "(supportedMediaCommands=${status.supportedMediaCommands}); sending anyway",
+        )
+      }
+      if (BuildConfig.DEBUG) Log.d(TAG, "$label: issuing")
+      val outcome = runCatching { block(client) }
+      val thrown = outcome.exceptionOrNull()
+      if (thrown != null) {
+        Log.w(TAG, "$label failed", thrown)
+        return@runOnMain
+      }
+      // A null result means this call site declined to issue anything — the
+      // only such case is a queue index the receiver's model hasn't synced
+      // yet, which is a normal transient, not a fault.
+      val pending = outcome.getOrNull()
+      if (pending == null) {
+        if (BuildConfig.DEBUG) Log.d(TAG, "$label: no request issued")
+        return@runOnMain
+      }
+      pending.setResultCallback { result ->
+        if (closed) return@setResultCallback
+        if (!result.status.isSuccess) {
+          Log.w(
+            TAG,
+            "$label failed: ${result.status.statusCode} ${result.status.statusMessage}",
+          )
+        }
+      }
     }
   }
 

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,17 @@ 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.
   }
 }

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,23 @@ 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()
   }
 }

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

@@ -46,8 +46,12 @@ import org.robolectric.android.controller.ServiceController
  */
 @UnstableApi
 internal class PlaybackServiceTestHandle(
-  private val controller: ServiceController<PlaybackService>
+  private val controller: ServiceController<PlaybackService>,
+  private val binder: PlaybackService.LocalBinder,
 ) {
+  /** The bound service's live engine, for asserting local-path transport. */
+  val engine: PlaybackEngine get() = binder.engine
+
   fun destroy() {
     controller.destroy()
   }
@@ -79,5 +83,5 @@ internal fun bindPlaybackServiceForTest(
     deferred.await()
   }
 
-  return PlaybackServiceTestHandle(controller)
+  return PlaybackServiceTestHandle(controller, binder as PlaybackService.LocalBinder)
 }

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

@@ -0,0 +1,68 @@
+package com.margelo.nitro.queueplayer
+
+import android.media.audiofx.Equalizer
+import org.robolectric.annotation.Implements
+import org.robolectric.shadows.ShadowAudioEffect
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.util.Optional
+
+/**
+ * Models a five-band hardware equalizer so the legacy attach path resolves
+ * the same way on every run.
+ *
+ * [ShadowAudioEffect] answers the AudioEffect surface but falls back to a
+ * four-byte zero for any parameter it does not know, which the constructor's
+ * `short` reads cannot hold — so constructing an [Equalizer] throws before
+ * any band is queried. Supplying the parameters it reads makes a real attach
+ * distinguishable from a failed one. Levels written with `setBandLevel` land
+ * in the base shadow's parameter map, so they read back through the ordinary
+ * [Equalizer] API.
+ */
+@Implements(Equalizer::class)
+class ShadowEqualizer : ShadowAudioEffect() {
+
+  override fun getDefaultParameter(parameter: ByteBuffer): Optional<ByteBuffer> {
+    val key = parameter.duplicate().order(ByteOrder.nativeOrder())
+    if (key.remaining() < Int.SIZE_BYTES) return Optional.empty()
+    return when (key.int) {
+      PARAM_NUM_BANDS -> Optional.of(shorts(BAND_COUNT))
+      PARAM_LEVEL_RANGE -> Optional.of(shorts(MIN_LEVEL_MB, MAX_LEVEL_MB))
+      PARAM_BAND_LEVEL -> Optional.of(shorts(0))
+      PARAM_GET_NUM_OF_PRESETS -> Optional.of(shorts(0))
+      PARAM_CENTER_FREQ -> {
+        val band = if (key.remaining() >= Int.SIZE_BYTES) key.int else 0
+        Optional.of(ints(CENTER_FREQS_MILLI_HZ[band.coerceIn(0, BAND_COUNT - 1)]))
+      }
+      else -> Optional.empty()
+    }
+  }
+
+  private fun shorts(vararg values: Int): ByteBuffer =
+    ByteBuffer.allocate(values.size * Short.SIZE_BYTES).order(ByteOrder.nativeOrder()).apply {
+      values.forEach { putShort(it.toShort()) }
+      flip()
+    }
+
+  private fun ints(vararg values: Int): ByteBuffer =
+    ByteBuffer.allocate(values.size * Int.SIZE_BYTES).order(ByteOrder.nativeOrder()).apply {
+      values.forEach { putInt(it) }
+      flip()
+    }
+
+  companion object {
+    const val BAND_COUNT = 5
+    const val MIN_LEVEL_MB = -1500
+    const val MAX_LEVEL_MB = 1500
+
+    /** Centre frequencies in milliHz, matching a typical OEM five-band set. */
+    private val CENTER_FREQS_MILLI_HZ =
+      intArrayOf(60_000, 230_000, 910_000, 3_600_000, 14_000_000)
+
+    private const val PARAM_NUM_BANDS = 0
+    private const val PARAM_LEVEL_RANGE = 1
+    private const val PARAM_BAND_LEVEL = 2
+    private const val PARAM_CENTER_FREQ = 3
+    private const val PARAM_GET_NUM_OF_PRESETS = 7
+  }
+}

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

@@ -0,0 +1,162 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import com.margelo.nitro.queueplayer.cast.FakeRemotePlayer
+import com.margelo.nitro.queueplayer.cast.PlaybackStateRouter
+import com.margelo.nitro.queueplayer.cast.RemotePlaybackState
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * OS-surface transport commands — hardware and Bluetooth media keys, and the
+ * media-session skip callbacks — drive the receiver while a cast session owns
+ * playback. Routing them to the local engine would play the phone speaker over
+ * the receiver, or skip a queue nobody is listening to.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class TrackPlayerCastCommandRoutingTest {
+
+  private lateinit var player: TrackPlayer
+  private lateinit var serviceHandle: PlaybackServiceTestHandle
+  private val remote = FakeRemotePlayer()
+
+  private fun context() = ApplicationProvider.getApplicationContext<android.content.Context>()
+
+  private fun handler() = player.mediaSessionCommandHandler
+
+  @Before
+  fun setUp() {
+    PlaybackStateRouter.setActive(null)
+    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()
+    )
+  }
+
+  @After
+  fun tearDown() {
+    PlaybackStateRouter.setActive(null)
+    player.destroyInternal()
+    serviceHandle.destroy()
+  }
+
+  @Test
+  fun `media play key drives the receiver`() {
+    PlaybackStateRouter.setActive(remote)
+
+    handler().onMediaPlay()
+
+    assertEquals(listOf("play"), remote.transportCalls)
+  }
+
+  @Test
+  fun `media pause key drives the receiver`() {
+    PlaybackStateRouter.setActive(remote)
+
+    handler().onMediaPause()
+
+    assertEquals(listOf("pause"), remote.transportCalls)
+  }
+
+  @Test
+  fun `toggle key pauses a playing receiver`() {
+    remote.reportState(RemotePlaybackState.PLAYING)
+    PlaybackStateRouter.setActive(remote)
+
+    handler().onMediaTogglePlayPause()
+
+    assertEquals(listOf("pause"), remote.transportCalls)
+  }
+
+  @Test
+  fun `toggle key pauses a buffering receiver`() {
+    remote.reportState(RemotePlaybackState.BUFFERING)
+    PlaybackStateRouter.setActive(remote)
+
+    handler().onMediaTogglePlayPause()
+
+    assertEquals(listOf("pause"), remote.transportCalls)
+  }
+
+  @Test
+  fun `toggle key pauses a loading receiver`() {
+    remote.reportState(RemotePlaybackState.LOADING)
+    PlaybackStateRouter.setActive(remote)
+
+    handler().onMediaTogglePlayPause()
+
+    assertEquals(listOf("pause"), remote.transportCalls)
+  }
+
+  @Test
+  fun `toggle key resumes a paused receiver`() {
+    remote.reportState(RemotePlaybackState.PAUSED)
+    PlaybackStateRouter.setActive(remote)
+
+    handler().onMediaTogglePlayPause()
+
+    assertEquals(listOf("play"), remote.transportCalls)
+  }
+
+  @Test
+  fun `media skip keys drive the receiver queue`() {
+    PlaybackStateRouter.setActive(remote)
+
+    handler().onMediaSkipNext()
+    handler().onMediaSkipPrevious()
+
+    assertEquals(listOf("queueNext", "queuePrev"), remote.transportCalls)
+  }
+
+  @Test
+  fun `session skip commands drive the receiver queue and stay claimed`() {
+    PlaybackStateRouter.setActive(remote)
+
+    assertEquals(true, handler().onSkipToNextCommand())
+    assertEquals(true, handler().onSkipToPreviousCommand())
+    assertEquals(listOf("queueNext", "queuePrev"), remote.transportCalls)
+  }
+
+  @Test
+  fun `play key drives the local engine when no cast session is active`() {
+    handler().onMediaPlay()
+
+    assertEquals(true, serviceHandle.engine.mediaSessionPlayer.playWhenReady)
+    assertEquals(emptyList<String>(), remote.transportCalls)
+  }
+
+  @Test
+  fun `pause key drives the local engine when no cast session is active`() {
+    handler().onMediaPlay()
+    handler().onMediaPause()
+
+    assertEquals(false, serviceHandle.engine.mediaSessionPlayer.playWhenReady)
+    assertEquals(emptyList<String>(), remote.transportCalls)
+  }
+
+  @Test
+  fun `toggle key drives the local engine when no cast session is active`() {
+    handler().onMediaPlay()
+    handler().onMediaTogglePlayPause()
+
+    assertEquals(false, serviceHandle.engine.mediaSessionPlayer.playWhenReady)
+    assertEquals(emptyList<String>(), remote.transportCalls)
+  }
+}