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

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/AndroidManifest.xml

@@ -18,6 +18,14 @@
         android:name="android.hardware.audio.output"
         android:required="false" />
 
+    <!-- Visibility of Android Auto's connection-state provider; without it the car never reads as connected -->
+    <queries>
+        <provider
+            android:name="androidx.car.app.connection.provider"
+            android:authorities="androidx.car.app.connection"
+            tools:ignore="MissingClass" />
+    </queries>
+
     <application>
         <!-- Google Cast: supplies CastOptions (receiver app ID) to the Cast SDK.
              Apps shipping their own OptionsProvider must override with tools:replace. -->

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

@@ -1,15 +1,21 @@
 package com.margelo.nitro.nitroplayer
 
 import androidx.annotation.Keep
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.CommandButton
 import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
 import com.margelo.nitro.nitroplayer.core.clearAndroidAutoMediaLibrary
 import com.margelo.nitro.nitroplayer.core.setAndroidAutoMediaLibrary
+import com.margelo.nitro.nitroplayer.media.MediaSessionManager
+import com.margelo.nitro.nitroplayer.media.NitroPlayerMediaBrowserService
+import org.json.JSONArray
 
 @DoNotStrip
 @Keep
+@UnstableApi
 class HybridAndroidAutoMediaLibrary : HybridAndroidAutoMediaLibrarySpec() {
     private val core: TrackPlayerCore
 
@@ -23,4 +29,49 @@ class HybridAndroidAutoMediaLibrary : HybridAndroidAutoMediaLibrarySpec() {
     override fun setMediaLibrary(libraryJson: String): Promise<Unit> = Promise.async { core.setAndroidAutoMediaLibrary(libraryJson) }
 
     override fun clearMediaLibrary(): Promise<Unit> = Promise.async { core.clearAndroidAutoMediaLibrary() }
+
+    override fun onLoadChildren(callback: (requestId: String, parentId: String) -> Unit) {
+        core.mediaLibraryManager.childrenRequester = callback
+    }
+
+    override fun onSearch(callback: (requestId: String, query: String) -> Unit) {
+        core.mediaLibraryManager.searchRequester = callback
+        NitroPlayerMediaBrowserService.setSearchSupported(core.context, true)
+    }
+
+    override fun resolveRequest(
+        requestId: String,
+        itemsJson: String,
+    ) = core.mediaLibraryManager.resolve(requestId, itemsJson)
+
+    override fun setSessionButtons(buttonsJson: String) {
+        val array = JSONArray(buttonsJson)
+        val buttons =
+            (0 until array.length()).mapNotNull { i ->
+                val button = array.getJSONObject(i)
+                val icon = ICONS[button.optString("icon")] ?: return@mapNotNull null
+                MediaSessionManager.SessionButton(button.getString("action"), button.optString("title"), icon)
+            }
+        core.enqueue { core.mediaSessionManager?.setSessionButtons(buttons) }
+    }
+
+    override fun onSessionButtonPress(callback: (action: String) -> Unit) {
+        core.enqueue { core.mediaSessionManager?.onSessionButtonPress = callback }
+    }
+
+    override fun onPlaybackResumption(callback: () -> Unit) = core.mediaLibraryManager.setResumptionRequester(callback)
+
+    private companion object {
+        val ICONS =
+            mapOf(
+                "heart" to CommandButton.ICON_HEART_UNFILLED,
+                "heart_filled" to CommandButton.ICON_HEART_FILLED,
+                "star" to CommandButton.ICON_STAR_UNFILLED,
+                "star_filled" to CommandButton.ICON_STAR_FILLED,
+                "thumb_up" to CommandButton.ICON_THUMB_UP_UNFILLED,
+                "thumb_up_filled" to CommandButton.ICON_THUMB_UP_FILLED,
+                "plus" to CommandButton.ICON_PLUS,
+                "check" to CommandButton.ICON_CHECK_CIRCLE_FILLED,
+            )
+    }
 }

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/connection/AndroidAutoConnectionDetector.kt

@@ -59,9 +59,9 @@ class AndroidAutoConnectionDetector(
         try {
             val filter = IntentFilter(ACTION_CAR_CONNECTION_UPDATED)
 
-            // For Android 14+ (API 34+), we need to specify the receiver flags
+            // Exported: the broadcast comes from the Android Auto app, a NOT_EXPORTED receiver never gets it
             if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
-                context.registerReceiver(carConnectionReceiver, filter, Context.RECEIVER_NOT_EXPORTED)
+                context.registerReceiver(carConnectionReceiver, filter, Context.RECEIVER_EXPORTED)
             } else {
                 context.registerReceiver(carConnectionReceiver, filter)
             }

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

@@ -1,5 +1,6 @@
 package com.margelo.nitro.nitroplayer.core
 
+import android.net.Uri
 import androidx.media3.common.MediaItem
 import androidx.media3.common.Player
 
@@ -42,7 +43,18 @@ class ExoPlayerCore(
     fun getPlaybackSpeed(): Float = player.playbackParameters.speed
 
     // ── Queue mutations ────────────────────────────────────────────────────
-    fun prepare() = player.prepare()
+    // A lazy track's empty URI fails as "Source error"; stay idle until updateTracks supplies it
+    fun prepare() {
+        if (isLazyCurrent()) return
+        player.prepare()
+    }
+
+    // A prepared player loads a new current item by itself, so idle it while that item still has no URI
+    fun holdLazyCurrent() {
+        if (isLazyCurrent() && player.playbackState != Player.STATE_IDLE) player.stop()
+    }
+
+    private fun isLazyCurrent(): Boolean = player.currentMediaItem?.localConfiguration?.uri == Uri.EMPTY
 
     fun seekToDefaultPosition(windowIndex: Int) = player.seekToDefaultPosition(windowIndex)
 
@@ -51,7 +63,10 @@ class ExoPlayerCore(
     fun setMediaItems(
         items: List<MediaItem>,
         resetPosition: Boolean = false,
-    ) = player.setMediaItems(items, resetPosition)
+    ) {
+        player.setMediaItems(items, resetPosition)
+        holdLazyCurrent()
+    }
 
     fun addMediaItems(items: List<MediaItem>) = player.addMediaItems(items)
 

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

@@ -4,8 +4,8 @@ import android.util.Log
 import com.margelo.nitro.nitroplayer.BuildConfig
 
 object NitroPlayerLogger {
-    // Determine if logging is enabled based on build config
-    val isEnabled: Boolean = BuildConfig.DEBUG
+    // Release builds log after `adb shell setprop log.tag.NitroPlayer DEBUG` and an app restart
+    val isEnabled: Boolean = BuildConfig.DEBUG || Log.isLoggable("NitroPlayer", Log.DEBUG)
 
     /**
      * Preferred overload: message lambda is only evaluated when logging is enabled.

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

@@ -3,7 +3,9 @@
 package com.margelo.nitro.nitroplayer.core
 
 import com.margelo.nitro.nitroplayer.connection.AndroidAutoConnectionDetector
+import com.margelo.nitro.nitroplayer.media.MediaItem
 import com.margelo.nitro.nitroplayer.media.MediaLibraryParser
+import com.margelo.nitro.nitroplayer.media.MediaType
 import com.margelo.nitro.nitroplayer.media.NitroPlayerMediaBrowserService
 
 /**
@@ -13,56 +15,64 @@ import com.margelo.nitro.nitroplayer.media.NitroPlayerMediaBrowserService
 
 /** Called on the main thread from TrackPlayerCore.init via handler.post. */
 internal fun TrackPlayerCore.setupAndroidAutoDetector() {
+    // The car may have bound the browser before this core existed (cold start from the car)
+    if (NitroPlayerMediaBrowserService.isAndroidAutoConnected) setAndroidAutoConnected(true)
     androidAutoConnectionDetector =
         AndroidAutoConnectionDetector(context).apply {
             onConnectionChanged = { connected, _ ->
-                handler.post {
-                    isAndroidAutoConnectedField = connected
-                    NitroPlayerMediaBrowserService.isAndroidAutoConnected = connected
-                    notifyAndroidAutoConnection(connected)
-                }
+                handler.post { setAndroidAutoConnected(connected) }
             }
             registerCarConnectionReceiver()
         }
 }
 
-/** Called by MediaBrowserService when the user picks a track in Android Auto. */
-suspend fun TrackPlayerCore.playFromPlaylistTrack(mediaId: String) =
-    withPlayerContext {
-        try {
-            val colonIndex = mediaId.indexOf(':')
-            if (colonIndex <= 0 || colonIndex >= mediaId.length - 1) return@withPlayerContext
-            val playlistId = mediaId.substring(0, colonIndex)
-            val trackId = mediaId.substring(colonIndex + 1)
-            val playlist = playlistManager.getPlaylist(playlistId) ?: return@withPlayerContext
-            val trackIndex = playlist.tracks.indexOfFirst { it.id == trackId }
-            if (trackIndex < 0) return@withPlayerContext
-            if (currentPlaylistId != playlistId) {
-                loadPlaylistInternal(playlistId)
-            }
-            playFromIndexInternal(trackIndex)
-        } catch (_: Exception) {
+/** Android Auto binding the browser is proof of a connection, whatever the provider query said. */
+internal fun TrackPlayerCore.onAndroidAutoBrowserConnected() {
+    handler.post { setAndroidAutoConnected(true) }
+}
+
+private fun TrackPlayerCore.setAndroidAutoConnected(connected: Boolean) {
+    NitroPlayerMediaBrowserService.isAndroidAutoConnected = connected
+    if (isAndroidAutoConnectedField == connected) return
+    isAndroidAutoConnectedField = connected
+    updateJsKeepAlive()
+    notifyAndroidAutoConnection(connected)
+}
+
+/** Routes a controller's "playlistId:trackId" pick through the logical queue (window + lazy URLs); false for unknown ids. */
+internal fun TrackPlayerCore.playFromMediaId(mediaId: String): Boolean {
+    val colonIndex = mediaId.indexOf(':')
+    if (colonIndex <= 0) return false
+    val playlistId = mediaId.substring(0, colonIndex)
+    val trackRef = mediaId.substring(colonIndex + 1)
+    if (playlistManager.indexOfTrackRef(playlistId, trackRef) < 0) return false
+    startJsRuntimeIfNeeded()
+    enqueue {
+        val index = playlistManager.indexOfTrackRef(playlistId, trackRef)
+        // Resuming what is already loaded keeps its position; a failed item is reloaded instead
+        if (currentPlaylistId == playlistId && currentTrackIndex == index && exo.player.playerError == null) {
+            // Tapping a song still waiting for its URL asks the app for it again
+            if (getCurrentTrack()?.url.isNullOrEmpty()) checkUpcomingTracksForUrls(lookaheadCount, force = true)
+            return@enqueue
         }
+        if (index >= 0 && playlistManager.loadPlaylist(playlistId, index)) loadPlaylistOnQueue(playlistId, index)
     }
-
-private fun TrackPlayerCore.loadPlaylistInternal(playlistId: String) {
-    playNextStack.clear()
-    upNextQueue.clear()
-    currentTemporaryType = TrackPlayerCore.TemporaryType.NONE
-    val playlist = playlistManager.getPlaylist(playlistId) ?: return
-    currentPlaylistId = playlistId
-    updatePlayerQueue(playlist.tracks)
+    return true
 }
 
+private fun folderIds(items: List<MediaItem>?): List<String> = items.orEmpty().filter { it.mediaType == MediaType.FOLDER }.flatMap { listOf(it.id) + folderIds(it.children) }
+
 suspend fun TrackPlayerCore.setAndroidAutoMediaLibrary(libraryJson: String) =
     withPlayerContext {
         val library = MediaLibraryParser.fromJson(libraryJson)
+        val previous = folderIds(mediaLibraryManager.getMediaLibrary()?.rootItems)
         mediaLibraryManager.setMediaLibrary(library)
-        NitroPlayerMediaBrowserService.getInstance()?.onPlaylistsUpdated()
+        NitroPlayerMediaBrowserService.getInstance()?.onLibraryUpdated(previous + folderIds(library.rootItems) + mediaLibraryManager.loadedFolderIds)
     }
 
 suspend fun TrackPlayerCore.clearAndroidAutoMediaLibrary() =
     withPlayerContext {
+        val previous = folderIds(mediaLibraryManager.getMediaLibrary()?.rootItems)
         mediaLibraryManager.clear()
-        NitroPlayerMediaBrowserService.getInstance()?.onPlaylistsUpdated()
+        NitroPlayerMediaBrowserService.getInstance()?.onLibraryUpdated(previous + mediaLibraryManager.loadedFolderIds)
     }

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/TrackPlayerCast.kt

@@ -88,7 +88,7 @@ internal fun TrackPlayerCore.switchToLocalPlayer() {
     lastCastWaitTrackId = null
     exo = ExoPlayerCore(controller.localPlayer)
     playerListener?.let { controller.localPlayer.addListener(it) }
-    setMediaSessionPlayer(controller.localPlayer)
+    setMediaSessionPlayer(controller.localSessionPlayer)
 
     val localList = ArrayList<TrackItem>()
     currentTrack?.let { localList.add(it) }

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

@@ -12,6 +12,11 @@ import android.os.Bundle
 import android.os.Handler
 import android.os.IBinder
 import android.os.Looper
+import com.facebook.react.ReactApplication
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.jstasks.HeadlessJsTaskConfig
+import com.facebook.react.jstasks.HeadlessJsTaskContext
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.RepeatMode
@@ -22,6 +27,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,9 +78,19 @@ 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
+    internal var consecutiveSourceErrors = 0
+    internal val urlRequestedAt = HashMap<String, Long>()
+    internal var networkRetryCallback: android.net.ConnectivityManager.NetworkCallback? = null
 
     // ── Temporary queue ────────────────────────────────────────────────────
     internal var playNextStack: MutableList<TrackItem> = mutableListOf()
@@ -144,21 +161,47 @@ 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
+        // A repeated track keeps its rank among the occurrences, so editing elsewhere does not jump to another copy
+        val rank = old.subList(0, currentTrackIndex).count { it.id == anchor.id }
+        val occurrences = next.indices.filter { next[it].id == anchor.id }
+        val newIndex = occurrences.getOrElse(rank) { occurrences.lastOrNull() ?: -1 }
+        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
@@ -219,6 +262,7 @@ class TrackPlayerCore private constructor(
     // ── Singleton ──────────────────────────────────────────────────────────
     companion object {
         internal const val PROGRESS_INTERVAL_MS = 1000L
+        private const val KEEP_ALIVE_TASK = "NitroPlayerKeepAlive"
 
         @Volatile
         @Suppress("ktlint:standard:property-naming")
@@ -361,6 +405,34 @@ class TrackPlayerCore private constructor(
         }
     }
 
+    /** Lazy URLs come from JS; a process started by the car or a controller has no runtime until started. */
+    internal fun startJsRuntimeIfNeeded() {
+        val host = (context as? ReactApplication)?.reactHost ?: return
+        if (host.currentReactContext == null) host.start()
+    }
+
+    private var keepAliveTask: Pair<ReactContext, Int>? = null
+
+    /** Without a resumed activity (car, screen off) RN pauses JS timers; a headless task keeps them running while JS may be needed. */
+    internal fun updateJsKeepAlive() {
+        val wanted = isAndroidAutoConnectedField || (isExoInitialized && exo.playWhenReady)
+        val reactContext = (context as? ReactApplication)?.reactHost?.currentReactContext
+        keepAliveTask?.let { (taskContext, taskId) ->
+            val tasks = HeadlessJsTaskContext.getInstance(taskContext)
+            if (wanted && taskContext === reactContext && tasks.isTaskRunning(taskId)) return
+            if (tasks.isTaskRunning(taskId)) tasks.finishTask(taskId)
+            keepAliveTask = null
+        }
+        if (!wanted || reactContext == null || !reactContext.hasActiveReactInstance()) return
+        try {
+            val config = HeadlessJsTaskConfig(KEEP_ALIVE_TASK, Arguments.createMap(), 0, true)
+            keepAliveTask = reactContext to HeadlessJsTaskContext.getInstance(reactContext).startTask(config)
+            NitroPlayerLogger.log("TrackPlayerCore") { "keep-alive task started: ${keepAliveTask?.second}" }
+        } catch (e: Exception) {
+            NitroPlayerLogger.log("TrackPlayerCore") { "keep-alive task not started: ${e.message}" }
+        }
+    }
+
     // ── Simple read-only accessors ─────────────────────────────────────────
 
     fun isAndroidAutoConnected(): Boolean = isAndroidAutoConnectedField
@@ -389,7 +461,12 @@ class TrackPlayerCore private constructor(
 
     fun removeOnPlaybackProgressChangeListener(id: Long): Boolean = onProgressListeners.remove(id)
 
-    fun addOnTracksNeedUpdateListener(cb: (List<TrackItem>, Int) -> Unit): Long = onTracksNeedUpdateListeners.add(cb)
+    fun addOnTracksNeedUpdateListener(cb: (List<TrackItem>, Int) -> Unit): Long {
+        val id = onTracksNeedUpdateListeners.add(cb)
+        // Requests raised before JS was listening (headless start) are otherwise lost
+        enqueue { checkUpcomingTracksForUrls(lookaheadCount, force = true) }
+        return id
+    }
 
     fun removeOnTracksNeedUpdateListener(id: Long): Boolean = onTracksNeedUpdateListeners.remove(id)
 

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

@@ -31,6 +31,7 @@ internal class TrackPlayerEventListener(
         with(core) {
             // TRACK repeat: REPEAT_MODE_ONE fires this every loop — not a real track change
             if (reason == Player.MEDIA_ITEM_TRANSITION_REASON_REPEAT) return
+            exo.holdLazyCurrent()
 
             // Remove the track that just finished/was skipped from temp lists
             if ((
@@ -61,9 +62,13 @@ internal class TrackPlayerEventListener(
             val previousTrackIndex = currentTrackIndex
             if (currentTemporaryType == TrackPlayerCore.TemporaryType.NONE && mediaItem != null) {
                 val trackId = extractTrackId(mediaItem.mediaId)
-                val newIdx = currentTracks.indexOfFirst { it.id == trackId }
+                // Moving through the timeline lands on the next occurrence of a repeated track, not its first
+                val advancing = reason == Player.MEDIA_ITEM_TRANSITION_REASON_AUTO || reason == Player.MEDIA_ITEM_TRANSITION_REASON_SEEK
+                val newIdx = currentTrackIndexOf(trackId, if (advancing) currentTrackIndex + 1 else currentTrackIndex)
                 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
@@ -135,6 +140,7 @@ internal class TrackPlayerEventListener(
         reason: Int,
     ) {
         val r = if (reason == Player.PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST) Reason.USER_ACTION else null
+        core.updateJsKeepAlive()
         core.emitStateChange(r)
     }
 
@@ -154,7 +160,10 @@ internal class TrackPlayerEventListener(
     }
 
     override fun onIsPlayingChanged(isPlaying: Boolean) {
-        if (isPlaying) core.startProgressTicks()
+        if (isPlaying) {
+            core.startProgressTicks()
+            core.onPlaybackHealthy()
+        }
         core.emitStateChange()
     }
 
@@ -171,21 +180,7 @@ internal class TrackPlayerEventListener(
         }
     }
 
-    override fun onPlayerError(error: PlaybackException) {
-        with(core) {
-            NitroPlayerLogger.log(
-                "TrackPlayer",
-                "Player error: ${error.errorCodeName} - ${error.message}",
-            )
-            notifyPlaybackStateChange(TrackPlayerState.STOPPED, Reason.ERROR)
-            // 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()) {
-                exo.seekToNext()
-                exo.prepare()
-            }
-        }
-    }
+    override fun onPlayerError(error: PlaybackException) = core.handlePlayerError(error)
 
     override fun onAudioSessionIdChanged(audioSessionId: Int) {
         if (audioSessionId != 0) {