react-native-queue-player 1.0.0

package/ios/AudioTapProvider.swift

@@ -0,0 +1,647 @@
+import AVFoundation
+import Foundation
+
+/// Module-internal `AudioMixProvider` shared by the equalizer and
+/// visualizer Hybrids on iOS.
+///
+/// One tap per `AVPlayerItem`, one set of post-EQ samples, fanned out
+/// to every registered consumer. Both `Equalizer` and `Visualizer`
+/// register at Hybrid construction; neither references the other.
+///
+/// Responsibilities:
+///  - Owns the per-item `AVAudioMix` build (the EQ tap + DSP closure).
+///  - Holds the equalizer master gain state (gains + version + enabled
+///    flag) consulted by the per-item `EQProcessor` cascade.
+///  - Decides whether to install a tap on a given item: install when
+///    any registered consumer's `wantsTap` returns true. The tap runs
+///    EQ in pass-through when only the visualizer wants frames.
+///  - Fans out post-EQ audio frames to every registered consumer's
+///    `onAudioFrame` on the audio render thread.
+///  - Notifies registered consumers when the active asset changes so
+///    HLS detection lands at subscribe time.
+///  - Asks the playback engine to re-evaluate per-item mixes when a
+///    consumer's `wantsTap` would change (EQ enable toggle, first
+///    visualizer subscriber, last subscriber drop).
+///
+/// Threading:
+///  - Consumer registration runs on the JS bridge thread at Hybrid
+///    construction.
+///  - `audioMix(for:)` runs on main (engine call site).
+///  - `deliverAudioFrame` runs on the audio render thread; the
+///    per-frame fan-out walks an immutable consumer snapshot under
+///    [consumersLock] and is allocation-free.
+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.
+  static let shared = AudioTapProvider()
+
+  /// Consumer of the post-EQ audio pipeline. Equalizer + Visualizer
+  /// each construct one of these and register it with the provider
+  /// at Hybrid init. Identity is the consumer reference itself —
+  /// duplicate registrations replace the prior entry.
+  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.
+    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
+    /// 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
+    /// confirmation must check `EQTap.isHLS(asset)` themselves.
+    /// Used by the visualizer to surface `hls-source` synchronously
+    /// at subscribe time without poking the player.
+    let onActiveAssetChange: (AVAsset?) -> Void
+
+    init(
+      wantsTap: @escaping () -> Bool,
+      onAudioFrame: @escaping (UnsafePointer<Float>, Int, Double) -> Void,
+      onActiveAssetChange: @escaping (AVAsset?) -> Void
+    ) {
+      self.wantsTap = wantsTap
+      self.onAudioFrame = onAudioFrame
+      self.onActiveAssetChange = onActiveAssetChange
+    }
+  }
+
+  /// 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.
+  private let stateLock = NSLock()
+
+  private var currentGains: [Double]
+  private var gainsVersion: UInt64 = 0
+  private var enabled: Bool = false
+  /// Pin-at-configure flag honoured by the visualizer Hybrid. When
+  /// false, `Visualizer.subscribe` rejects with `'visualization-disabled'`
+  /// and the visualizer's Consumer's `wantsTap` returns false even when
+  /// JS subscribers exist — `audioMix(for:)`'s `anyConsumerWantsTap()`
+  /// short-circuit then skips tap construction unless EQ also wants
+  /// frames. Written by `TrackPlayer.configure(_:)` on every call;
+  /// default `true` preserves existing behaviour for consumers who
+  /// never set the new field.
+  private var visualizationEnabled: Bool = true
+  private var consumers: [Consumer] = []
+
+  /// Weak reference to the active playback engine. Wired in by
+  /// `wireToPlaybackEngine`; held weak so the provider never extends
+  /// the engine's lifetime (iOS rebuilds the engine on TrackPlayer
+  /// destroy + reconfigure).
+  private weak var playbackEngine: PlaybackEngine?
+
+  /// 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
+  /// matches the item's, and registers it here for mode-driven
+  /// recompute. The hash table holds weak references — entries
+  /// disappear automatically when the engine drops the underlying
+  /// item from its queue.
+  private let activeItemStates = NSHashTable<ItemRGState>.weakObjects()
+
+  /// Currently-selected ReplayGain mode. Read on every mode-driven
+  /// recompute path (item-state-extract completion, mode change).
+  private var replayGainMode: ReplayGainMode = .off
+
+  /// Fired after the per-item async metadata extract completes and
+  /// `ItemRGState.setData` lands. TrackPlayer subscribes to re-resolve
+  /// the now-playing format for the affected item — without this, the
+  /// initial format snapshot taken at `\.currentItem` KVO time captures
+  /// `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?
+
+  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)
+  }
+
+  // MARK: - Engine wiring
+
+  /// 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.
+  func wireToPlaybackEngine(_ engine: PlaybackEngine) {
+    stateLock.lock()
+    self.playbackEngine = engine
+    stateLock.unlock()
+    engine.setAudioMixProvider(self)
+  }
+
+  /// Detach the provider from any previously-wired engine. Hops to
+  /// main if needed — AVFoundation expects `setAudioMixProvider` on
+  /// the main thread.
+  func detachFromEngine() {
+    stateLock.lock()
+    let engine = self.playbackEngine
+    self.playbackEngine = nil
+    stateLock.unlock()
+    guard let engine = engine else { return }
+    if Thread.isMainThread {
+      engine.setAudioMixProvider(nil)
+    } else {
+      DispatchQueue.main.async {
+        engine.setAudioMixProvider(nil)
+      }
+    }
+  }
+
+  /// 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.
+  func refreshActiveItemMixes() {
+    stateLock.lock()
+    let engine = self.playbackEngine
+    stateLock.unlock()
+    guard let engine = engine else { return }
+    if Thread.isMainThread {
+      engine.refreshAllItemMixes()
+    } else {
+      DispatchQueue.main.async {
+        engine.refreshAllItemMixes()
+      }
+    }
+  }
+
+  // MARK: - Consumer registration
+
+  /// Register [consumer] for post-EQ audio frames + 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.
+  func register(_ consumer: Consumer) {
+    stateLock.lock()
+    consumers.append(consumer)
+    stateLock.unlock()
+  }
+
+  /// Drop [consumer] from the provider's fan-out list. Identity is
+  /// the consumer reference. Safe to call from any thread.
+  func unregister(_ consumer: Consumer) {
+    stateLock.lock()
+    consumers.removeAll { $0 === consumer }
+    stateLock.unlock()
+  }
+
+  /// True when at least one registered consumer's `wantsTap` returns
+  /// 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 {
+    stateLock.lock()
+    let snapshot = consumers
+    stateLock.unlock()
+    for consumer in snapshot {
+      if consumer.wantsTap() { return true }
+    }
+    return false
+  }
+
+  // MARK: - EQ master gain state
+
+  /// Lock-protected snapshot of the enabled flag. Called from main
+  /// on every `audioMix(for:)` invocation.
+  func isEnabledSnapshot() -> Bool {
+    stateLock.lock()
+    let value = enabled
+    stateLock.unlock()
+    return value
+  }
+
+  /// Lock-protected snapshot of the `visualizationEnabled` flag.
+  /// Read by the visualizer Hybrid on every `subscribe` and by its
+  /// Consumer's `wantsTap` predicate; written by
+  /// `TrackPlayer.configure(_:)` on every call.
+  func isVisualizationEnabledSnapshot() -> Bool {
+    stateLock.lock()
+    let value = visualizationEnabled
+    stateLock.unlock()
+    return value
+  }
+
+  /// Lock-protected `visualizationEnabled` write. Called from
+  /// `TrackPlayer.configure(_:)`. Idempotent re-write per configure
+  /// call so the latest value is always live for subsequent
+  /// `subscribe` / `wantsTap` queries.
+  func setVisualizationEnabled(_ value: Bool) {
+    stateLock.lock()
+    visualizationEnabled = value
+    stateLock.unlock()
+  }
+
+  /// Lock-protected enabled-flag write. The Equalizer Hybrid mirrors
+  /// its own enabled state through here; the caller decides whether
+  /// to follow up with `refreshActiveItemMixes`.
+  func setEnabled(_ value: Bool) {
+    stateLock.lock()
+    enabled = value
+    stateLock.unlock()
+  }
+
+  /// Replace the master band-gain state and bump `gainsVersion`.
+  /// Active per-item EQProcessor cascades observe the version
+  /// advance on their next render-thread callback and recompute
+  /// coefficients in place.
+  func setGains(_ gains: [Double]) {
+    stateLock.lock()
+    currentGains = gains
+    gainsVersion &+= 1
+    stateLock.unlock()
+  }
+
+  /// Snapshot the master gains + their version + EQ enabled flag
+  /// under one lock acquisition. Per-item cascades compare the version
+  /// against their last-seen value to decide whether to recompute
+  /// coefficients; the enabled flag drives the pass-through gate.
+  /// Single locked read keeps the render-thread cost to one critical
+  /// section per buffer batch.
+  func gainsSnapshot() -> (version: UInt64, gains: [Double], enabled: Bool) {
+    stateLock.lock()
+    let snapshot = (version: gainsVersion, gains: currentGains, enabled: enabled)
+    stateLock.unlock()
+    return snapshot
+  }
+
+  /// Diagnostic + provider-internal read of the current gains.
+  func getGains() -> [Double] {
+    return gainsSnapshot().gains
+  }
+
+  // MARK: - ReplayGain mode + per-item recompute
+
+  /// Snapshot the current ReplayGain mode. Read by the TrackPlayer
+  /// Hybrid's `getReplayGainMode`.
+  func getReplayGainMode() -> ReplayGainMode {
+    stateLock.lock()
+    let mode = replayGainMode
+    stateLock.unlock()
+    return mode
+  }
+
+  /// Update the ReplayGain mode and recompute gain on every active
+  /// item's processor from its cached `ReplayGainData`. Items whose
+  /// extraction is still pending pick up the new mode automatically
+  /// when their extract completes — the completion handler runs the
+  /// same locked recompute helper, which always reads the live mode
+  /// inside the critical section.
+  ///
+  /// Also asks the engine to re-evaluate per-item mixes: the
+  /// internal RG Consumer's `wantsTap` predicate flips whenever the
+  /// mode crosses the off / non-off boundary, so a pre-flip item
+  /// that skipped tap install (no other consumer wanted it) needs
+  /// a fresh `audioMix(for:)` walk to pick up the tap. Mirrors the
+  /// `refreshActiveItemMixes` path EQ + Visualizer use when their
+  /// own `wantsTap` flips.
+  func setReplayGainMode(_ mode: ReplayGainMode) {
+    stateLock.lock()
+    replayGainMode = mode
+    let states = activeItemStates.allObjects
+    stateLock.unlock()
+    for state in states {
+      recomputeWithLock(state: state)
+    }
+    refreshActiveItemMixes()
+  }
+
+  /// Recompute [state]'s linear gain from its cached `ReplayGainData`
+  /// under the live mode and push to its processor. `state.lock`
+  /// (inside `state.snapshotData()`) and `processor.lock` (inside
+  /// `processor.setLinearGain`) are each held briefly, sequentially —
+  /// never simultaneously, never with `stateLock` co-held with
+  /// `state.lock`. `stateLock` brackets the live-mode read + gain
+  /// push so a concurrent `setReplayGainMode` cannot interleave
+  /// between read + push and leave the processor at a stale gain.
+  private func recomputeWithLock(state: ItemRGState) {
+    let data = state.snapshotData()
+    stateLock.lock()
+    let selectorMode = Self.selectorMode(from: replayGainMode)
+    let linearGain = Self.computeLinearGain(data: data, mode: selectorMode)
+    state.processor.setLinearGain(linearGain)
+    stateLock.unlock()
+  }
+
+  /// Pure gain math per NOTES.md §25. Selects the `(gainDb, peak)`
+  /// pair from [data] under [mode] (strict, no fallback), then:
+  ///
+  /// ```
+  /// linearGain = pow(10, gainDb / 20)
+  /// if peak != nil and peak > 0.001 and peak != 1.0:
+  ///   linearGain = min(linearGain, 1.0 / peak)
+  /// ```
+  ///
+  /// Returns 1.0 (unity) whenever the selected mode's gain tag is
+  /// absent — RG is inactive for that track.
+  ///
+  /// Takes the pure-Swift `ReplayGainSelectorMode` rather than the
+  /// Nitrogen-generated `ReplayGainMode` so the math compiles off
+  /// the Swift↔C++ interop graph (NOTES.md §6); production callers
+  /// translate at the call site via `selectorMode(from:)`.
+  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))
+    }
+    return raw
+  }
+
+  /// Map the Nitrogen-generated `ReplayGainMode` to the pure-Swift
+  /// `ReplayGainSelectorMode` consumed by `computeLinearGain` and
+  /// `ReplayGainData.selectGain`.
+  static func selectorMode(from mode: ReplayGainMode) -> ReplayGainSelectorMode {
+    switch mode {
+    case .off: return .off
+    case .track: return .track
+    case .album: return .album
+    }
+  }
+
+  /// True when [state]'s cached `ReplayGainData` carries a tag for
+  /// the active mode (i.e. the gain push would land at non-unity).
+  /// Surfaced through `replayGainActiveForItem(_:)` so the
+  /// NowPlayingFormat path can populate the `replayGainActive` field
+  /// without recomputing the linear gain itself.
+  func replayGainActiveForItem(_ item: AVPlayerItem) -> Bool {
+    stateLock.lock()
+    let mode = replayGainMode
+    stateLock.unlock()
+    guard let state = item.replayGainState else { return false }
+    let data = state.snapshotData()
+    let (gainDb, _) = data?.selectGain(mode: Self.selectorMode(from: mode)) ?? (nil, nil)
+    return gainDb != nil
+  }
+
+  /// Snapshot [item]'s cached `ReplayGainData`. Returns `nil` when
+  /// the item carries no RG state yet (HLS / track-less item that
+  /// bypassed the tap, or extract not yet complete + no-tag track).
+  func replayGainDataForItem(_ item: AVPlayerItem) -> ReplayGainData? {
+    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())
+    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)
+        }
+      }
+    }
+  }
+
+  // MARK: - Render-thread frame fan-out
+
+  /// Render-thread entry point invoked by `EQProcessor.tapProcessClosure`
+  /// once per render batch with a post-EQ mono mix. Snapshots the
+  /// consumer list under the lock and dispatches outside it so a
+  /// long-running FFT cannot block JS-side registration.
+  @inline(__always)
+  func deliverAudioFrame(
+    output: UnsafePointer<Float>,
+    frameCount: Int,
+    sampleRate: Double
+  ) {
+    stateLock.lock()
+    let snapshot = consumers
+    stateLock.unlock()
+    for consumer in snapshot {
+      consumer.onAudioFrame(output, frameCount, sampleRate)
+    }
+  }
+
+  // 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
+  /// 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.
+  func audioMix(for item: AVPlayerItem) -> AVAudioMix? {
+    let asset = item.asset
+    // Notify every registered consumer of the candidate asset before
+    // the bypass checks. Visualizer uses this to fire `hls-source`
+    // synchronously at subscribe time.
+    stateLock.lock()
+    let consumerSnapshot = consumers
+    stateLock.unlock()
+    for consumer in consumerSnapshot {
+      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)
+
+    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
+    // `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 }
+
+    let sampleRate = asbd.mSampleRate
+    let channelCount = Int(asbd.mChannelsPerFrame)
+    if sampleRate <= 0 || channelCount <= 0 {
+      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
+    }()
+
+    let eqClosure = processor.tapProcessClosure()
+    let rgProcessor = rgState.processor
+    let composedClosure: EQTap.ProcessFn = { input, output, frames, channels, bufferIndex, liveCount in
+      // Tap delivers `input == output` (same pointer); RG mutates the
+      // shared buffer in place, EQ then reads the post-RG samples.
+      rgProcessor.process(buffer: input, frames: frames)
+      eqClosure(input, output, frames, channels, bufferIndex, liveCount)
+    }
+
+    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) }
+    )
+  }
+
+  /// 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
+
+/// Pairs a `ReplayGainProcessor` with the cached `ReplayGainData`
+/// extracted from its item's asset metadata. Owned by the
+/// `AVPlayerItem` it's attached to (associated-object) so its
+/// lifetime tracks the item.
+final class ItemRGState {
+
+  let processor: ReplayGainProcessor
+  private let lock = NSLock()
+  private var data: ReplayGainData?
+
+  init(processor: ReplayGainProcessor) {
+    self.processor = processor
+  }
+
+  /// Update the cached metadata. The render-thread gain push happens
+  /// in `AudioTapProvider.recomputeWithLock(state:)` after this call.
+  func setData(_ value: ReplayGainData?) {
+    lock.lock()
+    data = value
+    lock.unlock()
+  }
+
+  /// Snapshot the cached data under the lock. Returns `nil` if the
+  /// extractor produced no usable tags or the extract is still in
+  /// flight.
+  func snapshotData() -> ReplayGainData? {
+    lock.lock()
+    let value = data
+    lock.unlock()
+    return value
+  }
+}
+
+// Associated-object key for `AVPlayerItem.replayGainState`. Distinct
+// pointer per Cocoa convention (the address itself is the key — the
+// content is unused, but the variable must outlive the items).
+private var rgStateAssociatedObjectKey: UInt8 = 0
+
+extension AVPlayerItem {
+  /// The `ItemRGState` attached to this item by `AudioTapProvider`,
+  /// or `nil` for items the provider hasn't seen (e.g. items
+  /// constructed outside the tap path).
+  var replayGainState: ItemRGState? {
+    get {
+      objc_getAssociatedObject(self, &rgStateAssociatedObjectKey) as? ItemRGState
+    }
+    set {
+      objc_setAssociatedObject(
+        self,
+        &rgStateAssociatedObjectKey,
+        newValue,
+        .OBJC_ASSOCIATION_RETAIN_NONATOMIC
+      )
+    }
+  }
+}