react-native-nitro-player 1.6.0-alpha.1 → 1.7.0-alpha.0

package/ios/core/TrackPlayerListener.swift

@@ -169,12 +169,14 @@ extension TrackPlayerCore {
   func playerItemDidPlayToEndTimeInternal(_ notification: Notification) {
     NitroPlayerLogger.log("TrackPlayerCore", "\n🏁 Track finished playing")
     guard let finishedItem = notification.object as? AVPlayerItem else { return }
+    // Items without our trackId belong to another AVPlayer in the host app
+    guard finishedItem.trackId != nil else { return }
 
     // 1. TRACK repeat — handle FIRST, before any temp-track removal
-    if currentRepeatMode == .track {
+    if currentRepeatMode == .track, finishedItem === player?.currentItem {
       NitroPlayerLogger.log("TrackPlayerCore", "🔁 TRACK repeat — seeking to zero and replaying")
       player?.seek(to: .zero)
-      player?.play()
+      player?.rate = Float(currentPlaybackSpeed)
       return  // do not remove temp tracks, do not notify track change (same track looping)
     }
 
@@ -201,14 +203,18 @@ extension TrackPlayerCore {
   }
 
   @objc func playerItemFailedToPlayToEndTime(_ notification: Notification) {
-    if let error = notification.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error {
+    guard (notification.object as? AVPlayerItem)?.trackId != nil else { return }
+    guard let error = notification.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error
+    else { return }
+    playerQueue.async { [weak self] in
       NitroPlayerLogger.log("TrackPlayerCore", "❌ Playback failed - \(error)")
-      notifyPlaybackStateChange(.stopped, .error)
+      self?.notifyPlaybackStateChange(.stopped, .error)
     }
   }
 
   @objc func playerItemNewErrorLogEntry(_ notification: Notification) {
-    guard let item = notification.object as? AVPlayerItem, let errorLog = item.errorLog() else { return }
+    guard let item = notification.object as? AVPlayerItem, item.trackId != nil,
+      let errorLog = item.errorLog() else { return }
     for event in errorLog.events ?? [] {
       NitroPlayerLogger.log("TrackPlayerCore", "❌ Error log - \(event.errorComment ?? "Unknown error") - Code: \(event.errorStatusCode)")
     }
@@ -220,6 +226,7 @@ extension TrackPlayerCore {
   @objc func playerItemTimeJumped(_ notification: Notification) {
     playerQueue.async { [weak self] in
       guard let self, let player = self.player, let currentItem = player.currentItem else { return }
+      guard (notification.object as? AVPlayerItem) === currentItem else { return }
       let position = currentItem.currentTime().seconds
       let duration = currentItem.duration.seconds
       NitroPlayerLogger.log("TrackPlayerCore", "🎯 Time jumped (seek detected) - position: \(Int(position))s")
@@ -301,7 +308,7 @@ extension TrackPlayerCore {
           lastItem = item
         }
         currentTrackIndex = 0
-        player.play()
+        player.rate = Float(currentPlaybackSpeed)
 
         if let firstTrack = currentTracks.first {
           notifyTrackChange(firstTrack, .repeat)
@@ -454,16 +461,8 @@ extension TrackPlayerCore {
           self?.setupBoundaryTimeObserver()
           // First item is buffered and ready — disable stall waiting for gapless inter-track transitions
           self?.player?.automaticallyWaitsToMinimizeStalling = false
-          // Update now playing info now that duration is available (capture on playerQueue first)
-          let state = self?.getStateInternal()
-          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, queueCount: metrics.count, positionInQueue: metrics.position)
-            }
-          }
+          // Update now playing info now that duration is available (captured on playerQueue)
+          self?.refreshMediaSession()
         } else if item.status == .failed {
           NitroPlayerLogger.log("TrackPlayerCore",
             "❌ Item failed — \(item.error?.localizedDescription ?? "unknown error")")

package/ios/core/TrackPlayerNotify.swift

@@ -13,24 +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 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 metrics = actualQueueMetrics()
-    DispatchQueue.main.async { [weak self] in
-      self?.mediaSessionManager?.updateFromPlayerQueue(
-        track: track, state: state, queueCount: metrics.count, positionInQueue: metrics.position)
-    }
+    refreshMediaSession(track: track)
   }
 
   func notifyPlaybackStateChange(_ state: TrackPlayerState, _ reason: Reason?) {
     onPlaybackStateChangeListeners.forEach { $0(state, reason) }
-    guard let track = getCurrentTrack() else { return }
-    let playerState = getStateInternal()
+    refreshMediaSession()
+  }
+
+  /// Must run on playerQueue — values are captured here and handed to main pre-computed
+  func refreshMediaSession(track providedTrack: TrackItem? = nil) {
+    guard let track = providedTrack ?? getCurrentTrack() else { return }
+    let state = getStateInternal()
     let metrics = actualQueueMetrics()
+    let playbackSpeed = currentPlaybackSpeed
     DispatchQueue.main.async { [weak self] in
       self?.mediaSessionManager?.updateFromPlayerQueue(
-        track: track, state: playerState, queueCount: metrics.count, positionInQueue: metrics.position)
+        track: track, state: state, queueCount: metrics.count,
+        positionInQueue: metrics.position, playbackSpeed: playbackSpeed)
     }
   }
 

package/ios/core/TrackPlayerPlayback.swift

@@ -98,33 +98,49 @@ extension TrackPlayerCore {
 
   func configureOnQueue(
     androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
-    showInNotification: Bool?, lookaheadCount: Int?
+    showInNotification: Bool?, lookaheadCount: Int?,
+    remoteSkipForwardInterval: Double?, remoteSkipBackwardInterval: Double?
   ) {
     if let la = lookaheadCount {
       self.lookaheadCount = la
       NitroPlayerLogger.log("TrackPlayerCore", "🔄 Lookahead count set to: \(la)")
     }
+    let playbackSpeed = currentPlaybackSpeed
     DispatchQueue.main.async { [weak self] in
       self?.mediaSessionManager?.configure(
         androidAutoEnabled: androidAutoEnabled,
         carPlayEnabled: carPlayEnabled,
-        showInNotification: showInNotification
+        showInNotification: showInNotification,
+        remoteSkipForwardInterval: remoteSkipForwardInterval,
+        remoteSkipBackwardInterval: remoteSkipBackwardInterval,
+        playbackSpeed: playbackSpeed
       )
     }
   }
   func configure(
     androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
-    showInNotification: Bool?, lookaheadCount: Int?
+    showInNotification: Bool?, lookaheadCount: Int?,
+    remoteSkipForwardInterval: Double?, remoteSkipBackwardInterval: Double?
   ) async {
     await withPlayerQueueNoThrow {
       self.configureOnQueue(
         androidAutoEnabled: androidAutoEnabled, carPlayEnabled: carPlayEnabled,
-        showInNotification: showInNotification, lookaheadCount: lookaheadCount)
+        showInNotification: showInNotification, lookaheadCount: lookaheadCount,
+        remoteSkipForwardInterval: remoteSkipForwardInterval,
+        remoteSkipBackwardInterval: remoteSkipBackwardInterval)
     }
   }
 
-  func setPlaybackSpeedOnQueue(_ speed: Double) {
+  func setPlaybackSpeedOnQueue(_ speed: Double) throws {
+    guard speed.isFinite, speed > 0 else {
+      throw NSError(
+        domain: "NitroPlayer",
+        code: -1,
+        userInfo: [NSLocalizedDescriptionKey: "Speed must be finite and greater than 0"]
+      )
+    }
     currentPlaybackSpeed = speed
+    defer { refreshMediaSession() }
     if isCasting {
       castManager?.setPlaybackRate(Float(speed))
       return
@@ -134,8 +150,30 @@ extension TrackPlayerCore {
       player.rate = Float(speed)
     }
   }
-  func setPlaybackSpeed(_ speed: Double) async {
-    await withPlayerQueueNoThrow { self.setPlaybackSpeedOnQueue(speed) }
+  func setPlaybackSpeed(_ speed: Double) async throws {
+    try await withPlayerQueue { try self.setPlaybackSpeedOnQueue(speed) }
+  }
+
+  func seekByOnQueue(offset: Double) {
+    if isCasting {
+      let position = castManager?.lastKnownRemotePosition ?? 0
+      let duration = castManager?.lastKnownRemoteDuration ?? 0
+      var target = max(0, position + offset)
+      if duration > 0, duration.isFinite { target = min(target, duration) }
+      castManager?.seek(to: target)
+      return
+    }
+    guard let player = self.player else { return }
+    let position = player.currentTime().seconds
+    guard position.isFinite else { return }
+    var target = max(0, position + offset)
+    if let duration = player.currentItem?.duration.seconds, duration > 0, duration.isFinite {
+      target = min(target, duration)
+    }
+    seekInternal(position: target)
+  }
+  func seekBy(offset: Double) async {
+    await withPlayerQueueNoThrow { self.seekByOnQueue(offset: offset) }
   }
 
   func getPlaybackSpeed() async -> Double {
@@ -150,6 +188,7 @@ extension TrackPlayerCore {
 
   func playInternal() {
     NitroPlayerLogger.log("TrackPlayerCore", "▶️ play() called")
+    activateAudioSessionIfNeeded()
     self.intendedToPlay = true
     // An explicit play() is the ground truth for intent — clear any stale
     // interruption flag so a missed AVAudioSession `.ended` can't permanently
@@ -187,7 +226,7 @@ extension TrackPlayerCore {
     guard let player = self.player else { return }
     self.isManuallySeeked = true
     let time = CMTime(seconds: position, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
-    player.seek(to: time) { [weak self] completed in
+    player.seek(to: time) { _ in
        // HackFix I dont know how to fix this, but it works.
       let rate = Double(player.rate)
       DispatchQueue.main.async {
@@ -197,10 +236,8 @@ extension TrackPlayerCore {
           MPNowPlayingInfoCenter.default().nowPlayingInfo = info
         }
       }
-      if completed {
-        let duration = player.currentItem?.duration.seconds ?? 0.0
-        self?.notifySeek(position, duration)
-      }
+      // No notifySeek here — the same seek fires AVPlayerItemTimeJumped,
+      // whose handler already emits it; calling both doubled every onSeek.
     }
   }
 
@@ -240,11 +277,12 @@ extension TrackPlayerCore {
 
     if queuePlayer.items().count > 1 {
       queuePlayer.advanceToNextItem()
+    } else if currentRepeatMode == .playlist, !currentTracks.isEmpty {
+      // Manual skip at the last track wraps, matching natural-end behavior
+      _ = skipToIndexInternal(index: 0)
     } else {
-      queuePlayer.pause()
-      self.intendedToPlay = false
-      self.isRecoveringFromStall = false
-      self.notifyPlaybackStateChange(.stopped, .end)
+      // No next track — no-op and keep playing, matching Android
+      NitroPlayerLogger.log("TrackPlayerCore", "⏭️ skipToNext at last track — nothing to advance to")
     }
 
     checkUpcomingTracksForUrls(lookahead: lookaheadCount)

package/ios/core/TrackPlayerQueueBuild.swift

@@ -85,6 +85,7 @@ extension TrackPlayerCore {
     // Clear old preloaded assets when loading new queue
     for asset in preloadedAssets.values { asset.cancelLoading() }
     preloadedAssets.removeAll()
+    preloadGeneration += 1
 
     guard let existingPlayer = self.player else {
       NitroPlayerLogger.log("TrackPlayerCore", "❌ No player available")
@@ -262,7 +263,7 @@ extension TrackPlayerCore {
 
     self.preloadUpcomingTracks(from: index + 1)
 
-    if wasPlaying { player.play() }
+    if wasPlaying { player.rate = Float(currentPlaybackSpeed) }
     return true
   }
 
@@ -569,6 +570,7 @@ extension TrackPlayerCore {
     // Swift Array/Dictionary are not safe for concurrent access.
     let queuedTrackIds = Set(player?.items().compactMap { $0.trackId } ?? [])
     let alreadyPreloaded = Set(preloadedAssets.keys)
+    let generation = preloadGeneration
     let endIndex = min(startIndex + Constants.gaplessPreloadCount, currentTracks.count)
     guard startIndex >= 0, startIndex < endIndex else { return }
     let candidates = Array(currentTracks[startIndex..<endIndex])
@@ -607,7 +609,17 @@ extension TrackPlayerCore {
 
           if allKeysLoaded {
             self?.playerQueue.async {
-              self?.preloadedAssets[track.id] = asset
+              guard let self else { return }
+              // Stale completion: the queue was torn down (or this track left it)
+              // while the asset was still loading — publishing would hand a dead
+              // or wrong-URL asset to createGaplessPlayerItem
+              guard self.preloadGeneration == generation,
+                self.currentTracks.contains(where: { $0.id == track.id })
+              else {
+                asset.cancelLoading()
+                return
+              }
+              self.preloadedAssets[track.id] = asset
               NitroPlayerLogger.log("TrackPlayerCore", "🎯 Preloaded asset for upcoming track: \(track.title)")
             }
           }

package/ios/core/TrackPlayerTempQueue.swift

@@ -55,6 +55,7 @@ extension TrackPlayerCore {
       self.currentTracks = playlist.tracks
       for asset in self.preloadedAssets.values { asset.cancelLoading() }
       self.preloadedAssets.removeAll()
+      self.preloadGeneration += 1
       _ = self.rebuildQueueFromPlaylistIndex(index: targetIndex)
     }
     self.emitStateChange()

package/ios/core/TrackPlayerUrlLoader.swift

@@ -79,7 +79,9 @@ extension TrackPlayerCore {
     let affectedPlaylists = self.playlistManager.updateTracks(tracks: safeTracks)
 
     // Replace the current AVPlayerItem when its URL just resolved (local only — cast reloads below instead).
-    if !self.isCasting, let update = currentTrack, currentTrackIsEmpty, !update.url.isEmpty {
+    // Look up the FRESH track — the pre-update snapshot's URL is empty by definition here.
+    if !self.isCasting, currentTrackIsEmpty,
+      let update = safeTracks.first(where: { $0.id == currentTrackId }), !update.url.isEmpty {
       NitroPlayerLogger.log("TrackPlayerCore",
         "🔄 Replacing current AVPlayerItem for track with resolved URL: \(update.id)")
       if let newItem = self.createGaplessPlayerItem(for: update, isPreload: false) {
@@ -131,14 +133,20 @@ extension TrackPlayerCore {
           "🔄 No current item — full queue rebuild from currentTrackIndex \(self.currentTrackIndex)")
         self.removeAllItemsCancellingLoads(player)
         var lastItem: AVPlayerItem? = nil
-        for (offset, track) in self.currentTracks[max(0, self.currentTrackIndex)...].enumerated() {
+        // Window like every other rebuild path — materializing the whole remaining
+        // playlist builds thousands of AVPlayerItems on playerQueue at once.
+        let windowed = self.currentTracks[max(0, self.currentTrackIndex)...]
+          .prefix(1 + Constants.queueWindowSize)
+        for (offset, track) in windowed.enumerated() {
           let isPreload = offset < Constants.gaplessPreloadCount
           if let newItem = self.createGaplessPlayerItem(for: track, isPreload: isPreload) {
             player.insert(newItem, after: lastItem)
             lastItem = newItem
           }
         }
-        player.play()
+        if self.intendedToPlay {
+          player.rate = Float(self.currentPlaybackSpeed)
+        }
         self.preloadUpcomingTracks(from: self.currentTrackIndex + 1)
       } else {
         // A current AVPlayerItem already exists — preserve it and only rebuild upcoming items.

package/ios/download/DownloadDatabase.swift

@@ -150,6 +150,13 @@ final class DownloadDatabase {
 
   func getDownloadedTrack(trackId: String) -> DownloadedTrack? {
     return queue.sync {
+      _getDownloadedTrackUnsafe(trackId: trackId)
+    }
+  }
+
+  /// Must be called from within `queue` — a nested `queue.sync` here would
+  /// deadlock against pending barrier writers on this concurrent queue.
+  private func _getDownloadedTrackUnsafe(trackId: String) -> DownloadedTrack? {
       NitroPlayerLogger.log("DownloadDatabase", "🔍 DownloadDatabase.getDownloadedTrack() for trackId: \(trackId)")
       NitroPlayerLogger.log("DownloadDatabase", "   Total records in memory: \(downloadedTracks.count)")
       NitroPlayerLogger.log("DownloadDatabase", "   Available trackIds: \(Array(downloadedTracks.keys))")
@@ -175,7 +182,6 @@ final class DownloadDatabase {
 
       NitroPlayerLogger.log("DownloadDatabase", "   ✅ File exists, returning track")
       return recordToDownloadedTrack(record)
-    }
   }
 
   func getAllDownloadedTracks() -> [DownloadedTrack] {
@@ -214,7 +220,13 @@ final class DownloadDatabase {
   }
 
   func getDownloadedPlaylist(playlistId: String) -> DownloadedPlaylist? {
-    return queue.sync { () -> DownloadedPlaylist? in
+    return queue.sync {
+      _getDownloadedPlaylistUnsafe(playlistId: playlistId)
+    }
+  }
+
+  /// Must be called from within `queue` — see `_getDownloadedTrackUnsafe`.
+  private func _getDownloadedPlaylistUnsafe(playlistId: String) -> DownloadedPlaylist? {
       guard let trackIds = playlistTracks[playlistId], !trackIds.isEmpty else { return nil }
       guard let playlistModel = PlaylistManager.shared.getPlaylist(playlistId: playlistId) else {
         return nil
@@ -224,7 +236,7 @@ final class DownloadDatabase {
       var totalSize: Double = 0
 
       for trackId in trackIds {
-        if let track = getDownloadedTrack(trackId: trackId) {
+        if let track = _getDownloadedTrackUnsafe(trackId: trackId) {
           downloadedTracks.append(track)
           totalSize += track.fileSize
         }
@@ -243,7 +255,6 @@ final class DownloadDatabase {
           ?? Date().timeIntervalSince1970,
         isComplete: isComplete
       )
-    }
   }
 
   func getAllDownloadedPlaylists() -> [DownloadedPlaylist] {
@@ -251,7 +262,7 @@ final class DownloadDatabase {
       var playlists: [DownloadedPlaylist] = []
 
       for playlistId in playlistTracks.keys {
-        if let playlist = getDownloadedPlaylist(playlistId: playlistId) {
+        if let playlist = _getDownloadedPlaylistUnsafe(playlistId: playlistId) {
           playlists.append(playlist)
         }
       }

package/ios/download/DownloadFileManager.swift

@@ -24,33 +24,30 @@ final class DownloadFileManager {
 
   private let fileManager = FileManager.default
 
-  private lazy var privateDownloadsDirectory: URL = {
+  // `let` computed once in the singleton's init — Swift `lazy var` initialization
+  // is not atomic and these were first-touched from multiple queues.
+  private let privateDownloadsDirectory: URL
+  private let publicDownloadsDirectory: URL
+
+  // MARK: - Initialization
+
+  private init() {
     let documentsPath = fileManager.urls(for: .documentDirectory, in: .userDomainMask).first!
-    let downloadsPath = documentsPath.appendingPathComponent(Self.privateDownloadsFolderName)
 
+    let downloadsPath = documentsPath.appendingPathComponent(Self.privateDownloadsFolderName)
     if !fileManager.fileExists(atPath: downloadsPath.path) {
       try? fileManager.createDirectory(at: downloadsPath, withIntermediateDirectories: true)
     }
+    privateDownloadsDirectory = downloadsPath
 
-    return downloadsPath
-  }()
-
-  private lazy var publicDownloadsDirectory: URL = {
     // On iOS, we can't write to a truly public folder, but we can use the shared container
     // or the Documents folder which is accessible via Files app
-    let documentsPath = fileManager.urls(for: .documentDirectory, in: .userDomainMask).first!
     let publicPath = documentsPath.appendingPathComponent(Self.publicDownloadsFolderName)
-
     if !fileManager.fileExists(atPath: publicPath.path) {
       try? fileManager.createDirectory(at: publicPath, withIntermediateDirectories: true)
     }
-
-    return publicPath
-  }()
-
-  // MARK: - Initialization
-
-  private init() {}
+    publicDownloadsDirectory = publicPath
+  }
 
   // MARK: - File Operations
 

package/ios/download/DownloadManagerCore.swift

@@ -42,7 +42,7 @@ final class DownloadManagerCore: NSObject {
       withIdentifier: Self.backgroundSessionIdentifier)
     configuration.isDiscretionary = false
     configuration.sessionSendsLaunchEvents = true
-    configuration.allowsCellularAccess = !config.wifiOnlyDownloads!
+    configuration.allowsCellularAccess = !(config.wifiOnlyDownloads ?? false)
     return URLSession(configuration: configuration, delegate: self, delegateQueue: nil)
   }()
 
@@ -66,9 +66,11 @@ final class DownloadManagerCore: NSObject {
 
   // MARK: - Callbacks
 
-  private var progressCallbacks: [(DownloadProgress) -> Void] = []
-  private var stateChangeCallbacks: [(String, String, DownloadState, DownloadError?) -> Void] = []
-  private var completeCallbacks: [(DownloadedTrack) -> Void] = []
+  // Keyed so HybridDownloadManager.deinit can remove its registrations instead
+  // of leaking closures into dead JS runtimes across reloads
+  private var progressCallbacks: [(UUID, (DownloadProgress) -> Void)] = []
+  private var stateChangeCallbacks: [(UUID, (String, String, DownloadState, DownloadError?) -> Void)] = []
+  private var completeCallbacks: [(UUID, (DownloadedTrack) -> Void)] = []
 
   // MARK: - Thread Safety
 
@@ -180,8 +182,10 @@ final class DownloadManagerCore: NSObject {
       guard let task = self.activeTasks[downloadId] else { return }
 
       task.cancel(byProducingResumeData: { resumeData in
-        // Store resume data for later
-        self.taskMetadata[downloadId]?.resumeData = resumeData
+        // Runs on the URLSession delegate queue — hop back for the shared dict
+        self.queue.async(flags: .barrier) {
+          self.taskMetadata[downloadId]?.resumeData = resumeData
+        }
       })
 
       self.taskMetadata[downloadId]?.state = .paused
@@ -264,7 +268,9 @@ final class DownloadManagerCore: NSObject {
   private func _pauseDownloadUnsafe(downloadId: String) {
     guard let task = self.activeTasks[downloadId] else { return }
     task.cancel(byProducingResumeData: { resumeData in
-      self.taskMetadata[downloadId]?.resumeData = resumeData
+      self.queue.async(flags: .barrier) {
+        self.taskMetadata[downloadId]?.resumeData = resumeData
+      }
     })
     self.taskMetadata[downloadId]?.state = .paused
     if let trackId = self.taskMetadata[downloadId]?.trackId {
@@ -505,23 +511,50 @@ final class DownloadManagerCore: NSObject {
 
   // MARK: - Callbacks
 
-  func addProgressCallback(_ callback: @escaping (DownloadProgress) -> Void) {
+  @discardableResult
+  func addProgressCallback(_ callback: @escaping (DownloadProgress) -> Void) -> UUID {
+    let id = UUID()
+    queue.async(flags: .barrier) {
+      self.progressCallbacks.append((id, callback))
+    }
+    return id
+  }
+
+  func removeProgressCallback(id: UUID) {
     queue.async(flags: .barrier) {
-      self.progressCallbacks.append(callback)
+      self.progressCallbacks.removeAll { $0.0 == id }
     }
   }
 
+  @discardableResult
   func addStateChangeCallback(
     _ callback: @escaping (String, String, DownloadState, DownloadError?) -> Void
-  ) {
+  ) -> UUID {
+    let id = UUID()
+    queue.async(flags: .barrier) {
+      self.stateChangeCallbacks.append((id, callback))
+    }
+    return id
+  }
+
+  func removeStateChangeCallback(id: UUID) {
+    queue.async(flags: .barrier) {
+      self.stateChangeCallbacks.removeAll { $0.0 == id }
+    }
+  }
+
+  @discardableResult
+  func addCompleteCallback(_ callback: @escaping (DownloadedTrack) -> Void) -> UUID {
+    let id = UUID()
     queue.async(flags: .barrier) {
-      self.stateChangeCallbacks.append(callback)
+      self.completeCallbacks.append((id, callback))
     }
+    return id
   }
 
-  func addCompleteCallback(_ callback: @escaping (DownloadedTrack) -> Void) {
+  func removeCompleteCallback(id: UUID) {
     queue.async(flags: .barrier) {
-      self.completeCallbacks.append(callback)
+      self.completeCallbacks.removeAll { $0.0 == id }
     }
   }
 
@@ -726,8 +759,9 @@ final class DownloadManagerCore: NSObject {
   }
 
   private func notifyProgress(_ progress: DownloadProgress) {
+    let callbacks = self.progressCallbacks
     DispatchQueue.main.async {
-      for callback in self.progressCallbacks {
+      for (_, callback) in callbacks {
         callback(progress)
       }
     }
@@ -736,16 +770,18 @@ final class DownloadManagerCore: NSObject {
   private func notifyStateChange(
     downloadId: String, trackId: String, state: DownloadState, error: DownloadError?
   ) {
+    let callbacks = self.stateChangeCallbacks
     DispatchQueue.main.async {
-      for callback in self.stateChangeCallbacks {
+      for (_, callback) in callbacks {
         callback(downloadId, trackId, state, error)
       }
     }
   }
 
   private func notifyComplete(_ downloadedTrack: DownloadedTrack) {
+    let callbacks = self.completeCallbacks
     DispatchQueue.main.async {
-      for callback in self.completeCallbacks {
+      for (_, callback) in callbacks {
         callback(downloadedTrack)
       }
     }
@@ -907,6 +943,14 @@ extension DownloadManagerCore: URLSessionDownloadDelegate {
       self.taskMetadata[downloadId]?.totalBytes =
         totalBytesExpectedToWrite > 0 ? Double(totalBytesExpectedToWrite) : nil
 
+      // ~4 Hz per download — didWriteData fires many times per second per task
+      // and every emission is a main-queue hop plus a JS event
+      let now = Date().timeIntervalSince1970
+      if let last = self.taskMetadata[downloadId]?.lastProgressEmitAt, now - last < 0.25 {
+        return
+      }
+      self.taskMetadata[downloadId]?.lastProgressEmitAt = now
+
       let progress = DownloadProgress(
         trackId: trackId,
         downloadId: downloadId,
@@ -1010,6 +1054,7 @@ private struct DownloadTaskMetadata {
   var bytesDownloaded: Double = 0
   var totalBytes: Double?
   var error: DownloadError?
+  var lastProgressEmitAt: TimeInterval = 0
 
   func toDownloadTask() -> DownloadTask {
     let progress = DownloadProgress(