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

package/ios/core/TrackPlayerCast.swift

@@ -16,6 +16,12 @@
 import AVFoundation
 import Foundation
 
+/// Receiver state captured before the Cast session tears its caches down.
+struct CastTransferSnapshot {
+  let trackId: String?
+  let position: Double
+}
+
 extension TrackPlayerCore {
 
   // MARK: - Cast-safety helpers
@@ -62,44 +68,67 @@ extension TrackPlayerCore {
   }
 
   /// The Cast session ended — rebuild local playback at the last remote position.
-  func handleCastDisconnected() {
+  func handleCastDisconnected(_ snapshot: CastTransferSnapshot) {
     playerQueue.async { [weak self] in
       guard let self else { return }
       guard self.isCasting else { return }
-      let resumePosition = self.castManager?.lastKnownRemotePosition ?? 0
-      let remoteTrackId = self.castManager?.currentRemoteTrackId
+      let resumePosition = snapshot.position
+      let remoteTrackId = snapshot.trackId
       self.isCasting = false
 
-      let index = self.currentTrackIndex
-      guard index >= 0 && index < self.currentTracks.count else { return }
+      // A backend transfer is not a track change.
+      self.backendTransferTargetId = remoteTrackId
+      let hadAnchor = self.currentTrackIndex >= 0
+      let index = max(0, self.currentTrackIndex)
 
       // rebuildQueueFromPlaylistIndex wipes the temp lists — preserve them
       let savedPlayNext = self.playNextStack
       let savedUpNext = self.upNextQueue
+      let remoteTemp = remoteTrackId.flatMap { id in
+        savedPlayNext.first { $0.id == id } ?? savedUpNext.first { $0.id == id }
+      }
 
-      _ = self.rebuildQueueFromPlaylistIndex(index: index)
-
-      if !savedPlayNext.isEmpty || !savedUpNext.isEmpty {
-        self.playNextStack = savedPlayNext
-        self.upNextQueue = savedUpNext
+      if self.currentTracks.isEmpty {
+        // Playlist emptied while casting: bootstrap the local player from the remote temp.
+        guard let player = self.player, let temp = remoteTemp,
+          let item = self.createGaplessPlayerItem(for: temp, isPreload: false)
+        else {
+          self.backendTransferTargetId = nil
+          return
+        }
+        self.removeAllItemsCancellingLoads(player)
+        player.insert(item, after: nil)
+        self.currentTemporaryType = savedPlayNext.contains { $0.id == temp.id } ? .playNext : .upNext
+        self.currentTrackIndex = -1
         self.rebuildAVQueueFromCurrentPosition()
         self.notifyTemporaryQueueChange()
-      }
-
-      // If the receiver was playing the head temp track, make it current again
-      // (mirrors skipToNext: remove from its list before it becomes current)
-      if let target = remoteTrackId, target != self.player?.currentItem?.trackId {
-        if self.playNextStack.first?.id == target {
-          self.playNextStack.removeFirst()
-          self.player?.advanceToNextItem()
-          self.currentTemporaryType = .playNext
-          self.notifyTemporaryQueueChange()
-        } else if self.playNextStack.isEmpty, self.upNextQueue.first?.id == target {
-          self.upNextQueue.removeFirst()
-          self.player?.advanceToNextItem()
-          self.currentTemporaryType = .upNext
+      } else {
+        guard self.rebuildQueueFromPlaylistIndex(index: index, emitChange: false) else {
+          self.backendTransferTargetId = nil
+          return
+        }
+        if !savedPlayNext.isEmpty || !savedUpNext.isEmpty {
+          self.playNextStack = savedPlayNext
+          self.upNextQueue = savedUpNext
+          self.rebuildAVQueueFromCurrentPosition()
           self.notifyTemporaryQueueChange()
         }
+
+        // The temp stays in its list; the builder skips the current id and transitions drop it.
+        if let target = remoteTrackId, target != self.player?.currentItem?.trackId {
+          if self.playNextStack.first?.id == target {
+            self.player?.advanceToNextItem()
+            self.currentTemporaryType = .playNext
+          } else if self.playNextStack.isEmpty, self.upNextQueue.first?.id == target {
+            self.player?.advanceToNextItem()
+            self.currentTemporaryType = .upNext
+          }
+          // The advance consumed track 0; re-queue it after the temps.
+          if !hadAnchor, self.currentTemporaryType != .none {
+            self.currentTrackIndex = -1
+            self.rebuildAVQueueFromCurrentPosition()
+          }
+        }
       }
 
       // Only seek when the local current track is the one that was playing remotely
@@ -111,6 +140,7 @@ extension TrackPlayerCore {
       if self.intendedToPlay {
         self.player?.rate = Float(self.currentPlaybackSpeed)
       }
+      if self.player?.currentItem?.trackId == remoteTrackId { self.backendTransferTargetId = nil }
     }
   }
 
@@ -127,14 +157,36 @@ extension TrackPlayerCore {
     loadCastQueue(fromActualIndex: startIndex, autoplay: autoplay, position: position)
   }
 
-  /// Atomically (re)load the receiver queue from `index` in the actual queue (lazy targets stop the receiver and wait for updateTracks).
+  /// The whole castable queue, so a shuffle can reorder items before the current one. Nil when the current is lazy.
+  func castableQueue(_ actual: [TrackItem], currentIdx: Int) -> (tracks: [TrackItem], startIndex: Int)? {
+    guard currentIdx >= 0, currentIdx < actual.count else { return nil }
+    let after = castableUpcoming(Array(actual[currentIdx...]))
+    guard !after.isEmpty else { return nil }
+    let before = actual[..<currentIdx].filter { isTrackCastable($0) }
+    return (before + after, before.count)
+  }
+
+  /// A removed track finishing is no longer in the logical queue, so the receiver's own current anchors it.
+  func castDesiredQueue() -> (tracks: [TrackItem], currentId: String)? {
+    guard let currentId = activeCurrentTrackId else { return nil }
+    let actual = getActualQueueInternal()
+    if let idx = actual.firstIndex(where: { $0.id == currentId }) {
+      guard let built = castableQueue(actual, currentIdx: idx) else { return nil }
+      return (built.tracks, currentId)
+    }
+    guard let remoteCurrent = castManager?.currentRemoteTrackItem else { return nil }
+    castManager?.setQueueRepeatMode(.off)
+    let rest = currentTrackIndex + 1 < currentTracks.count
+      ? Array(currentTracks[(currentTrackIndex + 1)...]) : []
+    return ([remoteCurrent] + castableUpcoming(playNextStack + upNextQueue + rest), remoteCurrent.id)
+  }
+
+  /// Atomically (re)load the receiver queue positioned at `index` in the actual queue (lazy targets stop the receiver and wait for updateTracks).
   func loadCastQueue(fromActualIndex index: Int, autoplay: Bool, position: Double) {
     let queue = getActualQueueInternal()
     guard index >= 0, index < queue.count else { return }
-    let slice = Array(queue[index...])
-    let playable = castableUpcoming(slice)
 
-    guard !playable.isEmpty else {
+    guard let built = castableQueue(queue, currentIdx: index) else {
       // Lazy target — silence the receiver and wait for updateTracks to reload.
       castManager?.stop()
       checkUpcomingTracksForUrls(lookahead: lookaheadCount)
@@ -142,19 +194,21 @@ extension TrackPlayerCore {
     }
 
     // Resume mid-track only when the receiver starts on the requested track.
-    let effectivePosition = playable[0].id == slice[0].id ? position : 0
+    let startTrack = built.tracks[built.startIndex]
+    let effectivePosition = startTrack.id == queue[index].id ? position : 0
 
-    castManager?.setExpectedCurrentTrack(playable[0].id)
+    castManager?.setExpectedCurrentTrack(startTrack.id)
     castManager?.loadQueue(
-      tracks: playable,
+      tracks: built.tracks,
+      startIndex: built.startIndex,
       position: effectivePosition,
       autoplay: autoplay,
-      repeatMode: currentRepeatMode
+      repeatMode: isTransientPlayOut() ? .off : currentRepeatMode
     )
     checkUpcomingTracksForUrls(lookahead: lookaheadCount)
   }
 
-  /// Sync the receiver's upcoming items: append-only extensions don't interrupt playback; anything else reloads at the current position.
+  /// Current-preserving operations; the reconciler reloads only when receiver state is untrusted.
   func syncCastQueueAfterCurrent() {
     guard let cast = castManager else { return }
     guard cast.hasLoadedMedia else {
@@ -162,38 +216,8 @@ extension TrackPlayerCore {
       loadCastQueue(autoplay: intendedToPlay, position: 0)
       return
     }
-
-    let queue = getActualQueueInternal()
-    guard let current = getCurrentTrack(),
-      let currentIdx = queue.firstIndex(where: { $0.id == current.id })
-    else { return }
-
-    let desired = castableUpcoming(Array(queue[(currentIdx + 1)...]))
-    let desiredIds = desired.map { $0.id }
-
-    let loaded = cast.loadedTrackIds
-    let existingUpcoming: [String]
-    if let ei = loaded.firstIndex(of: current.id) {
-      existingUpcoming = Array(loaded[(ei + 1)...])
-    } else {
-      existingUpcoming = []
-    }
-
-    if desiredIds == existingUpcoming { return } // already in sync
-
-    if desiredIds.count > existingUpcoming.count,
-      Array(desiredIds.prefix(existingUpcoming.count)) == existingUpcoming {
-      // Strict tail extension — append without touching current playback.
-      let toAppend = Array(desired.suffix(desiredIds.count - existingUpcoming.count))
-      castManager?.appendToQueue(tracks: toAppend)
-    } else {
-      // Order changed / items removed — atomic reload preserving position.
-      loadCastQueue(
-        fromActualIndex: currentIdx,
-        autoplay: intendedToPlay,
-        position: cast.lastKnownRemotePosition
-      )
-    }
+    guard let desired = castDesiredQueue() else { return }
+    cast.reconcileQueue(desired: desired.tracks, currentTrackId: desired.currentId)
   }
 
   // MARK: - Cast-mode navigation (mirrors the local skip logic, minus AVQueuePlayer)
@@ -273,6 +297,11 @@ extension TrackPlayerCore {
     }
 
     if currentTemporaryType != .none {
+      // No playlist track to return to: restart the temp without touching its list.
+      if currentTracks.isEmpty {
+        castManager?.seek(to: 0)
+        return
+      }
       // Leaving a temp track removes it, then return to the current original.
       if let currentId = activeCurrentTrackId {
         if currentTemporaryType == .playNext,
@@ -284,6 +313,8 @@ extension TrackPlayerCore {
         }
       }
       currentTemporaryType = .none
+      // Cursor may be -1 (anchor removed): return to the resume slot.
+      currentTrackIndex = max(0, currentTrackIndex)
       notifyTemporaryQueueChange()
     } else if currentTrackIndex > 0 {
       currentTrackIndex -= 1

package/ios/core/TrackPlayerCore.swift

@@ -52,6 +52,8 @@ class TrackPlayerCore: NSObject {
   // 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
+  // Set by handleCastDisconnected: suppresses onChangeTrack until the local player reaches this id.
+  internal var backendTransferTargetId: String?
   internal var isManuallySeeked = false
   internal var currentRepeatMode: RepeatMode = .off
   internal var currentPlaybackSpeed: Double = 1.0
@@ -266,6 +268,7 @@ class TrackPlayerCore: NSObject {
       }
       self.currentItemObservers.removeAll()
       self.detachMetadataOutput()
+      self.backendTransferTargetId = nil
       if let p = self.player {
         p.removeObserver(self, forKeyPath: "status")
         p.removeObserver(self, forKeyPath: "rate")
@@ -288,6 +291,34 @@ class TrackPlayerCore: NSObject {
   }
 }
 
+enum AnchorOutcome { case none, kept, removed }
+
+extension TrackPlayerCore {
+  /// Re-resolves the anchor by id, or moves the cursor to the resume slot when it was removed.
+  @discardableResult
+  func assignCurrentTracks(_ next: [TrackItem]) -> AnchorOutcome {
+    let old = currentTracks
+    let anchor = old[safe: currentTrackIndex]
+    currentTracks = next
+    guard let anchor else { return .none }
+    if let newIndex = next.firstIndex(where: { $0.id == anchor.id }) {
+      currentTrackIndex = newIndex
+      return .kept
+    }
+    let alive = Set(next.map(\.id))
+    let followerId = old.dropFirst(currentTrackIndex + 1).first { alive.contains($0.id) }?.id
+    let resume = followerId.flatMap { id in next.firstIndex { $0.id == id } } ?? next.count
+    currentTrackIndex = resume - 1
+    return .removed
+  }
+
+  /// True while the playing item was removed from the playlist and is finishing.
+  func isTransientPlayOut() -> Bool {
+    guard currentTemporaryType == .none, let id = activeCurrentTrackId else { return false }
+    return !currentTracks.contains { $0.id == id }
+  }
+}
+
 // Safe array subscript
 extension Array {
   subscript(safe index: Int) -> Element? {

package/ios/core/TrackPlayerListener.swift

@@ -172,8 +172,12 @@ extension TrackPlayerCore {
     // Items without our trackId belong to another AVPlayer in the host app
     guard finishedItem.trackId != nil else { return }
 
+    // A track removed from the playlist is finishing: it must play once, never loop.
+    let finishedWasRemoved =
+      finishedItem.trackId.map { id in !currentTracks.contains { $0.id == id } } ?? false
+
     // 1. TRACK repeat — handle FIRST, before any temp-track removal
-    if currentRepeatMode == .track {
+    if currentRepeatMode == .track && !finishedWasRemoved {
       if player?.currentItem == nil || player?.currentItem === finishedItem {
         NitroPlayerLogger.log("TrackPlayerCore", "🔁 TRACK repeat — no queued copy, seeking to zero")
         player?.seek(to: .zero)
@@ -317,6 +321,12 @@ extension TrackPlayerCore {
           notifyTrackChange(firstTrack, .repeat)
         }
         notifyTemporaryQueueChange()
+      } else if let player = self.player, player.items().isEmpty, !hasUpcomingTrack() {
+        // AVQueuePlayer leaves `rate` at 1 with no item left, so state would keep reading as
+        // playing after the last track ends. Stop for real and tell JS.
+        player.rate = 0
+        intendedToPlay = false
+        emitStateChange(reason: .end)
       }
       return
     }
@@ -362,6 +372,12 @@ extension TrackPlayerCore {
     // Setup KVO observers for current item
     setupCurrentItemObservers(item: currentItem)
 
+    // A Cast disconnect rebuilds around the receiver's track; none of those transitions is a change.
+    let isBackendTransfer = backendTransferTargetId != nil
+    if let target = backendTransferTargetId, currentItem.trackId == target {
+      backendTransferTargetId = nil
+    }
+
     // Update track index and determine temporary type
     if let trackId = currentItem.trackId {
       NitroPlayerLogger.log("TrackPlayerCore", "🔍 Looking up trackId '\(trackId)' in currentTracks...")
@@ -375,7 +391,7 @@ extension TrackPlayerCore {
         if currentTemporaryType == .playNext { tempTrack = playNextStack.first(where: { $0.id == trackId }) }
         else if currentTemporaryType == .upNext { tempTrack = upNextQueue.first(where: { $0.id == trackId }) }
         if let track = tempTrack {
-          if isRecoveryReplace || isRepeatLoop {
+          if isRecoveryReplace || isRepeatLoop || isBackendTransfer {
             NitroPlayerLogger.log("TrackPlayerCore",
               "   ♻️ Same-track transition for '\(track.title)' — suppressing onChangeTrack")
           } else {
@@ -393,7 +409,7 @@ extension TrackPlayerCore {
 
         if let track = currentTracks[safe: index] {
           NitroPlayerLogger.log("TrackPlayerCore", "   🎵 Track: \(track.title) - \(track.artist)")
-          if oldIndex != index {
+          if oldIndex != index && !isBackendTransfer {
             NitroPlayerLogger.log("TrackPlayerCore", "   📢 Emitting onChangeTrack (index changed from \(oldIndex) to \(index))")
             let wrappedToStart =
               currentRepeatMode == .playlist && index == 0 && oldIndex == currentTracks.count - 1

package/ios/core/TrackPlayerPlayback.swift

@@ -75,7 +75,8 @@ extension TrackPlayerCore {
     let previousMode = currentRepeatMode
     currentRepeatMode = mode
     player?.actionAtItemEnd = .advance
-    if isCasting { castManager?.setQueueRepeatMode(mode) }
+    // A transient play-out (removed item finishing) must not loop, whatever the user picks.
+    if isCasting { castManager?.setQueueRepeatMode(isTransientPlayOut() ? .off : mode) }
     if !isCasting, previousMode != mode, player?.currentItem != nil {
       rebuildAVQueueFromCurrentPosition()
     }
@@ -258,13 +259,7 @@ extension TrackPlayerCore {
       return
     }
 
-    if currentRepeatMode == .track {
-      let items = queuePlayer.items()
-      if items.count > 1, let copyId = items[1].trackId, copyId == items[0].trackId {
-        queuePlayer.remove(items[1])
-      }
-      rebuildAVQueueFromCurrentPosition(skipRepeatCopy: true)
-    }
+    dropRepeatCopyBeforeManualSkip(queuePlayer)
 
     // Remove current temp track from its list before advancing
     if let trackId = queuePlayer.currentItem?.trackId {
@@ -308,6 +303,12 @@ extension TrackPlayerCore {
       // If more than threshold seconds in, restart current track
       queuePlayer.seek(to: .zero)
     } else if self.currentTemporaryType != .none {
+      // No playlist track to return to (all removed): restart the temp without touching its list.
+      if currentTracks.isEmpty {
+        queuePlayer.seek(to: .zero)
+        checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+        return
+      }
       // Playing temporary track — remove from its list, then go back to original track
       if let trackId = queuePlayer.currentItem?.trackId {
         if currentTemporaryType == .playNext, let idx = playNextStack.firstIndex(where: { $0.id == trackId }) {
@@ -318,8 +319,8 @@ extension TrackPlayerCore {
           notifyTemporaryQueueChange()
         }
       }
-      // Go back to current original track position (skip back from temp)
-      _ = rebuildQueueFromPlaylistIndex(index: self.currentTrackIndex)
+      // Go back to current original track position (skip back from temp); cursor may be -1 (anchor removed) → resume slot 0
+      _ = rebuildQueueFromPlaylistIndex(index: max(0, self.currentTrackIndex))
     } else if self.currentTrackIndex > 0 {
       // Go to previous track in original playlist
       _ = rebuildQueueFromPlaylistIndex(index: self.currentTrackIndex - 1)
@@ -398,6 +399,7 @@ extension TrackPlayerCore {
       return
     }
 
+    playlistManager.setCurrentPlaylistId(playlistId)
     if self.currentPlaylistId != playlistId {
       NitroPlayerLogger.log("TrackPlayerCore", "🔄 Loading new playlist: \(playlistId)")
       if let playlist = self.playlistManager.getPlaylist(playlistId: playlistId) {

package/ios/core/TrackPlayerQueue.swift

@@ -218,7 +218,11 @@ extension TrackPlayerCore {
         // (rebuildAVQueueFromCurrentPosition will skip it by ID)
         playNextStack.removeSubrange(0..<targetIdx)
       }
-      rebuildAVQueueFromCurrentPosition()
+      if let player = player, currentRepeatMode == .track {
+        dropRepeatCopyBeforeManualSkip(player)
+      } else {
+        rebuildAVQueueFromCurrentPosition()
+      }
       player?.advanceToNextItem()
       return true
     }
@@ -231,7 +235,11 @@ extension TrackPlayerCore {
       if let targetIdx = upNextQueue.firstIndex(where: { $0.id == targetTrack.id }), targetIdx > 0 {
         upNextQueue.removeSubrange(0..<targetIdx)
       }
-      rebuildAVQueueFromCurrentPosition()
+      if let player = player, currentRepeatMode == .track {
+        dropRepeatCopyBeforeManualSkip(player)
+      } else {
+        rebuildAVQueueFromCurrentPosition()
+      }
       player?.advanceToNextItem()
       return true
     }

package/ios/core/TrackPlayerQueueBuild.swift

@@ -39,6 +39,17 @@ extension TrackPlayerCore {
     player.removeAllItems()
   }
 
+  /// Under repeat `track` the queue holds a copy of the current item; a manual skip must
+  /// step past it to the real next track, not replay the same one.
+  func dropRepeatCopyBeforeManualSkip(_ player: AVQueuePlayer) {
+    guard currentRepeatMode == .track else { return }
+    let items = player.items()
+    if items.count > 1, let copyId = items[1].trackId, copyId == items[0].trackId {
+      player.remove(items[1])
+    }
+    rebuildAVQueueFromCurrentPosition(skipRepeatCopy: true)
+  }
+
   func updatePlayerQueue(tracks: [TrackItem]) {
     // While casting, mirror the new queue to the Cast device instead of building
     // the local AVQueuePlayer (which would start local audio).
@@ -71,6 +82,7 @@ extension TrackPlayerCore {
     // Store tracks for index tracking
     currentTracks = tracks
     currentTrackIndex = 0
+    backendTransferTargetId = nil
     NitroPlayerLogger.log("TrackPlayerCore", "🔢 Reset currentTrackIndex to 0 (will be updated by KVO observer)")
 
     // Remove old boundary observer if exists
@@ -167,7 +179,9 @@ extension TrackPlayerCore {
   /// Clears temporary tracks, rebuilds AVQueuePlayer from `index` in the original playlist,
   /// and resumes playback only if the player was already playing (preserves paused state).
   @discardableResult
-  func rebuildQueueFromPlaylistIndex(index: Int) -> Bool {
+  func rebuildQueueFromPlaylistIndex(index: Int, emitChange: Bool = true) -> Bool {
+    // A real jump supersedes any in-progress backend transfer.
+    if emitChange { backendTransferTargetId = nil }
     guard index >= 0 && index < self.currentTracks.count else {
       NitroPlayerLogger.log("TrackPlayerCore", "❌ rebuildQueueFromPlaylistIndex - invalid index \(index), currentTracks.count = \(self.currentTracks.count)")
       return false
@@ -216,7 +230,7 @@ extension TrackPlayerCore {
       }
       if let p = player { removeAllItemsCancellingLoads(p) }
       self.currentTracks = fullPlaylist
-      if let track = self.currentTracks[safe: index] {
+      if emitChange, let track = self.currentTracks[safe: index] {
         notifyTrackChange(track, .skip)
       }
       return true
@@ -256,7 +270,7 @@ extension TrackPlayerCore {
     self.currentTracks = fullPlaylist
 
     NitroPlayerLogger.log("TrackPlayerCore", "   ✅ Gapless queue recreated. Now at index: \(self.currentTrackIndex)")
-    if let track = self.getCurrentTrack() {
+    if emitChange, let track = self.getCurrentTrack() {
       NitroPlayerLogger.log("TrackPlayerCore", "   🎵 Playing: \(track.title)")
       notifyTrackChange(track, .skip)
     }
@@ -296,14 +310,12 @@ extension TrackPlayerCore {
     // delegate to rebuildQueueFromPlaylistIndex so the player immediately
     // starts what is now at currentTrackIndex in the updated list.
     if !currentTracks.contains(where: { $0.id == playingTrackId }) &&
-      currentTemporaryType == .none {
-      let targetIndex = currentTrackIndex < currentTracks.count
-        ? currentTrackIndex : currentTracks.count - 1
-      if targetIndex >= 0 {
-        _ = rebuildQueueFromPlaylistIndex(index: targetIndex)
-      }
+      currentTemporaryType == .none && !currentTracks.isEmpty {
+      // currentTrackIndex + 1 is the resume slot set by assignCurrentTracks.
+      _ = rebuildQueueFromPlaylistIndex(index: min(currentTrackIndex + 1, currentTracks.count - 1))
       return
     }
+    // Removed item still playing: fall through so the diff keeps only the temps.
 
     // Sync currentTrackIndex to the track's actual position after a playlist mutation
     // (e.g. reorder). Without this, the remaining-tracks slice uses the stale index,

package/ios/core/TrackPlayerTempQueue.swift

@@ -74,25 +74,37 @@ extension TrackPlayerCore {
 
       // 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
-        }
-
-        // Update tracks list without interrupting playback
-        self.currentTracks = playlist.tracks
-        self.rebuildAVQueueFromCurrentPosition()
-        self.checkUpcomingTracksForUrls(lookahead: self.lookaheadCount)
+        guard let self, generation == self.playlistUpdateGeneration else { return }
+        self.syncCurrentPlaylistOnQueue(playlistId: playlistId)
       }
     }
   }
 
+  /// Applies the stored playlist to the live queue without re-preparing the playing item.
+  func syncCurrentPlaylistOnQueue(playlistId: String) {
+    playlistUpdateGeneration &+= 1
+    guard currentPlaylistId == playlistId,
+      let playlist = playlistManager.getPlaylist(playlistId: playlistId) else { return }
+
+    // If nothing is playing yet, do a full load
+    guard isCasting || player?.currentItem != nil else {
+      updatePlayerQueue(tracks: playlist.tracks)
+      checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+      return
+    }
+
+    let outcome = assignCurrentTracks(playlist.tracks)
+    if isCasting, outcome == .removed, currentTemporaryType == .none, !currentTracks.isEmpty {
+      // The receiver's current item was removed: jump to the resume slot.
+      _ = rebuildQueueFromPlaylistIndex(index: min(currentTrackIndex + 1, currentTracks.count - 1))
+    } else {
+      // No preload here: the rebuild queues the new items and currentItemDidChange preloads on the
+      // next transition. Kicking off asset loads now competes with the item that is still playing.
+      rebuildAVQueueFromCurrentPosition()
+    }
+    checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+  }
+
   func playNextOnQueue(trackId: String) throws {
     guard let track = findTrackById(trackId) else {
       throw NSError(domain: "NitroPlayer", code: 404, userInfo: [NSLocalizedDescriptionKey: "Track \(trackId) not found"])

package/ios/core/TrackPlayerUrlLoader.swift

@@ -49,9 +49,12 @@ extension TrackPlayerCore {
         NitroPlayerLogger.log("TrackPlayerCore",
           "🔄 Updating current track (\(currentItemFailed ? "failed item" : "no URL")): \(track.id)")
         return !track.url.isEmpty
+      case track.id == currentTrackId && track.url == currentTrack?.url && !track.url.isEmpty:
+        // Same URL is a metadata-only edit (a title or artwork refresh); the item is untouched.
+        return true
       case track.id == currentTrackId:
         NitroPlayerLogger.log("TrackPlayerCore",
-          "⚠️ Skipping update for currently playing track: \(track.id) (preserves gapless)")
+          "⚠️ Skipping URL change for currently playing track: \(track.id) (preserves gapless)")
         return false
       case track.url.isEmpty:
         NitroPlayerLogger.log("TrackPlayerCore", "⚠️ Skipping track with empty URL: \(track.id)")
@@ -98,7 +101,7 @@ extension TrackPlayerCore {
 
       // Sync currentTracks from the freshly-updated PlaylistManager
       if let updatedPlaylist = self.playlistManager.getPlaylist(playlistId: currentId) {
-        self.currentTracks = updatedPlaylist.tracks
+        self.assignCurrentTracks(updatedPlaylist.tracks)
         NitroPlayerLogger.log("TrackPlayerCore",
           "📥 Synced currentTracks from PlaylistManager (\(self.currentTracks.count) tracks)")
       }
@@ -159,6 +162,7 @@ extension TrackPlayerCore {
 
     NitroPlayerLogger.log("TrackPlayerCore",
       "✅ Track updates complete - \(affectedPlaylists.count) playlists affected")
+    refreshMediaSession()
   }
 
   func getTracksNeedingUrlsInternal() -> [TrackItem] {