react-native-queue-player 1.0.0

package/ios/Equalizer.swift

@@ -0,0 +1,321 @@
+import Foundation
+import NitroModules
+
+/// 10-band parametric equalizer HybridObject for iOS.
+///
+/// Routes the JS-facing surface through:
+///  - `AudioTapProvider` (shared per-AVPlayerItem cascade attach +
+///    post-EQ frame fan-out to other consumers)
+///  - `EQProcessor` (the actual vDSP_biquad pipeline, instantiated
+///    per item by the provider)
+///  - `CustomPresetStore` (UserDefaults-backed custom presets)
+///
+/// The provider is module-internal (`AudioTapProvider.shared`); the
+/// playback engine reaches it at `setAudioMixProvider` time via the
+/// `wireToPlaybackEngine` call below.
+///
+/// Reconstruction contract: when JS drops the `getEqualizer()`
+/// singleton and a fresh Hybrid is constructed (e.g. after a JS
+/// reload), the new instance resets the provider to `enabled=false`
+/// + flat gains. Consumer apps that persist EQ state across reloads
+/// must reapply it after the new Hybrid is ready — the lib does not
+/// fire `onEnabledChange` / `onBandChange` for this implicit reset
+/// because the JS side already knows it just dropped the singleton.
+final class Equalizer: HybridEqualizerSpec {
+
+  /// The most recently constructed Equalizer instance. The iOS
+  /// playback engine reaches for this at attach time so it can
+  /// wire the shared `AudioTapProvider` to the active player without
+  /// threading the Hybrid reference through Nitro's bridge.
+  ///
+  /// Acquire `currentLock` when reading or writing — `init()` runs
+  /// on the JS bridge while a prior instance may still be mid-
+  /// `audioMix(for:)` or mid-`deliverAudioFrame` on main / render.
+  /// Mirrors the locked-static pattern on `Visualizer.current`.
+  ///
+  /// Strong reference: lifecycle is JS-managed (Nitro releases the
+  /// Hybrid when the JS-side `getEqualizer()` singleton drops),
+  /// so the strong static doesn't cause a leak — JS reload zeroes
+  /// it via the second-construction teardown path below.
+  private static let currentLock = NSLock()
+  private static var _current: Equalizer?
+  static var current: Equalizer? {
+    get {
+      currentLock.lock(); defer { currentLock.unlock() }
+      return _current
+    }
+    set {
+      currentLock.lock(); defer { currentLock.unlock() }
+      _current = newValue
+    }
+  }
+
+  let provider: AudioTapProvider
+  private let presetStore: CustomPresetStore
+  private var consumer: AudioTapProvider.Consumer?
+
+  /// Master gain state. Source of truth on the JS side; the
+  /// provider replicates this to per-item processors at attach
+  /// time. Each mutation (band gain, preset apply) updates this
+  /// AND the provider's master state in lockstep.
+  ///
+  /// Read + written under [stateQueue].
+  private var gainsDb: [Double] = Array(repeating: 0, count: 10)
+
+  /// Enabled state mirrored to the provider; the provider's
+  /// `audioMix(for:)` short-circuits when no consumer wants the tap.
+  ///
+  /// Read + written under [stateQueue].
+  private var enabled: Bool = false
+
+  /// Serialises every state-mutating path so JS callers firing
+  /// `setBandGain` and `setEnabled` concurrently from
+  /// `Promise.async` (which runs on Swift's cooperative pool, not
+  /// main) don't tear `gainsDb` or race the provider's master
+  /// gains. Reads from `getBands` and `isEnabled` also take the
+  /// queue so they observe a consistent snapshot.
+  private let stateQueue = DispatchQueue(label: "com.margelo.nitro.queueplayer.equalizerState")
+
+  private let onBandChangeListeners = ListenerRegistry<([EqualizerBand]) -> Void>()
+  private let onEnabledChangeListeners = ListenerRegistry<(Bool) -> Void>()
+
+  init(provider: AudioTapProvider = .shared,
+       presetStore: CustomPresetStore = CustomPresetStore()) {
+    self.provider = provider
+    self.presetStore = presetStore
+    super.init()
+    // Tear the prior instance's consumer registration down before it
+    // loses the static reference — otherwise the prior instance's
+    // `wantsTap` predicate keeps the tap installed on the engine
+    // even after JS has dropped that Equalizer Hybrid.
+    Equalizer.current?.detachConsumerOnRefresh()
+    Equalizer.current = self
+    provider.setEnabled(false)
+    provider.setGains(gainsDb)
+    registerConsumer()
+  }
+
+  /// Detach the prior Equalizer instance's consumer + EQ state when
+  /// a fresh instance takes over [Equalizer.current]. Called from the
+  /// new instance's `init` before it claims the static reference.
+  internal func detachConsumerOnRefresh() {
+    if let consumer = self.consumer {
+      provider.unregister(consumer)
+      self.consumer = nil
+    }
+  }
+
+  private func registerConsumer() {
+    // Tap install demand reads the provider's own enabled flag; the
+    // closure does not capture `self`, so the consumer outlives an
+    // Equalizer Hybrid replacement without holding the prior Hybrid
+    // alive. The EQ's post-DSP frame hook fires regardless of the
+    // enabled state — when enabled is false but another consumer
+    // (visualizer) wants the tap, the EQProcessor runs pass-through
+    // and still produces a valid mono mix.
+    let provider = self.provider
+    let consumer = AudioTapProvider.Consumer(
+      wantsTap: { provider.isEnabledSnapshot() },
+      // The Equalizer produces the post-EQ pipeline (its EQProcessor
+      // runs the DSP inside the tap). It does not need a separate
+      // frame-receive callback; consumed-by-EQ frames are delivered
+      // to other consumers through the provider's `deliverAudioFrame`.
+      onAudioFrame: { _, _, _ in },
+      // The EQ doesn't need active-asset notifications — its DSP
+      // path is per-item and the provider already gates HLS bypass
+      // before constructing an EQProcessor.
+      onActiveAssetChange: { _ in }
+    )
+    self.consumer = consumer
+    provider.register(consumer)
+  }
+
+  // MARK: - JS-facing async surface
+
+  func setEnabled(enabled: Bool) throws -> Promise<Void> {
+    return Promise.async {
+      self.setEnabledInternal(enabled)
+    }
+  }
+
+  func isEnabled() throws -> Bool {
+    return stateQueue.sync { enabled }
+  }
+
+  func getBands() throws -> [EqualizerBand] {
+    return stateQueue.sync { currentBandsSnapshot() }
+  }
+
+  func setBandGain(index: Double, gainDb: Double) throws -> Promise<Void> {
+    return Promise.async {
+      self.setBandGainInternal(index: Int(index), gainDb: gainDb)
+    }
+  }
+
+  func setAllBandGains(gains: [Double]) throws -> Promise<Void> {
+    return Promise.async {
+      self.setAllBandGainsInternal(gains)
+    }
+  }
+
+  func applyPreset(name: String) throws -> Promise<Void> {
+    return Promise.async {
+      if !self.applyPresetInternal(name: name) {
+        throw RuntimeError("Equalizer preset not found: \(name)")
+      }
+    }
+  }
+
+  func getPresets() throws -> [EqualizerPreset] {
+    let custom = presetStore.loadAll().sorted { $0.name < $1.name }
+    return builtinPresets() + custom
+  }
+
+  func saveCustomPreset(name: String) throws -> Promise<Void> {
+    return Promise.async {
+      if EqualizerPresets.getByName(name) != nil {
+        throw RuntimeError("Cannot overwrite built-in preset: \(name)")
+      }
+      // Snapshot current gains under the state lock so a JS-side
+      // setBandGain in flight doesn't tear the array we persist.
+      let snapshot = self.stateQueue.sync { self.gainsDb }
+      self.presetStore.save(name: name, gains: snapshot)
+    }
+  }
+
+  func deleteCustomPreset(name: String) throws -> Promise<Void> {
+    return Promise.async {
+      self.presetStore.delete(name: name)
+    }
+  }
+
+  func reset() throws -> Promise<Void> {
+    return Promise.async {
+      _ = self.applyPresetInternal(name: "Flat")
+    }
+  }
+
+  func onBandChange(
+    callback: @escaping (_ bands: [EqualizerBand]) -> Void
+  ) throws -> () -> Void {
+    let id = onBandChangeListeners.add(callback)
+    // Seed the new subscriber with the current snapshot so consumers
+    // don't have to call getBands first. Spec contract.
+    callback(stateQueue.sync { currentBandsSnapshot() })
+    return { [weak self] in self?.onBandChangeListeners.remove(id: id) }
+  }
+
+  func onEnabledChange(
+    callback: @escaping (_ enabled: Bool) -> Void
+  ) throws -> () -> Void {
+    let id = onEnabledChangeListeners.add(callback)
+    callback(stateQueue.sync { enabled })
+    return { [weak self] in self?.onEnabledChangeListeners.remove(id: id) }
+  }
+
+  // MARK: - Engine wiring
+
+  /// Wire the shared `AudioTapProvider` onto [playbackEngine] so the
+  /// engine can ask for an `AVAudioMix` per AVPlayerItem it queues.
+  /// Called by `TrackPlayer` once its `GaplessEngine` is constructed;
+  /// the provider's `audioMix(for:)` then applies the per-item EQ
+  /// cascade. Mirrors the Android `wireToPlaybackEngine` pattern.
+  func wireToPlaybackEngine(_ playbackEngine: PlaybackEngine) {
+    provider.wireToPlaybackEngine(playbackEngine)
+  }
+
+  // MARK: - Synchronous core
+  //
+  // Every mutating method is serialised under [stateQueue] so JS
+  // callers firing concurrently from `Promise.async` (Swift's
+  // cooperative pool) don't tear `gainsDb`, `enabled`, or the
+  // provider's master gains. Listener fires happen outside the
+  // lock to keep the registry's own queue from interleaving.
+  //
+  // Band-gain mutations (`setBandGainInternal`,
+  // `setAllBandGainsInternal`) skip the engine-refresh path: a
+  // call to `provider.setGains` bumps the master gains version
+  // counter, and each active per-item tap recomputes coefficients
+  // on its next render-thread callback. Keeping the audioMix
+  // attached avoids the audible cutout an attach/detach cycle
+  // would cause on slider drag.
+
+  func setEnabledInternal(_ value: Bool) {
+    let changed: Bool = stateQueue.sync {
+      if enabled == value { return false }
+      enabled = value
+      provider.setEnabled(value)
+      return true
+    }
+    if changed {
+      // Re-attach the audioMix on every queued AVPlayerItem so the
+      // currently-playing track picks up the new enabled state. Without
+      // this the user toggles EQ on but hears nothing — the active item's
+      // audioMix was set to nil when the provider was disabled, and
+      // AVPlayerItem.audioMix is a one-shot wire-up at queue time.
+      provider.refreshActiveItemMixes()
+      onEnabledChangeListeners.forEach { $0(value) }
+    }
+  }
+
+  func setBandGainInternal(index: Int, gainDb: Double) {
+    if index < 0 || index >= 10 { return }
+    let snapshot: [EqualizerBand]? = stateQueue.sync {
+      let clamped = max(-12, min(12, gainDb))
+      gainsDb[index] = clamped
+      provider.setGains(gainsDb)
+      return currentBandsSnapshot()
+    }
+    if let snapshot = snapshot {
+      onBandChangeListeners.forEach { $0(snapshot) }
+    }
+  }
+
+  func setAllBandGainsInternal(_ gains: [Double]) {
+    let snapshot: [EqualizerBand]? = stateQueue.sync {
+      let n = min(gains.count, 10)
+      for i in 0..<n {
+        gainsDb[i] = max(-12, min(12, gains[i]))
+      }
+      provider.setGains(gainsDb)
+      return currentBandsSnapshot()
+    }
+    if let snapshot = snapshot {
+      onBandChangeListeners.forEach { $0(snapshot) }
+    }
+  }
+
+  /// Returns true when the named preset existed and was applied.
+  /// The async wrapper drops the boolean and resolves Promise<Void>.
+  @discardableResult
+  func applyPresetInternal(name: String) -> Bool {
+    if let presetGains = EqualizerPresets.getByName(name) {
+      setAllBandGainsInternal(presetGains)
+      return true
+    }
+    let customs = presetStore.loadAll()
+    if let custom = customs.first(where: { $0.name == name }) {
+      setAllBandGainsInternal(custom.gains)
+      return true
+    }
+    return false
+  }
+
+  // MARK: - Helpers
+
+  private func currentBandsSnapshot() -> [EqualizerBand] {
+    return EqualizerPresets.frequencies.enumerated().map { idx, freq in
+      EqualizerBand(frequencyHz: freq, gainDb: gainsDb[idx])
+    }
+  }
+
+  private func builtinPresets() -> [EqualizerPreset] {
+    return EqualizerPresets.getNames().map { name in
+      EqualizerPreset(
+        name: name,
+        gains: EqualizerPresets.getByName(name) ?? [],
+        builtin: true
+      )
+    }
+  }
+}

package/ios/EqualizerPresets.swift

@@ -0,0 +1,48 @@
+import Foundation
+
+/// Built-in 10-band equalizer presets keyed by display name.
+///
+/// 10 ISO-standard centre frequencies (Hz) span the audible
+/// spectrum from sub-bass (31) to high treble (16k). Each preset's
+/// gains array is in dB, one entry per band, ordered low-to-high
+/// to match `frequencies`.
+///
+/// Presets are stored as an ordered array of (name, gains) tuples so
+/// `getNames()` returns the canonical chip-display order. The presets
+/// are read-only constants — consumer-side custom presets live in
+/// `CustomPresetStore`.
+enum EqualizerPresets {
+
+  static let frequencies: [Double] = [
+    31, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000,
+  ]
+
+  private static let presets: [(name: String, gains: [Double])] = [
+    ("Flat",           [ 0.0,  0.0,  0.0,  0.0,  0.0,  0.0,  0.0,  0.0,  0.0,  0.0]),
+    ("Reference",      [ 4.0,  4.0,  2.0,  1.0,  0.0,  0.0,  2.0,  3.0,  1.0, -2.0]),
+    ("Bass Boost",     [ 6.0,  5.0,  3.0,  1.0,  0.0,  0.0,  0.0,  0.0,  0.0,  0.0]),
+    ("Bass Reducer",   [-6.0, -5.0, -3.0, -1.0,  0.0,  0.0,  0.0,  0.0,  0.0,  0.0]),
+    ("Treble Boost",   [ 0.0,  0.0,  0.0,  0.0,  0.0,  0.0,  2.0,  4.0,  5.0,  6.0]),
+    ("Treble Reducer", [ 0.0,  0.0,  0.0,  0.0,  0.0,  0.0, -2.0, -4.0, -5.0, -6.0]),
+    ("V-Shaped",       [ 5.0,  4.0,  2.0,  0.0, -2.0, -3.0, -1.0,  2.0,  4.0,  5.0]),
+    ("Vocal Boost",    [-3.0, -2.0,  0.0,  1.0,  2.0,  3.0,  4.0,  3.0,  1.0,  0.0]),
+    ("Spoken Word",    [-6.0, -4.0, -2.0,  0.0,  2.0,  4.0,  4.0,  3.0, -1.0, -3.0]),
+    ("Late Night",     [ 6.0,  5.0,  2.0,  1.0,  1.0,  2.0,  3.0,  2.0,  3.0,  5.0]),
+    ("Acoustic",       [ 3.0,  2.0,  1.0,  0.0,  0.0,  1.0,  2.0,  3.0,  2.0,  1.0]),
+    ("Rock",           [ 5.0,  3.0, -2.0, -3.0, -1.0,  2.0,  4.0,  5.0,  5.0,  5.0]),
+    ("Hip-Hop",        [ 5.0,  5.0,  3.0,  1.0, -1.0,  0.0,  1.0,  3.0,  4.0,  5.0]),
+    ("Small Speakers", [ 5.0,  6.0,  3.0,  0.0,  0.0,  1.0,  2.0,  4.0,  5.0,  6.0]),
+    ("Jazz",           [ 3.0,  2.0,  0.0,  1.0,  2.0,  1.0,  0.0,  1.0,  2.0,  3.0]),
+    ("Electronic",     [ 5.0,  4.0,  2.0,  0.0, -2.0,  1.0,  2.0,  3.0,  4.0,  6.0]),
+  ]
+
+  /// Returns the gain array (dB) for `name`, or `nil` if unknown.
+  static func getByName(_ name: String) -> [Double]? {
+    return presets.first(where: { $0.name == name })?.gains
+  }
+
+  /// Display names in canonical chip-display order.
+  static func getNames() -> [String] {
+    return presets.map { $0.name }
+  }
+}

package/ios/FFTProcessor.swift

@@ -0,0 +1,237 @@
+import Accelerate
+import Foundation
+import NitroModules
+
+/// Cached `mach_timebase_info`. The Darwin contract documents this as
+/// constant for the life of the process, but `mach_timebase_info` is
+/// a syscall — at 60 Hz fan-out per visualizer subscriber the cache
+/// matters for the render-thread budget.
+private let machTimebase: mach_timebase_info_data_t = {
+  var info = mach_timebase_info_data_t()
+  mach_timebase_info(&info)
+  return info
+}()
+
+@inline(__always)
+private func nowNanos() -> UInt64 {
+  let raw = mach_absolute_time()
+  return raw * UInt64(machTimebase.numer) / UInt64(machTimebase.denom)
+}
+
+/// Per-subscriber visualizer processor for iOS. Wraps a vDSP FFT
+/// setup over a ring buffer of samples ingested from the audio
+/// render thread. Calls `onFrame` on the main actor at
+/// `intervalMs` cadence with float32 magnitudes (+ optional raw
+/// pre-window PCM samples) and the stream sample rate.
+///
+/// When `includeSamples == true` the `samples` payload carries the
+/// raw mono-mix PCM read from the same ring window the FFT just
+/// consumed — pre-Hann, suitable for an oscilloscope / Lissajous
+/// consumer. Matches the Android contract.
+///
+/// The processor only ingests the first deinterleaved channel
+/// (bufferIndex 0) — iOS tap callbacks fire once per channel and
+/// summing across channels would require tracking partial frames.
+/// Single-channel visualization is documented behavior; matches the
+/// "left channel" convention common to most desktop visualizers.
+///
+/// Real-time thread hygiene: every per-emit buffer is allocated once
+/// at construction and reused. The `ingest` and `emitFrame` paths
+/// are allocation-free until the JS-bridge handoff at the end of
+/// `emitFrame`, where we copy the magnitudes into a Nitro
+/// `ArrayBuffer` for the bridge crossing.
+final class FFTProcessor {
+
+  let fftSize: Int
+  let intervalMs: Int
+  let includeSamples: Bool
+  /// Receives the FFT magnitudes (and optionally raw samples) as
+  /// Nitro `ArrayBuffer`s — single memcpy per emit, no `[Float]`
+  /// intermediates. Caller is responsible for dispatching the
+  /// downstream JS-bridge call off the audio render thread.
+  private let onFrame: (ArrayBuffer, ArrayBuffer?, Double) -> Void
+
+  // vDSP setup
+  private let log2N: vDSP_Length
+  private let fftSetup: FFTSetup
+
+  // All per-emit scratch held as long-lived raw pointers so the
+  // render-thread hot path never triggers Array's CoW allocation.
+  private let ringPtr: UnsafeMutablePointer<Float>
+  private let windowPtr: UnsafeMutablePointer<Float>
+  private let windowedPtr: UnsafeMutablePointer<Float>
+  private let realPtr: UnsafeMutablePointer<Float>
+  private let imagPtr: UnsafeMutablePointer<Float>
+  private let magsPtr: UnsafeMutablePointer<Float>
+  private let outputPtr: UnsafeMutablePointer<Float>
+  /// Raw pre-window PCM scratch. Allocated only when `includeSamples`
+  /// is true; populated in a separate post-windowing loop in
+  /// `emitFrame` so the per-iteration windowing loop stays branch-free.
+  private let samplesPtr: UnsafeMutablePointer<Float>?
+
+  private let ringCap: Int
+  private var writeIdx: Int = 0
+  private var lastEmitNs: UInt64 = 0
+
+  init(
+    fftSize: Int,
+    intervalMs: Int,
+    includeSamples: Bool,
+    onFrame: @escaping (ArrayBuffer, ArrayBuffer?, Double) -> Void
+  ) throws {
+    guard fftSize > 1 && (fftSize & (fftSize - 1)) == 0 else {
+      throw RuntimeError("fftSize must be a power of two > 1, got \(fftSize)")
+    }
+    guard intervalMs > 0 else {
+      throw RuntimeError("intervalMs must be > 0, got \(intervalMs)")
+    }
+    self.fftSize = fftSize
+    self.intervalMs = intervalMs
+    self.includeSamples = includeSamples
+    self.onFrame = onFrame
+
+    let log2N = vDSP_Length(fftSize.trailingZeroBitCount)
+    self.log2N = log2N
+    guard let setup = vDSP_create_fftsetup(log2N, FFTRadix(kFFTRadix2)) else {
+      throw RuntimeError("Failed to allocate vDSP FFT setup for fftSize=\(fftSize)")
+    }
+    self.fftSetup = setup
+
+    let cap = fftSize * 2
+    self.ringCap = cap
+    self.ringPtr = UnsafeMutablePointer<Float>.allocate(capacity: cap)
+    self.ringPtr.initialize(repeating: 0, count: cap)
+    self.windowPtr = UnsafeMutablePointer<Float>.allocate(capacity: fftSize)
+    vDSP_hann_window(self.windowPtr, vDSP_Length(fftSize), 0)
+    self.windowedPtr = UnsafeMutablePointer<Float>.allocate(capacity: fftSize)
+    self.windowedPtr.initialize(repeating: 0, count: fftSize)
+    let half = fftSize / 2
+    self.realPtr = UnsafeMutablePointer<Float>.allocate(capacity: half)
+    self.realPtr.initialize(repeating: 0, count: half)
+    self.imagPtr = UnsafeMutablePointer<Float>.allocate(capacity: half)
+    self.imagPtr.initialize(repeating: 0, count: half)
+    self.magsPtr = UnsafeMutablePointer<Float>.allocate(capacity: half)
+    self.magsPtr.initialize(repeating: 0, count: half)
+    self.outputPtr = UnsafeMutablePointer<Float>.allocate(capacity: half)
+    self.outputPtr.initialize(repeating: 0, count: half)
+    if includeSamples {
+      let ptr = UnsafeMutablePointer<Float>.allocate(capacity: fftSize)
+      ptr.initialize(repeating: 0, count: fftSize)
+      self.samplesPtr = ptr
+    } else {
+      self.samplesPtr = nil
+    }
+  }
+
+  deinit {
+    ringPtr.deinitialize(count: ringCap)
+    ringPtr.deallocate()
+    windowPtr.deallocate()
+    windowedPtr.deinitialize(count: fftSize)
+    windowedPtr.deallocate()
+    let half = fftSize / 2
+    realPtr.deinitialize(count: half)
+    realPtr.deallocate()
+    imagPtr.deinitialize(count: half)
+    imagPtr.deallocate()
+    magsPtr.deinitialize(count: half)
+    magsPtr.deallocate()
+    outputPtr.deinitialize(count: half)
+    outputPtr.deallocate()
+    if let samplesPtr = samplesPtr {
+      samplesPtr.deinitialize(count: fftSize)
+      samplesPtr.deallocate()
+    }
+    vDSP_destroy_fftsetup(fftSetup)
+  }
+
+  /// Append `frameCount` samples from `samples` to the ring buffer
+  /// and emit a frame if `intervalMs` has elapsed and at least
+  /// `fftSize` samples are buffered. Caller is responsible for
+  /// passing only the first deinterleaved channel — multi-channel
+  /// inputs are handled by skipping non-zero `bufferIndex` values
+  /// at the call site (see `Visualizer.deliverAudioFrame`).
+  func ingest(samples: UnsafePointer<Float>, frameCount: Int, sampleRate: Double) {
+    // ringCap is fftSize * 2 — both powers of two, so wrap-around can
+    // be a free bitmask instead of a 64-bit signed modulo per sample.
+    let mask = ringCap - 1
+    var idx = writeIdx
+    for i in 0..<frameCount {
+      ringPtr[idx & mask] = samples[i]
+      idx += 1
+    }
+    writeIdx = idx
+
+    if writeIdx < fftSize { return }
+    let now = nowNanos()
+    if now - lastEmitNs < UInt64(intervalMs) * 1_000_000 { return }
+    lastEmitNs = now
+
+    emitFrame(sampleRate: sampleRate)
+  }
+
+  private func emitFrame(sampleRate: Double) {
+    let mask = ringCap - 1
+    let n = fftSize
+    let half = n / 2
+
+    // Window the latest n samples into the persistent windowed
+    // buffer.
+    let start = writeIdx - n
+    for i in 0..<n {
+      windowedPtr[i] = ringPtr[(start + i) & mask] * windowPtr[i]
+    }
+
+    // Capture the raw pre-window PCM in a separate pass when the
+    // subscriber asked for it. Kept out of the windowing loop above
+    // so the hot loop stays branch-free.
+    if let samples = samplesPtr {
+      for i in 0..<n {
+        samples[i] = ringPtr[(start + i) & mask]
+      }
+    }
+
+    // Pack interleaved real → split-complex via vDSP_ctoz. The
+    // even-index samples land in real, odd in imag — the standard
+    // vDSP_fft_zrip preprocessing for real-valued FFTs.
+    var split = DSPSplitComplex(realp: realPtr, imagp: imagPtr)
+    windowedPtr.withMemoryRebound(to: DSPComplex.self, capacity: half) { complexSrc in
+      vDSP_ctoz(complexSrc, 2, &split, 1, vDSP_Length(half))
+    }
+    vDSP_fft_zrip(fftSetup, &split, 1, log2N, FFTDirection(FFT_FORWARD))
+    // After the in-place real FFT, bin 0 holds DC in `realp[0]`
+    // and Nyquist in `imagp[0]`. We drop the Nyquist to keep
+    // length === n/2 (matches Android).
+    vDSP_zvmags(&split, 1, magsPtr, 1, vDSP_Length(half))
+
+    // sqrt + scale to one-sided amplitude (* 2/n). DC gets the
+    // same scaling — matches Android's RadixTwoFFT.magnitudes
+    // convention (documented "DC double-scaled" trade-off).
+    // vvsqrtf (vForce) + vDSP_vsmul vectorise on Apple silicon's NEON.
+    var halfCount = Int32(half)
+    vvsqrtf(outputPtr, magsPtr, &halfCount)
+    var scaleVar = Float(2) / Float(n)
+    vDSP_vsmul(outputPtr, 1, &scaleVar, outputPtr, 1, vDSP_Length(half))
+
+    // Single memcpy per emit at the bridge boundary — output goes
+    // directly into a Nitro ArrayBuffer; no `[Float]` Array
+    // intermediate. The ArrayBuffer is reference-counted + safe to
+    // hand across the dispatch boundary downstream.
+    let fftBytes = half * MemoryLayout<Float>.size
+    let fftBuffer = outputPtr.withMemoryRebound(to: UInt8.self, capacity: fftBytes) { rawPtr in
+      ArrayBuffer.copy(of: rawPtr, size: fftBytes)
+    }
+    let samplesBuffer: ArrayBuffer?
+    if let samples = samplesPtr {
+      let samplesBytes = n * MemoryLayout<Float>.size
+      samplesBuffer = samples.withMemoryRebound(to: UInt8.self, capacity: samplesBytes) {
+        rawPtr in
+        ArrayBuffer.copy(of: rawPtr, size: samplesBytes)
+      }
+    } else {
+      samplesBuffer = nil
+    }
+
+    onFrame(fftBuffer, samplesBuffer, sampleRate)
+  }
+}