react-native-nitro-player 1.5.0 → 1.5.1-alpha.0

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

@@ -37,6 +37,14 @@ internal fun TrackPlayerCore.castableUpcoming(tracks: List<TrackItem>): List<Tra
     return result
 }
 
+/**
+ * Upcoming MediaItems kept materialized behind the current one. The logical queue
+ * (currentTracks + temp lists) stays complete; only ExoPlayer's timeline is windowed,
+ * and it is topped up on every item transition. Building a MediaItem is not free —
+ * each one resolves the effective URL, which used to stat() the download record.
+ */
+internal const val QUEUE_WINDOW_SIZE = 4
+
 internal fun TrackPlayerCore.mediaIdFor(track: TrackItem): String {
     val playlistId = currentPlaylistId ?: ""
     return if (playlistId.isNotEmpty()) "$playlistId:${track.id}" else track.id
@@ -70,8 +78,9 @@ internal fun TrackPlayerCore.rebuildQueueAndPlayFromIndex(index: Int) {
         return
     }
 
+    val windowEnd = minOf(index + 1 + QUEUE_WINDOW_SIZE, currentTracks.size)
     val mediaItems =
-        currentTracks.subList(index, currentTracks.size).map { track ->
+        currentTracks.subList(index, windowEnd).map { track ->
             makeMediaItem(track, mediaIdFor(track))
         }
 
@@ -92,7 +101,7 @@ internal fun TrackPlayerCore.rebuildQueueFromCurrentPosition() {
     val currentTrackId = exo.currentMediaItem?.mediaId?.let { extractTrackId(it) }
 
     if (
-        currentTrackId != null && 
+        currentTrackId != null &&
         currentTracks.none { it.id == currentTrackId } &&
         currentTemporaryType == TrackPlayerCore.TemporaryType.NONE
     ) {
@@ -131,12 +140,32 @@ internal fun TrackPlayerCore.rebuildQueueFromCurrentPosition() {
         }
     }
 
-    val newMediaItems = newQueueTracks.map { makeMediaItem(it, mediaIdFor(it)) }
+    // Window the materialized timeline; onMediaItemTransition tops it back up.
+    // NOT while casting: the receiver holds the whole queue (rebuildQueueAndPlayFromIndex
+    // loads it unwindowed), so truncating here would cut it down to the window size.
+    if (!isCastingField && newQueueTracks.size > QUEUE_WINDOW_SIZE) {
+        newQueueTracks = newQueueTracks.subList(0, QUEUE_WINDOW_SIZE)
+    }
+
+    // Keep the longest matching prefix of already-buffered items and rebuild only from
+    // the first divergence. A pure append (the common window top-up) touches nothing
+    // 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
+    ) {
+        commonPrefix++
+    }
 
-    if (exo.mediaItemCount > currentIndex + 1) {
-        exo.removeMediaItems(currentIndex + 1, exo.mediaItemCount)
+    if (exo.mediaItemCount > currentIndex + 1 + commonPrefix) {
+        exo.removeMediaItems(currentIndex + 1 + commonPrefix, exo.mediaItemCount)
+    }
+    if (commonPrefix < newQueueTracks.size) {
+        exo.addMediaItems(
+            newQueueTracks.subList(commonPrefix, newQueueTracks.size).map { makeMediaItem(it, mediaIdFor(it)) },
+        )
     }
-    exo.addMediaItems(newMediaItems)
 }
 
 /** Desired upcoming list after the current track: playNext + upNext + remaining originals, with the playing temp track ([currentId]) skipped. */
@@ -203,7 +232,8 @@ internal fun TrackPlayerCore.updatePlayerQueue(tracks: List<TrackItem>) {
         return
     }
 
-    val mediaItems = tracks.map { makeMediaItem(it, mediaIdFor(it)) }
+    currentTrackIndex = 0
+    val mediaItems = tracks.take(1 + QUEUE_WINDOW_SIZE).map { makeMediaItem(it, mediaIdFor(it)) }
     exo.setMediaItems(mediaItems, true)
     if (exo.playbackState == Player.STATE_IDLE && mediaItems.isNotEmpty()) {
         exo.prepare()
@@ -239,15 +269,17 @@ internal fun TrackPlayerCore.makeMediaItem(
         try {
             val headersRaw = payload.toHashMap()["headers"]
             if (headersRaw is Map<*, *>) {
-                val headers = headersRaw
-                    .mapNotNull { (k, v) -> if (k is String && v is String) k to v else null }
-                    .toMap()
+                val headers =
+                    headersRaw
+                        .mapNotNull { (k, v) -> if (k is String && v is String) k to v else null }
+                        .toMap()
                 if (headers.isNotEmpty()) {
                     com.margelo.nitro.nitroplayer.media.AuthAwareHttpDataSourceFactory
                         .setHeadersForUrl(effectiveUrl, headers)
                 }
             }
-        } catch (_: Exception) {}
+        } catch (_: Exception) {
+        }
     }
 
     return MediaItem

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

@@ -43,12 +43,16 @@ internal fun TrackPlayerCore.initFromService(binder: NitroPlayerPlaybackService.
     if (sessionId != 0) {
         try {
             EqualizerCore.getInstance(context).initialize(sessionId)
-        } catch (_: Exception) { }
+        } catch (_: Exception) {
+        }
     }
 
     // Start progress ticks on the main looper
-    playerHandler.postDelayed(progressUpdateRunnable, 250)
+    playerHandler.postDelayed(progressUpdateRunnable, TrackPlayerCore.PROGRESS_INTERVAL_MS)
 
     // Signal that the player is ready — unblocks all withPlayerContext callers
     completeServiceReady()
+
+    // Flush any commands JS issued before the service bound, in their original order
+    startCommandDraining()
 }

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

@@ -14,16 +14,21 @@ import com.margelo.nitro.nitroplayer.TrackItem
 suspend fun TrackPlayerCore.loadPlaylist(
     playlistId: String,
     startIndex: Int? = null,
-) =
-    withPlayerContext {
+) = withPlayerContext { loadPlaylistOnQueue(playlistId, startIndex) }
+
+internal fun TrackPlayerCore.loadPlaylistOnQueue(
+    playlistId: String,
+    startIndex: Int? = null,
+) {
+    run {
         playNextStack.clear()
         upNextQueue.clear()
         currentTemporaryType = TrackPlayerCore.TemporaryType.NONE
-        val playlist = playlistManager.getPlaylist(playlistId) ?: return@withPlayerContext
+        val playlist = playlistManager.getPlaylist(playlistId) ?: return@run
 
         val targetIndex =
             if (startIndex != null) {
-                if (startIndex < 0 || startIndex >= playlist.tracks.size) return@withPlayerContext
+                if (startIndex < 0 || startIndex >= playlist.tracks.size) return@run
                 startIndex
             } else {
                 0
@@ -41,6 +46,7 @@ suspend fun TrackPlayerCore.loadPlaylist(
         checkUpcomingTracksForUrls(lookaheadCount)
         notifyTemporaryQueueChange()
     }
+}
 
 /**
  * Debounced update — coalesces rapid back-to-back mutations into one player rebuild.
@@ -80,39 +86,43 @@ internal fun TrackPlayerCore.addToUpNextInternal(trackId: String) {
 
 // ── Remove / clear ────────────────────────────────────────────────────────
 
-suspend fun TrackPlayerCore.removeFromPlayNext(trackId: String): Boolean =
-    withPlayerContext {
-        val idx = playNextStack.indexOfFirst { it.id == trackId }
-        if (idx < 0) return@withPlayerContext false
-        playNextStack.removeAt(idx)
-        if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
-        notifyTemporaryQueueChange()
-        true
-    }
+suspend fun TrackPlayerCore.removeFromPlayNext(trackId: String): Boolean = withPlayerContext { removeFromPlayNextOnQueue(trackId) }
 
-suspend fun TrackPlayerCore.removeFromUpNext(trackId: String): Boolean =
-    withPlayerContext {
-        val idx = upNextQueue.indexOfFirst { it.id == trackId }
-        if (idx < 0) return@withPlayerContext false
-        upNextQueue.removeAt(idx)
-        if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
-        notifyTemporaryQueueChange()
-        true
-    }
+internal fun TrackPlayerCore.removeFromPlayNextOnQueue(trackId: String): Boolean {
+    val idx = playNextStack.indexOfFirst { it.id == trackId }
+    if (idx < 0) return false
+    playNextStack.removeAt(idx)
+    if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
+    notifyTemporaryQueueChange()
+    return true
+}
 
-suspend fun TrackPlayerCore.clearPlayNext() =
-    withPlayerContext {
-        playNextStack.clear()
-        if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
-        notifyTemporaryQueueChange()
-    }
+suspend fun TrackPlayerCore.removeFromUpNext(trackId: String): Boolean = withPlayerContext { removeFromUpNextOnQueue(trackId) }
 
-suspend fun TrackPlayerCore.clearUpNext() =
-    withPlayerContext {
-        upNextQueue.clear()
-        if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
-        notifyTemporaryQueueChange()
-    }
+internal fun TrackPlayerCore.removeFromUpNextOnQueue(trackId: String): Boolean {
+    val idx = upNextQueue.indexOfFirst { it.id == trackId }
+    if (idx < 0) return false
+    upNextQueue.removeAt(idx)
+    if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
+    notifyTemporaryQueueChange()
+    return true
+}
+
+suspend fun TrackPlayerCore.clearPlayNext() = withPlayerContext { clearPlayNextOnQueue() }
+
+internal fun TrackPlayerCore.clearPlayNextOnQueue() {
+    playNextStack.clear()
+    if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
+    notifyTemporaryQueueChange()
+}
+
+suspend fun TrackPlayerCore.clearUpNext() = withPlayerContext { clearUpNextOnQueue() }
+
+internal fun TrackPlayerCore.clearUpNextOnQueue() {
+    upNextQueue.clear()
+    if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
+    notifyTemporaryQueueChange()
+}
 
 // ── Reorder ───────────────────────────────────────────────────────────────
 
@@ -123,26 +133,30 @@ suspend fun TrackPlayerCore.clearUpNext() =
 suspend fun TrackPlayerCore.reorderTemporaryTrack(
     trackId: String,
     newIndex: Int,
-): Boolean =
-    withPlayerContext {
-        val combined = (playNextStack + upNextQueue).toMutableList()
-        val fromIdx = combined.indexOfFirst { it.id == trackId }
-        if (fromIdx < 0) return@withPlayerContext false
-        val track = combined.removeAt(fromIdx)
-        val clampedIndex = newIndex.coerceIn(0, combined.size)
-        combined.add(clampedIndex, track)
-
-        // Split back at original playNextStack.size boundary (reduced if an item was moved out)
-        val pnSize = playNextStack.size
-        playNextStack.clear()
-        upNextQueue.clear()
-        playNextStack.addAll(combined.take(pnSize))
-        upNextQueue.addAll(combined.drop(pnSize))
+): Boolean = withPlayerContext { reorderTemporaryTrackOnQueue(trackId, newIndex) }
 
-        if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
-        notifyTemporaryQueueChange()
-        true
-    }
+internal fun TrackPlayerCore.reorderTemporaryTrackOnQueue(
+    trackId: String,
+    newIndex: Int,
+): Boolean {
+    val combined = (playNextStack + upNextQueue).toMutableList()
+    val fromIdx = combined.indexOfFirst { it.id == trackId }
+    if (fromIdx < 0) return false
+    val track = combined.removeAt(fromIdx)
+    val clampedIndex = newIndex.coerceIn(0, combined.size)
+    combined.add(clampedIndex, track)
+
+    // Split back at original playNextStack.size boundary (reduced if an item was moved out)
+    val pnSize = playNextStack.size
+    playNextStack.clear()
+    upNextQueue.clear()
+    playNextStack.addAll(combined.take(pnSize))
+    upNextQueue.addAll(combined.drop(pnSize))
+
+    if (isExoInitialized && exo.currentMediaItem != null) rebuildQueueFromCurrentPosition()
+    notifyTemporaryQueueChange()
+    return true
+}
 
 // ── Read-only accessors ────────────────────────────────────────────────────
 

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

@@ -12,8 +12,10 @@ import com.margelo.nitro.nitroplayer.TrackItem
 
 // ── Track updates (URL resolution) ────────────────────────────────────────
 
-suspend fun TrackPlayerCore.updateTracks(tracks: List<TrackItem>) =
-    withPlayerContext {
+suspend fun TrackPlayerCore.updateTracks(tracks: List<TrackItem>) = withPlayerContext { updateTracksOnQueue(tracks) }
+
+internal fun TrackPlayerCore.updateTracksOnQueue(tracks: List<TrackItem>) {
+    run {
         val currentTrack = getCurrentTrack()
         val currentTrackId = currentTrack?.id
         val currentTrackIsEmpty = currentTrack?.url.isNullOrEmpty()
@@ -32,7 +34,7 @@ suspend fun TrackPlayerCore.updateTracks(tracks: List<TrackItem>) =
                     else -> true
                 }
             }
-        if (safeTracks.isEmpty()) return@withPlayerContext
+        if (safeTracks.isEmpty()) return@run
 
         val affectedPlaylists: Map<String, Int> = playlistManager.updateTracks(safeTracks)
 
@@ -64,12 +66,13 @@ suspend fun TrackPlayerCore.updateTracks(tracks: List<TrackItem>) =
                 } else {
                     rebuildQueueFromCurrentPosition()
                 }
-                return@withPlayerContext
+                return@run
             }
 
             rebuildQueueFromCurrentPosition()
         }
     }
+}
 
 // ── Track queries ─────────────────────────────────────────────────────────
 
@@ -84,14 +87,42 @@ internal fun TrackPlayerCore.getTracksNeedingUrlsInternal(): List<TrackItem> {
 
 suspend fun TrackPlayerCore.getNextTracks(count: Int): List<TrackItem> = withPlayerContext { getNextTracksInternal(count) }
 
+/**
+ * Walks the queue structure directly instead of materializing the whole queue — this
+ * runs on every skip and every progress tick, so it must not be O(playlist) just to
+ * read the next few tracks.
+ */
 internal fun TrackPlayerCore.getNextTracksInternal(count: Int): List<TrackItem> {
-    val actualQueue = getActualQueueInternal()
-    if (actualQueue.isEmpty()) return emptyList()
-    val currentIdx = actualQueue.indexOfFirst { it.id == getCurrentTrack()?.id }
-    if (currentIdx == -1) return emptyList()
-    val start = currentIdx + 1
-    val end = minOf(start + count, actualQueue.size)
-    return if (start < actualQueue.size) actualQueue.subList(start, end) else emptyList()
+    if (count <= 0) return emptyList()
+    val out = ArrayList<TrackItem>(count)
+    val currentId = if (isExoInitialized) exo.currentMediaItem?.mediaId?.let { extractTrackId(it) } else null
+
+    var skippedPlayNext = currentTemporaryType != TrackPlayerCore.TemporaryType.PLAY_NEXT
+    for (track in playNextStack) {
+        if (!skippedPlayNext && track.id == currentId) {
+            skippedPlayNext = true
+            continue
+        }
+        out.add(track)
+        if (out.size == count) return out
+    }
+
+    var skippedUpNext = currentTemporaryType != TrackPlayerCore.TemporaryType.UP_NEXT
+    for (track in upNextQueue) {
+        if (!skippedUpNext && track.id == currentId) {
+            skippedUpNext = true
+            continue
+        }
+        out.add(track)
+        if (out.size == count) return out
+    }
+
+    var index = currentTrackIndex + 1
+    while (index < currentTracks.size && out.size < count) {
+        out.add(currentTracks[index])
+        index++
+    }
+    return out
 }
 
 suspend fun TrackPlayerCore.getCurrentTrackIndex(): Int = withPlayerContext { currentTrackIndex }

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

@@ -39,6 +39,15 @@ class DownloadDatabase private constructor(
     }
 
     private val downloadedTracks = mutableMapOf<String, DownloadedTrackRecord>()
+
+    /**
+     * Memoized `File.exists()` verdicts, keyed by track ID.
+     *
+     * Queue building asks "is this downloaded?" once per track, and each answer used to
+     * cost a stat() — O(playlist) syscalls per rebuild, on the main looper. Records only
+     * change through this class, so the verdict is cached and dropped in [saveToDisk].
+     */
+    private val existenceCache = mutableMapOf<String, Boolean>()
     private val playlistTracks = mutableMapOf<String, MutableSet<String>>()
     private val fileManager = DownloadFileManager.getInstance(context)
     private val ioScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
@@ -82,11 +91,21 @@ class DownloadDatabase private constructor(
     fun isTrackDownloaded(trackId: String): Boolean {
         synchronized(this) {
             val record = downloadedTracks[trackId] ?: return false
-            // Verify file still exists
-            return File(record.localPath).exists()
+            return cachedFileExists(trackId, record.localPath)
         }
     }
 
+    /** Caller must hold the monitor. */
+    private fun cachedFileExists(
+        trackId: String,
+        path: String,
+    ): Boolean = existenceCache.getOrPut(trackId) { File(path).exists() }
+
+    /** Drops every memoized verdict — files may have changed outside the app. */
+    fun invalidateExistenceCache() {
+        synchronized(this) { existenceCache.clear() }
+    }
+
     fun isPlaylistDownloaded(playlistId: String): Boolean {
         synchronized(this) {
             val trackIds = playlistTracks[playlistId] ?: return false
@@ -118,8 +137,8 @@ class DownloadDatabase private constructor(
         synchronized(this) {
             val record = downloadedTracks[trackId] ?: return null
 
-            // Verify file still exists
-            if (!File(record.localPath).exists()) {
+            // Verify file still exists (memoized)
+            if (!cachedFileExists(trackId, record.localPath)) {
                 // File was deleted externally, clean up record
                 downloadedTracks.remove(trackId)
                 saveToDisk()
@@ -302,6 +321,9 @@ class DownloadDatabase private constructor(
 
     // Persistence — called while holding synchronized(this); snapshots data then writes on IO.
     private fun saveToDisk() {
+        // Every record mutation funnels through here, so this is the one place that has
+        // to drop memoized File.exists() verdicts.
+        existenceCache.clear()
         val trackSnapshot = downloadedTracks.toMap()
         val playlistSnapshot = playlistTracks.mapValues { it.value.toSet() }
         ioScope.launch {

package/ios/HybridTrackPlayer.swift

@@ -25,40 +25,63 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
     super.init()
   }
 
+  // MARK: - Ordered dispatch
+  //
+  // `Promise.async` starts an unordered Task, so the hop onto the player queue used
+  // to happen at an arbitrary later point: two calls made in order from JS could
+  // reach the player in reverse order (play-then-pause landing as pause-then-play).
+  // Enqueueing synchronously here — on the JS thread, at call time — makes the serial
+  // queue's FIFO order equal the JS call order.
+
+  private func enqueue<T>(_ block: @escaping () -> T) -> Promise<T> {
+    let promise = Promise<T>()
+    core.playerQueue.async { promise.resolve(withResult: block()) }
+    return promise
+  }
+
+  private func enqueueThrowing<T>(_ block: @escaping () throws -> T) -> Promise<T> {
+    let promise = Promise<T>()
+    core.playerQueue.async {
+      do { promise.resolve(withResult: try block()) }
+      catch { promise.reject(withError: error) }
+    }
+    return promise
+  }
+
   // MARK: - Playback Control (async Promise<Void>)
 
   func play() throws -> Promise<Void> {
-    Promise.async { await self.core.play() }
+    enqueue { self.core.playOnQueue() }
   }
 
   func pause() throws -> Promise<Void> {
-    Promise.async { await self.core.pause() }
+    enqueue { self.core.pauseOnQueue() }
   }
 
   func seek(position: Double) throws -> Promise<Void> {
-    Promise.async { await self.core.seek(position: position) }
+    enqueue { self.core.seekOnQueue(position: position) }
   }
 
   func skipToNext() throws -> Promise<Void> {
-    Promise.async { await self.core.skipToNext() }
+    enqueue { self.core.skipToNextOnQueue() }
   }
 
   func skipToPrevious() throws -> Promise<Void> {
-    Promise.async { await self.core.skipToPrevious() }
+    enqueue { self.core.skipToPreviousOnQueue() }
   }
 
   func playSong(songId: String, fromPlaylist: String?) throws -> Promise<Void> {
-    Promise.async { await self.core.playSong(songId: songId, fromPlaylist: fromPlaylist) }
+    enqueue { self.core.playSongInternal(songId: songId, fromPlaylist: fromPlaylist) }
   }
 
   func skipToIndex(index: Double) throws -> Promise<Bool> {
-    Promise.async { await self.core.skipToIndex(index: Int(index)) }
+    enqueue { self.core.skipToIndexOnQueue(index: Int(index)) }
   }
 
   // MARK: - Repeat / Volume / Config
 
   func setRepeatMode(mode: RepeatMode) throws -> Promise<Void> {
-    Promise.async { await self.core.setRepeatMode(mode: mode) }
+    enqueue { self.core.setRepeatModeOnQueue(mode: mode) }
   }
 
   func getRepeatMode() throws -> RepeatMode {
@@ -66,12 +89,12 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
   }
 
   func setVolume(volume: Double) throws -> Promise<Void> {
-    Promise.async { await self.core.setVolume(volume: volume) }
+    enqueue { self.core.setVolumeOnQueue(volume: volume) }
   }
 
   func configure(config: PlayerConfig) throws -> Promise<Void> {
-    Promise.async {
-      await self.core.configure(
+    enqueue {
+      self.core.configureOnQueue(
         androidAutoEnabled: config.androidAutoEnabled,
         carPlayEnabled: config.carPlayEnabled,
         showInNotification: config.showInNotification,
@@ -83,80 +106,80 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
   // MARK: - Queue / State reads
 
   func getActualQueue() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getActualQueue() }
+    enqueue { self.core.getActualQueueInternal() }
   }
 
   func getState() throws -> Promise<PlayerState> {
-    Promise.async { await self.core.getState() }
+    enqueue { self.core.getStateInternal() }
   }
 
   func getCurrentTrackIndex() throws -> Promise<Double> {
-    Promise.async { Double(await self.core.getCurrentTrackIndex()) }
+    enqueue { Double(self.core.currentTrackIndex) }
   }
 
   // MARK: - URL updates / lazy loading
 
   func updateTracks(tracks: [TrackItem]) throws -> Promise<Void> {
-    Promise.async { await self.core.updateTracks(tracks: tracks) }
+    enqueue { self.core.updateTracksInternal(tracks: tracks) }
   }
 
   func getTracksById(trackIds: [String]) throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getTracksById(trackIds: trackIds) }
+    enqueue { self.core.getPlaylistManager().getTracksById(trackIds: trackIds) }
   }
 
   func getTracksNeedingUrls() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getTracksNeedingUrls() }
+    enqueue { self.core.getTracksNeedingUrlsInternal() }
   }
 
   func getNextTracks(count: Double) throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getNextTracks(count: Int(count)) }
+    enqueue { self.core.getNextTracksInternal(count: Int(count)) }
   }
 
   // MARK: - Playback speed
   func setPlaybackSpeed(speed: Double) throws -> Promise<Void> {
-    Promise.async { await self.core.setPlaybackSpeed(speed) }
+    enqueue { self.core.setPlaybackSpeedOnQueue(speed) }
   }
 
   func getPlaybackSpeed() throws -> Promise<Double> {
-    Promise.async { await self.core.getPlaybackSpeed() }
+    enqueue { self.core.currentPlaybackSpeed }
   }
 
   // MARK: - Temporary queue v2
 
   func addToUpNext(trackId: String) throws -> Promise<Void> {
-    Promise.async { try await self.core.addToUpNext(trackId: trackId) }
+    enqueueThrowing { try self.core.addToUpNextOnQueue(trackId: trackId) }
   }
 
   func playNext(trackId: String) throws -> Promise<Void> {
-    Promise.async { try await self.core.playNext(trackId: trackId) }
+    enqueueThrowing { try self.core.playNextOnQueue(trackId: trackId) }
   }
 
   func removeFromPlayNext(trackId: String) throws -> Promise<Bool> {
-    Promise.async { await self.core.removeFromPlayNext(trackId: trackId) }
+    enqueue { self.core.removeFromPlayNextOnQueue(trackId: trackId) }
   }
 
   func removeFromUpNext(trackId: String) throws -> Promise<Bool> {
-    Promise.async { await self.core.removeFromUpNext(trackId: trackId) }
+    enqueue { self.core.removeFromUpNextOnQueue(trackId: trackId) }
   }
 
   func clearPlayNext() throws -> Promise<Void> {
-    Promise.async { await self.core.clearPlayNext() }
+    enqueue { self.core.clearPlayNextOnQueue() }
   }
 
   func clearUpNext() throws -> Promise<Void> {
-    Promise.async { await self.core.clearUpNext() }
+    enqueue { self.core.clearUpNextOnQueue() }
   }
 
   func reorderTemporaryTrack(trackId: String, newIndex: Double) throws -> Promise<Bool> {
-    Promise.async { await self.core.reorderTemporaryTrack(trackId: trackId, newIndex: Int(newIndex)) }
+    enqueue { self.core.reorderTemporaryTrackOnQueue(trackId: trackId, newIndex: Int(newIndex)) }
   }
 
   func getPlayNextQueue() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getPlayNextQueue() }
+    enqueue { self.core.playNextStack }
   }
 
   func getUpNextQueue() throws -> Promise<[TrackItem]> {
-    Promise.async { await self.core.getUpNextQueue() }
+    enqueue { self.core.upNextQueue }
   }
 
   // MARK: - Android Auto (iOS no-op)

package/ios/core/TrackPlayerCore.swift

@@ -26,6 +26,10 @@ class TrackPlayerCore: NSObject {
     static let preferredForwardBufferDuration: Double = 30.0
     static let preloadAssetKeys: [String] = ["playable", "duration", "tracks", "preferredTransform"]
     static let gaplessPreloadCount: Int = 3
+    /// Upcoming AVPlayerItems kept materialized behind the current one. The logical
+    /// queue (currentTracks + temp lists) stays complete; only the AVQueuePlayer is
+    /// windowed, and it is topped up on every item transition.
+    static let queueWindowSize: Int = 4
     // Stall & failure recovery
     static let maxFailedItemRetries: Int = 3
     static let failedItemRetryDelay: TimeInterval = 2.0
@@ -44,7 +48,10 @@ class TrackPlayerCore: NSObject {
   internal var currentPlaylistId: String?
   internal var currentTrackIndex: Int = -1
   internal var currentTracks: [TrackItem] = []
-  internal var pendingPlaylistUpdateWorkItem: DispatchWorkItem?
+  // Bumped on every updatePlaylist request (playerQueue-owned). A queued rebuild
+  // whose generation is stale was superseded by a later request and is dropped,
+  // so a burst of playlist mutations collapses into a single rebuild.
+  internal var playlistUpdateGeneration: UInt64 = 0
   internal var isManuallySeeked = false
   internal var currentRepeatMode: RepeatMode = .off
   internal var currentPlaybackSpeed: Double = 1.0
@@ -239,6 +246,7 @@ class TrackPlayerCore: NSObject {
       NotificationCenter.default.removeObserver(self)
       self.pathMonitor?.cancel()
       self.pathMonitor = nil
+      for asset in self.preloadedAssets.values { asset.cancelLoading() }
       self.preloadedAssets.removeAll()
       self.failedItemRetryCounts.removeAll()
       self.redirectResolver.clear()