react-native-queue-player 1.1.2 → 2.0.0

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/airplay/MulticastLockHolder.kt

@@ -70,6 +70,6 @@ internal class MulticastLockHolder(context: Context) {
     fun isHeld(): Boolean = lock?.isHeld == true
 
     private companion object {
-        const val LOCK_TAG = "rntp-airplay-discovery"
+        const val LOCK_TAG = "QueuePlayer.AirPlayDiscovery"
     }
 }

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

@@ -14,9 +14,9 @@ import com.margelo.nitro.queueplayer.CastReceiver
 
 /**
  * Chromecast backend — owns discovery via MediaRouter and session
- * lifecycle via GMS SessionManager. Surfaces discovery, connect, and
- * disconnect today; queue load + transport-state translation arrive
- * with the cast engine-swap work.
+ * lifecycle via GMS SessionManager, plus the transport calls that
+ * address the SDK session directly. Queue load and transport-state
+ * translation live in [ChromecastSession] and [RemoteMediaCallbacks].
  */
 internal class ChromecastBackend(
   private val context: Context,

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/main/java/com/margelo/nitro/queueplayer/cast/http/LocalMediaServer.kt

@@ -32,7 +32,7 @@ import kotlinx.coroutines.runBlocking
  *
  * Binds to `0.0.0.0` on an OS-assigned port. Range / HEAD /
  * Content-Length fall out of Ktor's `LocalFileContent` + `PartialContent`
- * plugin. Refcounted via `acquire(sessionId)` / `release()`.
+ * plugin. Refcounted via `acquire(sessionId, context)` / `release(sessionId)`.
  */
 class LocalMediaServer {
   private val lock = Any()
@@ -51,38 +51,26 @@ class LocalMediaServer {
   var serverPort: Int = -1
     private set
 
-  @Volatile
-  var lifecycleListener: LocalMediaServerLifecycle? = null
-
   @Volatile
   private var addressMonitor: LocalAddressMonitor? = null
 
   val currentLanAddress: String?
     get() = addressMonitor?.currentAddress
 
-  fun attachAddressMonitor(monitor: LocalAddressMonitor) {
-    addressMonitor = monitor
-  }
-
-  fun addAddressChangeListener(
-    listener: LocalAddressMonitor.Listener,
-  ): LocalAddressMonitor.Subscription? = addressMonitor?.addListener(listener)
-
   fun acquire(sessionId: String, context: Context): MediaServerHandle {
     val first = refCount.getAndIncrement() == 0
     if (first) {
       ensureStarted()
       ensureAddressMonitor(context)
-      lifecycleListener?.onActiveStateChanged(true)
     }
     return MediaServerHandle(this, sessionId)
   }
 
   // Lazily create + start the LAN-address monitor the first time the
   // server is acquired. `start()` seeds `currentAddress` synchronously
-  // from the active network, so the address is available to the very
-  // first `currentLanAddress` read (the cast handoff loads immediately
-  // on connect, before any async network callback would land).
+  // when the active network is Wi-Fi, so the address is available to
+  // the very first `currentLanAddress` read (the cast handoff loads
+  // immediately on connect, before any async network callback lands).
   private fun ensureAddressMonitor(context: Context) {
     synchronized(lock) {
       if (addressMonitor != null) return
@@ -93,29 +81,21 @@ class LocalMediaServer {
   internal fun release(sessionId: String) {
     registry.revokeAll(sessionId)
     val last = refCount.decrementAndGet() == 0
-    if (last) {
-      stop()
-      lifecycleListener?.onActiveStateChanged(false)
-    }
+    if (last) stop()
   }
 
   internal fun register(sessionId: String, file: File, contentType: String?): String =
     registry.register(sessionId, file, contentType)
 
-  internal fun revoke(token: String) = registry.revoke(token)
-
-  internal fun resolve(token: String): RegisteredMedia? = registry.resolve(token)
-
   private fun ensureStarted() {
     synchronized(lock) {
       if (engine != null) return
-      // Bind on every interface (Wi-Fi LAN, cellular, VPN) — Chromecast
-      // receivers pull from the phone's LAN IP, and we cannot
-      // pre-determine which interface the receiver will use. URLs
-      // handed back to receivers go through `MediaServerHandle.url`,
-      // which scopes hosts to the active Wi-Fi address via
-      // `LocalAddressMonitor`. Tokens are 32 hex chars (high entropy);
-      // unauthorized callers cannot enumerate served media.
+      // Listen on every interface; the URL host selects the Wi-Fi one.
+      // URLs handed back to receivers go through
+      // `MediaServerHandle.register(file, lanAddress, contentType)` with the
+      // host from `currentLanAddress` (`LocalAddressMonitor.currentAddress`,
+      // the Wi-Fi network's address). Tokens are 32 hex chars (high
+      // entropy); unauthorized callers cannot enumerate served media.
       val started = embeddedServer(CIO, port = 0, host = "0.0.0.0") {
         install(PartialContent)
         install(AutoHeadResponse)
@@ -153,8 +133,4 @@ class LocalMediaServer {
       addressMonitor = null
     }
   }
-
-  internal fun stopForTest() {
-    stop()
-  }
 }

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/http/MediaServerHandle.kt

@@ -31,11 +31,6 @@ class MediaServerHandle internal constructor(
     return "http://$lanAddress:$port/media/$token"
   }
 
-  fun revoke(token: String) {
-    if (closed.get()) return
-    server.revoke(token)
-  }
-
   fun close() {
     if (closed.compareAndSet(false, true)) {
       server.release(sessionId)

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/http/MediaTokenRegistry.kt

@@ -22,16 +22,10 @@ internal class MediaTokenRegistry {
 
   fun resolve(token: String): RegisteredMedia? = tokens[token]
 
-  fun revoke(token: String) {
-    tokens.remove(token)
-  }
-
   fun revokeAll(sessionId: String) {
     val iter = tokens.entries.iterator()
     while (iter.hasNext()) {
       if (iter.next().value.sessionId == sessionId) iter.remove()
     }
   }
-
-  fun size(): Int = tokens.size
 }

package/android/src/main/java/com/margelo/nitro/queueplayer/cast/net/LocalAddressMonitor.kt

@@ -7,37 +7,38 @@ import android.net.Network
 import android.net.NetworkCapabilities
 import android.net.NetworkRequest
 import java.net.Inet4Address
-import java.util.concurrent.CopyOnWriteArrayList
 
 /**
- * Surfaces the host's primary LAN IPv4 address and notifies listeners
- * on change. Owned by `LocalMediaServer`; backends consume via the
- * server's `addAddressChangeListener`.
+ * Surfaces the host's Wi-Fi IPv4 address. Owned by `LocalMediaServer`,
+ * which exposes it to backends as `currentLanAddress`.
  *
  * Detection via [ConnectivityManager.NetworkCallback] on a request for
- * `TRANSPORT_WIFI | TRANSPORT_CELLULAR`. Cellular included so mobile-
- * hotspot setups (phone hotspot fed to a Chromecast) work.
+ * `TRANSPORT_WIFI` (the request's default capabilities exclude VPNs), so
+ * only a Wi-Fi network's address is ever served, and a cellular network
+ * coming or going neither replaces nor clears it.
  */
 class LocalAddressMonitor(private val context: Context) {
 
-  fun interface Listener {
-    fun onAddressChanged(newAddress: String?)
-  }
-
-  private val listeners = CopyOnWriteArrayList<Listener>()
-
   @Volatile
   var currentAddress: String? = null
     private set
 
+  /**
+   * The network whose link properties supplied [currentAddress]. Two Wi-Fi
+   * networks overlap during a handover — the new one reports its link before
+   * the old one is lost — so a loss clears the address only when it is the
+   * network the address came from.
+   */
+  private var addressNetwork: Network? = null
+
   private var registered = false
   private val callback = object : ConnectivityManager.NetworkCallback() {
     override fun onLinkPropertiesChanged(network: Network, linkProperties: LinkProperties) {
-      updateAddress(linkProperties)
+      updateAddress(network, linkProperties)
     }
 
     override fun onLost(network: Network) {
-      updateAddress(null)
+      if (network == addressNetwork) updateAddress(null, null)
     }
   }
 
@@ -47,14 +48,23 @@ class LocalAddressMonitor(private val context: Context) {
       ?: return
     val request = NetworkRequest.Builder()
       .addTransportType(NetworkCapabilities.TRANSPORT_WIFI)
-      .addTransportType(NetworkCapabilities.TRANSPORT_CELLULAR)
       .build()
     cm.registerNetworkCallback(request, callback)
     registered = true
-    // Seed synchronously from the active network so `currentAddress` is
-    // populated immediately — the cast handoff reads it right after
-    // connect, before the first async onLinkPropertiesChanged lands.
-    updateAddress(cm.activeNetwork?.let { cm.getLinkProperties(it) })
+    // Seed synchronously so `currentAddress` is populated immediately —
+    // the cast handoff reads it right after connect, before the first
+    // async onLinkPropertiesChanged lands. The active network is used
+    // only when it passes the request's own filter (Wi-Fi, not a VPN:
+    // a VPN over Wi-Fi carries the Wi-Fi transport but a tunnel address).
+    // When Wi-Fi is up but not the default network, the address arrives
+    // with that network's first onLinkPropertiesChanged instead.
+    val active = cm.activeNetwork ?: return
+    val caps = cm.getNetworkCapabilities(active) ?: return
+    if (caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) &&
+      caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_VPN)
+    ) {
+      updateAddress(active, cm.getLinkProperties(active))
+    }
   }
 
   fun stop() {
@@ -65,22 +75,11 @@ class LocalAddressMonitor(private val context: Context) {
     registered = false
   }
 
-  fun addListener(listener: Listener): Subscription {
-    listeners.add(listener)
-    return Subscription { listeners.remove(listener) }
-  }
-
-  private fun updateAddress(linkProperties: LinkProperties?) {
+  private fun updateAddress(network: Network?, linkProperties: LinkProperties?) {
     val ipv4 = linkProperties?.linkAddresses
       ?.firstOrNull { it.address is Inet4Address && !it.address.isLoopbackAddress }
       ?.address?.hostAddress
-    if (ipv4 != currentAddress) {
-      currentAddress = ipv4
-      listeners.forEach { it.onAddressChanged(ipv4) }
-    }
-  }
-
-  fun interface Subscription {
-    fun remove()
+    addressNetwork = if (ipv4 != null) network else null
+    currentAddress = ipv4
   }
 }

package/android/src/test/java/androidx/media3/session/{MediaSessionControllerRequestTestSeam.kt → MediaSessionControllerRequestTestSupport.kt}

@@ -3,7 +3,7 @@ package androidx.media3.session
 import androidx.media3.common.util.UnstableApi
 
 /**
- * Test-only seam into Media3's controller-request scope.
+ * Test-only access to Media3's controller-request scope.
  *
  * `MediaSession.getControllerForCurrentRequest()` is non-null only for
  * the duration of a controller-originated `Player` call, set by Media3

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

@@ -80,6 +80,8 @@ class AvrcpMetadataTest {
       duration = null,
       artworkUrl = null,
       extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null,
     )
     setQueueOnSession(listOf(track))
 
@@ -100,6 +102,8 @@ class AvrcpMetadataTest {
       duration = null,
       artworkUrl = "https://example.com/cover.jpg",
       extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null,
     )
     setQueueOnSession(listOf(track))
 
@@ -120,6 +124,8 @@ class AvrcpMetadataTest {
       duration = 42.0,
       artworkUrl = null,
       extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null,
     )
     setQueueOnSession(listOf(track))
 
@@ -137,6 +143,8 @@ class AvrcpMetadataTest {
       duration = null,
       artworkUrl = null,
       extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null,
     )
     val second = TrackItem(
       id = "second",
@@ -147,6 +155,8 @@ class AvrcpMetadataTest {
       duration = null,
       artworkUrl = null,
       extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null,
     )
 
     setQueueOnSession(listOf(first))
@@ -170,6 +180,8 @@ class AvrcpMetadataTest {
       duration = null,
       artworkUrl = null,
       extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null,
     )
     setQueueOnSession(listOf(track))
     assertEquals(1, session.player.mediaItemCount)

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

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

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

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