react-native-queue-player 1.0.0

package/ios/Tests/EqualizerHybridTests.swift

@@ -0,0 +1,303 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Wiring coverage for the iOS `Equalizer` HybridObject.
+/// Targets the synchronous internal core; the async Promise-
+/// returning surface is exercised at integration via the demo
+/// Maestro EQ suite.
+final class EqualizerHybridTests: XCTestCase {
+
+  private var defaults: UserDefaults!
+  private var suiteName: String!
+
+  override func setUp() {
+    super.setUp()
+    suiteName = "test.equalizerHybrid.\(UUID().uuidString)"
+    defaults = UserDefaults(suiteName: suiteName)!
+  }
+
+  override func tearDown() {
+    defaults.removePersistentDomain(forName: suiteName)
+    defaults = nil
+    suiteName = nil
+    super.tearDown()
+  }
+
+  private func makeEqualizer() -> Equalizer {
+    return Equalizer(
+      provider: AudioTapProvider(),
+      presetStore: CustomPresetStore(defaults: defaults)
+    )
+  }
+
+  func testInitialStateIsDisabledWithFlatGains() {
+    let eq = makeEqualizer()
+    XCTAssertFalse(try eq.isEnabled())
+    let bands = try! eq.getBands()
+    XCTAssertEqual(10, bands.count)
+    XCTAssertTrue(bands.allSatisfy { $0.gainDb == 0 })
+  }
+
+  func testGetPresetsReturns16BuiltinsWhenNoCustom() {
+    let eq = makeEqualizer()
+    let presets = try! eq.getPresets()
+    XCTAssertEqual(16, presets.count)
+    XCTAssertTrue(presets.allSatisfy { $0.builtin })
+  }
+
+  func testApplyPresetInternalRockUpdatesBandGains() {
+    let eq = makeEqualizer()
+    XCTAssertTrue(eq.applyPresetInternal(name: "Rock"))
+    let bands = try! eq.getBands()
+    XCTAssertEqual(5.0, bands[0].gainDb, accuracy: 0.0001)
+    XCTAssertEqual(3.0, bands[1].gainDb, accuracy: 0.0001)
+  }
+
+  func testApplyPresetInternalUnknownNameIsNoOp() {
+    let eq = makeEqualizer()
+    XCTAssertFalse(eq.applyPresetInternal(name: "DoesNotExist"))
+    let bands = try! eq.getBands()
+    XCTAssertTrue(bands.allSatisfy { $0.gainDb == 0 })
+  }
+
+  func testApplyPresetUnknownNameRejectsPromise() async throws {
+    let eq = makeEqualizer()
+    let promise = try eq.applyPreset(name: "Bogus")
+    do {
+      _ = try await promise.await()
+      XCTFail("expected applyPreset(\"Bogus\") to reject")
+    } catch {
+      XCTAssertTrue(
+        "\(error)".contains("Equalizer preset not found: Bogus"),
+        "unexpected error message: \(error)"
+      )
+    }
+  }
+
+  func testSaveCustomPresetRejectsBuiltinName() async throws {
+    let eq = makeEqualizer()
+    let promise = try eq.saveCustomPreset(name: "Flat")
+    do {
+      _ = try await promise.await()
+      XCTFail("expected saveCustomPreset(\"Flat\") to reject")
+    } catch {
+      XCTAssertTrue(
+        "\(error)".contains("Cannot overwrite built-in preset: Flat"),
+        "unexpected error message: \(error)"
+      )
+    }
+  }
+
+  func testSetBandGainInternalRoutesToProvider() {
+    let eq = makeEqualizer()
+    eq.setBandGainInternal(index: 3, gainDb: 5)
+    XCTAssertEqual(5.0, try! eq.getBands()[3].gainDb, accuracy: 0.0001)
+    // Provider master state should reflect the same gain.
+    XCTAssertEqual(5.0, eq.provider.getGains()[3], accuracy: 0.0001)
+  }
+
+  func testSetBandGainInternalClampsOutOfSpec() {
+    let eq = makeEqualizer()
+    eq.setBandGainInternal(index: 0, gainDb: 99)
+    eq.setBandGainInternal(index: 1, gainDb: -99)
+    let bands = try! eq.getBands()
+    XCTAssertEqual(12.0, bands[0].gainDb, accuracy: 0.0001)
+    XCTAssertEqual(-12.0, bands[1].gainDb, accuracy: 0.0001)
+  }
+
+  func testSetEnabledInternalMirrorsProviderAndFiresListeners() {
+    let eq = makeEqualizer()
+    var received: [Bool] = []
+    // Registration auto-fires once with current state (default false).
+    _ = try! eq.onEnabledChange { received.append($0) }
+    received.removeAll()
+    eq.setEnabledInternal(true)
+    eq.setEnabledInternal(false)
+    XCTAssertEqual([true, false], received)
+    XCTAssertFalse(eq.provider.isEnabledSnapshot())
+  }
+
+  func testSetEnabledInternalIdempotentDoesNotFire() {
+    let eq = makeEqualizer()
+    var received: [Bool] = []
+    _ = try! eq.onEnabledChange { received.append($0) }
+    // Discard the auto-fire-on-registration entry.
+    received.removeAll()
+    eq.setEnabledInternal(false)
+    XCTAssertEqual([], received)
+  }
+
+  func testOnBandChangeFiresWithSnapshotOnMutation() {
+    let eq = makeEqualizer()
+    var fired: [EqualizerBand]?
+    _ = try! eq.onBandChange { fired = $0 }
+    eq.setBandGainInternal(index: 0, gainDb: 4)
+    XCTAssertEqual(10, fired?.count)
+    XCTAssertEqual(4.0, fired?[0].gainDb ?? 0, accuracy: 0.0001)
+  }
+
+  func testCurrentReferencePublishedOnConstruction() {
+    let eq = makeEqualizer()
+    XCTAssertTrue(Equalizer.current === eq)
+  }
+
+  func testApplyPresetInternalAppliesCustomPresetByName() async throws {
+    let eq = makeEqualizer()
+    // Seed the band gains we want the saved preset to capture, then
+    // persist them under a known custom name via the public async
+    // surface (matches how JS callers reach `saveCustomPreset`).
+    eq.setBandGainInternal(index: 0, gainDb: 6)
+    eq.setBandGainInternal(index: 5, gainDb: -3)
+    _ = try await eq.saveCustomPreset(name: "TestEqualizerSuite").await()
+    // Mutate the live gains so we can prove the apply restores the
+    // saved snapshot rather than reading back a stale buffer.
+    eq.setBandGainInternal(index: 0, gainDb: 0)
+    eq.setBandGainInternal(index: 5, gainDb: 0)
+    XCTAssertTrue(eq.applyPresetInternal(name: "TestEqualizerSuite"))
+    let bands = try eq.getBands()
+    XCTAssertEqual(6.0, bands[0].gainDb, accuracy: 0.0001)
+    XCTAssertEqual(-3.0, bands[5].gainDb, accuracy: 0.0001)
+  }
+
+  // MARK: - Engine refresh wiring
+
+  /// Wiring the EQ to a PlaybackEngine MUST also register the
+  /// provider with the engine. The audible-EQ path on iOS depends
+  /// on this so the engine knows whom to ask for `audioMix(for:)`.
+  func testWireToPlaybackEngineRegistersProvider() {
+    let eq = makeEqualizer()
+    let stub = RecordingEngineStub()
+    eq.wireToPlaybackEngine(stub)
+    XCTAssertTrue(stub.lastSetProvider === eq.provider)
+  }
+
+  /// When the user toggles EQ enabled, currently-playing
+  /// AVPlayerItems must have their audioMix re-attached. Without
+  /// this, the active track keeps its previously-nil audioMix and
+  /// the listener hears no change. The Equalizer dispatches the
+  /// refresh on the main queue, so the test waits for that hop.
+  func testSetEnabledTriggersEngineRefresh() {
+    let eq = makeEqualizer()
+    let stub = RecordingEngineStub()
+    eq.wireToPlaybackEngine(stub)
+    let initialRefreshCount = stub.refreshCount
+    let exp = expectation(description: "refresh fires for setEnabled true")
+    stub.onRefresh = { exp.fulfill() }
+    eq.setEnabledInternal(true)
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertGreaterThan(stub.refreshCount, initialRefreshCount)
+  }
+
+  /// Band-gain mutations route to the active item via the
+  /// provider's gains-version bump — the running tap recomputes
+  /// coefficients on its next render call. Detaching/reattaching
+  /// the audioMix on every slider tick would cause an audible
+  /// cutout, so the engine refresh path is reserved for the
+  /// enable transition.
+  func testSetBandGainDoesNotTriggerEngineRefresh() {
+    let eq = makeEqualizer()
+    let stub = RecordingEngineStub()
+    eq.wireToPlaybackEngine(stub)
+    let initialRefreshCount = stub.refreshCount
+    eq.setBandGainInternal(index: 4, gainDb: -6)
+    let exp = expectation(description: "drain main queue")
+    DispatchQueue.main.async { exp.fulfill() }
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertEqual(stub.refreshCount, initialRefreshCount)
+  }
+
+  /// `setAllBandGainsInternal` (the path under preset apply + reset)
+  /// also avoids the engine refresh — same gains-version mechanism
+  /// keeps the active tap in sync without rebuilding the audioMix.
+  func testSetAllBandGainsDoesNotTriggerEngineRefresh() {
+    let eq = makeEqualizer()
+    let stub = RecordingEngineStub()
+    eq.wireToPlaybackEngine(stub)
+    let initialRefreshCount = stub.refreshCount
+    eq.setAllBandGainsInternal([3, 3, 3, 3, 3, 3, 3, 3, 3, 3])
+    let exp = expectation(description: "drain main queue")
+    DispatchQueue.main.async { exp.fulfill() }
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertEqual(stub.refreshCount, initialRefreshCount)
+  }
+
+  /// Each band-gain mutation bumps the provider's monotonic gains
+  /// version so per-item taps know to recompute coefficients on
+  /// their next render call.
+  func testSetBandGainBumpsProviderVersion() {
+    let eq = makeEqualizer()
+    let initial = eq.provider.gainsSnapshot().version
+    eq.setBandGainInternal(index: 2, gainDb: 4)
+    let after = eq.provider.gainsSnapshot().version
+    XCTAssertGreaterThan(after, initial)
+  }
+
+  /// Idempotent setEnabled (false → false) is a no-op and must NOT
+  /// pay the refresh cost — keeps the path cheap when the JS
+  /// surface fires redundant toggles during reload.
+  func testIdempotentSetEnabledDoesNotRefresh() {
+    let eq = makeEqualizer()
+    let stub = RecordingEngineStub()
+    eq.wireToPlaybackEngine(stub)
+    let initial = stub.refreshCount
+    eq.setEnabledInternal(false)
+    // No expectation here — assert the count is unchanged after a
+    // brief main-queue drain so any spurious dispatch would land.
+    let exp = expectation(description: "drain main queue")
+    DispatchQueue.main.async { exp.fulfill() }
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertEqual(stub.refreshCount, initial)
+  }
+}
+
+/// Counts `setAudioMixProvider` + `refreshAllItemMixes` calls so
+/// the wiring tests above can assert the EQ drives the engine.
+/// All other PlaybackEngine methods are no-op stubs.
+private final class RecordingEngineStub: PlaybackEngine {
+  var lastSetProvider: AudioMixProvider?
+  var refreshCount: Int = 0
+  var onRefresh: (() -> Void)?
+
+  func prepare(items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) async {}
+  func release() {}
+  func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {}
+  @discardableResult
+  func insertItems(_ items: [AVPlayerItem], after: AVPlayerItem?) -> Bool { true }
+  func remove(_ item: AVPlayerItem) {}
+  func removeAllItems() {}
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool { true }
+  func play() {}
+  func pause() {}
+  func stop() {}
+  func seek(toIndex index: Int, position: TimeInterval) {}
+  func skipToNext() {}
+  func skipToPrevious() {}
+  func setVolume(_ volume: Float) {}
+  func setPlaybackSpeed(_ speed: Float) {}
+  func seedPlaybackSpeed(_ speed: Float) {}
+  func setRepeatMode(_ mode: RepeatMode) {}
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {}
+
+  var currentMediaItemIndex: Int { -1 }
+  var currentPositionSeconds: TimeInterval { 0 }
+  var currentDurationSeconds: TimeInterval { 0 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var isPlaying: Bool { false }
+  var timeControlStatus: AVPlayer.TimeControlStatus { .paused }
+  var currentMediaItem: AVPlayerItem? { nil }
+  var allMediaItems: [AVPlayerItem] { [] }
+
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {
+    lastSetProvider = provider
+  }
+
+  func refreshAllItemMixes() {
+    refreshCount += 1
+    onRefresh?()
+  }
+
+  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async {}
+
+  var delegate: PlaybackEngineDelegate?
+}

package/ios/Tests/EqualizerPresetsTests.swift

@@ -0,0 +1,69 @@
+import XCTest
+@testable import QueuePlayer
+
+final class EqualizerPresetsTests: XCTestCase {
+
+  private static let expectedOrderedNames: [String] = [
+    "Flat",
+    "Reference",
+    "Bass Boost",
+    "Bass Reducer",
+    "Treble Boost",
+    "Treble Reducer",
+    "V-Shaped",
+    "Vocal Boost",
+    "Spoken Word",
+    "Late Night",
+    "Acoustic",
+    "Rock",
+    "Hip-Hop",
+    "Small Speakers",
+    "Jazz",
+    "Electronic",
+  ]
+
+  func testFrequenciesSpanTenISOBands() {
+    XCTAssertEqual(
+      [31, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000],
+      EqualizerPresets.frequencies
+    )
+  }
+
+  func testGetNamesReturnsSixteenEntriesInCanonicalDisplayOrder() {
+    let names = EqualizerPresets.getNames()
+    XCTAssertEqual(16, names.count)
+    XCTAssertEqual(Self.expectedOrderedNames, names)
+  }
+
+  func testEveryPresetHasTenBands() {
+    for name in EqualizerPresets.getNames() {
+      let gains = EqualizerPresets.getByName(name)
+      XCTAssertEqual(10, gains?.count, "Preset '\(name)' must have 10 bands")
+    }
+  }
+
+  func testFlatPresetIsAllZeroGains() {
+    let flat = EqualizerPresets.getByName("Flat")
+    XCTAssertEqual(Array(repeating: 0.0, count: 10), flat)
+  }
+
+  func testGetByNameReturnsNilForUnknownPreset() {
+    XCTAssertNil(EqualizerPresets.getByName("Nonexistent"))
+  }
+
+  func testRockPresetGainsMatchTheRBJTable() {
+    let rock = EqualizerPresets.getByName("Rock")!
+    let expected: [Double] = [5.0, 3.0, -2.0, -3.0, -1.0, 2.0, 4.0, 5.0, 5.0, 5.0]
+    for (i, e) in expected.enumerated() {
+      XCTAssertEqual(e, rock[i], accuracy: 0.0001)
+    }
+  }
+
+  func testTrebleBoostPresetGainsMatchTheRBJTable() {
+    let tb = EqualizerPresets.getByName("Treble Boost")!
+    let expected: [Double] = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 2.0, 4.0, 5.0, 6.0]
+    for (i, e) in expected.enumerated() {
+      XCTAssertEqual(e, tb[i], accuracy: 0.0001)
+    }
+  }
+}

package/ios/Tests/FFTProcessorTests.swift

@@ -0,0 +1,303 @@
+import Accelerate
+import XCTest
+import NitroModules
+@testable import QueuePlayer
+
+/// Unit coverage for the iOS vDSP-backed `FFTProcessor`. Synthesises
+/// inputs with known spectra and asserts the magnitude bins land
+/// where they should — same contract as Android's `RadixTwoFFTTest`.
+final class FFTProcessorTests: XCTestCase {
+
+  private func arrayBufferToFloats(_ buffer: ArrayBuffer) -> [Float] {
+    let count = buffer.size / MemoryLayout<Float>.size
+    let raw = buffer.data
+    return raw.withMemoryRebound(to: Float.self, capacity: count) { ptr in
+      Array(UnsafeBufferPointer(start: ptr, count: count))
+    }
+  }
+
+  func testEmitsAFrameOnceEnoughSamplesLand() throws {
+    let exp = expectation(description: "frame emitted")
+    var capturedSampleRate: Double = 0
+    let proc = try FFTProcessor(
+      fftSize: 256, intervalMs: 1, includeSamples: false,
+    ) { _, _, sampleRate in
+      capturedSampleRate = sampleRate
+      exp.fulfill()
+    }
+    let n = 256
+    var samples = [Float](repeating: 0, count: n)
+    for i in 0..<n {
+      samples[i] = sin(2.0 * .pi * 8 * Float(i) / Float(n))
+    }
+    samples.withUnsafeBufferPointer { p in
+      proc.ingest(samples: p.baseAddress!, frameCount: n, sampleRate: 48000)
+    }
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertEqual(capturedSampleRate, 48000, accuracy: 0.001)
+  }
+
+  func testDoesNotEmitUntilFftSizeSamplesAccumulate() throws {
+    var calls = 0
+    let proc = try FFTProcessor(
+      fftSize: 512, intervalMs: 1, includeSamples: false,
+    ) { _, _, _ in calls += 1 }
+    let half = [Float](repeating: 0, count: 256)
+    half.withUnsafeBufferPointer { p in
+      proc.ingest(samples: p.baseAddress!, frameCount: 256, sampleRate: 44100)
+    }
+    XCTAssertEqual(calls, 0, "halfway full ring should not emit")
+    let rest = [Float](repeating: 0.1, count: 256)
+    rest.withUnsafeBufferPointer { p in
+      proc.ingest(samples: p.baseAddress!, frameCount: 256, sampleRate: 44100)
+    }
+    // The callback hops to main; spin the run loop to give it a chance.
+    let exp = expectation(description: "emit landed")
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { exp.fulfill() }
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertEqual(calls, 1)
+  }
+
+  func testIncludeSamplesPopulatesSamplesPayload() throws {
+    var capturedSamples: ArrayBuffer?
+    let exp = expectation(description: "frame emitted")
+    let proc = try FFTProcessor(
+      fftSize: 128, intervalMs: 1, includeSamples: true,
+    ) { _, samples, _ in
+      capturedSamples = samples
+      exp.fulfill()
+    }
+    let buffer = [Float](repeating: 0.5, count: 128)
+    buffer.withUnsafeBufferPointer { p in
+      proc.ingest(samples: p.baseAddress!, frameCount: 128, sampleRate: 44100)
+    }
+    wait(for: [exp], timeout: 1.0)
+    let samples = try XCTUnwrap(capturedSamples)
+    XCTAssertEqual(samples.size, 128 * MemoryLayout<Float>.size)
+  }
+
+  func testIncludeSamplesFalseLeavesSamplesNil() throws {
+    var capturedSamples: ArrayBuffer?
+    var captured = false
+    let exp = expectation(description: "frame emitted")
+    let proc = try FFTProcessor(
+      fftSize: 128, intervalMs: 1, includeSamples: false,
+    ) { _, samples, _ in
+      capturedSamples = samples
+      captured = true
+      exp.fulfill()
+    }
+    let buffer = [Float](repeating: 0.5, count: 128)
+    buffer.withUnsafeBufferPointer { p in
+      proc.ingest(samples: p.baseAddress!, frameCount: 128, sampleRate: 44100)
+    }
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertTrue(captured)
+    XCTAssertNil(capturedSamples)
+  }
+
+  func testPureSinePeaksAtExpectedBin() throws {
+    var capturedFft: ArrayBuffer?
+    let exp = expectation(description: "frame emitted")
+    let n = 256
+    let k = 8
+    let proc = try FFTProcessor(
+      fftSize: n, intervalMs: 1, includeSamples: false,
+    ) { fft, _, _ in
+      capturedFft = fft
+      exp.fulfill()
+    }
+    var samples = [Float](repeating: 0, count: n)
+    for i in 0..<n {
+      samples[i] = cos(2.0 * .pi * Float(k) * Float(i) / Float(n))
+    }
+    samples.withUnsafeBufferPointer { p in
+      proc.ingest(samples: p.baseAddress!, frameCount: n, sampleRate: 48000)
+    }
+    wait(for: [exp], timeout: 1.0)
+    let fft = try XCTUnwrap(capturedFft)
+    let mags = arrayBufferToFloats(fft)
+    let peakBin = mags.indices.max(by: { mags[$0] < mags[$1] }) ?? -1
+    XCTAssertEqual(peakBin, k, "peak should land at bin \(k)")
+    // The Hann window's main lobe spans ~3 bins, so immediate
+    // neighbours of the peak carry ~50% of the peak energy. Test
+    // that everything OUTSIDE the main lobe (k-1 .. k+1) is far
+    // below the peak.
+    for i in mags.indices {
+      if i >= k - 1 && i <= k + 1 { continue }
+      XCTAssertLessThan(
+        mags[i], mags[k] / 50,
+        "bin \(i) (\(mags[i])) should be far below bin \(k) (\(mags[k]))",
+      )
+    }
+  }
+
+  func testStereoInputProducesArithmeticMonoMix() throws {
+    // Drive the EQProcessor's tap closure with two deinterleaved
+    // buffers (channel 0 = +0.5, channel 1 = -0.3). The closure
+    // collapses the post-EQ buffers into `(L+R)/2 = +0.1` and hands
+    // a single mono frame to `Visualizer.deliverAudioFrame`. With
+    // band gains all zero the cascade is identity, so the mono mix
+    // is the arithmetic mean of the two channel inputs.
+    //
+    // Verification path: subscribe a real `FFTProcessor` via
+    // `Visualizer.subscribe(includeSamples:)`. The captured samples
+    // payload is the raw pre-window mono-mix PCM, so every bin
+    // must equal +0.1 directly.
+    // Construct an isolated AudioTapProvider for this test so a
+    // shared-singleton subscription elsewhere can't tear samples
+    // we're capturing here. Both the Visualizer and the EQProcessor
+    // route through this same provider — the visualizer registers as
+    // a consumer, and the processor delivers frames into the
+    // provider's fan-out.
+    let priorVisualizer = Visualizer.current
+    let provider = AudioTapProvider()
+    let viz = Visualizer(provider: provider)
+    Visualizer.current = viz
+    addTeardownBlock {
+      Visualizer.current = priorVisualizer
+    }
+
+    let n = 256
+    let exp = expectation(description: "frame emitted")
+    var capturedSamples: ArrayBuffer?
+    let dispose = try viz.subscribe(
+      config: VisualizerConfig(
+        fftSize: Double(n), updateIntervalMs: 1, includeSamples: true,
+      ),
+      onFrame: { frame in
+        capturedSamples = frame.samples
+        exp.fulfill()
+      },
+      onError: { _ in },
+    )
+
+    let proc = EQProcessor(provider: provider)
+    proc.setSampleRate(48_000)
+    proc.setChannelCount(2)
+    proc.setBandGains(Array(repeating: 0, count: 10))
+    // `tapPrepare` is what the live tap fires from
+    // `MTAudioProcessingTapPrepareCallback`; the test invokes it
+    // directly to set up the mono-mix scratch ahead of the
+    // render-thread closure body.
+    proc.tapPrepare(maxFrames: n)
+    let closure = proc.tapProcessClosure()
+
+    let leftIn = UnsafeMutablePointer<Float>.allocate(capacity: n)
+    let leftOut = UnsafeMutablePointer<Float>.allocate(capacity: n)
+    let rightIn = UnsafeMutablePointer<Float>.allocate(capacity: n)
+    let rightOut = UnsafeMutablePointer<Float>.allocate(capacity: n)
+    defer {
+      leftIn.deallocate()
+      leftOut.deallocate()
+      rightIn.deallocate()
+      rightOut.deallocate()
+    }
+    for i in 0..<n {
+      leftIn[i] = 0.5
+      rightIn[i] = -0.3
+      leftOut[i] = -99
+      rightOut[i] = -99
+    }
+    closure(leftIn, leftOut, n, 1, 0, 2)
+    closure(rightIn, rightOut, n, 1, 1, 2)
+
+    wait(for: [exp], timeout: 1.0)
+    let samples = try XCTUnwrap(capturedSamples)
+    XCTAssertEqual(samples.size, n * MemoryLayout<Float>.size)
+
+    let count = samples.size / MemoryLayout<Float>.size
+    let recovered = samples.data.withMemoryRebound(to: Float.self, capacity: count) { ptr in
+      Array(UnsafeBufferPointer(start: ptr, count: count))
+    }
+    for i in 0..<n {
+      XCTAssertEqual(recovered[i], 0.1, accuracy: 1e-4,
+        "samples[\(i)] should be the raw +0.1 mono mix")
+    }
+
+    dispose()
+  }
+
+  func testIntervalThrottlesBackToBackEmissions() throws {
+    var calls = 0
+    let proc = try FFTProcessor(
+      fftSize: 64, intervalMs: 1000, includeSamples: false,
+    ) { _, _, _ in calls += 1 }
+    let buffer = [Float](repeating: 0.25, count: 64)
+    buffer.withUnsafeBufferPointer { p in
+      proc.ingest(samples: p.baseAddress!, frameCount: 64, sampleRate: 48000)
+      proc.ingest(samples: p.baseAddress!, frameCount: 64, sampleRate: 48000)
+    }
+    let exp = expectation(description: "drained")
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { exp.fulfill() }
+    wait(for: [exp], timeout: 1.0)
+    XCTAssertEqual(calls, 1, "second back-to-back call must be throttled")
+  }
+
+  func testFrameEmissionResumesAfterIngestQuietWindow() throws {
+    // Contract: a quiet window (no `ingest` calls) does NOT leave the
+    // processor in a state that suppresses subsequent emits — once
+    // `ingest` resumes, `onFrame` fires again at the documented
+    // intervalMs cadence. Live audio chains express "pause" by
+    // ceasing tap callbacks; the unit-test analogue is a sleep
+    // window. End-to-end pause/play coverage lives in the
+    // `visualizer:*` integration suite's `pause-stops-resume-restarts`
+    // step.
+    let n = 256
+    let intervalMs = 1
+    let lock = NSLock()
+    var frames = 0
+    let proc = try FFTProcessor(
+      fftSize: n,
+      intervalMs: intervalMs,
+      includeSamples: false,
+    ) { _, _, _ in
+      lock.lock(); frames += 1; lock.unlock()
+    }
+
+    let buffer = UnsafeMutablePointer<Float>.allocate(capacity: n)
+    defer { buffer.deallocate() }
+    for i in 0..<n {
+      buffer[i] = sin(Float(i) * 0.05)
+    }
+
+    // Steady-state pre-pause: each `ingest` emits at most once per
+    // `intervalMs` window, so back-to-back calls with millisecond-
+    // scale sleeps drive a measurable cadence.
+    for _ in 0..<8 {
+      proc.ingest(samples: buffer, frameCount: n, sampleRate: 48_000)
+      Thread.sleep(forTimeInterval: 0.005)
+    }
+    let framesBeforePause = readFrames(lock: lock, frames: &frames)
+    XCTAssertGreaterThan(
+      framesBeforePause, 0,
+      "steady-state delivery should produce at least one frame",
+    )
+
+    // Pause: stop calling `ingest`. Wait well past the interval —
+    // no new frames should land.
+    Thread.sleep(forTimeInterval: 0.020)
+    let framesAfterPause = readFrames(lock: lock, frames: &frames)
+    XCTAssertEqual(
+      framesAfterPause, framesBeforePause,
+      "frame count must not advance while delivery is paused",
+    )
+
+    // Resume: deliver again. The next interval window must produce
+    // at least one new frame.
+    for _ in 0..<8 {
+      proc.ingest(samples: buffer, frameCount: n, sampleRate: 48_000)
+      Thread.sleep(forTimeInterval: 0.005)
+    }
+    let framesAfterResume = readFrames(lock: lock, frames: &frames)
+    XCTAssertGreaterThan(
+      framesAfterResume, framesAfterPause,
+      "frame count must advance once delivery resumes",
+    )
+  }
+
+  private func readFrames(lock: NSLock, frames: inout Int) -> Int {
+    lock.lock(); defer { lock.unlock() }
+    return frames
+  }
+}