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

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(

package/ios/equalizer/EqualizerCore.swift

@@ -28,6 +28,27 @@ class EqualizerCore {
 
   // Current gains storage - internal so TapContext can access
   private(set) var currentGains: [Double] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+
+  // Guards currentGains/gainsDirty between the JS thread (slider writes) and the
+  // MTAudioProcessingTap render thread — unsynchronized Swift Array access is a
+  // CoW data race (torn coefficients, loud glitches, rare crashes)
+  private var gainsLock = os_unfair_lock_s()
+
+  func withGainsLock<T>(_ body: () -> T) -> T {
+    os_unfair_lock_lock(&gainsLock)
+    defer { os_unfair_lock_unlock(&gainsLock) }
+    return body()
+  }
+
+  /// Render-thread accessor: returns a snapshot of the gains and clears the dirty
+  /// flag atomically, or nil when nothing changed.
+  func consumeDirtyGains() -> [Double]? {
+    return withGainsLock {
+      guard gainsDirty else { return nil }
+      gainsDirty = false
+      return currentGains
+    }
+  }
   private var cachedBands: [EqualizerBand]?
   private var cachedCustomPresets: [EqualizerPreset]?
 
@@ -209,9 +230,11 @@ class EqualizerCore {
     guard bandIndex >= 0 && bandIndex < 10 else { return false }
 
     let clampedGain = max(-12.0, min(12.0, gainDb))
-    currentGains[bandIndex] = clampedGain
+    withGainsLock {
+      currentGains[bandIndex] = clampedGain
+      gainsDirty = true
+    }
     cachedBands = nil
-    gainsDirty = true
 
     currentPresetName = nil
     notifyBandChange(getBands())
@@ -226,11 +249,13 @@ class EqualizerCore {
   func setAllBandGains(_ gains: [Double]) -> Bool {
     guard gains.count == 10 else { return false }
 
-    for i in 0..<10 {
-      currentGains[i] = max(-12.0, min(12.0, gains[i]))
+    withGainsLock {
+      for i in 0..<10 {
+        currentGains[i] = max(-12.0, min(12.0, gains[i]))
+      }
+      gainsDirty = true
     }
     cachedBands = nil
-    gainsDirty = true
 
     notifyBandChange(getBands())
     saveBandGains(currentGains)
@@ -406,7 +431,10 @@ class EqualizerCore {
       let gains = try? JSONDecoder().decode([Double].self, from: data),
       gains.count == 10
     {
-      currentGains = gains
+      withGainsLock {
+        currentGains = gains
+        gainsDirty = true
+      }
     }
     // else: migration from 5-band or fresh install — start at flat (currentGains already zeroed)
 
@@ -478,9 +506,10 @@ private class TapContext {
   }
 
   func updateCoefficients() {
-    guard let eqCore = eqCore else { return }
+    // Snapshot + dirty-clear happen atomically under the gains lock; nil means
+    // another consumer already took this change
+    guard let gains = eqCore?.consumeDirtyGains() else { return }
     let frequencies: [Float] = [31, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000]
-    let gains = eqCore.currentGains
 
     for i in 0..<10 {
       filterCoeffs[i] = calculatePeakingEQCoefficients(
@@ -490,7 +519,6 @@ private class TapContext {
         sampleRate: Double(sampleRate)
       )
     }
-    eqCore.gainsDirty = false
   }
 
   /// Calculate biquad coefficients for a peaking EQ filter