react-native-queue-player 1.2.0 → 2.0.1

package/ios/AudioTapProvider.swift

@@ -26,7 +26,8 @@ import Foundation
 /// Threading:
 ///  - Consumer registration runs on the JS bridge thread at Hybrid
 ///    construction.
-///  - `audioMix(for:)` runs on main (engine call site).
+///  - `audioMix(for:)` runs on the mix dispatch target — main by
+///    default, `TrackPlayer`'s `playerQueue` once it wires in.
 ///  - `deliverAudioFrame` runs on the audio render thread; the
 ///    per-frame fan-out walks an immutable consumer snapshot under
 ///    [consumersLock] and is allocation-free.
@@ -34,8 +35,8 @@ final class AudioTapProvider: AudioMixProvider {
 
   /// Module-internal singleton. Both `Equalizer` and `Visualizer`
   /// register against this instance at Hybrid construction time. The
-  /// constructor seam (`AudioTapProvider()`) stays available for
-  /// tests that need an isolated provider.
+  /// constructor (`AudioTapProvider()`) stays available for tests
+  /// that need an isolated provider.
   static let shared = AudioTapProvider()
 
   /// Consumer of the post-EQ audio pipeline. Equalizer + Visualizer
@@ -45,15 +46,15 @@ final class AudioTapProvider: AudioMixProvider {
   final class Consumer {
     /// Returns true when this consumer needs the tap installed on
     /// the active player items right now (EQ enabled / visualizer
-    /// has subscribers). Polled from `audioMix(for:)` on the main
-    /// thread.
+    /// has subscribers). Polled from `audioMix(for:)` on the mix
+    /// dispatch target.
     let wantsTap: () -> Bool
     /// Render-thread callback fired once per render batch with the
     /// post-EQ mono mixdown. Must not allocate, lock, or
     /// synchronously dispatch.
     let onAudioFrame: (UnsafePointer<Float>, Int, Double) -> Void
-    /// Fired on the main thread from `audioMix(for:)` whenever a new
-    /// item becomes the candidate for tap install. Fires for EVERY
+    /// Fired on the mix dispatch target from `audioMix(for:)` whenever
+    /// a new item becomes the candidate for tap install. Fires for EVERY
     /// candidate item the engine queues, including items where the
     /// tap will not install (HLS, format-detection failure, no
     /// consumer wantsTap). Consumers that need post-install
@@ -76,8 +77,9 @@ final class AudioTapProvider: AudioMixProvider {
   /// Lock protecting `currentGains` + `enabled` + `consumers`.
   /// Acquired on the audio render thread (gain snapshot), the JS
   /// bridge (consumer registration + state mutation), and the
-  /// playback-engine main path (`audioMix(for:)`); short critical
-  /// section keeps render-thread cost negligible.
+  /// playback engine's mix path (`audioMix(for:)` on the mix dispatch
+  /// target); short critical section keeps render-thread cost
+  /// negligible.
   private let stateLock = NSLock()
 
   private var currentGains: [Double]
@@ -100,6 +102,17 @@ final class AudioTapProvider: AudioMixProvider {
   /// destroy + reconfigure).
   private weak var playbackEngine: PlaybackEngine?
 
+  /// Dispatch target for the engine-facing mix work in
+  /// `wireToPlaybackEngine`, `detachFromEngine` and
+  /// `refreshActiveItemMixes`. Defaults to the
+  /// main queue; `setMixDispatchTarget` repoints it at whichever
+  /// queue serialises player access and `resetMixDispatchTarget`
+  /// puts it back.
+  private var mixQueue: DispatchQueue = .main
+  /// Reports whether the calling thread is already executing on
+  /// `mixQueue`, so an in-queue caller runs inline.
+  private var mixQueueIsCurrent: () -> Bool = { Thread.isMainThread }
+
   /// Live `ReplayGain` state for every queued `AVPlayerItem`. Each
   /// `audioMix(for:)` allocates a fresh `ItemRGState`, attaches it
   /// to the item via objc associated-object so the state's lifetime
@@ -120,63 +133,97 @@ final class AudioTapProvider: AudioMixProvider {
   /// `replayGainDataForItem == nil` (the extract is still in flight)
   /// and the cached format never refreshes when RG values eventually
   /// land. Receives the AVPlayerItem the extract completed for.
-  var onItemReplayGainDataPopulated: ((AVPlayerItem) -> Void)?
-
-  /// Internal RG Consumer registered at construction. Holds the tap
-  /// installed unconditionally so a `setReplayGainMode` off → on
-  /// transition affects the currently-playing item without needing to
-  /// re-install `AVPlayerItem.audioMix`. AVPlayer silently drops a
-  /// fresh `audioMix` assignment on items that have already begun
-  /// rendering (see comment on `GaplessEngine.refreshAllItemMixes`),
-  /// so gating the tap on `replayGainMode != .off` meant mode-flip
-  /// during playback never actually applied gain to the active track.
-  ///
-  /// The cost of an always-installed tap when RG is off is negligible:
-  /// `ReplayGainProcessor.process` early-returns on a unity-gain
-  /// branch test at the head of each callback. EQ + Visualizer
-  /// consumers still gate their own contribution to the composed tap
-  /// closure independently; this Consumer only ensures the tap
-  /// scaffolding is in place so the RG processor's gain (which `recomputeWithLock`
-  /// can update at any time, thread-safely) is read by the audio
-  /// render thread on every buffer batch.
-  private var replayGainTapConsumer: Consumer?
+  var onItemReplayGainDataPopulated: ((AVPlayerItem) -> Void)? {
+    get { stateLock.withLock { replayGainPopulatedCallback } }
+    set { stateLock.withLock { replayGainPopulatedCallback = newValue } }
+  }
+  /// Written by `TrackPlayer` on its player queue; read under `stateLock`
+  /// where the extract completes.
+  private var replayGainPopulatedCallback: ((AVPlayerItem) -> Void)?
 
   init(initialGains: [Double] = Array(repeating: 0, count: EQProcessor.bandCount)) {
     self.currentGains = initialGains
-    let consumer = Consumer(
-      wantsTap: { true },
-      onAudioFrame: { _, _, _ in },
-      onActiveAssetChange: { _ in }
-    )
-    self.replayGainTapConsumer = consumer
-    register(consumer)
+    // A consumer that always wants the tap, registered for the provider's
+    // life, so the tap is installed regardless of EQ / visualizer state and
+    // a `setReplayGainMode` off → on transition affects the currently-playing
+    // item without re-installing `AVPlayerItem.audioMix` — AVPlayer silently
+    // drops a fresh `audioMix` on an item that has begun rendering (see
+    // `GaplessEngine.refreshAllItemMixes`). The cost with RG off is
+    // negligible: `ReplayGainProcessor.process` early-returns on a unity-gain
+    // test at the head of each callback, leaving the pass-through EQ and the
+    // mono mixdown. EQ and Visualizer consumers gate their own contribution
+    // independently; this one only keeps the tap in place so the RG gain
+    // `recomputeWithLock` updates is read by the audio render thread on
+    // every buffer batch.
+    register(
+      Consumer(
+        wantsTap: { true },
+        onAudioFrame: { _, _, _ in },
+        onActiveAssetChange: { _ in }
+      ))
   }
 
   // MARK: - Engine wiring
 
+  /// Route the provider's engine calls through [queue]. [queue] must
+  /// serialise all player access, and [isCurrent] must report whether
+  /// the calling thread is already on it — a caller that is runs the
+  /// work inline instead of deferring it behind an async hop. Defaults
+  /// to the main queue.
+  func setMixDispatchTarget(_ queue: DispatchQueue, isCurrent: @escaping () -> Bool) {
+    stateLock.lock()
+    mixQueue = queue
+    mixQueueIsCurrent = isCurrent
+    stateLock.unlock()
+  }
+
+  /// Put the engine-facing mix work back on the main queue. The provider
+  /// outlives any one player, so a teardown that leaves a player-owned queue
+  /// installed here would dispatch the next player's mix work onto a dead one.
+  func resetMixDispatchTarget() {
+    stateLock.lock()
+    mixQueue = .main
+    mixQueueIsCurrent = { Thread.isMainThread }
+    stateLock.unlock()
+  }
+
   /// Wire the provider to [engine] so per-item `audioMix(for:)`
   /// queries route through this provider, and so consumers can ask
-  /// for an engine-wide refresh when their `wantsTap` flips.
+  /// for an engine-wide refresh when their `wantsTap` flips. Hops to
+  /// the mix dispatch target if needed — AVFoundation expects
+  /// `setAudioMixProvider` on the queue that serialises player access.
   func wireToPlaybackEngine(_ engine: PlaybackEngine) {
     stateLock.lock()
     self.playbackEngine = engine
+    let queue = mixQueue
+    let isCurrent = mixQueueIsCurrent
     stateLock.unlock()
-    engine.setAudioMixProvider(self)
+    // `setAudioMixProvider` refreshes every item's mix, which walks the
+    // player, so it takes the same hop `detachFromEngine` does.
+    if isCurrent() {
+      engine.setAudioMixProvider(self)
+    } else {
+      queue.async {
+        engine.setAudioMixProvider(self)
+      }
+    }
   }
 
   /// Detach the provider from any previously-wired engine. Hops to
-  /// main if needed — AVFoundation expects `setAudioMixProvider` on
-  /// the main thread.
+  /// the mix dispatch target if needed — AVFoundation expects
+  /// `setAudioMixProvider` on the queue that serialises player access.
   func detachFromEngine() {
     stateLock.lock()
     let engine = self.playbackEngine
     self.playbackEngine = nil
+    let queue = mixQueue
+    let isCurrent = mixQueueIsCurrent
     stateLock.unlock()
     guard let engine = engine else { return }
-    if Thread.isMainThread {
+    if isCurrent() {
       engine.setAudioMixProvider(nil)
     } else {
-      DispatchQueue.main.async {
+      queue.async {
         engine.setAudioMixProvider(nil)
       }
     }
@@ -185,17 +232,20 @@ final class AudioTapProvider: AudioMixProvider {
   /// Ask the active engine to re-evaluate every item's audioMix. A
   /// consumer calls this when its `wantsTap` would change (EQ enable
   /// toggle, first visualizer subscriber arriving, last subscriber
-  /// dropping). Hops to main; AVFoundation expects `AVPlayer.items()`
-  /// + `AVPlayerItem.audioMix` on the main thread.
+  /// dropping). Hops to the mix dispatch target; AVFoundation expects
+  /// `AVPlayer.items()` + `AVPlayerItem.audioMix` on the queue that
+  /// serialises player access.
   func refreshActiveItemMixes() {
     stateLock.lock()
     let engine = self.playbackEngine
+    let queue = mixQueue
+    let isCurrent = mixQueueIsCurrent
     stateLock.unlock()
     guard let engine = engine else { return }
-    if Thread.isMainThread {
+    if isCurrent() {
       engine.refreshAllItemMixes()
     } else {
-      DispatchQueue.main.async {
+      queue.async {
         engine.refreshAllItemMixes()
       }
     }
@@ -203,10 +253,25 @@ final class AudioTapProvider: AudioMixProvider {
 
   // MARK: - Consumer registration
 
-  /// Register [consumer] for post-EQ audio frames + active-asset
+  /// Broadcast which asset is actually active, without touching audio mixes.
+  ///
+  /// `audioMix(for:)` announces its argument, which is right when the engine
+  /// is attaching the item about to play and wrong when something walks the
+  /// queue: the last item walked would be left as the active asset. Callers
+  /// that refresh several items re-assert the playing one through here.
+  func noteActiveAsset(_ asset: AVAsset?) {
+    stateLock.lock()
+    let consumerSnapshot = consumers
+    stateLock.unlock()
+    for consumer in consumerSnapshot {
+      consumer.onActiveAssetChange(asset)
+    }
+  }
+
+  /// Register [consumer] for post-EQ audio frames and active-asset
   /// notifications. The provider holds the consumer strongly until
-  /// `unregister` runs. Order of registration does not matter — both
-  /// callbacks fire under the same snapshot iteration.
+  /// `unregister` runs. Order of registration does not matter — both callbacks
+  /// fire under the same snapshot iteration.
   func register(_ consumer: Consumer) {
     stateLock.lock()
     consumers.append(consumer)
@@ -225,7 +290,7 @@ final class AudioTapProvider: AudioMixProvider {
   /// true. Snapshots the consumer list under the lock and evaluates
   /// each predicate outside it so a misbehaving predicate cannot
   /// block render-thread fan-out.
-  private func anyConsumerWantsTap() -> Bool {
+  func anyConsumerWantsTap() -> Bool {
     stateLock.lock()
     let snapshot = consumers
     stateLock.unlock()
@@ -237,8 +302,8 @@ final class AudioTapProvider: AudioMixProvider {
 
   // MARK: - EQ master gain state
 
-  /// Lock-protected snapshot of the enabled flag. Called from main
-  /// on every `audioMix(for:)` invocation.
+  /// Lock-protected snapshot of the enabled flag. Called on the mix
+  /// dispatch target on every `audioMix(for:)` invocation.
   func isEnabledSnapshot() -> Bool {
     stateLock.lock()
     let value = enabled
@@ -359,14 +424,21 @@ final class AudioTapProvider: AudioMixProvider {
   }
 
   /// Pure gain math per NOTES.md §25. Selects the `(gainDb, peak)`
-  /// pair from [data] under [mode] (strict, no fallback), then:
+  /// pair from [data] under [mode] (strict, no fallback), then caps
+  /// the result for clip safety:
   ///
   /// ```
-  /// linearGain = pow(10, gainDb / 20)
-  /// if peak != nil and peak > 0.001 and peak != 1.0:
-  ///   linearGain = min(linearGain, 1.0 / peak)
+  /// cap = usable peak ? 1.0 / peak : 1.0
+  /// linearGain = min(pow(10, gainDb / 20), cap)
   /// ```
   ///
+  /// A peak is usable inside the `0.001 ... 2.0` band that
+  /// `ReplayGainExtractor.acceptPeak` holds — full scale (`1.0`) and
+  /// true peaks above it included. With no usable peak the cap sits at
+  /// unity, so a boost is suppressed rather than applied unprotected: a
+  /// peak cannot be derived from a gain. Attenuation is untouched
+  /// either way, since a negative gain can never clip.
+  ///
   /// Returns 1.0 (unity) whenever the selected mode's gain tag is
   /// absent — RG is inactive for that track.
   ///
@@ -377,11 +449,12 @@ final class AudioTapProvider: AudioMixProvider {
   static func computeLinearGain(data: ReplayGainData?, mode: ReplayGainSelectorMode) -> Float {
     let (gainDb, peak) = data?.selectGain(mode: mode) ?? (nil, nil)
     guard let gainDb = gainDb else { return 1.0 }
-    var raw = Float(pow(10.0, gainDb / 20.0))
-    if let peak = peak, peak > 0.001, peak != 1.0 {
-      raw = min(raw, Float(1.0 / peak))
+    let raw = Float(pow(10.0, gainDb / 20.0))
+    var cap: Float = 1.0
+    if let peak = peak, peak >= 0.001, peak <= 2.0 {
+      cap = Float(1.0 / peak)
     }
-    return raw
+    return min(raw, cap)
   }
 
   /// Map the Nitrogen-generated `ReplayGainMode` to the pure-Swift
@@ -417,31 +490,92 @@ final class AudioTapProvider: AudioMixProvider {
     item.replayGainState?.snapshotData()
   }
 
-  /// Idempotently attach an `ItemRGState` to the item and kick off
-  /// the one-shot `MetadataReader` extract Task. Called from
-  /// `audioMix(for:)` BEFORE the tap-mix bypass conditions so RG
-  /// values populate independently of AVFoundation's track-loading
-  /// lifecycle. Re-invocation on the same item (e.g. when the
-  /// engine re-resolves mixes after tracks load) is a no-op.
-  func ensureReplayGainExtraction(for item: AVPlayerItem) {
-    guard item.replayGainState == nil else { return }
-    let rgState = ItemRGState(processor: ReplayGainProcessor())
+  /// Attach per-item ReplayGain state and arm the read of the item's own
+  /// metadata. Called from `audioMix(for:)` BEFORE the tap-mix bypass
+  /// conditions so RG values populate independently of AVFoundation's
+  /// track-loading lifecycle. Re-invocation on the same item is a no-op.
+  ///
+  /// Issues no network read of its own. `AssetReplayGainReader` reads the
+  /// metadata AVPlayer has already prepared, which costs zero requests and
+  /// zero bytes — so the read is bounded by AVPlayer's own preroll horizon
+  /// (measured: exactly one prepared item out of eight enqueued) rather than
+  /// by how many items the engine has queued.
+  @discardableResult
+  func attachReplayGainState(to item: AVPlayerItem) -> ItemRGState {
+    if let existing = item.replayGainState { return existing }
+    let rgState = ItemRGState(processor: ReplayGainProcessor(), item: item)
     item.replayGainState = rgState
     stateLock.lock()
     activeItemStates.add(rgState)
     stateLock.unlock()
-    guard let urlAsset = item.asset as? AVURLAsset else { return }
-    let url = urlAsset.url
-    Task { [weak rgState, weak item] in
-      let data = await ReplayGainExtractor.extract(from: url)
-      guard let rgState = rgState else { return }
-      rgState.setData(data)
-      self.recomputeWithLock(state: rgState)
-      if let item = item {
-        await MainActor.run {
-          self.onItemReplayGainDataPopulated?(item)
-        }
-      }
+
+    // `.new` only, never `.initial` (NOTES.md §18), paired with the explicit
+    // synchronous bootstrap below.
+    rgState.statusObservation = item.observe(\.status, options: [.new]) {
+      [weak self, weak rgState] observed, _ in
+      guard let self = self, let rgState = rgState else { return }
+      self.readReplayGainWhenPrepared(state: rgState, item: observed)
+    }
+    // Explicit synchronous bootstrap, because an observer waiting for a
+    // transition that has already happened never fires. `audioMix(for:)`
+    // reaches this method from `refreshActiveItemMixes()` as well as from
+    // queue construction — on every ReplayGain mode crossing of the off /
+    // non-off boundary, and on crossfade cross-attach — and those calls can
+    // carry an item that is already `.readyToPlay`. Whether a given release's
+    // engine wiring produces such a first attach is not something this method
+    // can know, which is exactly why the bootstrap is unconditional.
+    readReplayGainWhenPrepared(state: rgState, item: item)
+    return rgState
+  }
+
+  /// Resolve [item]'s ReplayGain once it is prepared, and deliver it into
+  /// [state]. No-op until `.readyToPlay`, and at most once per state — a
+  /// prepared item's metadata does not change under it, and both the observer
+  /// and the bootstrap can reach a ready item.
+  ///
+  /// The consumer's claim is stamped on the item at queue-build time, and a
+  /// claimed item is never read: the merge discards detection in full, so
+  /// reading the file's tags could only produce a value to throw away. That
+  /// also means the merge happens before the first value is delivered rather
+  /// than after — a listener never sees a detected value corrected to a
+  /// supplied one.
+  ///
+  /// Delivery is unconditional on the result: a resolve that found nothing
+  /// still lands, so the now-playing snapshot refreshes and reports the honest
+  /// absence rather than staying at whatever the pre-read snapshot said.
+  private func readReplayGainWhenPrepared(state: ItemRGState, item: AVPlayerItem) {
+    guard item.status == .readyToPlay else { return }
+    guard state.beginReplayGainRead() else { return }
+    let supplied = item.suppliedReplayGain
+    Task { [weak self] in
+      let detected = supplied == nil ? await AssetReplayGainReader.read(item: item) : nil
+      guard let self = self else { return }
+      let data = ReplayGainData.merge(
+        suppliedClaimed: supplied != nil, supplied: supplied?.data, detected: detected
+      )
+      state.setData(data)
+      self.recomputeWithLock(state: state)
+      // Required, not optional: this is what refreshes the emitted now-playing
+      // snapshot when the read lands. Without it `onNowPlayingFormatChange`
+      // reports null ReplayGain forever, while `getNowPlayingFormat()` stays
+      // correct because it reads live — so a polling test would not notice.
+      //
+      // Hopped onto the mix dispatch target rather than fired inline: the
+      // bootstrap path runs inside `audioMix(for:)`, which the engine calls
+      // mid-`setItems` between `canInsert` and `insert`; the notification
+      // reaches JS, and a listener mutating the queue there would mutate
+      // the queue the engine is building. The callback is snapshotted here
+      // rather than re-read on the target queue so the hop captures a
+      // value, not the non-Sendable provider.
+      // Both under the lock that guards them: this runs on the cooperative
+      // pool, and `mixQueue` is rewritten by `setMixDispatchTarget` and reset
+      // by teardown. Reading it unguarded can dispatch player-state work onto
+      // a queue that is no longer the one serialising it.
+      let (notify, queue) = stateLock.withLock { (self.replayGainPopulatedCallback, self.mixQueue) }
+      // The consumer reads the active item and writes the last-emitted format,
+      // which is player state — so this lands on the queue that serialises it,
+      // not on main.
+      queue.async { notify?(item) }
     }
   }
 
@@ -468,16 +602,17 @@ final class AudioTapProvider: AudioMixProvider {
   // MARK: - AudioMixProvider
 
   /// Builds the per-`AVPlayerItem` `AVAudioMix` that carries the EQ
-  /// tap + ReplayGain pre-gain stage. Called from the engine's main-
-  /// thread queue construction path on every fresh item. The body
+  /// tap + ReplayGain pre-gain stage. Called on the mix dispatch
+  /// target from the engine's item construction path on every fresh
+  /// item. The body
   /// briefly holds `stateLock` three times — once to snapshot the
   /// consumer list for the asset-change fan-out, once inside
   /// `anyConsumerWantsTap` to read the consumer snapshot, once to
   /// register the per-item ReplayGain state. All three critical
   /// sections are constant-time (consumer count is O(2): EQ +
   /// Visualizer) and never call out to JS while the lock is held,
-  /// so the main-thread cost is sub-millisecond on a typical
-  /// consumer config.
+  /// so the cost on the calling queue is sub-millisecond on a
+  /// typical consumer config.
   func audioMix(for item: AVPlayerItem) -> AVAudioMix? {
     let asset = item.asset
     // Notify every registered consumer of the candidate asset before
@@ -490,71 +625,50 @@ final class AudioTapProvider: AudioMixProvider {
       consumer.onActiveAssetChange(asset)
     }
 
-    // Eagerly attach RG state + spawn one-shot metadata extract for
-    // this item, regardless of the tap-mix bypass conditions. RG
-    // only needs the source URL — `MetadataReader` reads the file
-    // header bytes directly and never touches AVFoundation's demux
-    // pipeline. Decoupling it from `audioMix(for:)`'s tracks-loaded /
-    // format-descriptions / ASBD gates means RG values surface
-    // within milliseconds of `setQueue`, even for fresh remote
-    // items whose AVAsset track key hasn't loaded yet.
-    ensureReplayGainExtraction(for: item)
+    // Eagerly attach RG state + arm the metadata read for this item,
+    // regardless of the tap-mix bypass conditions. The read waits on
+    // `.readyToPlay`, which is a different and later gate than this
+    // method's tracks-loaded / format-descriptions / ASBD checks, so
+    // attaching here rather than below them means a mode change or a
+    // mix refresh can never leave an item without RG state.
+    attachReplayGainState(to: item)
 
     if !anyConsumerWantsTap() { return nil }
 
     if EQTap.isHLS(asset) { return nil }
 
-    // Tracks-loaded gate: `asset.tracks(withMediaType:)` is a
-    // synchronous accessor that BLOCKS the calling thread to load
-    // tracks if the "tracks" key isn't already loaded. Engine
-    // queue-mutation paths invoke this method on the main thread
-    // for fresh items whose remote tracks haven't loaded yet — a
-    // synchronous block there freezes the JS bridge for the
-    // duration of the network fetch. Returning nil keeps the main
-    // thread free; once tracks load, the engine fires
+    // Tracks-loaded gate: `status(of:)` reports the tracks key's
+    // current load state without loading it, and the mix has no
+    // `AVAssetTrack` to key its input parameters to until that key
+    // is loaded. Engine queue-mutation paths invoke this method on
+    // the mix dispatch target for fresh items whose remote tracks
+    // haven't loaded yet; returning nil rather than waiting on the load
+    // keeps the JS bridge free. Once tracks load, the engine fires
     // `engineActiveItemFormatChanged` and the TrackPlayer-level
     // handler re-fires `refreshActiveItemMixes`, which re-evaluates
     // every queued item's mix off the now-loaded tracks key.
-    var keyError: NSError?
-    let status = asset.statusOfValue(forKey: "tracks", error: &keyError)
-    guard status == .loaded else { return nil }
-
-    guard
-      let track = asset.tracks(withMediaType: .audio).first,
-      let format = track.formatDescriptions.first as CFTypeRef?,
-      CFGetTypeID(format) == CMFormatDescriptionGetTypeID()
-    else {
-      return nil
-    }
-    let cmFormat = format as! CMFormatDescription
-    guard let asbd = readASBD(cmFormat) else { return nil }
+    guard case .loaded(let tracks) = asset.status(of: .tracks) else { return nil }
 
-    let sampleRate = asbd.mSampleRate
-    let channelCount = Int(asbd.mChannelsPerFrame)
-    if sampleRate <= 0 || channelCount <= 0 {
-      return nil
-    }
+    // An audio track is what the mix keys its input parameters to. The
+    // cascade's sample rate and channel count come from the tap's prepare
+    // callback instead of the track's advertised format: the tap reports the
+    // format it will actually deliver, which is what the DSP has to match,
+    // and asking the track means reading a key nothing in the playback
+    // lifecycle ever loads.
+    guard tracks.contains(where: { $0.mediaType == .audio }) else { return nil }
 
     let processor = EQProcessor(provider: self)
-    processor.setSampleRate(sampleRate)
-    processor.setChannelCount(channelCount)
     // The processor's first tap callback compares its initial
     // version (0) against the provider's current version and pulls
     // the gains under the lock — avoids a double-recompute on item
     // construction.
 
-    // `ensureReplayGainExtraction(for:)` already attached the
-    // per-item rgState; reuse it here so the tap composition
-    // shares the same processor whose gain `recomputeWithLock`
-    // updates as the mode flips.
-    let rgState = item.replayGainState ?? {
-      let s = ItemRGState(processor: ReplayGainProcessor())
-      item.replayGainState = s
-      stateLock.lock()
-      activeItemStates.add(s)
-      stateLock.unlock()
-      return s
-    }()
+    // The audioMix entry point already attached the per-item rgState; reuse it
+    // so the tap composition shares the same processor whose gain
+    // `recomputeWithLock` updates as the mode flips.
+    // Both creation sites route through one function so they cannot diverge:
+    // this one is shadowed today only because the other always runs first.
+    let rgState = attachReplayGainState(to: item)
 
     let eqClosure = processor.tapProcessClosure()
     let rgProcessor = rgState.processor
@@ -568,23 +682,18 @@ final class AudioTapProvider: AudioMixProvider {
     return EQTap.audioMix(
       for: item,
       process: composedClosure,
-      // Size the mono-mix scratch buffer on the tap's prepare
-      // callback so the render thread never allocates. `maxFrames`
-      // is the tap's per-batch frame budget.
-      prepare: { frames in processor.tapPrepare(maxFrames: frames) }
+      // Configure the cascade and size the mono-mix scratch buffer on the
+      // tap's prepare callback, which runs once ahead of the process loop, so
+      // the render thread never allocates and never runs against a rate or
+      // channel count the tap is not actually delivering.
+      prepare: { frames, format in
+        processor.setSampleRate(format.mSampleRate)
+        processor.setChannelCount(Int(format.mChannelsPerFrame))
+        processor.tapPrepare(maxFrames: frames)
+      }
     )
   }
 
-  /// Pull the AudioStreamBasicDescription from a CMFormatDescription
-  /// without forcing a copy. Returns `nil` if the format isn't a
-  /// linear-PCM audio format (e.g. compressed source whose
-  /// formatDescription wraps the encoded format).
-  private func readASBD(_ format: CMFormatDescription) -> AudioStreamBasicDescription? {
-    guard let pointer = CMAudioFormatDescriptionGetStreamBasicDescription(format) else {
-      return nil
-    }
-    return pointer.pointee
-  }
 }
 
 // MARK: - Per-item ReplayGain state
@@ -596,11 +705,37 @@ final class AudioTapProvider: AudioMixProvider {
 final class ItemRGState {
 
   let processor: ReplayGainProcessor
+  /// The state is an associated object OF the item, so a strong reference here
+  /// would be a cycle.
+  weak var item: AVPlayerItem?
+  /// `\.status` observation on the owning item, installed by
+  /// `AudioTapProvider.attachReplayGainState`. Held here so its lifetime
+  /// matches the item's — the item owns this state, so the observation dies
+  /// with the thing it observes.
+  var statusObservation: NSKeyValueObservation?
   private let lock = NSLock()
   private var data: ReplayGainData?
+  private var replayGainReadStarted = false
 
-  init(processor: ReplayGainProcessor) {
+  init(processor: ReplayGainProcessor, item: AVPlayerItem? = nil) {
     self.processor = processor
+    self.item = item
+  }
+
+  deinit {
+    statusObservation?.invalidate()
+  }
+
+  /// Claim the one metadata read this state gets. Returns `true` to exactly
+  /// one caller; the `\.status` observer and the synchronous bootstrap both
+  /// reach a prepared item, and `refreshActiveItemMixes()` can re-run the
+  /// bootstrap, so the claim has to be atomic rather than a plain flag check.
+  func beginReplayGainRead() -> Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    if replayGainReadStarted { return false }
+    replayGainReadStarted = true
+    return true
   }
 
   /// Update the cached metadata. The render-thread gain push happens

package/ios/CarPlayBridge.swift

@@ -164,15 +164,3 @@ final class CarPlayBridge {
   }
 }
 
-// `NSLock.withLock` is iOS 16+; the lib's deployment target sits at
-// iOS 15.1 (per `min_ios_version_supported`), so a backport is the
-// only safe pattern. Drop this when the deployment target advances.
-private extension NSLock {
-  @inline(__always)
-  func withLock<R>(_ body: () throws -> R) rethrows -> R {
-    lock()
-    defer { unlock() }
-    return try body()
-  }
-}
-