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

package/ios/core/TrackPlayerTempQueue.swift

@@ -9,159 +9,166 @@ import Foundation
 extension TrackPlayerCore {
 
   func loadPlaylist(playlistId: String, startIndex: Int? = nil) async {
-    await withPlayerQueueNoThrow {
-      self.playNextStack.removeAll()
-      self.upNextQueue.removeAll()
-      self.currentTemporaryType = .none
-
-      NitroPlayerLogger.log("TrackPlayerCore", "\n" + String(repeating: "🎼", count: Constants.playlistSeparatorLength))
-      NitroPlayerLogger.log("TrackPlayerCore", "📂 LOAD PLAYLIST REQUEST")
-      NitroPlayerLogger.log("TrackPlayerCore", "   Playlist ID: \(playlistId)")
-      NitroPlayerLogger.log("TrackPlayerCore", "   🧹 Cleared temporary tracks")
-
-      guard let playlist = self.playlistManager.getPlaylist(playlistId: playlistId) else {
-        NitroPlayerLogger.log("TrackPlayerCore", "   ❌ Playlist NOT FOUND")
-        NitroPlayerLogger.log("TrackPlayerCore", String(repeating: "🎼", count: Constants.playlistSeparatorLength) + "\n")
-        return
-      }
+    await withPlayerQueueNoThrow { self.loadPlaylistOnQueue(playlistId: playlistId, startIndex: startIndex) }
+  }
 
-      NitroPlayerLogger.log("TrackPlayerCore", "   ✅ Found playlist: \(playlist.name)")
-      NitroPlayerLogger.log("TrackPlayerCore", "   📋 Contains \(playlist.tracks.count) tracks:")
-      for (index, track) in playlist.tracks.enumerated() {
-        NitroPlayerLogger.log("TrackPlayerCore", "      [\(index + 1)] \(track.title) - \(track.artist)")
-      }
+  func loadPlaylistOnQueue(playlistId: String, startIndex: Int? = nil) {
+    self.playNextStack.removeAll()
+    self.upNextQueue.removeAll()
+    self.currentTemporaryType = .none
+
+    NitroPlayerLogger.log("TrackPlayerCore", "\n" + String(repeating: "🎼", count: Constants.playlistSeparatorLength))
+    NitroPlayerLogger.log("TrackPlayerCore", "📂 LOAD PLAYLIST REQUEST")
+    NitroPlayerLogger.log("TrackPlayerCore", "   Playlist ID: \(playlistId)")
+    NitroPlayerLogger.log("TrackPlayerCore", "   🧹 Cleared temporary tracks")
+
+    guard let playlist = self.playlistManager.getPlaylist(playlistId: playlistId) else {
+      NitroPlayerLogger.log("TrackPlayerCore", "   ❌ Playlist NOT FOUND")
       NitroPlayerLogger.log("TrackPlayerCore", String(repeating: "🎼", count: Constants.playlistSeparatorLength) + "\n")
+      return
+    }
 
-      let targetIndex: Int
-      if let startIndex {
-        guard startIndex >= 0 && startIndex < playlist.tracks.count else {
-          NitroPlayerLogger.log("TrackPlayerCore", "   ❌ Invalid start index: \(startIndex) (track count: \(playlist.tracks.count))")
-          return
-        }
-        targetIndex = startIndex
-      } else {
-        targetIndex = 0
-      }
+    NitroPlayerLogger.log("TrackPlayerCore", "   ✅ Found playlist: \(playlist.name)")
+    NitroPlayerLogger.log("TrackPlayerCore", "   📋 Contains \(playlist.tracks.count) tracks:")
+    for (index, track) in playlist.tracks.enumerated() {
+      NitroPlayerLogger.log("TrackPlayerCore", "      [\(index + 1)] \(track.title) - \(track.artist)")
+    }
+    NitroPlayerLogger.log("TrackPlayerCore", String(repeating: "🎼", count: Constants.playlistSeparatorLength) + "\n")
 
-      self.currentPlaylistId = playlistId
-      if targetIndex == 0 {
-        self.updatePlayerQueue(tracks: playlist.tracks)
-      } else {
-        // Bypass updatePlayerQueue to avoid emitting a spurious onTrackChange for index 0.
-        // Set currentTracks directly so rebuildQueueFromPlaylistIndex can use them.
-        self.currentTracks = playlist.tracks
-        self.preloadedAssets.removeAll()
-        _ = self.rebuildQueueFromPlaylistIndex(index: targetIndex)
+    let targetIndex: Int
+    if let startIndex {
+      guard startIndex >= 0 && startIndex < playlist.tracks.count else {
+        NitroPlayerLogger.log("TrackPlayerCore", "   ❌ Invalid start index: \(startIndex) (track count: \(playlist.tracks.count))")
+        return
       }
-      self.emitStateChange()
-      self.checkUpcomingTracksForUrls(lookahead: self.lookaheadCount)
-      self.notifyTemporaryQueueChange()
+      targetIndex = startIndex
+    } else {
+      targetIndex = 0
+    }
+
+    self.currentPlaylistId = playlistId
+    if targetIndex == 0 {
+      self.updatePlayerQueue(tracks: playlist.tracks)
+    } else {
+      // Bypass updatePlayerQueue to avoid emitting a spurious onTrackChange for index 0.
+      // Set currentTracks directly so rebuildQueueFromPlaylistIndex can use them.
+      self.currentTracks = playlist.tracks
+      for asset in self.preloadedAssets.values { asset.cancelLoading() }
+      self.preloadedAssets.removeAll()
+      _ = self.rebuildQueueFromPlaylistIndex(index: targetIndex)
     }
+    self.emitStateChange()
+    self.checkUpcomingTracksForUrls(lookahead: self.lookaheadCount)
+    self.notifyTemporaryQueueChange()
   }
 
+  /// Callable from any thread (PlaylistManager runs on its own queue) — all state
+  /// access happens on playerQueue.
   func updatePlaylist(playlistId: String) {
-    guard currentPlaylistId == playlistId else { return }
-
-    // Cancel any pending rebuild so back-to-back calls collapse into a single rebuild.
-    pendingPlaylistUpdateWorkItem?.cancel()
-
-    let workItem = DispatchWorkItem { [weak self] in
-      guard let self, self.currentPlaylistId == playlistId,
-        let playlist = self.playlistManager.getPlaylist(playlistId: playlistId) else { return }
+    playerQueue.async { [weak self] in
+      guard let self, self.currentPlaylistId == playlistId else { return }
+
+      self.playlistUpdateGeneration &+= 1
+      let generation = self.playlistUpdateGeneration
+
+      // Run at the tail of the current burst; stale generations drop out.
+      self.playerQueue.async { [weak self] in
+        guard let self, generation == self.playlistUpdateGeneration,
+          self.currentPlaylistId == playlistId,
+          let playlist = self.playlistManager.getPlaylist(playlistId: playlistId) else { return }
+
+        // If nothing is playing yet, do a full load
+        guard self.player?.currentItem != nil else {
+          self.updatePlayerQueue(tracks: playlist.tracks)
+          self.checkUpcomingTracksForUrls(lookahead: self.lookaheadCount)
+          return
+        }
 
-      // If nothing is playing yet, do a full load
-      guard self.player?.currentItem != nil else {
-        self.updatePlayerQueue(tracks: playlist.tracks)
+        // Update tracks list without interrupting playback
+        self.currentTracks = playlist.tracks
+        self.rebuildAVQueueFromCurrentPosition()
         self.checkUpcomingTracksForUrls(lookahead: self.lookaheadCount)
-        return
       }
-
-      // Update tracks list without interrupting playback
-      self.currentTracks = playlist.tracks
-      self.rebuildAVQueueFromCurrentPosition()
-      self.checkUpcomingTracksForUrls(lookahead: self.lookaheadCount)
     }
-
-    pendingPlaylistUpdateWorkItem = workItem
-    playerQueue.async(execute: workItem)
   }
 
-  func playNext(trackId: String) async throws {
-    try await withPlayerQueue {
-      guard let track = self.findTrackById(trackId) else {
-        throw NSError(domain: "NitroPlayer", code: 404, userInfo: [NSLocalizedDescriptionKey: "Track \(trackId) not found"])
-      }
-      NitroPlayerLogger.log("TrackPlayerCore", "⏭️ playNext(\(trackId))")
-      self.playNextStack.insert(track, at: 0)
-      NitroPlayerLogger.log("TrackPlayerCore", "   ✅ Added '\(track.title)' to playNext stack (position: 1)")
-      if self.player?.currentItem != nil { self.rebuildAVQueueFromCurrentPosition() }
-      self.notifyTemporaryQueueChange()
+  func playNextOnQueue(trackId: String) throws {
+    guard let track = findTrackById(trackId) else {
+      throw NSError(domain: "NitroPlayer", code: 404, userInfo: [NSLocalizedDescriptionKey: "Track \(trackId) not found"])
     }
+    NitroPlayerLogger.log("TrackPlayerCore", "⏭️ playNext(\(trackId))")
+    playNextStack.insert(track, at: 0)
+    if player?.currentItem != nil { rebuildAVQueueFromCurrentPosition() }
+    notifyTemporaryQueueChange()
+  }
+  func playNext(trackId: String) async throws {
+    try await withPlayerQueue { try self.playNextOnQueue(trackId: trackId) }
   }
 
-  func addToUpNext(trackId: String) async throws {
-    try await withPlayerQueue {
-      guard let track = self.findTrackById(trackId) else {
-        throw NSError(domain: "NitroPlayer", code: 404, userInfo: [NSLocalizedDescriptionKey: "Track \(trackId) not found"])
-      }
-      NitroPlayerLogger.log("TrackPlayerCore", "📋 addToUpNext(\(trackId))")
-      self.upNextQueue.append(track)
-      NitroPlayerLogger.log("TrackPlayerCore", "   ✅ Added '\(track.title)' to upNext queue (position: \(self.upNextQueue.count))")
-      if self.player?.currentItem != nil { self.rebuildAVQueueFromCurrentPosition() }
-      self.notifyTemporaryQueueChange()
+  func addToUpNextOnQueue(trackId: String) throws {
+    guard let track = findTrackById(trackId) else {
+      throw NSError(domain: "NitroPlayer", code: 404, userInfo: [NSLocalizedDescriptionKey: "Track \(trackId) not found"])
     }
+    NitroPlayerLogger.log("TrackPlayerCore", "📋 addToUpNext(\(trackId))")
+    upNextQueue.append(track)
+    if player?.currentItem != nil { rebuildAVQueueFromCurrentPosition() }
+    notifyTemporaryQueueChange()
+  }
+  func addToUpNext(trackId: String) async throws {
+    try await withPlayerQueue { try self.addToUpNextOnQueue(trackId: trackId) }
   }
 
+  func removeFromPlayNextOnQueue(trackId: String) -> Bool {
+    guard let idx = playNextStack.firstIndex(where: { $0.id == trackId }) else { return false }
+    playNextStack.remove(at: idx)
+    if player?.currentItem != nil { rebuildAVQueueFromCurrentPosition() }
+    notifyTemporaryQueueChange()
+    return true
+  }
   func removeFromPlayNext(trackId: String) async -> Bool {
-    await withPlayerQueueNoThrow {
-      guard let idx = self.playNextStack.firstIndex(where: { $0.id == trackId }) else { return false }
-      self.playNextStack.remove(at: idx)
-      if self.player?.currentItem != nil { self.rebuildAVQueueFromCurrentPosition() }
-      self.notifyTemporaryQueueChange()
-      return true
-    }
+    await withPlayerQueueNoThrow { self.removeFromPlayNextOnQueue(trackId: trackId) }
   }
 
+  func removeFromUpNextOnQueue(trackId: String) -> Bool {
+    guard let idx = upNextQueue.firstIndex(where: { $0.id == trackId }) else { return false }
+    upNextQueue.remove(at: idx)
+    if player?.currentItem != nil { rebuildAVQueueFromCurrentPosition() }
+    notifyTemporaryQueueChange()
+    return true
+  }
   func removeFromUpNext(trackId: String) async -> Bool {
-    await withPlayerQueueNoThrow {
-      guard let idx = self.upNextQueue.firstIndex(where: { $0.id == trackId }) else { return false }
-      self.upNextQueue.remove(at: idx)
-      if self.player?.currentItem != nil { self.rebuildAVQueueFromCurrentPosition() }
-      self.notifyTemporaryQueueChange()
-      return true
-    }
+    await withPlayerQueueNoThrow { self.removeFromUpNextOnQueue(trackId: trackId) }
   }
 
-  func clearPlayNext() async {
-    await withPlayerQueueNoThrow {
-      self.playNextStack.removeAll()
-      if self.player?.currentItem != nil { self.rebuildAVQueueFromCurrentPosition() }
-      self.notifyTemporaryQueueChange()
-    }
+  func clearPlayNextOnQueue() {
+    playNextStack.removeAll()
+    if player?.currentItem != nil { rebuildAVQueueFromCurrentPosition() }
+    notifyTemporaryQueueChange()
   }
+  func clearPlayNext() async { await withPlayerQueueNoThrow { self.clearPlayNextOnQueue() } }
 
-  func clearUpNext() async {
-    await withPlayerQueueNoThrow {
-      self.upNextQueue.removeAll()
-      if self.player?.currentItem != nil { self.rebuildAVQueueFromCurrentPosition() }
-      self.notifyTemporaryQueueChange()
-    }
+  func clearUpNextOnQueue() {
+    upNextQueue.removeAll()
+    if player?.currentItem != nil { rebuildAVQueueFromCurrentPosition() }
+    notifyTemporaryQueueChange()
+  }
+  func clearUpNext() async { await withPlayerQueueNoThrow { self.clearUpNextOnQueue() } }
+
+  func reorderTemporaryTrackOnQueue(trackId: String, newIndex: Int) -> Bool {
+    var combined = playNextStack + upNextQueue
+    guard let fromIdx = combined.firstIndex(where: { $0.id == trackId }) else { return false }
+    let track = combined.remove(at: fromIdx)
+    let clamped = newIndex.clamped(to: 0...combined.count)
+    combined.insert(track, at: clamped)
+    let pnSize = playNextStack.count
+    playNextStack = Array(combined.prefix(pnSize))
+    upNextQueue = Array(combined.dropFirst(pnSize))
+    if player?.currentItem != nil { rebuildAVQueueFromCurrentPosition() }
+    notifyTemporaryQueueChange()
+    return true
   }
-
   func reorderTemporaryTrack(trackId: String, newIndex: Int) async -> Bool {
-    await withPlayerQueueNoThrow {
-      var combined = self.playNextStack + self.upNextQueue
-      guard let fromIdx = combined.firstIndex(where: { $0.id == trackId }) else { return false }
-      let track = combined.remove(at: fromIdx)
-      let clamped = newIndex.clamped(to: 0...combined.count)
-      combined.insert(track, at: clamped)
-      let pnSize = self.playNextStack.count
-      self.playNextStack = Array(combined.prefix(pnSize))
-      self.upNextQueue = Array(combined.dropFirst(pnSize))
-      if self.player?.currentItem != nil { self.rebuildAVQueueFromCurrentPosition() }
-      self.notifyTemporaryQueueChange()
-      return true
-    }
+    await withPlayerQueueNoThrow { self.reorderTemporaryTrackOnQueue(trackId: trackId, newIndex: newIndex) }
   }
 
   func getPlayNextQueue() async -> [TrackItem] {

package/ios/core/TrackPlayerUrlLoader.swift

@@ -71,7 +71,7 @@ extension TrackPlayerCore {
     for trackId in updatedTrackIds {
       if self.preloadedAssets[trackId] != nil {
         NitroPlayerLogger.log("TrackPlayerCore", "🗑️ Invalidating preloaded asset for track: \(trackId)")
-        self.preloadedAssets.removeValue(forKey: trackId)
+        self.preloadedAssets.removeValue(forKey: trackId)?.cancelLoading()
       }
     }
 
@@ -129,7 +129,7 @@ extension TrackPlayerCore {
         // No AVPlayerItem exists yet — lazy-load mode: URLs were empty when the queue first loaded.
         NitroPlayerLogger.log("TrackPlayerCore",
           "🔄 No current item — full queue rebuild from currentTrackIndex \(self.currentTrackIndex)")
-        player.removeAllItems()
+        self.removeAllItemsCancellingLoads(player)
         var lastItem: AVPlayerItem? = nil
         for (offset, track) in self.currentTracks[max(0, self.currentTrackIndex)...].enumerated() {
           let isPreload = offset < Constants.gaplessPreloadCount
@@ -164,17 +164,41 @@ extension TrackPlayerCore {
     }
   }
 
+  /// Walks the queue structure directly instead of materializing the whole queue —
+  /// this runs on every skip and on the periodic boundary observer, so it must not
+  /// be O(playlist) just to read the next few tracks.
   func getNextTracksInternal(count: Int) -> [TrackItem] {
-    let actualQueue = getActualQueueInternal()
-    guard !actualQueue.isEmpty else { return [] }
+    guard count > 0 else { return [] }
+    var out: [TrackItem] = []
+    out.reserveCapacity(count)
+    let currentId = activeCurrentTrackId
+
+    var skippedPlayNext = currentTemporaryType != .playNext
+    for track in playNextStack {
+      if !skippedPlayNext && track.id == currentId {
+        skippedPlayNext = true
+        continue
+      }
+      out.append(track)
+      if out.count == count { return out }
+    }
 
-    guard let currentTrack = getCurrentTrack(),
-      let currentIndex = actualQueue.firstIndex(where: { $0.id == currentTrack.id })
-    else { return [] }
+    var skippedUpNext = currentTemporaryType != .upNext
+    for track in upNextQueue {
+      if !skippedUpNext && track.id == currentId {
+        skippedUpNext = true
+        continue
+      }
+      out.append(track)
+      if out.count == count { return out }
+    }
 
-    let startIndex = currentIndex + 1
-    let endIndex = min(startIndex + count, actualQueue.count)
-    return startIndex < actualQueue.count ? Array(actualQueue[startIndex..<endIndex]) : []
+    var index = currentTrackIndex + 1
+    while index < currentTracks.count && out.count < count {
+      out.append(currentTracks[index])
+      index += 1
+    }
+    return out
   }
 
   func checkUpcomingTracksForUrls(lookahead: Int = 5) {

package/ios/download/DownloadDatabase.swift

@@ -28,6 +28,39 @@ final class DownloadDatabase {
   private let queue = DispatchQueue(
     label: "com.nitroplayer.downloadDatabase", attributes: .concurrent)
 
+  /// Memoized `fileExists` verdicts, keyed by track ID.
+  ///
+  /// Queue building calls `isTrackDownloaded` / `getDownloadedTrack` once per track,
+  /// and each call used to stat() the file — O(playlist) syscalls per rebuild, on the
+  /// thread that also drives playback. Downloads only change through this class (or
+  /// through the user deleting files behind our back, which `syncDownloads()` handles),
+  /// so the verdict is cached and invalidated on every mutation.
+  /// Guarded by its own lock rather than `queue` so it can be filled from inside
+  /// concurrent read blocks (`queue.sync`) without a barrier.
+  private var existenceCache: [String: Bool] = [:]
+  private let existenceCacheLock = NSLock()
+
+  private func cachedFileExists(trackId: String, path: @autoclosure () -> String) -> Bool {
+    existenceCacheLock.lock()
+    let cached = existenceCache[trackId]
+    existenceCacheLock.unlock()
+    if let cached { return cached }
+
+    let exists = FileManager.default.fileExists(atPath: path())
+    existenceCacheLock.lock()
+    existenceCache[trackId] = exists
+    existenceCacheLock.unlock()
+    return exists
+  }
+
+  /// Drops every memoized verdict. Called on any record mutation, and safe to call
+  /// externally when files may have changed outside the app.
+  func invalidateExistenceCache() {
+    existenceCacheLock.lock()
+    existenceCache.removeAll()
+    existenceCacheLock.unlock()
+  }
+
   // MARK: - Initialization
 
   private init() {
@@ -70,22 +103,14 @@ final class DownloadDatabase {
         NitroPlayerLogger.log("DownloadDatabase", "🔍 Track \(trackId) NOT found in database")
         return false
       }
-      // Verify file still exists
-      let absolutePath = resolveAbsolutePath(for: record)
-      let exists = FileManager.default.fileExists(atPath: absolutePath)
-      if exists {
-        NitroPlayerLogger.log("DownloadDatabase", "✅ Track \(trackId) IS downloaded at \(absolutePath)")
-      } else {
-        NitroPlayerLogger.log("DownloadDatabase", "❌ Track \(trackId) record exists but file NOT found at \(absolutePath)")
-      }
-      return exists
+      // Verify file still exists (memoized — this runs once per track per queue rebuild)
+      return cachedFileExists(trackId: trackId, path: resolveAbsolutePath(for: record))
     }
   }
 
   private func _isTrackDownloadedUnsafe(trackId: String) -> Bool {
     guard let record = downloadedTracks[trackId] else { return false }
-    let absolutePath = resolveAbsolutePath(for: record)
-    return FileManager.default.fileExists(atPath: absolutePath)
+    return cachedFileExists(trackId: trackId, path: resolveAbsolutePath(for: record))
   }
 
   func isPlaylistDownloaded(playlistId: String) -> Bool {
@@ -137,8 +162,8 @@ final class DownloadDatabase {
       let absolutePath = resolveAbsolutePath(for: record)
       NitroPlayerLogger.log("DownloadDatabase", "   Found record, checking file at: \(absolutePath)")
 
-      // Verify file still exists
-      guard FileManager.default.fileExists(atPath: absolutePath) else {
+      // Verify file still exists (memoized)
+      guard cachedFileExists(trackId: trackId, path: absolutePath) else {
         NitroPlayerLogger.log("DownloadDatabase", "   ❌ File does NOT exist, cleaning up record")
         // File was deleted externally, clean up record
         queue.async(flags: .barrier) {
@@ -357,6 +382,9 @@ final class DownloadDatabase {
   // MARK: - Persistence
 
   private func saveToDisk() {
+    // Every record mutation funnels through here, so this is the one place that has
+    // to drop memoized fileExists verdicts.
+    invalidateExistenceCache()
     do {
       let tracksData = try JSONEncoder().encode(downloadedTracks)
       // Convert Set to Array for encoding

package/ios/media/MediaSessionManager.swift

@@ -31,7 +31,11 @@ class MediaSessionManager {
   // Cached values received from playerQueue — main-thread-only reads (no sync needed)
   private var cachedTrack: TrackItem?
   private var cachedState: PlayerState?
-  private var cachedQueue: [TrackItem] = []
+  // Only the queue length and the current track's position are needed — never the
+  // items themselves. Copying the whole queue on every state change was O(playlist)
+  // per event; these two Ints are computed on playerQueue instead.
+  private var cachedQueueCount: Int = 0
+  private var cachedPositionInQueue: Int = -1
 
   init() {
     setupRemoteCommandCenter()
@@ -56,10 +60,13 @@ class MediaSessionManager {
   //
   // Receives pre-computed values captured on playerQueue — no player access here.
 
-  func updateFromPlayerQueue(track: TrackItem, state: PlayerState, queue: [TrackItem]) {
+  func updateFromPlayerQueue(
+    track: TrackItem, state: PlayerState, queueCount: Int, positionInQueue: Int
+  ) {
     cachedTrack = track
     cachedState = state
-    cachedQueue = queue
+    cachedQueueCount = queueCount
+    cachedPositionInQueue = positionInQueue
     refreshInternal()
   }
 
@@ -88,11 +95,11 @@ class MediaSessionManager {
       return
     }
 
-    let queue = cachedQueue
-    let positionInQueue = queue.firstIndex(where: { $0.id == track.id }) ?? -1
-
-    updateNowPlayingInfoInternal(track: track, state: state, queue: queue, positionInQueue: positionInQueue)
-    updateCommandCenterState(state: state, queue: queue, positionInQueue: positionInQueue)
+    updateNowPlayingInfoInternal(
+      track: track, state: state,
+      queueCount: cachedQueueCount, positionInQueue: cachedPositionInQueue)
+    updateCommandCenterState(
+      state: state, queueCount: cachedQueueCount, positionInQueue: cachedPositionInQueue)
   }
 
   // MARK: - Now Playing Info
@@ -100,7 +107,7 @@ class MediaSessionManager {
   private func updateNowPlayingInfoInternal(
     track: TrackItem,
     state: PlayerState,
-    queue: [TrackItem],
+    queueCount: Int,
     positionInQueue: Int
   ) {
     let playerDuration = state.totalDuration
@@ -125,7 +132,7 @@ class MediaSessionManager {
       MPMediaItemPropertyPlaybackDuration: effectiveDuration,
       MPNowPlayingInfoPropertyPlaybackRate: isPlaying ? 1.0 : 0.0,
       MPNowPlayingInfoPropertyDefaultPlaybackRate: 1.0,
-      MPNowPlayingInfoPropertyPlaybackQueueCount: max(1, queue.count),
+      MPNowPlayingInfoPropertyPlaybackQueueCount: max(1, queueCount),
       MPNowPlayingInfoPropertyPlaybackQueueIndex: max(0, positionInQueue),
     ]
 
@@ -238,12 +245,12 @@ class MediaSessionManager {
 
   private func updateCommandCenterState(
     state: PlayerState,
-    queue: [TrackItem],
+    queueCount: Int,
     positionInQueue: Int
   ) {
     let commandCenter = MPRemoteCommandCenter.shared()
     let hasCurrentTrack = positionInQueue >= 0
-    let isNotLast = positionInQueue < queue.count - 1
+    let isNotLast = positionInQueue < queueCount - 1
 
     let playerDuration = state.totalDuration
     let hasDuration = playerDuration > 0 && !playerDuration.isNaN && !playerDuration.isInfinite

package/ios/queue/HybridPlayerQueue.swift

@@ -77,14 +77,19 @@ final class HybridPlayerQueue: HybridPlayerQueueSpec {
 
   // MARK: - Playback control
 
+  /// Enqueued synchronously on the player queue so a `loadPlaylist()` followed by
+  /// `play()` from JS cannot be reordered — see HybridTrackPlayer.enqueue.
   func loadPlaylist(playlistId: String, index: Double?) throws -> Promise<Void> {
-    Promise.async {
-      let startIndex = index.map { Int($0) }
+    let startIndex = index.map { Int($0) }
+    let promise = Promise<Void>()
+    core.playerQueue.async {
       // Update PlaylistManager.currentPlaylistId so getCurrentPlaylistId() returns correctly
-      let loaded = self.playlistManager.loadPlaylist(playlistId: playlistId, index: startIndex)
-      guard loaded else { return }
-      await self.core.loadPlaylist(playlistId: playlistId, startIndex: startIndex)
+      if self.playlistManager.loadPlaylist(playlistId: playlistId, index: startIndex) {
+        self.core.loadPlaylistOnQueue(playlistId: playlistId, startIndex: startIndex)
+      }
+      promise.resolve(withResult: ())
     }
+    return promise
   }
 
   func getCurrentPlaylistId() throws -> Variant_NullType_String {

package/lib/hooks/callbackManager.d.ts

@@ -3,6 +3,7 @@ type PlaybackStateCallback = (state: TrackPlayerState, reason?: Reason) => void;
 type TrackChangeCallback = (track: TrackItem, reason?: Reason) => void;
 type PlaybackProgressCallback = (position: number, totalDuration: number, isManuallySeeked?: boolean) => void;
 type SeekCallback = (position: number, totalDuration: number) => void;
+type TemporaryQueueCallback = (playNextQueue: TrackItem[], upNextQueue: TrackItem[]) => void;
 /**
  * Internal subscription manager that allows multiple hooks to subscribe
  * to a single native callback. This solves the problem where registering
@@ -13,10 +14,14 @@ declare class CallbackSubscriptionManager {
     private trackChangeSubscribers;
     private playbackProgressSubscribers;
     private seekSubscribers;
+    private temporaryQueueSubscribers;
+    private playlistsChangedSubscribers;
+    private isPlaylistsChangedRegistered;
     private isPlaybackStateRegistered;
     private isTrackChangeRegistered;
     private isPlaybackProgressRegistered;
     private isSeekRegistered;
+    private isTemporaryQueueRegistered;
     /**
      * Subscribe to playback state changes
      * @returns Unsubscribe function
@@ -40,6 +45,18 @@ declare class CallbackSubscriptionManager {
      */
     subscribeToSeek(callback: SeekCallback): () => void;
     private ensurePlaybackProgressRegistered;
+    /**
+     * Subscribe to playNext / upNext changes
+     * @returns Unsubscribe function
+     */
+    subscribeToTemporaryQueueChange(callback: TemporaryQueueCallback): () => void;
+    /**
+     * Subscribe to playlist mutations (tracks added/removed/reordered).
+     * @returns Unsubscribe function
+     */
+    subscribeToPlaylistsChanged(callback: () => void): () => void;
+    private ensurePlaylistsChangedRegistered;
+    private ensureTemporaryQueueRegistered;
     private ensureSeekRegistered;
 }
 export declare const callbackManager: CallbackSubscriptionManager;