react-native-nitro-player 0.5.9-alpha.0 → 0.6.0

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

@@ -41,6 +41,28 @@ class TrackPlayerCore private constructor(
     private val handler = android.os.Handler(android.os.Looper.getMainLooper())
     private lateinit var player: ExoPlayer
     private val playlistManager = PlaylistManager.getInstance(context)
+
+    // Named Runnable so handler.removeCallbacks() can coalesce rapid playlist
+    // mutations (e.g. N individual removes followed by a batch add during shuffle)
+    // into a single player update, preventing audio gaps on Android.
+    private val updateCurrentPlaylistRunnable = Runnable {
+        val playlistId = currentPlaylistId ?: return@Runnable
+        val playlist = playlistManager.getPlaylist(playlistId) ?: return@Runnable
+
+        // Always update the canonical track list first.
+        currentTracks = playlist.tracks
+
+        if (::player.isInitialized && player.currentMediaItem != null && player.currentMediaItemIndex >= 0) {
+            // Something is actively playing — rebuild only the items AFTER the
+            // current position using surgical removeMediaItems/addMediaItems.
+            // This avoids setMediaItems() which replaces the entire ExoPlayer
+            // queue (including the current item) and causes an audible gap.
+            rebuildQueueFromCurrentPosition()
+        } else {
+            // Nothing playing yet — safe to do a full replace.
+            updatePlayerQueue(playlist.tracks)
+        }
+    }
     private val downloadManager = DownloadManagerCore.getInstance(context)
     private val mediaLibraryManager = MediaLibraryManager.getInstance(context)
     private var mediaSessionManager: MediaSessionManager? = null
@@ -84,6 +106,7 @@ class TrackPlayerCore private constructor(
 
     @Volatile private var currentRepeatMode: RepeatMode = RepeatMode.OFF
     private var lookaheadCount: Int = 5 // Number of tracks to preload ahead
+    private var playerListener: Player.Listener? = null
 
     // Temporary tracks for addToUpNext and playNext
     private var playNextStack: MutableList<TrackItem> = mutableListOf() // LIFO - last added plays first
@@ -177,8 +200,7 @@ class TrackPlayerCore private constructor(
                         registerCarConnectionReceiver()
                     }
 
-                player.addListener(
-                    object : Player.Listener {
+                val listener = object : Player.Listener {
                         override fun onMediaItemTransition(
                             mediaItem: MediaItem?,
                             reason: Int,
@@ -353,8 +375,9 @@ class TrackPlayerCore private constructor(
                                 }
                             }
                         }
-                    },
-                )
+                }
+                playerListener = listener
+                player.addListener(listener)
 
                 // Start progress updates
                 handler.post(progressUpdateRunnable)
@@ -433,14 +456,13 @@ class TrackPlayerCore private constructor(
      * Update the player queue when playlist changes
      */
     fun updatePlaylist(playlistId: String) {
-        handler.post {
-            if (currentPlaylistId == playlistId) {
-                val playlist = playlistManager.getPlaylist(playlistId)
-                if (playlist != null) {
-                    updatePlayerQueue(playlist.tracks)
-                }
-            }
-        }
+        // Debounce: rapid back-to-back calls (e.g. removing N tracks then adding
+        // the shuffled replacement) are coalesced into a single setMediaItems call.
+        // removeCallbacks cancels any pending-but-not-yet-executed callback so only
+        // the final playlist state triggers a player rebuild.
+        if (currentPlaylistId != playlistId) return
+        handler.removeCallbacks(updateCurrentPlaylistRunnable)
+        handler.post(updateCurrentPlaylistRunnable)
     }
 
     /**
@@ -1266,6 +1288,8 @@ class TrackPlayerCore private constructor(
         handler.post {
             androidAutoConnectionDetector?.unregisterCarConnectionReceiver()
             handler.removeCallbacks(progressUpdateRunnable)
+            playerListener?.let { player.removeListener(it) }
+            playerListener = null
         }
     }
 

package/ios/core/TrackPlayerCore.swift

@@ -48,6 +48,10 @@ class TrackPlayerCore: NSObject {
   private var currentPlaylistId: String?
   private var currentTrackIndex: Int = -1
   private var currentTracks: [TrackItem] = []
+  // Debounce work item — rapid playlist mutations (e.g. N individual removes
+  // during shuffle) are coalesced into a single rebuildAVQueueFromCurrentPosition
+  // call, preventing audio gaps/interruptions on iOS.
+  private var pendingPlaylistUpdateWorkItem: DispatchWorkItem?
   private var isManuallySeeked = false
   private var currentRepeatMode: RepeatMode = .off
   private var lookaheadCount: Int = 5  // Number of tracks to preload ahead
@@ -58,6 +62,10 @@ class TrackPlayerCore: NSObject {
   private var preloadedAssets: [String: AVURLAsset] = [:]
   private let preloadQueue = DispatchQueue(label: "com.nitroplayer.preload", qos: .utility)
 
+  // Debounce flag: prevents firing checkUpcomingTracksForUrls every boundary tick
+  // once we've already requested URLs for the current track's remaining window.
+  private var didRequestUrlsForCurrentItem = false
+
   // Temporary tracks for addToUpNext and playNext
   private var playNextStack: [TrackItem] = []  // LIFO - last added plays first
   private var upNextQueue: [TrackItem] = []  // FIFO - first added plays first
@@ -141,6 +149,25 @@ class TrackPlayerCore: NSObject {
 
     NitroPlayerLogger.log("TrackPlayerCore", "🎵 Gapless playback configured - automaticallyWaitsToMinimizeStalling=true (flipped to false on first readyToPlay)")
 
+    // Listen for EQ enabled/disabled changes so we can update ALL items in
+    // the queue atomically, keeping the audio pipeline configuration uniform.
+    // A mismatch (some items with tap, some without) forces AVQueuePlayer to
+    // reconfigure the pipeline at transition boundaries → audible gap.
+    EqualizerCore.shared.addOnEnabledChangeListener(owner: self) { [weak self] enabled in
+      guard let self = self, let player = self.player else { return }
+      DispatchQueue.main.async {
+        for item in player.items() {
+          if enabled {
+            EqualizerCore.shared.applyAudioMix(to: item)
+          } else {
+            item.audioMix = nil
+          }
+        }
+        NitroPlayerLogger.log("TrackPlayerCore",
+          "🎛️ EQ toggled \(enabled ? "ON" : "OFF") — updated \(player.items().count) items for pipeline consistency")
+      }
+    }
+
     setupPlayerObservers()
   }
 
@@ -227,26 +254,15 @@ class TrackPlayerCore: NSObject {
       interval = Constants.boundaryIntervalDefault
     }
 
-    // Create boundary times at each interval
-    var boundaryTimes: [NSValue] = []
-    boundaryTimes.reserveCapacity(Int(duration / interval) + 1)
-    var time: Double = 0
-    while time <= duration {
-      let cmTime = CMTime(seconds: time, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
-      boundaryTimes.append(NSValue(time: cmTime))
-      time += interval
-    }
-
-    NitroPlayerLogger.log("TrackPlayerCore", "⏱️ Setting up \(boundaryTimes.count) boundary observers (interval: \(interval)s, duration: \(Int(duration))s)")
+    NitroPlayerLogger.log("TrackPlayerCore", "⏱️ Setting up periodic observer (interval: \(interval)s, duration: \(Int(duration))s)")
 
-    // Add boundary time observer
-    boundaryTimeObserver = player.addBoundaryTimeObserver(forTimes: boundaryTimes, queue: .main) {
-      [weak self] in
-      guard let self = self else { return }
-      self.handleBoundaryTimeCrossed()
+    let cmInterval = CMTime(seconds: interval, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+    boundaryTimeObserver = player.addPeriodicTimeObserver(forInterval: cmInterval, queue: .main) {
+      [weak self] _ in
+      self?.handleBoundaryTimeCrossed()
     }
 
-    NitroPlayerLogger.log("TrackPlayerCore", "⏱️ Boundary time observer setup complete")
+    NitroPlayerLogger.log("TrackPlayerCore", "⏱️ Periodic time observer setup complete")
   }
 
   private func handleBoundaryTimeCrossed() {
@@ -270,6 +286,17 @@ class TrackPlayerCore: NSObject {
       isManuallySeeked ? true : nil
     )
     isManuallySeeked = false
+
+    // Proactive gapless URL resolution: when the track is within the
+    // buffer window of its end, check if any upcoming tracks still
+    // need URLs and fire the callback so JS can resolve them in time.
+    let remaining = duration - position
+    if remaining > 0 && remaining <= Constants.preferredForwardBufferDuration && !didRequestUrlsForCurrentItem {
+      didRequestUrlsForCurrentItem = true
+      NitroPlayerLogger.log("TrackPlayerCore",
+        "⏳ \(Int(remaining))s remaining — proactively checking upcoming URLs")
+      checkUpcomingTracksForUrls(lookahead: lookaheadCount)
+    }
   }
 
   // MARK: - Notification Handlers
@@ -395,6 +422,9 @@ class TrackPlayerCore: NSObject {
     // Clear old item observers
     currentItemObservers.removeAll()
 
+    // Reset proactive URL check debounce for the new track
+    didRequestUrlsForCurrentItem = false
+
     // Track changed - update index
     guard let player = player,
       let currentItem = player.currentItem
@@ -623,7 +653,13 @@ class TrackPlayerCore: NSObject {
   }
 
   func updatePlaylist(playlistId: String) {
-    DispatchQueue.main.async { [weak self] in
+    guard currentPlaylistId == playlistId else { return }
+
+    // Cancel any pending rebuild so back-to-back calls (e.g. N individual removes
+    // during shuffle) collapse into a single rebuild at the end.
+    pendingPlaylistUpdateWorkItem?.cancel()
+
+    let workItem = DispatchWorkItem { [weak self] in
       guard let self = self else { return }
       guard self.currentPlaylistId == playlistId,
         let playlist = self.playlistManager.getPlaylist(playlistId: playlistId)
@@ -641,6 +677,9 @@ class TrackPlayerCore: NSObject {
       // Rebuild only the items after the currently playing item
       self.rebuildAVQueueFromCurrentPosition()
     }
+
+    pendingPlaylistUpdateWorkItem = workItem
+    DispatchQueue.main.async(execute: workItem)
   }
 
   // MARK: - Public Methods
@@ -721,18 +760,17 @@ class TrackPlayerCore: NSObject {
       asset = preloadedAsset
       NitroPlayerLogger.log("TrackPlayerCore", "🚀 Using preloaded asset for \(track.title)")
     } else {
-      // No AVURLAssetPreferPreciseDurationAndTimingKey — gapless playback is achieved via
-      // AVQueuePlayer's internal audio buffer pre-roll, not timing metadata.
-      // Precise timing only helps with accurate VBR duration display, at the cost of
-      // deep file scanning that delays readyToPlay.
-      asset = AVURLAsset(url: url)
+      asset = AVURLAsset(url: url, options: [
+        AVURLAssetPreferPreciseDurationAndTimingKey: true
+      ])
     }
 
     let item = AVPlayerItem(asset: asset)
 
-    // Configure buffer duration for gapless playback
-    // This tells AVPlayer how much content to buffer ahead
-    item.preferredForwardBufferDuration = Constants.preferredForwardBufferDuration
+    // Let the system choose the optimal forward buffer size (0 = automatic).
+    // An explicit cap (e.g. 30 s) limits how much of the *next* queued item
+    // AVQueuePlayer pre-rolls, which can cause audible gaps on HTTP streams.
+    item.preferredForwardBufferDuration = 0
 
     // Enable automatic loading of item properties for faster starts
     item.canUseNetworkResourcesForLiveStreamingWhilePaused = true
@@ -740,14 +778,10 @@ class TrackPlayerCore: NSObject {
     // Store track ID for later reference
     item.trackId = track.id
 
-    // Apply equalizer audio mix to the player item
-    // This enables real-time EQ processing via MTAudioProcessingTap
-    // Apply equalizer audio mix to the player item
-    // This enables real-time EQ processing via MTAudioProcessingTap
-    EqualizerCore.shared.applyAudioMix(to: item)
-    NitroPlayerLogger.log("TrackPlayerCore", "🎛️ Requesting EQ audio mix application for \(track.title)")
-
-    // If this is a preload request, start loading asset keys asynchronously
+    // If this is a preload request, start loading asset keys asynchronously.
+    // EQ is applied INSIDE the completion handler so the "tracks" key is
+    // already loaded → applyAudioMix takes the synchronous fast-path and
+    // the tap is attached before AVQueuePlayer pre-rolls the item.
     if isPreload {
       asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) {
         // Asset keys are now loaded, which speeds up playback start
@@ -763,7 +797,13 @@ class TrackPlayerCore: NSObject {
         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 {
+      // Non-preload: asset may already have keys loaded (preloadedAssets cache)
+      // so applyAudioMix will use the sync path if possible, async otherwise.
+      EqualizerCore.shared.applyAudioMix(to: item)
     }
 
     return item
@@ -771,6 +811,13 @@ class TrackPlayerCore: NSObject {
 
   /// Preloads assets for upcoming tracks to enable gapless playback
   private func preloadUpcomingTracks(from startIndex: Int) {
+    // Capture the set of track IDs that already have AVPlayerItems in the
+    // queue (main-thread access). Creating duplicate AVURLAssets for these
+    // would start parallel HTTP downloads for the same URLs, competing
+    // with AVQueuePlayer's own pre-roll buffering and potentially starving
+    // the next-item buffer — resulting in an audible gap at the transition.
+    let queuedTrackIds = Set(player?.items().compactMap { $0.trackId } ?? [])
+
     preloadQueue.async { [weak self] in
       guard let self = self else { return }
 
@@ -782,14 +829,26 @@ class TrackPlayerCore: NSObject {
         guard i < tracks.count else { break }
         let track = tracks[i]
 
-        // Skip if already preloaded
-        if self.preloadedAssets[track.id] != nil {
+        // Skip if already preloaded OR already in the player queue
+        if self.preloadedAssets[track.id] != nil || queuedTrackIds.contains(track.id) {
           continue
         }
 
-        guard let url = URL(string: track.url) else { continue }
+        // Use effective URL so downloaded tracks preload from disk, not network
+        let effectiveUrlString = DownloadManagerCore.shared.getEffectiveUrl(track: track)
+        let isLocal = effectiveUrlString.hasPrefix("/")
 
-        let asset = AVURLAsset(url: url)
+        let url: URL
+        if isLocal {
+          url = URL(fileURLWithPath: effectiveUrlString)
+        } else {
+          guard let remoteUrl = URL(string: effectiveUrlString) else { continue }
+          url = remoteUrl
+        }
+
+        let asset = AVURLAsset(url: url, options: [
+          AVURLAssetPreferPreciseDurationAndTimingKey: true
+        ])
 
         // Preload essential keys for gapless playback
         asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) { [weak self] in
@@ -1007,10 +1066,12 @@ class TrackPlayerCore: NSObject {
     NitroPlayerLogger.log("TrackPlayerCore", "🔄 Removing \(existingPlayer.items().count) old items from player")
     existingPlayer.removeAllItems()
 
-    // Lazy-load mode: if any track has no URL yet, don't populate AVQueuePlayer items now.
-    // Adding downloaded tracks at incorrect positions would cause the wrong track to play.
-    // updateTracks will rebuild from the correct currentTrackIndex once URLs are resolved.
-    let isLazyLoad = tracks.contains { $0.url.isEmpty }
+    // Lazy-load mode: if any track has no URL AND is not downloaded locally,
+    // we can't create an AVPlayerItem for it and the queue order would be wrong.
+    // Downloaded tracks with empty remote URLs still play from disk via getEffectiveUrl.
+    let isLazyLoad = tracks.contains {
+      $0.url.isEmpty && !DownloadManagerCore.shared.isTrackDownloaded(trackId: $0.id)
+    }
     if isLazyLoad {
       NitroPlayerLogger.log("TrackPlayerCore", "⏳ Lazy-load mode — player cleared, awaiting URL resolution")
       return
@@ -1718,12 +1779,12 @@ class TrackPlayerCore: NSObject {
     // Update currentTrackIndex BEFORE updating queue
     self.currentTrackIndex = index
 
-    // Lazy-load guard: if the target track itself has no URL yet, the queue can't be built.
-    // Emit the track change now (so UI reflects the navigation) and defer queue population
-    // to updateTracks once URL resolution completes.
-    // Only check the target — other unresolved tracks elsewhere in the playlist shouldn't
-    // block a skip to a track that is already playable.
-    let isLazyLoad = fullPlaylist[index].url.isEmpty
+    // Lazy-load guard: if the target track has no URL AND is not downloaded locally,
+    // the queue can't be built. Defer to updateTracks once URL resolution completes.
+    // Downloaded tracks play from disk via getEffectiveUrl — no remote URL needed.
+    let targetTrack = fullPlaylist[index]
+    let isLazyLoad = targetTrack.url.isEmpty
+      && !DownloadManagerCore.shared.isTrackDownloaded(trackId: targetTrack.id)
     if isLazyLoad {
       NitroPlayerLogger.log("TrackPlayerCore", "   ⏳ Lazy-load — deferring AVQueuePlayer setup; emitting track change for index \(index)")
       self.currentTracks = fullPlaylist
@@ -1855,17 +1916,26 @@ class TrackPlayerCore: NSObject {
   /**
    * Rebuild the AVQueuePlayer from current position with temporary tracks
    * Order: [current] + [playNext stack reversed] + [upNext queue] + [remaining original]
+   *
+   * - Parameter changedTrackIds: When non-nil, performs a **surgical** update:
+   *   only AVPlayerItems whose track ID is in this set are removed and re-created.
+   *   All other pre-buffered items are left in place and new items are inserted
+   *   around them. This preserves AVQueuePlayer's internal audio pre-roll buffers
+   *   for gapless inter-track transitions.
+   *   When nil, the queue is fully torn down and rebuilt (used by skip, reorder,
+   *   addToUpNext, playNext, etc.).
    */
-  private func rebuildAVQueueFromCurrentPosition() {
+  private func rebuildAVQueueFromCurrentPosition(changedTrackIds: Set<String>? = nil) {
     guard let player = self.player else { return }
 
     let currentItem = player.currentItem
     let playingItems = player.items()
 
+    // ---- Build the desired upcoming track list ----
+
     var newQueueTracks: [TrackItem] = []
 
     // Add playNext stack (LIFO - most recently added plays first)
-    // Skip index 0 if current track is from playNext (it's already playing)
     if currentTemporaryType == .playNext && playNextStack.count > 1 {
       newQueueTracks.append(contentsOf: playNextStack.dropFirst())
     } else if currentTemporaryType != .playNext {
@@ -1873,7 +1943,6 @@ class TrackPlayerCore: NSObject {
     }
 
     // Add upNext queue (in order, FIFO)
-    // Skip index 0 if current track is from upNext (it's already playing)
     if currentTemporaryType == .upNext && upNextQueue.count > 1 {
       newQueueTracks.append(contentsOf: upNextQueue.dropFirst())
     } else if currentTemporaryType != .upNext {
@@ -1885,12 +1954,84 @@ class TrackPlayerCore: NSObject {
       newQueueTracks.append(contentsOf: currentTracks[(currentTrackIndex + 1)...])
     }
 
-    // Remove all items from player EXCEPT the currently playing one
+    // ---- Collect existing upcoming AVPlayerItems ----
+
+    let upcomingItems: [AVPlayerItem]
+    if let ci = currentItem, let ciIndex = playingItems.firstIndex(of: ci) {
+      upcomingItems = Array(playingItems.suffix(from: playingItems.index(after: ciIndex)))
+    } else {
+      upcomingItems = []
+    }
+
+    let existingIds = upcomingItems.compactMap { $0.trackId }
+    let desiredIds = newQueueTracks.map { $0.id }
+
+    // ---- Fast-path: nothing to do if queue already matches ----
+
+    if existingIds == desiredIds {
+      if let changedIds = changedTrackIds {
+        if Set(existingIds).isDisjoint(with: changedIds) {
+          NitroPlayerLogger.log("TrackPlayerCore",
+            "✅ Queue matches & no buffered URLs changed — preserving \(existingIds.count) items for gapless")
+          return
+        }
+      } else {
+        NitroPlayerLogger.log("TrackPlayerCore",
+          "✅ Queue already matches desired order — preserving \(existingIds.count) items for gapless")
+        return
+      }
+    }
+
+    // ---- Surgical path (changedTrackIds provided, e.g. from updateTracks) ----
+    // Only remove items whose URLs actually changed; insert newly-resolved items
+    // in the correct positions around existing, pre-buffered items.
+
+    if let changedIds = changedTrackIds {
+      // Build lookup of reusable (un-changed) items by track ID
+      var reusableByTrackId: [String: AVPlayerItem] = [:]
+      for item in upcomingItems {
+        if let trackId = item.trackId, !changedIds.contains(trackId) {
+          reusableByTrackId[trackId] = item
+        }
+      }
+
+      // Remove only items whose URLs changed
+      let desiredIdSet = Set(desiredIds)
+      for item in upcomingItems {
+        guard let trackId = item.trackId else { continue }
+        if changedIds.contains(trackId) || !desiredIdSet.contains(trackId) {
+          player.remove(item)
+        }
+      }
+
+      // Walk through the desired order, inserting new items around the
+      // reusable items that are still sitting in the queue untouched.
+      var lastAnchor: AVPlayerItem? = currentItem
+      for trackId in desiredIds {
+        if let reusable = reusableByTrackId[trackId] {
+          // Item is still in the queue at its original position — advance anchor
+          lastAnchor = reusable
+        } else if let track = newQueueTracks.first(where: { $0.id == trackId }),
+          let newItem = createGaplessPlayerItem(for: track, isPreload: false)
+        {
+          player.insert(newItem, after: lastAnchor)
+          lastAnchor = newItem
+        }
+      }
+
+      let preserved = reusableByTrackId.count
+      let inserted = desiredIds.count - preserved
+      NitroPlayerLogger.log("TrackPlayerCore",
+        "🔄 Surgical rebuild: preserved \(preserved) buffered items, inserted \(inserted) new items")
+      return
+    }
+
+    // ---- Full rebuild path (no changedTrackIds — skip, reorder, etc.) ----
+
     for item in playingItems where item != currentItem {
       player.remove(item)
     }
 
-    // Insert new items in order
     var lastItem = currentItem
     for track in newQueueTracks {
       if let item = createGaplessPlayerItem(for: track, isPreload: false) {
@@ -1898,7 +2039,6 @@ class TrackPlayerCore: NSObject {
         lastItem = item
       }
     }
-
   }
 
   /**
@@ -1960,7 +2100,11 @@ class TrackPlayerCore: NSObject {
       // Get current track to decide how to handle it
       let currentTrack = self.getCurrentTrack()
       let currentTrackId = currentTrack?.id
-      let currentTrackIsEmpty = currentTrack?.url.isEmpty ?? false
+      // A track is only "empty" if it has no remote URL AND is not downloaded.
+      // Downloaded tracks with empty .url are playing from disk — don't replace them.
+      let currentTrackIsEmpty = currentTrack.map {
+        $0.url.isEmpty && !DownloadManagerCore.shared.isTrackDownloaded(trackId: $0.id)
+      } ?? false
 
       // Filter out current track and validate
       let safeTracks = tracks.filter { track in
@@ -2047,7 +2191,9 @@ class TrackPlayerCore: NSObject {
           self.preloadUpcomingTracks(from: self.currentTrackIndex + 1)
         } else {
           // A current AVPlayerItem already exists — preserve it and only rebuild upcoming items.
-          self.rebuildAVQueueFromCurrentPosition()
+          // Pass the set of track IDs whose URLs actually changed so the rebuild
+          // can keep already-buffered items intact for gapless transitions.
+          self.rebuildAVQueueFromCurrentPosition(changedTrackIds: updatedTrackIds)
           // Re-preload upcoming tracks for gapless playback
           // CRITICAL: This restores gapless buffering after queue rebuild
           self.preloadUpcomingTracks(from: self.currentTrackIndex + 1)
@@ -2099,7 +2245,11 @@ class TrackPlayerCore: NSObject {
       return []
     }
 
-    return playlist.tracks.filter { $0.url.isEmpty }
+    // Only return tracks that truly can't play: empty remote URL AND not
+    // downloaded locally.  Downloaded tracks play from disk via getEffectiveUrl.
+    return playlist.tracks.filter {
+      $0.url.isEmpty && !DownloadManagerCore.shared.isTrackDownloaded(trackId: $0.id)
+    }
   }
 
   /**
@@ -2196,12 +2346,18 @@ class TrackPlayerCore: NSObject {
   private func checkUpcomingTracksForUrls(lookahead: Int = 5) {
     let upcomingTracks = getNextTracksInternal(count: lookahead)
 
-    // Always include the current track if it has no URL — it can't play without one
+    // Always include the current track if it has no URL and isn't downloaded — it can't play without one
     let currentTrack = getCurrentTrack()
-    let currentNeedsUrl = currentTrack.map { $0.url.isEmpty } ?? false
+    let currentNeedsUrl = currentTrack.map {
+      $0.url.isEmpty && !DownloadManagerCore.shared.isTrackDownloaded(trackId: $0.id)
+    } ?? false
     let candidateTracks = currentNeedsUrl ? [currentTrack!] + upcomingTracks : upcomingTracks
 
-    let tracksNeedingUrls = candidateTracks.filter { $0.url.isEmpty }
+    // Only request URLs for tracks that truly can't play: empty remote URL
+    // AND not downloaded locally (downloaded tracks play from disk via getEffectiveUrl).
+    let tracksNeedingUrls = candidateTracks.filter {
+      $0.url.isEmpty && !DownloadManagerCore.shared.isTrackDownloaded(trackId: $0.id)
+    }
 
     if !tracksNeedingUrls.isEmpty {
       NitroPlayerLogger.log(

package/ios/equalizer/EqualizerCore.swift

@@ -91,11 +91,35 @@ class EqualizerCore {
 
   // MARK: - Audio Mix Creation for AVPlayerItem
 
-  /// Applies an AVAudioMix with equalizer processing for the given AVPlayerItem asynchronously
+  /// Applies an AVAudioMix with equalizer processing for the given AVPlayerItem.
+  /// No-ops when the equalizer is disabled so that AVPlayerItems remain tap-free,
+  /// keeping the audio pipeline configuration identical across all queued items
+  /// and allowing AVQueuePlayer to perform seamless gapless transitions.
+  ///
+  /// When the asset's "tracks" key is already loaded (e.g. from preloading),
+  /// the mix is applied **synchronously** so the item enters AVQueuePlayer with
+  /// the correct tap from the start — avoiding a pipeline reconfiguration that
+  /// causes an audible gap at the transition.
   func applyAudioMix(to playerItem: AVPlayerItem) {
+    guard isEqualizerEnabled else {
+      // Ensure no stale tap remains from a previous enable/disable cycle
+      if playerItem.audioMix != nil {
+        playerItem.audioMix = nil
+      }
+      return
+    }
+
     let asset = playerItem.asset
 
-    // Load "tracks" key asynchronously to avoid blocking
+    // Fast path: "tracks" already loaded (from preloadUpcomingTracks) — apply synchronously.
+    var keyError: NSError?
+    if asset.statusOfValue(forKey: "tracks", error: &keyError) == .loaded {
+      buildAndApplyAudioMix(to: playerItem, asset: asset)
+      NitroPlayerLogger.log("EqualizerCore", "✅ Applied audio mix with EQ tap to player item (sync — preloaded)")
+      return
+    }
+
+    // Slow path: load "tracks" key asynchronously to avoid blocking
     asset.loadValuesAsynchronously(forKeys: ["tracks"]) { [weak self] in
       guard let self = self else { return }
 
@@ -113,50 +137,55 @@ class EqualizerCore {
         return
       }
 
-      guard let audioTrack = asset.tracks(withMediaType: .audio).first else {
-        NitroPlayerLogger.log("EqualizerCore", "⚠️ No audio track found in asset")
-        return
-      }
+      // Apply directly — audioMix is thread-safe and applying on the
+      // loadValues completion queue avoids a main-thread hop that would
+      // delay tap attachment and risk a pipeline mismatch at pre-roll time.
+      self.buildAndApplyAudioMix(to: playerItem, asset: asset)
+      NitroPlayerLogger.log("EqualizerCore", "✅ Applied audio mix with EQ tap to player item (async)")
+    }
+  }
 
-      // Create audio mix input parameters
-      let inputParams = AVMutableAudioMixInputParameters(track: audioTrack)
-
-      // Create the audio processing tap
-      var callbacks = MTAudioProcessingTapCallbacks(
-        version: kMTAudioProcessingTapCallbacksVersion_0,
-        clientInfo: UnsafeMutableRawPointer(Unmanaged.passRetained(self).toOpaque()),
-        init: tapInitCallback,
-        finalize: tapFinalizeCallback,
-        prepare: tapPrepareCallback,
-        unprepare: tapUnprepareCallback,
-        process: tapProcessCallback
-      )
+  /// Creates an MTAudioProcessingTap-backed AVAudioMix and sets it on the player item.
+  /// Must be called when the asset's "tracks" key is already loaded.
+  private func buildAndApplyAudioMix(to playerItem: AVPlayerItem, asset: AVAsset) {
+    guard let audioTrack = asset.tracks(withMediaType: .audio).first else {
+      NitroPlayerLogger.log("EqualizerCore", "⚠️ No audio track found in asset")
+      return
+    }
 
-      var tap: MTAudioProcessingTap?
-      let createStatus = MTAudioProcessingTapCreate(
-        kCFAllocatorDefault,
-        &callbacks,
-        kMTAudioProcessingTapCreationFlag_PreEffects,
-        &tap
-      )
+    // Create audio mix input parameters
+    let inputParams = AVMutableAudioMixInputParameters(track: audioTrack)
+
+    // Create the audio processing tap
+    var callbacks = MTAudioProcessingTapCallbacks(
+      version: kMTAudioProcessingTapCallbacksVersion_0,
+      clientInfo: UnsafeMutableRawPointer(Unmanaged.passRetained(self).toOpaque()),
+      init: tapInitCallback,
+      finalize: tapFinalizeCallback,
+      prepare: tapPrepareCallback,
+      unprepare: tapUnprepareCallback,
+      process: tapProcessCallback
+    )
 
-      guard createStatus == noErr, let audioTap = tap else {
-        NitroPlayerLogger.log("EqualizerCore", "❌ Failed to create audio processing tap, status: \(createStatus)")
-        return
-      }
+    var tap: MTAudioProcessingTap?
+    let createStatus = MTAudioProcessingTapCreate(
+      kCFAllocatorDefault,
+      &callbacks,
+      kMTAudioProcessingTapCreationFlag_PreEffects,
+      &tap
+    )
 
-      inputParams.audioTapProcessor = audioTap
+    guard createStatus == noErr, let audioTap = tap else {
+      NitroPlayerLogger.log("EqualizerCore", "❌ Failed to create audio processing tap, status: \(createStatus)")
+      return
+    }
 
-      // Create audio mix
-      let audioMix = AVMutableAudioMix()
-      audioMix.inputParameters = [inputParams]
+    inputParams.audioTapProcessor = audioTap
 
-      // Apply to player item on main thread (AVPlayerItem properties should be accessed/modified on main thread or serial queue usually, but audioMix is thread safe - safely done on main to be sure)
-      DispatchQueue.main.async {
-        playerItem.audioMix = audioMix
-        NitroPlayerLogger.log("EqualizerCore", "✅ Applied audio mix with EQ tap to player item (async)")
-      }
-    }
+    // Create and apply audio mix
+    let audioMix = AVMutableAudioMix()
+    audioMix.inputParameters = [inputParams]
+    playerItem.audioMix = audioMix
   }
 
   // MARK: - Public Methods

package/lib/hooks/usePlaylist.js

@@ -41,6 +41,9 @@ export function usePlaylist() {
     const [isLoading, setIsLoading] = useState(true);
     const isMounted = useRef(true);
     const hasSubscribed = useRef(false);
+    // Tracks the last fetched playlist ID so track-change events can skip
+    // a full refresh when the playlist itself hasn't changed.
+    const lastPlaylistIdRef = useRef(undefined);
     const refreshPlaylists = useCallback(() => {
         if (!isMounted.current)
             return;
@@ -49,6 +52,7 @@ export function usePlaylist() {
             const playlistId = PlayerQueue.getCurrentPlaylistId();
             if (!isMounted.current)
                 return;
+            lastPlaylistIdRef.current = playlistId;
             setCurrentPlaylistId(playlistId);
             // Get current playlist details
             if (playlistId) {
@@ -88,6 +92,24 @@ export function usePlaylist() {
             }
         }
     }, []);
+    // Lightweight track-change handler: only does a full refresh when the
+    // active playlist ID has actually changed (e.g. cross-playlist navigation).
+    // Within-playlist track changes — the common case — are skipped with a
+    // single bridge call instead of three.
+    const refreshOnTrackChange = useCallback(() => {
+        if (!isMounted.current)
+            return;
+        try {
+            const newPlaylistId = PlayerQueue.getCurrentPlaylistId();
+            if (newPlaylistId === lastPlaylistIdRef.current)
+                return;
+            lastPlaylistIdRef.current = newPlaylistId;
+            refreshPlaylists();
+        }
+        catch (error) {
+            console.error('[usePlaylist] Error checking playlist ID on track change:', error);
+        }
+    }, [refreshPlaylists]);
     // Initialize and setup mounted ref
     useEffect(() => {
         isMounted.current = true;
@@ -113,18 +135,17 @@ export function usePlaylist() {
             console.error('[usePlaylist] Error setting up playlist listener:', error);
         }
     }, [refreshPlaylists]);
-    // Also refresh when track changes (as it might indicate playlist loaded)
+    // Refresh on track change only if the active playlist ID changed.
     useEffect(() => {
         const unsubscribe = callbackManager.subscribeToTrackChange(() => {
-            // Refresh to update currentPlaylistId when track changes
             if (isMounted.current) {
-                refreshPlaylists();
+                refreshOnTrackChange();
             }
         });
         return () => {
             unsubscribe();
         };
-    }, [refreshPlaylists]);
+    }, [refreshOnTrackChange]);
     return {
         currentPlaylist,
         currentPlaylistId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "0.5.9-alpha.0",
+  "version": "0.6.0",
   "description": "A powerful audio player library for React Native with playlist management, playback controls, and support for Android Auto and CarPlay",
   "main": "lib/index",
   "module": "lib/index",

package/src/hooks/usePlaylist.ts

@@ -60,6 +60,9 @@ export function usePlaylist(): UsePlaylistResult {
   const [isLoading, setIsLoading] = useState(true)
   const isMounted = useRef(true)
   const hasSubscribed = useRef(false)
+  // Tracks the last fetched playlist ID so track-change events can skip
+  // a full refresh when the playlist itself hasn't changed.
+  const lastPlaylistIdRef = useRef<string | null | undefined>(undefined)
 
   const refreshPlaylists = useCallback(() => {
     if (!isMounted.current) return
@@ -68,6 +71,7 @@ export function usePlaylist(): UsePlaylistResult {
       // Get current playlist ID
       const playlistId = PlayerQueue.getCurrentPlaylistId()
       if (!isMounted.current) return
+      lastPlaylistIdRef.current = playlistId
       setCurrentPlaylistId(playlistId)
 
       // Get current playlist details
@@ -108,6 +112,25 @@ export function usePlaylist(): UsePlaylistResult {
     }
   }, [])
 
+  // Lightweight track-change handler: only does a full refresh when the
+  // active playlist ID has actually changed (e.g. cross-playlist navigation).
+  // Within-playlist track changes — the common case — are skipped with a
+  // single bridge call instead of three.
+  const refreshOnTrackChange = useCallback(() => {
+    if (!isMounted.current) return
+    try {
+      const newPlaylistId = PlayerQueue.getCurrentPlaylistId()
+      if (newPlaylistId === lastPlaylistIdRef.current) return
+      lastPlaylistIdRef.current = newPlaylistId
+      refreshPlaylists()
+    } catch (error) {
+      console.error(
+        '[usePlaylist] Error checking playlist ID on track change:',
+        error
+      )
+    }
+  }, [refreshPlaylists])
+
   // Initialize and setup mounted ref
   useEffect(() => {
     isMounted.current = true
@@ -136,19 +159,18 @@ export function usePlaylist(): UsePlaylistResult {
     }
   }, [refreshPlaylists])
 
-  // Also refresh when track changes (as it might indicate playlist loaded)
+  // Refresh on track change only if the active playlist ID changed.
   useEffect(() => {
     const unsubscribe = callbackManager.subscribeToTrackChange(() => {
-      // Refresh to update currentPlaylistId when track changes
       if (isMounted.current) {
-        refreshPlaylists()
+        refreshOnTrackChange()
       }
     })
 
     return () => {
       unsubscribe()
     }
-  }, [refreshPlaylists])
+  }, [refreshOnTrackChange])
 
   return {
     currentPlaylist,