react-native-nitro-player 1.7.0-alpha.3 → 1.7.0-alpha.5

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerNotify.kt

@@ -43,7 +43,12 @@ internal fun TrackPlayerCore.notifyTracksNeedUpdate(
     tracks: List<TrackItem>,
     lookahead: Int,
 ) {
+    NitroPlayerLogger.log("TrackPlayer") { "tracksNeedUpdate: ${tracks.size} track(s), listening=${!onTracksNeedUpdateListeners.isEmpty}" }
+    startJsRuntimeIfNeeded()
+    updateJsKeepAlive()
     onTracksNeedUpdateListeners.forEach { it(tracks, lookahead) }
+    // A lookup that hits a dead network usually fails in the app; ask again once it is back
+    awaitNetworkThenRetry(afterLoss = isNetworkValidated())
 }
 
 internal fun TrackPlayerCore.notifyTimedMetadata(metadata: TimedMetadata) {

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerPlayback.kt

@@ -20,11 +20,17 @@ import com.margelo.nitro.nitroplayer.media.NitroPlayerPlaybackService
 
 suspend fun TrackPlayerCore.play() = withPlayerContext { playOnQueue() }
 
-internal fun TrackPlayerCore.playOnQueue() = exo.play()
+internal fun TrackPlayerCore.playOnQueue() {
+    audioFocusController?.acquire()
+    exo.play()
+}
 
 suspend fun TrackPlayerCore.pause() = withPlayerContext { pauseOnQueue() }
 
-internal fun TrackPlayerCore.pauseOnQueue() = exo.pause()
+internal fun TrackPlayerCore.pauseOnQueue() {
+    exo.pause()
+    audioFocusController?.abandon()
+}
 
 suspend fun TrackPlayerCore.seek(position: Double) = withPlayerContext { seekOnQueue(position) }
 
@@ -55,9 +61,8 @@ internal fun TrackPlayerCore.skipToPreviousOnQueue() {
         }
 
         currentTemporaryType != TrackPlayerCore.TemporaryType.NONE -> {
-            // playFromIndexInternal clears both temp lists (matching iOS behavior),
-            // so no per-track removal is needed here
-            playFromIndexInternal(currentTrackIndex)
+            // playFromIndexInternal clears both temp lists; cursor may be -1 (anchor removed).
+            if (currentTracks.isEmpty()) exo.seekTo(0) else playFromIndexInternal(maxOf(0, currentTrackIndex))
         }
 
         currentTrackIndex > 0 -> {
@@ -76,12 +81,7 @@ suspend fun TrackPlayerCore.setRepeatMode(mode: RepeatMode) = withPlayerContext
 internal fun TrackPlayerCore.setRepeatModeOnQueue(mode: RepeatMode) {
     val previousMode = currentRepeatMode
     currentRepeatMode = mode
-    exo.setRepeatMode(
-        when (mode) {
-            RepeatMode.TRACK -> Player.REPEAT_MODE_ONE
-            else -> Player.REPEAT_MODE_OFF
-        },
-    )
+    applyBackendRepeatMode()
     if (!isCastingField && previousMode != mode &&
         (previousMode == RepeatMode.PLAYLIST || mode == RepeatMode.PLAYLIST)
     ) {
@@ -89,19 +89,44 @@ internal fun TrackPlayerCore.setRepeatModeOnQueue(mode: RepeatMode) {
     }
 }
 
+/** True while the playing item was removed from the playlist and is finishing. */
+internal fun TrackPlayerCore.isTransientPlayOut(): Boolean {
+    if (!isExoInitialized || currentTemporaryType != TrackPlayerCore.TemporaryType.NONE) return false
+    val item = exo.currentMediaItem ?: return false
+    return findTrack(item) == null
+}
+
+/** Follows the user's mode except during a transient play-out, which must finish once. */
+internal fun TrackPlayerCore.backendRepeatMode(): Int =
+    when {
+        isTransientPlayOut() -> Player.REPEAT_MODE_OFF
+        currentRepeatMode == RepeatMode.TRACK -> Player.REPEAT_MODE_ONE
+        else -> Player.REPEAT_MODE_OFF
+    }
+
+internal fun TrackPlayerCore.applyBackendRepeatMode() {
+    if (!isExoInitialized) return
+    val desired = backendRepeatMode()
+    if (exo.player.repeatMode != desired) exo.setRepeatMode(desired)
+}
+
 fun TrackPlayerCore.getRepeatMode(): RepeatMode = currentRepeatMode
 
 suspend fun TrackPlayerCore.setVolume(volume: Double) = withPlayerContext { setVolumeOnQueue(volume) }
 
 internal fun TrackPlayerCore.setVolumeOnQueue(volume: Double) {
     val clamped = volume.coerceIn(0.0, 100.0)
-    exo.setVolume((clamped / 100.0).toFloat())
+    userVolume = (clamped / 100.0).toFloat()
+    exo.setVolume(userVolume * if (isDucked) DUCK_VOLUME_FACTOR else 1f)
 }
 
 suspend fun TrackPlayerCore.configure(config: PlayerConfig) = withPlayerContext { configureOnQueue(config) }
 
 internal fun TrackPlayerCore.configureOnQueue(config: PlayerConfig) {
-    config.androidAutoEnabled?.let { NitroPlayerMediaBrowserService.isAndroidAutoEnabled = it }
+    // JS is calling, so the keep-alive task is registered: start it now if a headless start needs it
+    updateJsKeepAlive()
+    config.androidAudioFocus?.let { applyAudioFocusMode(it) }
+    config.androidAutoEnabled?.let { NitroPlayerMediaBrowserService.setAndroidAutoEnabled(context, it) }
     config.lookaheadCount?.let { lookaheadCount = it.toInt() }
     config.androidNotificationIcon?.let { NitroPlayerPlaybackService.notificationSmallIconResName = it }
     remoteSkipIntervalMs(config.remoteSkipForwardInterval)?.let { remoteSkipForwardIntervalMs = it }
@@ -185,6 +210,7 @@ internal fun TrackPlayerCore.playSongInternal(
 
     if (targetPlaylistId == null || songIndex < 0) return
 
+    playlistManager.setCurrentPlaylistId(targetPlaylistId)
     if (currentPlaylistId != targetPlaylistId) {
         val playlist = playlistManager.getPlaylist(targetPlaylistId) ?: return
         currentPlaylistId = targetPlaylistId

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerQueue.kt

@@ -72,8 +72,8 @@ suspend fun TrackPlayerCore.getActualQueue(): List<TrackItem> = withPlayerContex
 
 internal fun TrackPlayerCore.getActualQueueInternal(): List<TrackItem> {
     if (!isExoInitialized) return emptyList()
+    // May be -1 (no anchor while a temp plays); the arithmetic below handles it.
     val currentIndex = currentTrackIndex
-    if (currentIndex < 0) return emptyList()
 
     val queue = ArrayList<TrackItem>(currentTracks.size + playNextStack.size + upNextQueue.size)
 

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerQueueBuild.kt

@@ -46,6 +46,20 @@ internal fun TrackPlayerCore.castableUpcoming(tracks: List<TrackItem>): List<Tra
  */
 internal const val QUEUE_WINDOW_SIZE = 4
 
+/** Index of [trackId] in currentTracks; a repeated track resolves to its first occurrence at or after [from], wrapping. */
+internal fun TrackPlayerCore.currentTrackIndexOf(
+    trackId: String,
+    from: Int,
+): Int {
+    val size = currentTracks.size
+    val start = if (from in 0 until size) from else 0
+    for (k in 0 until size) {
+        val i = (start + k) % size
+        if (currentTracks[i].id == trackId) return i
+    }
+    return -1
+}
+
 internal fun TrackPlayerCore.mediaIdFor(track: TrackItem): String {
     val playlistId = currentPlaylistId ?: ""
     return if (playlistId.isNotEmpty()) "$playlistId:${track.id}" else track.id
@@ -88,6 +102,7 @@ internal fun TrackPlayerCore.rebuildQueueAndPlayFromIndex(index: Int) {
     currentTrackIndex = index
     exo.setMediaItems(mediaItems, true)
     exo.prepare()
+    applyBackendRepeatMode()
 }
 
 // ── Surgical rebuild (preserve current item) ──────────────────────────────
@@ -105,15 +120,19 @@ internal fun TrackPlayerCore.rebuildQueueFromCurrentPosition() {
         currentTracks.none { it.id == currentTrackId } &&
         currentTemporaryType == TrackPlayerCore.TemporaryType.NONE
     ) {
-        if (currentTracks.isEmpty()) return
-        playFromIndexInternal(minOf(currentTrackIndex, currentTracks.size - 1))
-        return
+        if (currentTracks.isNotEmpty()) {
+            // currentTrackIndex + 1 is the resume slot set by assignCurrentTracks.
+            playFromIndexInternal(minOf(currentTrackIndex + 1, currentTracks.size - 1))
+            return
+        }
+        // Transient play-out: the removed item must finish once, not loop.
+        applyBackendRepeatMode()
     }
 
     // Keep the logical playlist pointer in sync after playlist mutations.
     // Without this, getActualQueue/getState can report a stale index until the next track transition.
     if (currentTemporaryType == TrackPlayerCore.TemporaryType.NONE && currentTrackId != null) {
-        val resolvedIndex = currentTracks.indexOfFirst { it.id == currentTrackId }
+        val resolvedIndex = currentTrackIndexOf(currentTrackId, currentTrackIndex)
         if (resolvedIndex >= 0) {
             currentTrackIndex = resolvedIndex
         }
@@ -248,6 +267,7 @@ internal fun TrackPlayerCore.updatePlayerQueue(tracks: List<TrackItem>) {
     if (exo.playbackState == Player.STATE_IDLE && mediaItems.isNotEmpty()) {
         exo.prepare()
     }
+    applyBackendRepeatMode()
 }
 
 // ── MediaItem construction (member extension to access downloadManager) ────
@@ -262,6 +282,7 @@ internal fun TrackPlayerCore.makeMediaItem(
             .setTitle(track.title)
             .setArtist(track.artist)
             .setAlbumTitle(track.album)
+    if (track.duration > 0) metaBuilder.setDurationMs((track.duration * 1000).toLong())
 
     track.artwork?.asSecondOrNull()?.let { artworkUrl ->
         try {

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerRecovery.kt

@@ -0,0 +1,97 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
+package com.margelo.nitro.nitroplayer.core
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.Network
+import android.net.NetworkCapabilities
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.Player
+import com.margelo.nitro.nitroplayer.Reason
+import com.margelo.nitro.nitroplayer.TrackPlayerState
+
+// Lost network waits for connectivity and retries the same item; bad sources skip, capped so an unplayable queue stops
+
+internal const val MAX_CONSECUTIVE_SOURCE_ERRORS = 3
+
+internal fun TrackPlayerCore.handlePlayerError(error: PlaybackException) {
+    NitroPlayerLogger.log("TrackPlayer") { "Player error: ${error.errorCodeName} - ${error.message}" }
+    // Still waiting for its URL: updateTracks re-prepares it, skipping would cascade through the window
+    if (getCurrentTrack()?.url?.isEmpty() == true) {
+        checkUpcomingTracksForUrls(lookaheadCount, force = true)
+        return
+    }
+    notifyPlaybackStateChange(TrackPlayerState.STOPPED, Reason.ERROR)
+    if (error.isConnectivityError() && !isNetworkValidated()) {
+        awaitNetworkThenRetry()
+        return
+    }
+    consecutiveSourceErrors++
+    if (consecutiveSourceErrors >= MAX_CONSECUTIVE_SOURCE_ERRORS) return
+    // A source error leaves ExoPlayer in IDLE; skip the dead item and re-prepare so the rest of the queue keeps playing
+    if (!exo.hasNextMediaItem()) rebuildQueueFromCurrentPosition()
+    if (exo.hasNextMediaItem()) {
+        exo.seekToNext()
+        exo.prepare()
+    }
+}
+
+/** Called when playback actually starts, so earlier failures stop counting against the queue. */
+internal fun TrackPlayerCore.onPlaybackHealthy() {
+    consecutiveSourceErrors = 0
+}
+
+private fun PlaybackException.isConnectivityError(): Boolean =
+    errorCode == PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED ||
+        errorCode == PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT
+
+private fun TrackPlayerCore.connectivity(): ConnectivityManager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+
+internal fun TrackPlayerCore.isNetworkValidated(): Boolean {
+    val manager = connectivity()
+    val capabilities = manager.getNetworkCapabilities(manager.activeNetwork) ?: return false
+    return capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
+}
+
+/** Retries once the network is back; [afterLoss] first waits for it to drop, for work started while it was up. */
+internal fun TrackPlayerCore.awaitNetworkThenRetry(afterLoss: Boolean = false) {
+    if (networkRetryCallback != null) return
+    val callback =
+        object : ConnectivityManager.NetworkCallback() {
+            private var lost = !afterLoss
+            private var seen: Network? = null
+
+            override fun onLost(network: Network) {
+                lost = true
+            }
+
+            override fun onCapabilitiesChanged(
+                network: Network,
+                capabilities: NetworkCapabilities,
+            ) {
+                // Switching networks (Wi-Fi to mobile) breaks requests in flight just like a drop
+                if (seen != null && seen != network) lost = true
+                seen = network
+                if (!capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)) {
+                    lost = true
+                } else if (lost) {
+                    enqueue { retryAfterNetwork(this) }
+                }
+            }
+        }
+    networkRetryCallback = callback
+    connectivity().registerDefaultNetworkCallback(callback)
+}
+
+private fun TrackPlayerCore.retryAfterNetwork(callback: ConnectivityManager.NetworkCallback) {
+    if (networkRetryCallback !== callback) return
+    networkRetryCallback = null
+    try {
+        connectivity().unregisterNetworkCallback(callback)
+    } catch (_: IllegalArgumentException) {
+    }
+    // URLs the app could not fetch offline are asked for again; a failed item is retried only if nothing replaced it
+    checkUpcomingTracksForUrls(lookaheadCount, force = true)
+    if (exo.playbackState == Player.STATE_IDLE && exo.player.playerError != null) exo.prepare()
+}

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerSetup.kt

@@ -2,7 +2,6 @@ package com.margelo.nitro.nitroplayer.core
 
 import com.margelo.nitro.nitroplayer.equalizer.EqualizerCore
 import com.margelo.nitro.nitroplayer.media.MediaSessionManager
-import com.margelo.nitro.nitroplayer.media.NitroPlayerMediaBrowserService
 import com.margelo.nitro.nitroplayer.media.NitroPlayerPlaybackService
 
 /**
@@ -19,10 +18,6 @@ internal fun TrackPlayerCore.initFromService(binder: NitroPlayerPlaybackService.
             setTrackPlayerCore(this@initFromService)
         }
 
-    // Give MediaBrowserService access to this core and media session
-    NitroPlayerMediaBrowserService.trackPlayerCore = this
-    NitroPlayerMediaBrowserService.mediaSessionManager = mediaSessionManager
-
     // Attach player listener
     val listener = TrackPlayerEventListener(this)
     playerListener = listener

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/TrackPlayerUrlLoader.kt

@@ -2,6 +2,7 @@
 
 package com.margelo.nitro.nitroplayer.core
 
+import android.os.SystemClock
 import androidx.media3.common.Player
 import com.margelo.nitro.nitroplayer.TrackItem
 
@@ -24,7 +25,9 @@ internal fun TrackPlayerCore.updateTracksOnQueue(tracks: List<TrackItem>) {
         val safeTracks =
             tracks.filter { track ->
                 when {
-                    track.id == currentTrackId && !currentTrackIsEmpty -> false
+                    // Same URL is a metadata-only edit (a title or artwork refresh): it reaches
+                    // the session without touching the media, so gapless is unaffected.
+                    track.id == currentTrackId && !currentTrackIsEmpty -> track.url == currentTrack?.url
 
                     // preserve gapless
                     track.id == currentTrackId && currentTrackIsEmpty -> track.url.isNotEmpty()
@@ -35,12 +38,15 @@ internal fun TrackPlayerCore.updateTracksOnQueue(tracks: List<TrackItem>) {
                 }
             }
         if (safeTracks.isEmpty()) return@run
+        safeTracks.forEach { urlRequestedAt.remove(it.id) }
 
         val affectedPlaylists: Map<String, Int> = playlistManager.updateTracks(safeTracks)
 
         // Replace the current MediaItem when its URL just resolved (local only — the cast branch below reloads instead).
         val currentTrackResolvedNow = currentTrackUpdate != null && currentTrackIsEmpty && currentTrackUpdate.url.isNotEmpty()
-        if (!isCastingField && currentTrackResolvedNow) {
+        val currentMetadataChanged =
+            currentTrackUpdate != null && !currentTrackIsEmpty && currentTrackUpdate.url == currentTrack?.url
+        if (!isCastingField && (currentTrackResolvedNow || currentMetadataChanged)) {
             val exoIndex = exo.currentMediaItemIndex
             if (exoIndex >= 0) {
                 val playlistId = currentPlaylistId ?: ""
@@ -53,7 +59,7 @@ internal fun TrackPlayerCore.updateTracksOnQueue(tracks: List<TrackItem>) {
         if (currentPlaylistId != null && affectedPlaylists.containsKey(currentPlaylistId)) {
             val refreshedPlaylist = playlistManager.getPlaylist(currentPlaylistId!!)
             if (refreshedPlaylist != null) {
-                currentTracks = refreshedPlaylist.tracks
+                assignCurrentTracks(refreshedPlaylist.tracks)
                 val updatedById = currentTracks.associateBy { it.id }
                 playNextStack.forEachIndexed { i, t -> updatedById[t.id]?.let { if (it !== t) playNextStack[i] = it } }
                 upNextQueue.forEachIndexed { i, t -> updatedById[t.id]?.let { if (it !== t) upNextQueue[i] = it } }
@@ -129,7 +135,13 @@ suspend fun TrackPlayerCore.getCurrentTrackIndex(): Int = withPlayerContext { cu
 
 // ── URL lookahead ─────────────────────────────────────────────────────────
 
-internal fun TrackPlayerCore.checkUpcomingTracksForUrls(lookahead: Int = 5) {
+// One pick fires several queue events within a few hundred ms; the app is asked once for that burst
+private const val URL_REQUEST_COALESCE_MS = 500L
+
+internal fun TrackPlayerCore.checkUpcomingTracksForUrls(
+    lookahead: Int = 5,
+    force: Boolean = false,
+) {
     val upcomingTracks =
         if (currentTrackIndex < 0) {
             currentTracks.take(lookahead)
@@ -140,5 +152,10 @@ internal fun TrackPlayerCore.checkUpcomingTracksForUrls(lookahead: Int = 5) {
     val currentNeedsUrl = currentTrack != null && currentTrack.url.isEmpty()
     val candidates = if (currentNeedsUrl) listOf(currentTrack!!) + upcomingTracks else upcomingTracks
     val needUrls = candidates.filter { it.url.isEmpty() }
-    if (needUrls.isNotEmpty()) notifyTracksNeedUpdate(needUrls, lookahead)
+    val now = SystemClock.elapsedRealtime()
+    val ask = if (force) needUrls else needUrls.filter { track -> urlRequestedAt[track.id]?.let { now - it < URL_REQUEST_COALESCE_MS } != true }
+    if (ask.isEmpty()) return
+    if (urlRequestedAt.size > 1000) urlRequestedAt.clear()
+    ask.forEach { urlRequestedAt[it.id] = now }
+    notifyTracksNeedUpdate(ask, lookahead)
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/download/DownloadDatabase.kt

@@ -1,6 +1,7 @@
 package com.margelo.nitro.nitroplayer.download
 
 import android.content.Context
+import com.margelo.nitro.JNIOnLoad
 import com.margelo.nitro.core.AnyMap
 import com.margelo.nitro.core.NullType
 import com.margelo.nitro.nitroplayer.*
@@ -56,6 +57,8 @@ class DownloadDatabase private constructor(
     private val ioScope = CoroutineScope(Dispatchers.IO.limitedParallelism(1) + SupervisorJob())
 
     init {
+        // Persisted extraPayloads are AnyMaps; a process started without JS has not loaded Nitro's JNI yet
+        JNIOnLoad.initializeNativeNitro()
         loadFromDisk()
     }
 

package/android/src/main/java/com/margelo/nitro/nitroplayer/download/TrackItemJson.kt

@@ -1,5 +1,6 @@
 package com.margelo.nitro.nitroplayer.download
 
+import com.margelo.nitro.JNIOnLoad
 import com.margelo.nitro.core.AnyMap
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.Variant_NullType_String
@@ -8,6 +9,11 @@ import org.json.JSONObject
 // Survives process death inside the worker's inputData so a completed
 // download can be recorded even when the in-memory metadata maps are gone.
 internal object TrackItemJson {
+    // extraPayload is an AnyMap; downloads can run in a process JS never started
+    init {
+        JNIOnLoad.initializeNativeNitro()
+    }
+
     fun toJson(track: TrackItem): String =
         JSONObject()
             .apply {

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/AudioFocusController.kt

@@ -0,0 +1,87 @@
+package com.margelo.nitro.nitroplayer.media
+
+import android.content.Context
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.os.Build
+
+/**
+ * Owns audio focus for the 'duck' mode. ExoPlayer's own handling pauses on every transient
+ * loss, duckable or not, which is why a notification can stop playback outright.
+ */
+class AudioFocusController(
+    context: Context,
+    private val onDuck: (Boolean) -> Unit,
+    private val onPause: () -> Unit,
+) {
+    private val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+    private var request: AudioFocusRequest? = null
+    private var ducked = false
+    private var held = false
+
+    private val listener =
+        AudioManager.OnAudioFocusChangeListener { change ->
+            when (change) {
+                // Another app took focus for good — stop and let it go.
+                AudioManager.AUDIOFOCUS_LOSS -> {
+                    setDucked(false)
+                    onPause()
+                    abandon()
+                }
+
+                AudioManager.AUDIOFOCUS_LOSS_TRANSIENT,
+                AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK,
+                -> setDucked(true)
+
+                AudioManager.AUDIOFOCUS_GAIN -> setDucked(false)
+            }
+        }
+
+    private fun setDucked(next: Boolean) {
+        if (ducked == next) return
+        ducked = next
+        onDuck(next)
+    }
+
+    /** Returns false when the system refused focus, so the caller can leave playback alone. */
+    fun acquire(): Boolean {
+        if (held) return true
+        val attributes =
+            AudioAttributes
+                .Builder()
+                .setUsage(AudioAttributes.USAGE_MEDIA)
+                .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
+                .build()
+        val result =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                val built =
+                    AudioFocusRequest
+                        .Builder(AudioManager.AUDIOFOCUS_GAIN)
+                        .setAudioAttributes(attributes)
+                        .setWillPauseWhenDucked(false)
+                        .setOnAudioFocusChangeListener(listener)
+                        .build()
+                request = built
+                audioManager.requestAudioFocus(built)
+            } else {
+                @Suppress("DEPRECATION")
+                audioManager.requestAudioFocus(listener, AudioManager.STREAM_MUSIC, AudioManager.AUDIOFOCUS_GAIN)
+            }
+        held = result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
+        return held
+    }
+
+    fun abandon() {
+        if (!held) return
+        held = false
+        setDucked(false)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            request?.let { audioManager.abandonAudioFocusRequest(it) }
+            request = null
+        } else {
+            @Suppress("DEPRECATION")
+            audioManager.abandonAudioFocus(listener)
+        }
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/CastSessionController.kt

@@ -35,6 +35,8 @@ class CastSessionController(
     private val castContext: CastContext,
     val castPlayer: CastPlayer,
     val localPlayer: Player,
+    /** What the session drives locally — wraps [localPlayer] to route remote commands through the core. */
+    val localSessionPlayer: Player,
     val mediaSession: MediaSession,
     private val mainHandler: Handler,
 ) {

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/ExoPlayerBuilder.kt

@@ -8,6 +8,7 @@ import androidx.media3.datasource.DefaultDataSource
 import androidx.media3.exoplayer.DefaultLoadControl
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.exoplayer.source.DefaultMediaSourceFactory
+import androidx.media3.exoplayer.source.ShuffleOrder
 
 /**
  * Builds an [ExoPlayer] with the standard NitroPlayer configuration.
@@ -59,5 +60,7 @@ object ExoPlayerBuilder {
             .setWakeMode(C.WAKE_MODE_NETWORK)
             .setPauseAtEndOfMediaItems(false)
             .build()
+            // Queue order is ours; a controller's shuffle toggle must not randomize the window.
+            .apply { setShuffleOrder(ShuffleOrder.UnshuffledShuffleOrder(0)) }
     }
 }