react-native-nitro-player 1.7.0-alpha.2 → 1.7.0-alpha.4

package/README.md

@@ -82,6 +82,8 @@ Mutations return **`Promise<void>`** (or **`Promise<string>`** for `createPlayli
 | `addTracksToPlaylist(pid, tracks)`      | Both     | **Async**. Adds multiple tracks to a playlist.         |
 | `removeTrackFromPlaylist(pid, tid)`     | Both     | **Async**. Removes a track from a playlist.             |
 | `reorderTrackInPlaylist(pid, tid, idx)` | Both     | **Async**. Moves a track to a new position.             |
+| `removeTracksFromPlaylist(pid, tids)`   | Both     | **Async**. Removes several tracks in one call.          |
+| `shufflePlaylist(pid, options?)`        | Both     | **Async**. Shuffles a playlist without stopping playback.|
 
 ### Platform-Specific APIs
 
@@ -940,6 +942,13 @@ PlayerQueue.removeTrackFromPlaylist(playlistId, trackId)
 // Reorder tracks
 PlayerQueue.reorderTrackInPlaylist(playlistId, trackId, newIndex)
 
+// Remove several tracks in one native call
+PlayerQueue.removeTracksFromPlaylist(playlistId, [trackId1, trackId2])
+
+// Shuffle in place — the playing track keeps playing, no shuffle mode to turn off
+PlayerQueue.shufflePlaylist(playlistId)
+PlayerQueue.shufflePlaylist(playlistId, { keepCurrentTrackFirst: false })
+
 // Delete a playlist
 PlayerQueue.deletePlaylist(playlistId)
 ```

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

@@ -94,16 +94,11 @@ class HybridPlayerQueue : HybridPlayerQueueSpec() {
             core.updatePlaylist(playlistId)
         }
 
+    /** Same semantics as the batch form: unknown ids are skipped, only a missing playlist rejects. */
     override fun removeTrackFromPlaylist(
         playlistId: String,
         trackId: String,
-    ): Promise<Unit> =
-        Promise.async {
-            if (!playlistManager.removeTrackFromPlaylist(playlistId, trackId)) {
-                throw IllegalArgumentException("Track $trackId not found in playlist $playlistId")
-            }
-            core.updatePlaylist(playlistId)
-        }
+    ): Promise<Unit> = removeTracksFromPlaylist(playlistId, arrayOf(trackId))
 
     override fun reorderTrackInPlaylist(
         playlistId: String,
@@ -117,6 +112,49 @@ class HybridPlayerQueue : HybridPlayerQueueSpec() {
             core.updatePlaylist(playlistId)
         }
 
+    /** On the player looper: the live queue must reflect the removal before the promise resolves. */
+    override fun removeTracksFromPlaylist(
+        playlistId: String,
+        trackIds: Array<String>,
+    ): Promise<Unit> {
+        val promise = Promise<Unit>()
+        core.enqueue {
+            val removed = playlistManager.removeTracksFromPlaylist(playlistId, trackIds.toList())
+            if (removed == null) {
+                promise.reject(IllegalArgumentException("Playlist not found: $playlistId"))
+                return@enqueue
+            }
+            if (removed > 0 && core.getCurrentPlaylistId() == playlistId) core.syncCurrentPlaylistOnQueue()
+            promise.resolve(Unit)
+        }
+        return promise
+    }
+
+    /** On the player looper: the anchor id is player-thread state. */
+    override fun shufflePlaylist(
+        playlistId: String,
+        options: ShufflePlaylistOptions?,
+    ): Promise<Unit> {
+        val promise = Promise<Unit>()
+        core.enqueue {
+            val isCurrent = core.getCurrentPlaylistId() == playlistId
+            val pin =
+                if (isCurrent && options?.keepCurrentTrackFirst != false) {
+                    core.currentTracks.getOrNull(core.currentTrackIndex)?.id
+                } else {
+                    null
+                }
+            val changed = playlistManager.shufflePlaylist(playlistId, pin)
+            if (changed == null) {
+                promise.reject(IllegalArgumentException("Playlist not found: $playlistId"))
+                return@enqueue
+            }
+            if (changed && isCurrent) core.syncCurrentPlaylistOnQueue()
+            promise.resolve(Unit)
+        }
+        return promise
+    }
+
     // ── Playback control ──────────────────────────────────────────────────────
 
     /**

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

@@ -0,0 +1,65 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
+package com.margelo.nitro.nitroplayer.core
+
+import androidx.annotation.OptIn
+import androidx.media3.common.AudioAttributes
+import androidx.media3.common.C
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.ExoPlayer
+import com.margelo.nitro.nitroplayer.AndroidAudioFocusMode
+import com.margelo.nitro.nitroplayer.media.AudioFocusController
+
+/**
+ * Audio focus policy. ExoPlayer's built-in handling pauses on every transient loss — even the
+ * duckable kind a notification asks for — so 'duck' and 'ignore' take focus into our own hands.
+ */
+
+internal const val DUCK_VOLUME_FACTOR = 0.2f
+
+@OptIn(UnstableApi::class)
+internal fun TrackPlayerCore.applyAudioFocusMode(mode: AndroidAudioFocusMode) {
+    if (mode == audioFocusMode && (mode == AndroidAudioFocusMode.PAUSE) == (audioFocusController == null)) return
+    audioFocusMode = mode
+
+    audioFocusController?.abandon()
+    audioFocusController = null
+    isDucked = false
+
+    val local = exoOrNull() ?: return
+    // media3 only knows how to pause; it owns focus for the default mode and nothing else.
+    local.setAudioAttributes(mediaAudioAttributes(), mode == AndroidAudioFocusMode.PAUSE)
+    local.volume = userVolume
+
+    if (mode == AndroidAudioFocusMode.DUCK) {
+        audioFocusController =
+            AudioFocusController(
+                context,
+                onDuck = { ducked -> applyDuck(ducked) },
+                onPause = { playerHandler.post { pauseOnQueue() } },
+            )
+        if (isExoInitialized && exo.player.isPlaying) audioFocusController?.acquire()
+    }
+}
+
+@OptIn(UnstableApi::class)
+internal fun TrackPlayerCore.applyDuck(ducked: Boolean) {
+    playerHandler.post {
+        isDucked = ducked
+        exoOrNull()?.volume = userVolume * if (ducked) DUCK_VOLUME_FACTOR else 1f
+    }
+}
+
+private fun mediaAudioAttributes(): AudioAttributes =
+    AudioAttributes
+        .Builder()
+        .setUsage(C.USAGE_MEDIA)
+        .setContentType(C.AUDIO_CONTENT_TYPE_MUSIC)
+        .build()
+
+/** The local ExoPlayer, or null while casting (the CastPlayer has no audio focus of its own). */
+@OptIn(UnstableApi::class)
+internal fun TrackPlayerCore.exoOrNull(): ExoPlayer? {
+    if (!isExoInitialized) return null
+    return exo.player as? ExoPlayer
+}

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

@@ -22,6 +22,8 @@ import com.margelo.nitro.nitroplayer.connection.AndroidAutoConnectionDetector
 import com.margelo.nitro.nitroplayer.download.DownloadManagerCore
 import com.margelo.nitro.nitroplayer.media.ExoPlayerBuilder
 import com.margelo.nitro.nitroplayer.media.MediaLibraryManager
+import com.margelo.nitro.nitroplayer.AndroidAudioFocusMode
+import com.margelo.nitro.nitroplayer.media.AudioFocusController
 import com.margelo.nitro.nitroplayer.media.MediaSessionManager
 import com.margelo.nitro.nitroplayer.media.NitroPlayerPlaybackService
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
@@ -71,6 +73,13 @@ class TrackPlayerCore private constructor(
     @Volatile internal var currentRepeatMode: RepeatMode = RepeatMode.OFF
     internal var lookaheadCount: Int = 5
 
+    internal var audioFocusMode: AndroidAudioFocusMode = AndroidAudioFocusMode.PAUSE
+    internal var audioFocusController: AudioFocusController? = null
+
+    /** Volume the app asked for; ducking scales this instead of overwriting it. */
+    internal var userVolume: Float = 1f
+    internal var isDucked: Boolean = false
+
     internal var remoteSkipForwardIntervalMs: Long = ExoPlayerBuilder.DEFAULT_REMOTE_SKIP_INTERVAL_MS
     internal var remoteSkipBackwardIntervalMs: Long = ExoPlayerBuilder.DEFAULT_REMOTE_SKIP_INTERVAL_MS
     internal var playerListener: androidx.media3.common.Player.Listener? = null
@@ -144,21 +153,44 @@ class TrackPlayerCore private constructor(
         playerHandler.postDelayed(progressUpdateRunnable, PROGRESS_INTERVAL_MS)
     }
 
-    internal val updateCurrentPlaylistRunnable =
-        Runnable {
-            val id = currentPlaylistId ?: return@Runnable
-            val playlist = playlistManager.getPlaylist(id) ?: return@Runnable
-            currentTracks = playlist.tracks
-            if (::exo.isInitialized &&
-                exo.currentMediaItem != null &&
-                exo.currentMediaItemIndex >= 0
-            ) {
-                rebuildQueueFromCurrentPosition()
-            } else {
-                updatePlayerQueue(playlist.tracks)
-            }
-            checkUpcomingTracksForUrls(lookaheadCount)
+    internal enum class AnchorOutcome { NONE, KEPT, REMOVED }
+
+    /** Re-resolves the anchor by id, or moves the cursor to the resume slot when it was removed. */
+    internal fun assignCurrentTracks(next: List<TrackItem>): AnchorOutcome {
+        val old = currentTracks
+        val anchor = old.getOrNull(currentTrackIndex)
+        currentTracks = next
+        if (anchor == null) return AnchorOutcome.NONE
+        val newIndex = next.indexOfFirst { it.id == anchor.id }
+        if (newIndex >= 0) {
+            currentTrackIndex = newIndex
+            return AnchorOutcome.KEPT
         }
+        val alive = next.mapTo(HashSet()) { it.id }
+        val followerId = old.drop(currentTrackIndex + 1).firstOrNull { it.id in alive }?.id
+        val resume = followerId?.let { id -> next.indexOfFirst { it.id == id } } ?: next.size
+        currentTrackIndex = resume - 1
+        return AnchorOutcome.REMOVED
+    }
+
+    /** Applies the stored playlist to the live queue without re-preparing the playing item. */
+    internal fun syncCurrentPlaylistOnQueue() {
+        playerHandler.removeCallbacks(updateCurrentPlaylistRunnable)
+        val id = currentPlaylistId ?: return
+        val playlist = playlistManager.getPlaylist(id) ?: return
+        assignCurrentTracks(playlist.tracks)
+        if (::exo.isInitialized &&
+            exo.currentMediaItem != null &&
+            exo.currentMediaItemIndex >= 0
+        ) {
+            rebuildQueueFromCurrentPosition()
+        } else {
+            updatePlayerQueue(playlist.tracks)
+        }
+        checkUpcomingTracksForUrls(lookaheadCount)
+    }
+
+    internal val updateCurrentPlaylistRunnable = Runnable { syncCurrentPlaylistOnQueue() }
 
     // ── Service binding ────────────────────────────────────────────────────
     private var serviceBound = false

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

@@ -64,6 +64,8 @@ internal class TrackPlayerEventListener(
                 val newIdx = currentTracks.indexOfFirst { it.id == trackId }
                 if (newIdx >= 0 && newIdx != currentTrackIndex) currentTrackIndex = newIdx
             }
+            // A transient play-out ends here: restore the user's repeat mode.
+            core.applyBackendRepeatMode()
 
             val wrappedToStart = currentRepeatMode == RepeatMode.PLAYLIST &&
                 currentTrackIndex == 0 && previousTrackIndex == currentTracks.size - 1

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,18 +89,41 @@ 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.androidAudioFocus?.let { applyAudioFocusMode(it) }
     config.androidAutoEnabled?.let { NitroPlayerMediaBrowserService.isAndroidAutoEnabled = it }
     config.lookaheadCount?.let { lookaheadCount = it.toInt() }
     config.androidNotificationIcon?.let { NitroPlayerPlaybackService.notificationSmallIconResName = it }
@@ -185,6 +208,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

@@ -88,6 +88,7 @@ internal fun TrackPlayerCore.rebuildQueueAndPlayFromIndex(index: Int) {
     currentTrackIndex = index
     exo.setMediaItems(mediaItems, true)
     exo.prepare()
+    applyBackendRepeatMode()
 }
 
 // ── Surgical rebuild (preserve current item) ──────────────────────────────
@@ -105,9 +106,13 @@ 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.
@@ -158,9 +163,13 @@ internal fun TrackPlayerCore.rebuildQueueFromCurrentPosition() {
     // ExoPlayer has already prepared, so gapless transitions survive.
     val existingCount = exo.mediaItemCount - currentIndex - 1
     var commonPrefix = 0
-    while (commonPrefix < existingCount && commonPrefix < newQueueTracks.size &&
-        extractTrackId(exo.getMediaItemAt(currentIndex + 1 + commonPrefix).mediaId) == newQueueTracks[commonPrefix].id
-    ) {
+    while (commonPrefix < existingCount && commonPrefix < newQueueTracks.size) {
+        val existing = exo.getMediaItemAt(currentIndex + 1 + commonPrefix)
+        val track = newQueueTracks[commonPrefix]
+        if (extractTrackId(existing.mediaId) != track.id) break
+        // URI must match too — items materialized before lazy URL resolution are unplayable
+        val desiredUrl = if (isCastingField) track.url else downloadManager.getEffectiveUrl(track)
+        if (existing.localConfiguration?.uri?.toString().orEmpty() != desiredUrl) break
         commonPrefix++
     }
 
@@ -244,6 +253,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) ────

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

@@ -24,7 +24,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()
@@ -40,7 +42,9 @@ internal fun TrackPlayerCore.updateTracksOnQueue(tracks: List<TrackItem>) {
 
         // 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 +57,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 } }

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/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)) }
     }
 }

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

@@ -79,10 +79,12 @@ class MediaSessionManager(
 
     private fun updateMediaButtonPreferences() {
         val session = mediaSession ?: return
-        // Preferences replace Media3's default layout — prev/next must be declared or they vanish
+        // Preferences replace Media3's default layout — prev/next must be declared or they vanish.
+        // Compact only shows BACK / play-pause / FORWARD, so the ±N skips go to OVERFLOW; left in
+        // the forward slot they push Next out of the compact notification entirely.
         val preserved = session.mediaButtonPreferences.filterNot { it.isManagedButton() }
         session.setMediaButtonPreferences(
-            listOf(previousTrackButton(), skipBackButton(), skipForwardButton(), nextTrackButton()) + preserved,
+            listOf(previousTrackButton(), nextTrackButton(), skipBackButton(), skipForwardButton()) + preserved,
         )
     }
 
@@ -90,6 +92,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(CommandButton.ICON_PREVIOUS)
             .setPlayerCommand(Player.COMMAND_SEEK_TO_PREVIOUS)
+            .setSlots(CommandButton.SLOT_BACK)
             .setDisplayName(context.getString(R.string.nitro_player_previous_track))
             .build()
 
@@ -97,6 +100,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(CommandButton.ICON_NEXT)
             .setPlayerCommand(Player.COMMAND_SEEK_TO_NEXT)
+            .setSlots(CommandButton.SLOT_FORWARD)
             .setDisplayName(context.getString(R.string.nitro_player_next_track))
             .build()
 
@@ -104,6 +108,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(skipBackIcon(remoteSkipBackwardIntervalMs))
             .setPlayerCommand(Player.COMMAND_SEEK_BACK)
+            .setSlots(CommandButton.SLOT_OVERFLOW)
             .setDisplayName(
                 context.getString(
                     R.string.nitro_player_skip_back_seconds,
@@ -115,6 +120,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(skipForwardIcon(remoteSkipForwardIntervalMs))
             .setPlayerCommand(Player.COMMAND_SEEK_FORWARD)
+            .setSlots(CommandButton.SLOT_OVERFLOW)
             .setDisplayName(
                 context.getString(
                     R.string.nitro_player_skip_forward_seconds,

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

@@ -7,6 +7,7 @@ import android.os.Handler
 import android.os.IBinder
 import android.os.Looper
 import androidx.media3.cast.CastPlayer
+import androidx.media3.common.ForwardingPlayer
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.session.DefaultMediaNotificationProvider
@@ -15,6 +16,8 @@ import androidx.media3.session.MediaSessionService
 import com.google.android.gms.cast.framework.CastContext
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.skipToNextOnQueue
+import com.margelo.nitro.nitroplayer.core.skipToPreviousOnQueue
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
 
 /**
@@ -81,10 +84,32 @@ class NitroPlayerPlaybackService : MediaSessionService() {
         // Build ExoPlayer on main looper (default)
         player = ExoPlayerBuilder.build(this)
 
+        // The timeline is a window over the logical queue, so ExoPlayer's own prev/next would
+        // only ever move inside it — remote Previous seeks to 0 instead of the previous track.
+        // Route the remote controls through the same logical skips JS uses.
+        val sessionPlayer =
+            object : ForwardingPlayer(player) {
+                override fun seekToPrevious() {
+                    trackPlayerCore?.skipToPreviousOnQueue() ?: super.seekToPrevious()
+                }
+
+                override fun seekToPreviousMediaItem() {
+                    trackPlayerCore?.skipToPreviousOnQueue() ?: super.seekToPreviousMediaItem()
+                }
+
+                override fun seekToNext() {
+                    trackPlayerCore?.skipToNextOnQueue() ?: super.seekToNext()
+                }
+
+                override fun seekToNextMediaItem() {
+                    trackPlayerCore?.skipToNextOnQueue() ?: super.seekToNextMediaItem()
+                }
+            }
+
         // Build MediaSession
         val playlistManager = PlaylistManager.getInstance(this)
         mediaSession = MediaSession
-            .Builder(this, player)
+            .Builder(this, sessionPlayer)
             .setCallback(MediaSessionCallbackFactory.create(this, playlistManager))
             .apply { buildSessionActivity()?.let { setSessionActivity(it) } }
             .build()