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

package/ios/core/TrackPlayerListener.swift

@@ -292,7 +292,8 @@ extension TrackPlayerCore {
         upNextQueue.removeAll()
         currentTemporaryType = .none
 
-        let allItems = currentTracks.compactMap { createGaplessPlayerItem(for: $0, isPreload: false) }
+        let windowed = currentTracks.prefix(1 + Constants.queueWindowSize)
+        let allItems = windowed.compactMap { createGaplessPlayerItem(for: $0, isPreload: false) }
         var lastItem: AVPlayerItem? = nil
         for item in allItems {
           player.insert(item, after: lastItem)
@@ -399,6 +400,15 @@ extension TrackPlayerCore {
       setupBoundaryTimeObserver()
     }
 
+    // Top up the windowed AVQueuePlayer — the item we just consumed freed a slot.
+    // Only when it is actually short: rebuildAVQueueFromCurrentPosition can fall into
+    // rebuildQueueFromPlaylistIndex (current track no longer in the playlist), which
+    // replaces the current item and re-enters this callback. The length check makes any
+    // such re-entry a no-op and terminate.
+    if player.items().count - 1 < Constants.queueWindowSize {
+      rebuildAVQueueFromCurrentPosition()
+    }
+
     // Preload upcoming tracks for gapless playback
     preloadUpcomingTracks(from: currentTrackIndex + 1)
     cleanupPreloadedAssets(keepingFrom: currentTrackIndex)
@@ -421,11 +431,12 @@ extension TrackPlayerCore {
           self?.player?.automaticallyWaitsToMinimizeStalling = false
           // Update now playing info now that duration is available (capture on playerQueue first)
           let state = self?.getStateInternal()
-          let queue = self?.getActualQueueInternal() ?? []
+          let metrics = self?.actualQueueMetrics() ?? (count: 0, position: -1)
           let track = self?.getCurrentTrack()
           DispatchQueue.main.async {
             if let track = track, let state = state {
-              self?.mediaSessionManager?.updateFromPlayerQueue(track: track, state: state, queue: queue)
+              self?.mediaSessionManager?.updateFromPlayerQueue(
+                track: track, state: state, queueCount: metrics.count, positionInQueue: metrics.position)
             }
           }
         } else if item.status == .failed {
@@ -438,9 +449,13 @@ extension TrackPlayerCore {
     currentItemObservers.append(statusObserver)
 
     let bufferEmptyObserver = item.observe(\.isPlaybackBufferEmpty, options: [.new]) { [weak self] item, _ in
-      if item.isPlaybackBufferEmpty {
+      guard item.isPlaybackBufferEmpty else { return }
+      // KVO fires on an arbitrary thread — emitStateChange reads playerQueue-owned
+      // state (currentTracks, temp queues, isRecoveringFromStall), so hop first.
+      self?.playerQueue.async {
+        guard let self, self.player?.currentItem === item else { return }
         NitroPlayerLogger.log("TrackPlayerCore", "⏸️ Buffer empty (buffering)")
-        self?.emitStateChange()
+        self.emitStateChange()
       }
     }
     currentItemObservers.append(bufferEmptyObserver)

package/ios/core/TrackPlayerNotify.swift

@@ -13,22 +13,24 @@ extension TrackPlayerCore {
   // Called on playerQueue — invoke listeners directly (Nitro handles JS thread hop)
   func notifyTrackChange(_ track: TrackItem, _ reason: Reason?) {
     onChangeTrackListeners.forEach { $0(track, reason) }
-    // Capture state + queue now (on playerQueue), pass pre-computed values to main
+    // Capture state + queue metrics now (on playerQueue), pass pre-computed values to main.
+    // Metrics, not the queue itself — the media session only needs count and position.
     let state = getStateInternal()
-    let queue = getActualQueueInternal()
+    let metrics = actualQueueMetrics()
     DispatchQueue.main.async { [weak self] in
-      self?.mediaSessionManager?.updateFromPlayerQueue(track: track, state: state, queue: queue)
+      self?.mediaSessionManager?.updateFromPlayerQueue(
+        track: track, state: state, queueCount: metrics.count, positionInQueue: metrics.position)
     }
   }
 
   func notifyPlaybackStateChange(_ state: TrackPlayerState, _ reason: Reason?) {
     onPlaybackStateChangeListeners.forEach { $0(state, reason) }
+    guard let track = getCurrentTrack() else { return }
     let playerState = getStateInternal()
-    let queue = getActualQueueInternal()
-    let track = getCurrentTrack()
+    let metrics = actualQueueMetrics()
     DispatchQueue.main.async { [weak self] in
-      guard let track = track else { return }
-      self?.mediaSessionManager?.updateFromPlayerQueue(track: track, state: playerState, queue: queue)
+      self?.mediaSessionManager?.updateFromPlayerQueue(
+        track: track, state: playerState, queueCount: metrics.count, positionInQueue: metrics.position)
     }
   }
 

package/ios/core/TrackPlayerPlayback.swift

@@ -11,78 +11,98 @@ import MediaPlayer
 
 extension TrackPlayerCore {
 
-  func play() async {
+  // MARK: - Public commands
+  //
+  // Each command has a `…OnQueue` form that MUST run on `playerQueue` and an `async`
+  // shim for callers that are not already there (media-session remote commands).
+  // HybridTrackPlayer dispatches the `…OnQueue` form directly from the JS thread so
+  // the serial queue's FIFO order equals the JS call order — see HybridTrackPlayer.
+  //
+  // Reading `isCasting` inside the queue block (not before it) keeps every cast-vs-local
+  // decision on the thread that owns that flag.
+
+  func playOnQueue() {
     if isCasting {
       intendedToPlay = true
       castManager?.play()
       return
     }
-    await withPlayerQueueNoThrow { self.playInternal() }
+    playInternal()
   }
+  func play() async { await withPlayerQueueNoThrow { self.playOnQueue() } }
 
-  func pause() async {
+  func pauseOnQueue() {
     if isCasting {
       intendedToPlay = false
       castManager?.pause()
       return
     }
-    await withPlayerQueueNoThrow { self.pauseInternal() }
+    pauseInternal()
   }
+  func pause() async { await withPlayerQueueNoThrow { self.pauseOnQueue() } }
 
-  func seek(position: Double) async {
+  func seekOnQueue(position: Double) {
     if isCasting {
       castManager?.seek(to: position)
       return
     }
-    await withPlayerQueueNoThrow { self.seekInternal(position: position) }
+    seekInternal(position: position)
+  }
+  func seek(position: Double) async {
+    await withPlayerQueueNoThrow { self.seekOnQueue(position: position) }
   }
 
-  func skipToNext() async {
+  func skipToNextOnQueue() {
     if isCasting {
       castManager?.skipToNext()
       return
     }
-    await withPlayerQueueNoThrow { self.skipToNextInternal() }
+    skipToNextInternal()
   }
+  func skipToNext() async { await withPlayerQueueNoThrow { self.skipToNextOnQueue() } }
 
-  func skipToPrevious() async {
+  func skipToPreviousOnQueue() {
     if isCasting {
       // The receiver queue starts at the current track, so queuePreviousItem has nothing behind it — use core state instead.
-      await withPlayerQueueNoThrow { self.skipToPreviousCastInternal() }
+      skipToPreviousCastInternal()
       return
     }
-    await withPlayerQueueNoThrow { self.skipToPreviousInternal() }
+    skipToPreviousInternal()
   }
+  func skipToPrevious() async { await withPlayerQueueNoThrow { self.skipToPreviousOnQueue() } }
 
+  func setRepeatModeOnQueue(mode: RepeatMode) {
+    currentRepeatMode = mode
+    player?.actionAtItemEnd = (mode == .track) ? .none : .advance
+    if isCasting { castManager?.setQueueRepeatMode(mode) }
+    NitroPlayerLogger.log("TrackPlayerCore", "🔁 setRepeatMode: \(mode)")
+  }
   func setRepeatMode(mode: RepeatMode) async {
-    await withPlayerQueueNoThrow {
-      self.currentRepeatMode = mode
-      self.player?.actionAtItemEnd = (mode == .track) ? .none : .advance
-      if self.isCasting { self.castManager?.setQueueRepeatMode(mode) }
-      NitroPlayerLogger.log("TrackPlayerCore", "🔁 setRepeatMode: \(mode)")
-    }
+    await withPlayerQueueNoThrow { self.setRepeatModeOnQueue(mode: mode) }
   }
 
-  func setVolume(volume: Double) async {
+  func setVolumeOnQueue(volume: Double) {
+    let clamped = max(0.0, min(100.0, volume))
     if isCasting {
-      let clamped = max(0.0, min(100.0, volume))
       castManager?.setVolume(Float(clamped / 100.0))
       return
     }
-    await withPlayerQueueNoThrow {
-      let clamped = max(0.0, min(100.0, volume))
-      let normalized = Float(clamped / 100.0)
-      self.player?.volume = normalized
-      NitroPlayerLogger.log("TrackPlayerCore", "🔊 Volume set to \(Int(clamped))% (normalized: \(normalized))")
-    }
+    let normalized = Float(clamped / 100.0)
+    player?.volume = normalized
+    NitroPlayerLogger.log(
+      "TrackPlayerCore", "🔊 Volume set to \(Int(clamped))% (normalized: \(normalized))")
+  }
+  func setVolume(volume: Double) async {
+    await withPlayerQueueNoThrow { self.setVolumeOnQueue(volume: volume) }
   }
 
-  func configure(androidAutoEnabled: Bool?, carPlayEnabled: Bool?, showInNotification: Bool?, lookaheadCount: Int?) async {
-    await withPlayerQueueNoThrow {
-      if let la = lookaheadCount {
-        self.lookaheadCount = la
-        NitroPlayerLogger.log("TrackPlayerCore", "🔄 Lookahead count set to: \(la)")
-      }
+  func configureOnQueue(
+    androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
+    showInNotification: Bool?, lookaheadCount: Int?
+  ) {
+    if let la = lookaheadCount {
+      self.lookaheadCount = la
+      NitroPlayerLogger.log("TrackPlayerCore", "🔄 Lookahead count set to: \(la)")
     }
     DispatchQueue.main.async { [weak self] in
       self?.mediaSessionManager?.configure(
@@ -92,21 +112,31 @@ extension TrackPlayerCore {
       )
     }
   }
+  func configure(
+    androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
+    showInNotification: Bool?, lookaheadCount: Int?
+  ) async {
+    await withPlayerQueueNoThrow {
+      self.configureOnQueue(
+        androidAutoEnabled: androidAutoEnabled, carPlayEnabled: carPlayEnabled,
+        showInNotification: showInNotification, lookaheadCount: lookaheadCount)
+    }
+  }
 
-  func setPlaybackSpeed(_ speed: Double) async {
+  func setPlaybackSpeedOnQueue(_ speed: Double) {
+    currentPlaybackSpeed = speed
     if isCasting {
-      currentPlaybackSpeed = speed
       castManager?.setPlaybackRate(Float(speed))
       return
     }
-    await withPlayerQueueNoThrow {
-      self.currentPlaybackSpeed = speed
-      // Only update rate if currently playing; pause keeps rate at 0 until play() is called
-      if let player = self.player, player.rate != 0 {
-        player.rate = Float(speed)
-      }
+    // Only update rate if currently playing; pause keeps rate at 0 until play() is called
+    if let player = self.player, player.rate != 0 {
+      player.rate = Float(speed)
     }
   }
+  func setPlaybackSpeed(_ speed: Double) async {
+    await withPlayerQueueNoThrow { self.setPlaybackSpeedOnQueue(speed) }
+  }
 
   func getPlaybackSpeed() async -> Double {
     await withPlayerQueueNoThrow { self.currentPlaybackSpeed }
@@ -202,6 +232,12 @@ extension TrackPlayerCore {
       }
     }
 
+    // The AVQueuePlayer is windowed, so items().count is not the logical queue length.
+    // Top up first so there is always something to advance to while tracks remain.
+    if hasUpcomingTrack() {
+      if queuePlayer.items().count <= 1 { rebuildAVQueueFromCurrentPosition() }
+    }
+
     if queuePlayer.items().count > 1 {
       queuePlayer.advanceToNextItem()
     } else {

package/ios/core/TrackPlayerQueue.swift

@@ -18,11 +18,13 @@ extension TrackPlayerCore {
     await withPlayerQueueNoThrow { self.getActualQueueInternal() }
   }
 
+  @discardableResult
+  func skipToIndexOnQueue(index: Int) -> Bool {
+    isCasting ? skipToIndexCastInternal(index: index) : skipToIndexInternal(index: index)
+  }
+
   func skipToIndex(index: Int) async -> Bool {
-    if isCasting {
-      return await withPlayerQueueNoThrow { self.skipToIndexCastInternal(index: index) }
-    }
-    return await withPlayerQueueNoThrow { self.skipToIndexInternal(index: index) }
+    await withPlayerQueueNoThrow { self.skipToIndexOnQueue(index: index) }
   }
 
   func playFromIndex(index: Int) async {
@@ -144,6 +146,28 @@ extension TrackPlayerCore {
     return queue
   }
 
+  /// Length of the logical queue and the current track's position in it, derived
+  /// arithmetically. `getActualQueueInternal()` copies every TrackItem to answer the
+  /// same two questions — too expensive to run on every playback-state change.
+  func actualQueueMetrics() -> (count: Int, position: Int) {
+    let before: Int
+    if currentTemporaryType != .none {
+      before = min(currentTrackIndex + 1, currentTracks.count)
+    } else {
+      before = max(0, currentTrackIndex)
+    }
+    let hasCurrent = getCurrentTrack() != nil
+    let playNextCount =
+      currentTemporaryType == .playNext ? max(0, playNextStack.count - 1) : playNextStack.count
+    let upNextCount =
+      currentTemporaryType == .upNext ? max(0, upNextQueue.count - 1) : upNextQueue.count
+    let after =
+      currentTrackIndex + 1 < currentTracks.count ? currentTracks.count - (currentTrackIndex + 1) : 0
+
+    let count = before + (hasCurrent ? 1 : 0) + playNextCount + upNextCount + after
+    return (count, hasCurrent ? before : -1)
+  }
+
   func getCurrentTrack() -> TrackItem? {
     if currentTemporaryType != .none, let trackId = activeCurrentTrackId {
       if currentTemporaryType == .playNext { return playNextStack.first(where: { $0.id == trackId }) }

package/ios/core/TrackPlayerQueueBuild.swift

@@ -11,6 +11,34 @@ import Foundation
 
 extension TrackPlayerCore {
 
+  /// Cancels an item's outstanding asset loading before it is released.
+  ///
+  /// `AVURLAsset.dealloc` blocks the deallocating thread inside `URLAssetFinalize`
+  /// until any in-flight `loadValuesAsynchronously` / resource-loader work finishes —
+  /// and AVPlayer tears removed items down on the MAIN thread. Dropping items without
+  /// cancelling first therefore stalls the main run loop (and with it RCTTiming, so
+  /// JS timers stop firing) for as long as the pending loads take.
+  /// `cancelLoading()` itself waits for in-flight work to unwind, so it is only worth
+  /// paying on a full teardown (playlist switch / jump), never on the incremental
+  /// window rebuild that runs on every playNext / addToUpNext.
+  ///
+  /// A cancelled asset must never be handed back out: `createGaplessPlayerItem` reuses
+  /// `preloadedAssets`, and reusing a cancelled one yields an item that fails and then
+  /// burns the failed-item retry budget. Evict it instead.
+  func cancelLoading(of item: AVPlayerItem) {
+    guard let asset = item.asset as? AVURLAsset else { return }
+    if let trackId = item.trackId, preloadedAssets[trackId] === asset {
+      preloadedAssets.removeValue(forKey: trackId)
+    }
+    asset.cancelLoading()
+  }
+
+  /// Removes every item from the player, cancelling their asset loads first.
+  func removeAllItemsCancellingLoads(_ player: AVQueuePlayer) {
+    for item in player.items() { cancelLoading(of: item) }
+    player.removeAllItems()
+  }
+
   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).
@@ -55,6 +83,7 @@ extension TrackPlayerCore {
     player?.automaticallyWaitsToMinimizeStalling = true
 
     // Clear old preloaded assets when loading new queue
+    for asset in preloadedAssets.values { asset.cancelLoading() }
     preloadedAssets.removeAll()
 
     guard let existingPlayer = self.player else {
@@ -63,7 +92,7 @@ extension TrackPlayerCore {
     }
 
     NitroPlayerLogger.log("TrackPlayerCore", "🔄 Removing \(existingPlayer.items().count) old items from player")
-    existingPlayer.removeAllItems()
+    removeAllItemsCancellingLoads(existingPlayer)
 
     // Lazy-load mode if the first track needs a URL. Tracks further in the queue with
     // empty URLs are dropped safely by compactMap below and resolved via onTracksNeedUpdate.
@@ -75,7 +104,9 @@ extension TrackPlayerCore {
       return
     }
 
-    let items = tracks.enumerated().compactMap { (index, track) -> AVPlayerItem? in
+    // Only materialize a window of items — the rest are added as playback advances.
+    let windowed = tracks.prefix(1 + Constants.queueWindowSize)
+    let items = windowed.enumerated().compactMap { (index, track) -> AVPlayerItem? in
       let isPreload = index < Constants.gaplessPreloadCount
       return createGaplessPlayerItem(for: track, isPreload: isPreload)
     }
@@ -182,7 +213,7 @@ extension TrackPlayerCore {
         player?.removeTimeObserver(boundaryObserver)
         self.boundaryTimeObserver = nil
       }
-      player?.removeAllItems()
+      if let p = player { removeAllItemsCancellingLoads(p) }
       self.currentTracks = fullPlaylist
       if let track = self.currentTracks[safe: index] {
         notifyTrackChange(track, .skip)
@@ -190,7 +221,8 @@ extension TrackPlayerCore {
       return true
     }
 
-    let tracksToPlay = Array(fullPlaylist[index...])
+    let windowEnd = min(index + 1 + Constants.queueWindowSize, fullPlaylist.count)
+    let tracksToPlay = Array(fullPlaylist[index..<windowEnd])
     NitroPlayerLogger.log("TrackPlayerCore", "   🔄 Creating gapless queue with \(tracksToPlay.count) tracks starting from index \(index)")
 
     let items = tracksToPlay.enumerated().compactMap { (offset, track) -> AVPlayerItem? in
@@ -212,7 +244,7 @@ extension TrackPlayerCore {
     // Re-enable stall waiting for the new first track
     player.automaticallyWaitsToMinimizeStalling = true
 
-    player.removeAllItems()
+    removeAllItemsCancellingLoads(player)
     var lastItem: AVPlayerItem? = nil
     for item in items {
       player.insert(item, after: lastItem)
@@ -308,6 +340,11 @@ extension TrackPlayerCore {
       newQueueTracks.append(contentsOf: currentTracks[(currentTrackIndex + 1)...])
     }
 
+    // Window the materialized queue — currentItemDidChange tops it up on every transition.
+    if newQueueTracks.count > Constants.queueWindowSize {
+      newQueueTracks.removeSubrange(Constants.queueWindowSize...)
+    }
+
     // Collect existing upcoming AVPlayerItems
     let upcomingItems: [AVPlayerItem]
     if let ci = currentItem, let ciIndex = playingItems.firstIndex(of: ci) {
@@ -370,19 +407,47 @@ extension TrackPlayerCore {
       return
     }
 
-    // Full rebuild path (no changedTrackIds — skip, reorder, etc.)
-    for item in playingItems where item != currentItem {
+    // Incremental path (no changedTrackIds — skip, reorder, window top-up).
+    // Keep the longest matching prefix of already-buffered items and only rebuild
+    // from the first divergence. A pure append (the common window top-up) therefore
+    // touches nothing that is already buffered, preserving gapless transitions.
+    var commonPrefix = 0
+    while commonPrefix < upcomingItems.count,
+      commonPrefix < newQueueTracks.count,
+      upcomingItems[commonPrefix].trackId == newQueueTracks[commonPrefix].id
+    {
+      commonPrefix += 1
+    }
+
+    for item in upcomingItems[commonPrefix...] {
       player.remove(item)
     }
 
-    var lastItem = currentItem
-    for (offset, track) in newQueueTracks.enumerated() {
+    var lastItem: AVPlayerItem? = commonPrefix > 0 ? upcomingItems[commonPrefix - 1] : currentItem
+    for offset in commonPrefix..<newQueueTracks.count {
       let isPreload = offset < Constants.gaplessPreloadCount
-      if let item = createGaplessPlayerItem(for: track, isPreload: isPreload) {
+      if let item = createGaplessPlayerItem(for: newQueueTracks[offset], isPreload: isPreload) {
         player.insert(item, after: lastItem)
         lastItem = item
       }
     }
+
+    let created = newQueueTracks.count - commonPrefix
+    NitroPlayerLogger.log(
+      "TrackPlayerCore",
+      "🔄 Incremental rebuild: kept \(commonPrefix) buffered items, created \(created)")
+  }
+
+  /// True when the logical queue has a track after the current one, regardless of
+  /// how much of it is currently materialized into the AVQueuePlayer.
+  func hasUpcomingTrack() -> Bool {
+    let pendingPlayNext =
+      currentTemporaryType == .playNext ? max(0, playNextStack.count - 1) : playNextStack.count
+    if pendingPlayNext > 0 { return true }
+    let pendingUpNext =
+      currentTemporaryType == .upNext ? max(0, upNextQueue.count - 1) : upNextQueue.count
+    if pendingUpNext > 0 { return true }
+    return currentTrackIndex + 1 < currentTracks.count
   }
 
   /// Extracts custom HTTP headers (e.g. `Authorization`) from `extraPayload.headers`.
@@ -479,46 +544,40 @@ extension TrackPlayerCore {
     item.canUseNetworkResourcesForLiveStreamingWhilePaused = true
     item.trackId = track.id
 
-    if isPreload {
-      asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) {
-        var allKeysLoaded = true
-        for key in Constants.preloadAssetKeys {
-          var error: NSError?
-          let status = asset.statusOfValue(forKey: key, error: &error)
-          if status == .failed {
-            NitroPlayerLogger.log("TrackPlayerCore", "⚠️ Failed to load key '\(key)' for \(track.title): \(error?.localizedDescription ?? "unknown")")
-            allKeysLoaded = false
-          }
-        }
-        if allKeysLoaded {
-          NitroPlayerLogger.log("TrackPlayerCore", "✅ All asset keys preloaded for \(track.title)")
-        }
-        // "tracks" key is now loaded — EQ tap attaches synchronously
-        EqualizerCore.shared.applyAudioMix(to: item)
-      }
-    } else {
-      EqualizerCore.shared.applyAudioMix(to: item)
-    }
+    // Deliberately NOT calling loadValuesAsynchronously here.
+    //
+    // AVURLAsset.dealloc blocks its thread inside URLAssetFinalize until any in-flight
+    // key load finishes — and AVPlayer tears removed items down on the MAIN thread, so
+    // an item discarded mid-load stalls the main run loop (and RCTTiming with it, which
+    // stops JS timers). Asset warm-up still happens in preloadUpcomingTracks, which only
+    // publishes assets into `preloadedAssets` once every key has finished loading, so a
+    // reused preloaded asset has nothing in flight either.
+    //
+    // Caveat: with the equalizer ENABLED, applyAudioMix still loads the "tracks" key
+    // asynchronously for assets that don't have it yet, so a small window remains. That
+    // is unchanged from before (it was already the non-preload path) and is strictly
+    // less in-flight work than the previous 4-key preload on every queued item.
+    EqualizerCore.shared.applyAudioMix(to: item)
 
     return item
   }
 
   /// Preloads assets for upcoming tracks to enable gapless playback
   func preloadUpcomingTracks(from startIndex: Int) {
-    // Capture the set of track IDs that already have AVPlayerItems in the queue.
+    // Snapshot every piece of playerQueue-owned state HERE (we are on playerQueue).
+    // `preloadQueue` must never touch currentTracks / preloadedAssets directly —
+    // Swift Array/Dictionary are not safe for concurrent access.
     let queuedTrackIds = Set(player?.items().compactMap { $0.trackId } ?? [])
+    let alreadyPreloaded = Set(preloadedAssets.keys)
+    let endIndex = min(startIndex + Constants.gaplessPreloadCount, currentTracks.count)
+    guard startIndex >= 0, startIndex < endIndex else { return }
+    let candidates = Array(currentTracks[startIndex..<endIndex])
 
     preloadQueue.async { [weak self] in
       guard let self else { return }
 
-      let tracks = self.currentTracks
-      let endIndex = min(startIndex + Constants.gaplessPreloadCount, tracks.count)
-
-      for i in startIndex..<endIndex {
-        guard i < tracks.count else { break }
-        let track = tracks[i]
-
-        if self.preloadedAssets[track.id] != nil || queuedTrackIds.contains(track.id) {
+      for track in candidates {
+        if alreadyPreloaded.contains(track.id) || queuedTrackIds.contains(track.id) {
           continue
         }
 
@@ -567,7 +626,8 @@ extension TrackPlayerCore {
 
     let assetsToRemove = self.preloadedAssets.keys.filter { !keepIds.contains($0) }
     for id in assetsToRemove {
-      self.preloadedAssets.removeValue(forKey: id)
+      // Cancel before dropping the last reference — see cancelLoading(of:).
+      self.preloadedAssets.removeValue(forKey: id)?.cancelLoading()
     }
 
     if !assetsToRemove.isEmpty {

package/ios/core/TrackPlayerRecovery.swift

@@ -64,7 +64,7 @@ extension TrackPlayerCore {
     notifyTracksNeedUpdate(tracks: [track], lookahead: lookaheadCount)
 
     // A preloaded asset for this track shares the same dead connection state.
-    preloadedAssets.removeValue(forKey: trackId)
+    preloadedAssets.removeValue(forKey: trackId)?.cancelLoading()
     // Surface a buffering state while the retry is pending.
     isRecoveringFromStall = true
     emitStateChange()