react-native-nitro-player 0.0.1 → 0.3.0-alpha.10

package/ios/core/TrackPlayerCore.swift

@@ -31,6 +31,13 @@ class TrackPlayerCore: NSObject {
     // UI/Display constants
     static let separatorLineLength: Int = 80
     static let playlistSeparatorLength: Int = 40
+
+    // Gapless playback configuration
+    static let preferredForwardBufferDuration: Double = 30.0  // Buffer 30 seconds ahead
+    static let preloadAssetKeys: [String] = [
+      "playable", "duration", "tracks", "preferredTransform",
+    ]
+    static let gaplessPreloadCount: Int = 3  // Number of tracks to preload ahead
   }
 
   // MARK: - Properties
@@ -42,9 +49,26 @@ class TrackPlayerCore: NSObject {
   private var currentTrackIndex: Int = -1
   private var currentTracks: [TrackItem] = []
   private var isManuallySeeked = false
+  private var repeatMode: RepeatMode = .off
   private var boundaryTimeObserver: Any?
   private var currentItemObservers: [NSKeyValueObservation] = []
 
+  // Gapless playback: Cache for preloaded assets
+  private var preloadedAssets: [String: AVURLAsset] = [:]
+  private let preloadQueue = DispatchQueue(label: "com.nitroplayer.preload", qos: .utility)
+
+  // Temporary tracks for addToUpNext and playNext
+  private var playNextStack: [TrackItem] = []  // LIFO - last added plays first
+  private var upNextQueue: [TrackItem] = []  // FIFO - first added plays first
+  private var currentTemporaryType: TemporaryType = .none
+
+  // Enum to track what type of track is currently playing
+  private enum TemporaryType {
+    case none  // Playing from original playlist
+    case playNext  // Currently in playNextStack
+    case upNext  // Currently in upNextQueue
+  }
+
   var onChangeTrack: ((TrackItem, Reason?) -> Void)?
   var onPlaybackStateChange: ((TrackPlayerState, Reason?) -> Void)?
   var onSeek: ((Double, Double) -> Void)?
@@ -76,6 +100,24 @@ class TrackPlayerCore: NSObject {
 
   private func setupPlayer() {
     player = AVQueuePlayer()
+
+    // MARK: - Gapless Playback Configuration
+
+    // Disable automatic waiting to minimize stalling - this allows smoother transitions
+    // between tracks as AVPlayer won't pause to buffer excessively
+    player?.automaticallyWaitsToMinimizeStalling = false
+
+    // Set playback rate to 1.0 immediately when ready (reduces gap between tracks)
+    player?.actionAtItemEnd = .advance
+
+    // Configure for high-quality audio playback with minimal latency
+    if #available(iOS 15.0, *) {
+      player?.audiovisualBackgroundPlaybackPolicy = .continuesIfPossible
+    }
+
+    print(
+      "🎵 TrackPlayerCore: Gapless playback configured - automaticallyWaitsToMinimizeStalling=false")
+
     setupPlayerObservers()
   }
 
@@ -221,10 +263,22 @@ class TrackPlayerCore: NSObject {
       return
     }
 
-    if let trackId = finishedItem.trackId,
-      let track = currentTracks.first(where: { $0.id == trackId })
-    {
-      print("🏁 Finished: \(track.title)")
+    // Determine what type of track just finished and remove it from temporary lists
+    if let trackId = finishedItem.trackId {
+      // Check if it was a playNext track
+      if let index = playNextStack.firstIndex(where: { $0.id == trackId }) {
+        let track = playNextStack.remove(at: index)
+        print("🏁 Finished playNext track: \(track.title) - removed from stack")
+      }
+      // Check if it was an upNext track
+      else if let index = upNextQueue.firstIndex(where: { $0.id == trackId }) {
+        let track = upNextQueue.remove(at: index)
+        print("🏁 Finished upNext track: \(track.title) - removed from queue")
+      }
+      // Otherwise it was from original playlist
+      else if let track = currentTracks.first(where: { $0.id == trackId }) {
+        print("🏁 Finished original track: \(track.title)")
+      }
     }
 
     // Check remaining queue
@@ -232,6 +286,50 @@ class TrackPlayerCore: NSObject {
       print("📋 Remaining items in queue: \(player.items().count)")
     }
 
+    // Handle repeat modes
+    switch repeatMode {
+    case .track:
+      // Repeat current track - seek to beginning and play
+      print("🔁 TrackPlayerCore: Repeat mode is TRACK - replaying current track")
+      DispatchQueue.main.async { [weak self] in
+        guard let self = self, let player = self.player else { return }
+        // For temporary tracks, just seek to beginning
+        if self.currentTemporaryType != .none {
+          player.seek(to: .zero)
+          player.play()
+        } else {
+          // For original tracks, recreate via playFromIndex
+          self.playFromIndex(index: self.currentTrackIndex)
+        }
+      }
+      return
+
+    case .playlist:
+      // Check if we're at the end of the ORIGINAL playlist (ignore temps)
+      if currentTemporaryType == .none && currentTrackIndex >= currentTracks.count - 1 {
+        // Check if there are still temporary tracks
+        if !playNextStack.isEmpty || !upNextQueue.isEmpty {
+          print("🔁 TrackPlayerCore: Temporary tracks remaining, continuing...")
+        } else {
+          print("🔁 TrackPlayerCore: Repeat mode is PLAYLIST - restarting from beginning")
+          // Clear temps and restart
+          playNextStack.removeAll()
+          upNextQueue.removeAll()
+          DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.playFromIndex(index: 0)
+          }
+          return
+        }
+      } else {
+        print("🔁 TrackPlayerCore: Repeat mode is PLAYLIST - continuing to next track")
+      }
+
+    case .off:
+      // Default behavior - stop at end of playlist
+      print("🔁 TrackPlayerCore: Repeat mode is OFF")
+    }
+
     // Track ended naturally
     onChangeTrack?(
       getCurrentTrack()
@@ -375,12 +473,34 @@ class TrackPlayerCore: NSObject {
     // Setup KVO observers for current item
     setupCurrentItemObservers(item: currentItem)
 
-    // Update track index
+    // Update track index and determine temporary type
     if let trackId = currentItem.trackId {
       print("🔍 TrackPlayerCore: Looking up trackId '\(trackId)' in currentTracks...")
       print("   Current index BEFORE lookup: \(currentTrackIndex)")
 
-      if let index = currentTracks.firstIndex(where: { $0.id == trackId }) {
+      // Update temporary type
+      currentTemporaryType = determineCurrentTemporaryType()
+      print("   🎯 Track type: \(currentTemporaryType)")
+
+      // If it's a temporary track, don't update currentTrackIndex
+      if currentTemporaryType != .none {
+        // Find and emit the temporary track
+        var tempTrack: TrackItem? = nil
+        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 {
+          print("   🎵 Temporary track: \(track.title) - \(track.artist)")
+          print("   📢 Emitting onChangeTrack for temporary track")
+          onChangeTrack?(track, .skip)
+          mediaSessionManager?.onTrackChanged()
+        }
+      }
+      // It's an original playlist track
+      else if let index = currentTracks.firstIndex(where: { $0.id == trackId }) {
         print("   ✅ Found track at index: \(index)")
         print("   Setting currentTrackIndex from \(currentTrackIndex) to \(index)")
 
@@ -413,6 +533,11 @@ class TrackPlayerCore: NSObject {
     if currentItem.status == .readyToPlay {
       setupBoundaryTimeObserver()
     }
+
+    // MARK: - Gapless Playback: Preload upcoming tracks when track changes
+    // This ensures the next tracks are ready for seamless transitions
+    preloadUpcomingTracks(from: currentTrackIndex + 1)
+    cleanupPreloadedAssets(keepingFrom: currentTrackIndex)
   }
 
   private func setupCurrentItemObservers(item: AVPlayerItem) {
@@ -457,6 +582,12 @@ class TrackPlayerCore: NSObject {
       print("📂 TrackPlayerCore: LOAD PLAYLIST REQUEST")
       print("   Playlist ID: \(playlistId)")
 
+      // Clear temporary tracks when loading new playlist
+      self.playNextStack.removeAll()
+      self.upNextQueue.removeAll()
+      self.currentTemporaryType = .none
+      print("   🧹 Cleared temporary tracks")
+
       let playlist = self.playlistManager.getPlaylist(playlistId: playlistId)
       if let playlist = playlist {
         print("   ✅ Found playlist: \(playlist.name)")
@@ -521,6 +652,135 @@ class TrackPlayerCore: NSObject {
     mediaSessionManager?.onPlaybackStateChanged()
   }
 
+  // MARK: - Gapless Playback Helpers
+
+  /// Creates a gapless-optimized AVPlayerItem with proper buffering configuration
+  private func createGaplessPlayerItem(for track: TrackItem, isPreload: Bool = false)
+    -> AVPlayerItem?
+  {
+    guard let url = URL(string: track.url) else {
+      print("❌ TrackPlayerCore: Invalid URL for track: \(track.title) - \(track.url)")
+      return nil
+    }
+
+    // Check if we have a preloaded asset for this track
+    let asset: AVURLAsset
+    if let preloadedAsset = preloadedAssets[track.id] {
+      asset = preloadedAsset
+      print("🚀 TrackPlayerCore: Using preloaded asset for \(track.title)")
+    } else {
+      // Create asset with options optimized for gapless playback
+      asset = AVURLAsset(
+        url: url,
+        options: [
+          AVURLAssetPreferPreciseDurationAndTimingKey: true  // Ensures accurate duration for gapless transitions
+        ])
+    }
+
+    let item = AVPlayerItem(asset: asset)
+
+    // Configure buffer duration for gapless playback
+    // This tells AVPlayer how much content to buffer ahead
+    item.preferredForwardBufferDuration = Constants.preferredForwardBufferDuration
+
+    // Enable automatic loading of item properties for faster starts
+    item.canUseNetworkResourcesForLiveStreamingWhilePaused = true
+
+    // Store track ID for later reference
+    item.trackId = track.id
+
+    // If this is a preload request, start loading asset keys asynchronously
+    if isPreload {
+      asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) {
+        // Asset keys are now loaded, which speeds up playback start
+        var allKeysLoaded = true
+        for key in Constants.preloadAssetKeys {
+          var error: NSError?
+          let status = asset.statusOfValue(forKey: key, error: &error)
+          if status == .failed {
+            print(
+              "⚠️ TrackPlayerCore: Failed to load key '\(key)' for \(track.title): \(error?.localizedDescription ?? "unknown")"
+            )
+            allKeysLoaded = false
+          }
+        }
+        if allKeysLoaded {
+          print("✅ TrackPlayerCore: All asset keys preloaded for \(track.title)")
+        }
+      }
+    }
+
+    return item
+  }
+
+  /// Preloads assets for upcoming tracks to enable gapless playback
+  private func preloadUpcomingTracks(from startIndex: Int) {
+    preloadQueue.async { [weak self] in
+      guard let self = self else { return }
+
+      let endIndex = min(startIndex + Constants.gaplessPreloadCount, self.currentTracks.count)
+
+      for i in startIndex..<endIndex {
+        let track = self.currentTracks[i]
+
+        // Skip if already preloaded
+        if self.preloadedAssets[track.id] != nil {
+          continue
+        }
+
+        guard let url = URL(string: track.url) else { continue }
+
+        let asset = AVURLAsset(
+          url: url,
+          options: [
+            AVURLAssetPreferPreciseDurationAndTimingKey: true
+          ])
+
+        // Preload essential keys for gapless playback
+        asset.loadValuesAsynchronously(forKeys: Constants.preloadAssetKeys) { [weak self] in
+          var allKeysLoaded = true
+          for key in Constants.preloadAssetKeys {
+            var error: NSError?
+            let status = asset.statusOfValue(forKey: key, error: &error)
+            if status != .loaded {
+              allKeysLoaded = false
+              break
+            }
+          }
+
+          if allKeysLoaded {
+            DispatchQueue.main.async {
+              self?.preloadedAssets[track.id] = asset
+              print("🎯 TrackPlayerCore: Preloaded asset for upcoming track: \(track.title)")
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /// Clears preloaded assets that are no longer needed
+  private func cleanupPreloadedAssets(keepingFrom currentIndex: Int) {
+    preloadQueue.async { [weak self] in
+      guard let self = self else { return }
+
+      // Keep assets for current track and upcoming tracks within preload range
+      let keepRange =
+        currentIndex..<min(
+          currentIndex + Constants.gaplessPreloadCount + 1, self.currentTracks.count)
+      let keepIds = Set(keepRange.compactMap { self.currentTracks[safe: $0]?.id })
+
+      let assetsToRemove = self.preloadedAssets.keys.filter { !keepIds.contains($0) }
+      for id in assetsToRemove {
+        self.preloadedAssets.removeValue(forKey: id)
+      }
+
+      if !assetsToRemove.isEmpty {
+        print("🧹 TrackPlayerCore: Cleaned up \(assetsToRemove.count) preloaded assets")
+      }
+    }
+  }
+
   // MARK: - Queue Management
 
   private func updatePlayerQueue(tracks: [TrackItem]) {
@@ -545,40 +805,18 @@ class TrackPlayerCore: NSObject {
       boundaryTimeObserver = nil
     }
 
-    // Create AVPlayerItems from tracks
-    let items = tracks.compactMap { track -> AVPlayerItem? in
-      guard let url = URL(string: track.url) else {
-        print("❌ TrackPlayerCore: Invalid URL for track: \(track.title) - \(track.url)")
-        return nil
-      }
-
-      let item = AVPlayerItem(url: url)
+    // Clear old preloaded assets when loading new queue
+    preloadedAssets.removeAll()
 
-      // Set metadata using AVMutableMetadataItem
-      let metadata = AVMutableMetadataItem()
-      metadata.identifier = .commonIdentifierTitle
-      metadata.value = track.title as NSString
-      metadata.locale = Locale.current
-
-      let artistMetadata = AVMutableMetadataItem()
-      artistMetadata.identifier = .commonIdentifierArtist
-      artistMetadata.value = track.artist as NSString
-      artistMetadata.locale = Locale.current
-
-      let albumMetadata = AVMutableMetadataItem()
-      albumMetadata.identifier = .commonIdentifierAlbumName
-      albumMetadata.value = track.album as NSString
-      albumMetadata.locale = Locale.current
-
-      // Note: AVPlayerItem doesn't have externalMetadata property
-      // Metadata will be set via MPNowPlayingInfoCenter in MediaSessionManager
-
-      // Store track ID in item for later reference
-      item.trackId = track.id
-
-      return item
+    // Create gapless-optimized AVPlayerItems from tracks
+    let items = tracks.enumerated().compactMap { (index, track) -> AVPlayerItem? in
+      // First few items get preload treatment for faster initial playback
+      let isPreload = index < Constants.gaplessPreloadCount
+      return createGaplessPlayerItem(for: track, isPreload: isPreload)
     }
 
+    print("🎵 TrackPlayerCore: Created \(items.count) gapless-optimized player items")
+
     guard !items.isEmpty else {
       print("❌ TrackPlayerCore: No valid items to play")
       return
@@ -639,16 +877,64 @@ class TrackPlayerCore: NSObject {
       mediaSessionManager?.onTrackChanged()
     }
 
-    print("✅ TrackPlayerCore: Queue updated with \(items.count) tracks")
+    // Start preloading upcoming tracks for gapless playback
+    preloadUpcomingTracks(from: 1)
+
+    print("✅ TrackPlayerCore: Queue updated with \(items.count) gapless-optimized tracks")
   }
 
   func getCurrentTrack() -> TrackItem? {
+    // If playing a temporary track, return that
+    if currentTemporaryType != .none,
+      let currentItem = player?.currentItem,
+      let trackId = currentItem.trackId
+    {
+      if currentTemporaryType == .playNext {
+        return playNextStack.first(where: { $0.id == trackId })
+      } else if currentTemporaryType == .upNext {
+        return upNextQueue.first(where: { $0.id == trackId })
+      }
+    }
+
+    // Otherwise return from original playlist
     guard currentTrackIndex >= 0 && currentTrackIndex < currentTracks.count else {
       return nil
     }
     return currentTracks[currentTrackIndex]
   }
 
+  /**
+   * Get the actual queue with temporary tracks
+   * Returns: [original_before_current] + [current] + [playNext_stack] + [upNext_queue] + [original_after_current]
+   */
+  func getActualQueue() -> [TrackItem] {
+    var queue: [TrackItem] = []
+
+    // Add tracks before current (original playlist)
+    if currentTrackIndex > 0 {
+      queue.append(contentsOf: Array(currentTracks[0..<currentTrackIndex]))
+    }
+
+    // Add current track
+    if let current = getCurrentTrack() {
+      queue.append(current)
+    }
+
+    // Add playNext stack (LIFO - most recently added plays first)
+    // Stack is already in correct order since we insert at position 0
+    queue.append(contentsOf: playNextStack)
+
+    // Add upNext queue (in order, FIFO)
+    queue.append(contentsOf: upNextQueue)
+
+    // Add remaining original tracks
+    if currentTrackIndex + 1 < currentTracks.count {
+      queue.append(contentsOf: Array(currentTracks[(currentTrackIndex + 1)...]))
+    }
+
+    return queue
+  }
+
   func play() {
     print("▶️ TrackPlayerCore: play() called")
     DispatchQueue.main.async { [weak self] in
@@ -695,6 +981,12 @@ class TrackPlayerCore: NSObject {
     DispatchQueue.main.async { [weak self] in
       guard let self = self else { return }
 
+      // Clear temporary tracks when directly playing a song
+      self.playNextStack.removeAll()
+      self.upNextQueue.removeAll()
+      self.currentTemporaryType = .none
+      print("   🧹 Cleared temporary tracks")
+
       var targetPlaylistId: String?
       var songIndex: Int = -1
 
@@ -831,6 +1123,7 @@ class TrackPlayerCore: NSObject {
 
       print("\n⏮️ TrackPlayerCore: SKIP TO PREVIOUS")
       print("   Current index: \(self.currentTrackIndex)")
+      print("   Temporary type: \(self.currentTemporaryType)")
       print("   Current time: \(queuePlayer.currentTime().seconds)s")
 
       let currentTime = queuePlayer.currentTime()
@@ -839,8 +1132,12 @@ class TrackPlayerCore: NSObject {
         print(
           "   🔄 More than \(Int(Constants.skipToPreviousThreshold))s in, restarting current track")
         queuePlayer.seek(to: .zero)
+      } else if self.currentTemporaryType != .none {
+        // Playing temporary track - just restart it (temps are not navigable backwards)
+        print("   🔄 Playing temporary track - restarting it (temps not navigable backwards)")
+        queuePlayer.seek(to: .zero)
       } else if self.currentTrackIndex > 0 {
-        // Go to previous track
+        // Go to previous track in original playlist
         let previousIndex = self.currentTrackIndex - 1
         print("   ⏮️ Going to previous track at index \(previousIndex)")
         self.playFromIndex(index: previousIndex)
@@ -867,6 +1164,14 @@ class TrackPlayerCore: NSObject {
     }
   }
 
+  // MARK: - Repeat Mode
+
+  func setRepeatMode(mode: RepeatMode) -> Bool {
+    print("🔁 TrackPlayerCore: setRepeatMode called with mode: \(mode)")
+    self.repeatMode = mode
+    return true
+  }
+
   // MARK: - State Management
 
   func getState() -> PlayerState {
@@ -925,6 +1230,28 @@ class TrackPlayerCore: NSObject {
     return playlistManager.getAllPlaylists().map { $0.toGeneratedPlaylist() }
   }
 
+  // MARK: - Volume Control
+
+  func setVolume(volume: Double) -> Bool {
+    guard let player = player else {
+      print("⚠️ TrackPlayerCore: Cannot set volume - no player available")
+      return false
+    }
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self, let currentPlayer = self.player else {
+        return
+      }
+      // Clamp volume to 0-100 range
+      let clampedVolume = max(0.0, min(100.0, volume))
+      // Convert to 0.0-1.0 range for AVQueuePlayer
+      let normalizedVolume = Float(clampedVolume / 100.0)
+      currentPlayer.volume = normalizedVolume
+      print(
+        "🔊 TrackPlayerCore: Volume set to \(Int(clampedVolume))% (normalized: \(normalizedVolume))")
+    }
+    return true
+  }
+
   func playFromIndex(index: Int) {
     DispatchQueue.main.async { [weak self] in
       guard let self = self,
@@ -938,6 +1265,12 @@ class TrackPlayerCore: NSObject {
       print("   Total tracks in playlist: \(self.currentTracks.count)")
       print("   Current index: \(self.currentTrackIndex), target index: \(index)")
 
+      // Clear temporary tracks when jumping to specific index
+      self.playNextStack.removeAll()
+      self.upNextQueue.removeAll()
+      self.currentTemporaryType = .none
+      print("   🧹 Cleared temporary tracks")
+
       // Store the full playlist
       let fullPlaylist = self.currentTracks
 
@@ -947,14 +1280,15 @@ class TrackPlayerCore: NSObject {
       // Recreate the queue starting from the target index
       // This ensures all remaining tracks are in the queue
       let tracksToPlay = Array(fullPlaylist[index...])
-      print("   🔄 Creating queue with \(tracksToPlay.count) tracks starting from index \(index)")
-
-      // Update the queue (but keep the full currentTracks for reference)
-      let items = tracksToPlay.compactMap { track -> AVPlayerItem? in
-        guard let url = URL(string: track.url) else { return nil }
-        let item = AVPlayerItem(url: url)
-        item.trackId = track.id
-        return item
+      print(
+        "   🔄 Creating gapless queue with \(tracksToPlay.count) tracks starting from index \(index)"
+      )
+
+      // Create gapless-optimized player items
+      let items = tracksToPlay.enumerated().compactMap { (offset, track) -> AVPlayerItem? in
+        // First few items get preload treatment for faster playback
+        let isPreload = offset < Constants.gaplessPreloadCount
+        return self.createGaplessPlayerItem(for: track, isPreload: isPreload)
       }
 
       guard let player = self.player, !items.isEmpty else {
@@ -979,22 +1313,178 @@ class TrackPlayerCore: NSObject {
       // Restore the full playlist reference (don't slice it!)
       self.currentTracks = fullPlaylist
 
-      print("   ✅ Queue recreated. Now at index: \(self.currentTrackIndex)")
+      print("   ✅ Gapless queue recreated. Now at index: \(self.currentTrackIndex)")
       if let track = self.getCurrentTrack() {
         print("   🎵 Playing: \(track.title)")
         self.onChangeTrack?(track, .skip)
         self.mediaSessionManager?.onTrackChanged()
       }
 
+      // Start preloading upcoming tracks for gapless playback
+      self.preloadUpcomingTracks(from: index + 1)
+
       player.play()
     }
   }
 
+  // MARK: - Temporary Track Management
+
+  /**
+   * Add a track to the up-next queue (FIFO - first added plays first)
+   * Track will be inserted after currently playing track and any playNext tracks
+   */
+  func addToUpNext(trackId: String) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+
+      print("📋 TrackPlayerCore: addToUpNext(\(trackId))")
+
+      // Find the track from current playlist or all playlists
+      guard let track = self.findTrackById(trackId) else {
+        print("❌ TrackPlayerCore: Track \(trackId) not found")
+        return
+      }
+
+      // Add to end of upNext queue (FIFO)
+      self.upNextQueue.append(track)
+      print("   ✅ Added '\(track.title)' to upNext queue (position: \(self.upNextQueue.count))")
+
+      // Rebuild the player queue if actively playing
+      if self.player?.currentItem != nil {
+        self.rebuildAVQueueFromCurrentPosition()
+      }
+    }
+  }
+
+  /**
+   * Add a track to play next (LIFO - last added plays first)
+   * Track will be inserted immediately after currently playing track
+   */
+  func playNext(trackId: String) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+
+      print("⏭️ TrackPlayerCore: playNext(\(trackId))")
+
+      // Find the track from current playlist or all playlists
+      guard let track = self.findTrackById(trackId) else {
+        print("❌ TrackPlayerCore: Track \(trackId) not found")
+        return
+      }
+
+      // Insert at beginning of playNext stack (LIFO)
+      self.playNextStack.insert(track, at: 0)
+      print("   ✅ Added '\(track.title)' to playNext stack (position: 1)")
+
+      // Rebuild the player queue if actively playing
+      if self.player?.currentItem != nil {
+        self.rebuildAVQueueFromCurrentPosition()
+      }
+    }
+  }
+
+  /**
+   * Rebuild the AVQueuePlayer from current position with temporary tracks
+   * Order: [current] + [playNext stack reversed] + [upNext queue] + [remaining original]
+   */
+  private func rebuildAVQueueFromCurrentPosition() {
+    guard let player = self.player else { return }
+
+    print("\n🔄 TrackPlayerCore: REBUILDING QUEUE FROM CURRENT POSITION")
+    print("   playNext stack: \(playNextStack.count) tracks")
+    print("   upNext queue: \(upNextQueue.count) tracks")
+
+    // Don't interrupt currently playing item
+    let currentItem = player.currentItem
+    let playingItems = player.items()
+
+    // Build new queue order:
+    // [playNext stack] + [upNext queue] + [remaining original tracks]
+    var newQueueTracks: [TrackItem] = []
+
+    // Add playNext stack (LIFO - most recently added plays first)
+    // Stack is already in correct order since we insert at position 0
+    newQueueTracks.append(contentsOf: playNextStack)
+
+    // Add upNext queue (in order, FIFO)
+    newQueueTracks.append(contentsOf: upNextQueue)
+
+    // Add remaining original tracks
+    if currentTrackIndex + 1 < currentTracks.count {
+      let remainingOriginal = Array(currentTracks[(currentTrackIndex + 1)...])
+      newQueueTracks.append(contentsOf: remainingOriginal)
+    }
+
+    print("   New queue: \(newQueueTracks.count) tracks total")
+
+    // Remove all items from player EXCEPT the currently playing one
+    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) {
+        player.insert(item, after: lastItem)
+        lastItem = item
+      }
+    }
+
+    print("   ✅ Queue rebuilt successfully")
+  }
+
+  /**
+   * Find a track by ID from current playlist or all playlists
+   */
+  private func findTrackById(_ trackId: String) -> TrackItem? {
+    // First check current playlist
+    if let track = currentTracks.first(where: { $0.id == trackId }) {
+      return track
+    }
+
+    // Then check all playlists
+    let allPlaylists = playlistManager.getAllPlaylists()
+    for playlist in allPlaylists {
+      if let track = playlist.tracks.first(where: { $0.id == trackId }) {
+        return track
+      }
+    }
+
+    return nil
+  }
+
+  /**
+   * Determine what type of track is currently playing
+   */
+  private func determineCurrentTemporaryType() -> TemporaryType {
+    guard let currentItem = player?.currentItem,
+      let trackId = currentItem.trackId
+    else {
+      return .none
+    }
+
+    // Check if in playNext stack
+    if playNextStack.contains(where: { $0.id == trackId }) {
+      return .playNext
+    }
+
+    // Check if in upNext queue
+    if upNextQueue.contains(where: { $0.id == trackId }) {
+      return .upNext
+    }
+
+    return .none
+  }
+
   // MARK: - Cleanup
 
   deinit {
     print("🧹 TrackPlayerCore: Cleaning up...")
 
+    // Clear preloaded assets for gapless playback
+    preloadedAssets.removeAll()
+
     // Remove boundary time observer
     if let boundaryObserver = boundaryTimeObserver, let currentPlayer = player {
       currentPlayer.removeTimeObserver(boundaryObserver)