From 19c2fb6ec9eea4a2f611734c1b8897cb36cfe693 Mon Sep 17 00:00:00 2001 From: Talon Date: Tue, 23 Jun 2026 15:40:54 +0200 Subject: [PATCH] fix(ios): pace mic feed with a prebuffer cushion to stop flutter/crackle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The iOS mic was unusable — a consistent ~40-60ms flutter + volume fade ('slow fan') on every preset. The core sends each captured frame synchronously (no send pacer), so packet cadence == capture cadence, and the receiver's playout keeps near-zero buffering by design (its jitter estimate keys off the regular sender timestamp, so it's blind to arrival jitter). That's smooth only for a steady sender (desktop miniaudio = steady 20ms); the iOS AVAudioEngine tap delivers ~2 frames per ~40ms callback -> bursty -> receiver underruns -> PLC fade. Fix (iOS-only): the mic tap writes converted 48kHz int16 to an SPSC ring; a 20ms feed pump drains it and calls feedPcm at a steady cadence. The pump primes a small prebuffer cushion (3 frames ~60ms, self-healing up to ~120ms on underrun) before releasing, so the tap's bursts can't drain it to empty. Never reads a partial frame (read consumes what it returns -> partials were the crackle), and rebuilds with the current channel count each rebuild() (a frozen count fed mono-as-stereo = octave-up on a Stereo->Voice Chat switch). Trade-off: ~60-120ms added mic-send latency, unavoidable when de-bursting for a near-zero-buffer receiver. PROGRESS.md notes the proper follow-up: make the jitter buffer measure real RFC-3550 arrival jitter so the receiver absorbs bursts itself. Verified: xcodebuild Debug BUILD SUCCEEDED (iOS Simulator, arm64). --- PROGRESS.md | 40 +++++ .../IOSVoiceProcessingEngine.swift | 145 ++++++++++++++++-- 2 files changed, 176 insertions(+), 9 deletions(-) diff --git a/PROGRESS.md b/PROGRESS.md index dc91dd9..43d0e11 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -10,6 +10,46 @@ up instantly. Newest status at the top. ## ▶ Where we left off / next action +- **[ ] Soon — jitter buffer should measure REAL arrival jitter (RFC 3550), not sender + timestamps.** `JitterBuffer::push` (`core/src/audio/audio_engine.cpp:84-108`) estimates + jitter from `gap = ts - last_push_ts_`, where `ts` is the **sender's timestamp** — which is + perfectly regular (`ls.timestamp += samples` every frame, independent of when the packet is + actually sent). So `diff` is always ~0, `jitter_est_` stays 0, and `target_depth_ms_` is + pinned at its ~20 ms floor. The buffer is therefore **blind to real network/arrival jitter + and to bursty senders** — it never deepens. Combined with the playout deliberately seeding + to near-zero depth (`on_playback`, ~line 715), the receiver tolerates only a *steady* + sender. This is exactly why the iOS mic needed a send-side pacing cushion (below) and why + genuine network jitter would also cause underruns. **Fix:** measure inter-arrival jitter + the RFC 3550 way — `D = (arrival_j - arrival_i) - (ts_j - ts_i)` using a wall-clock arrival + stamp captured in `push()` — and drive `target_depth_ms_` off that EWMA (keep the existing + marker/silence-gap outlier rejection). Then the receiver absorbs bursts itself and the iOS + send cushion could be reduced or removed. Shared-core change → add a test and re-verify + desktop↔desktop stays low-latency (steady sender ⇒ ~0 arrival jitter ⇒ no regression). + +- **Done (2026-06-23):** **Fixed iOS mic flutter / crackle / octave-up.** The iOS mic was + unusable: a consistent ~40–60 ms flutter with volume fade ("talking through a slow fan") on + every preset. Root cause: the core sends each captured frame **synchronously** + (`on_capture_frame` → `encode_and_send_frame`, no send pacer), so packet cadence == capture + cadence; and the receiver's playout keeps **near-zero buffering** by design and its jitter + estimate is blind to arrival timing (see RFC-3550 item above). That's smooth only for a + *steady* sender (desktop miniaudio = steady 20 ms), but the iOS `AVAudioEngine` input tap + delivers ~2 frames per ~40 ms callback (more under VPIO) → bursty → receiver underruns → PLC + fade. + - **Fix (iOS-only, `clients/apple/iOS/VoiceCatiOS/IOSVoiceProcessingEngine.swift`):** the + mic tap converts to 48 kHz int16 and writes a lock-free SPSC ring; a 20 ms feed pump + drains it and calls `feedPcm` at a **steady** cadence so packets leave the core every + 20 ms (what the receiver expects). The pump **primes a small prebuffer cushion** + (`PumpState.targetFrames`, 3 frames ≈ 60 ms, self-healing up to ~120 ms on underrun) + before releasing, so the tap's bursts can't drain it to empty. Two correctness rules + (each had bit us): never read a partial frame (`read` consumes what it returns → + discarding partials caused crackle), and rebuild the pump with the current channel count + every `rebuild()` (a frozen channel count fed mono-as-stereo = octave-up on a Stereo→Voice + Chat switch). Trade-off: ~60–120 ms added mic-send latency — unavoidable when de-bursting + for a near-zero-buffer receiver; the RFC-3550 fix above would let us shrink it. + - **Verify:** `xcodebuild` Debug **BUILD SUCCEEDED** (iOS Simulator, arm64). Audible test + requires a real device (simulator has no real mic route): mic should be smooth on Voice + Chat / Mono Mic / Stereo Mic, including switching presets while live (no octave). + - **Done (2026-06-23):** **Fixed Apple client link failure (stale xcframework missing RNNoise).** Both `VoiceCatMac` and `VoiceCatiOS` failed to link with `Undefined symbols for architecture arm64: _rnnoise_create / _rnnoise_destroy / _rnnoise_process_frame`. Root diff --git a/clients/apple/iOS/VoiceCatiOS/IOSVoiceProcessingEngine.swift b/clients/apple/iOS/VoiceCatiOS/IOSVoiceProcessingEngine.swift index 9e7908d..335974d 100644 --- a/clients/apple/iOS/VoiceCatiOS/IOSVoiceProcessingEngine.swift +++ b/clients/apple/iOS/VoiceCatiOS/IOSVoiceProcessingEngine.swift @@ -73,6 +73,16 @@ final class PCMRing { return n } + /// Consumer-side snapshot of how many interleaved int16 samples are currently buffered. Lets a + /// paced consumer check for a full frame *before* calling `read`, so it never reads (and thus + /// discards) a partial frame. Single consumer only (same thread that calls `read`). + var availableSamples: Int { + let r = readIdx + OSMemoryBarrier() + let w = writeIdx + return Int(w &- r) + } + /// Discard everything buffered — call before (re)starting so stale pre-roll isn't played. func reset() { OSMemoryBarrier(); readIdx = writeIdx } @@ -94,7 +104,9 @@ final class PCMRing { /// from it and renders through the engine output. This runs the whole time we're connected, /// so remote audio plays even before the user joins voice (no "can't hear anyone"). /// - **mic → core:** when the mic is active a tap on the input node converts to 48 kHz int16 and -/// calls `client.feedPcm(micStreamId)`. +/// writes to a pacing ring; a 20 ms timer releases steady 960-sample frames to +/// `client.feedPcm(micStreamId)`. The core sends each captured frame synchronously, so this +/// steady cadence is what keeps packets from bursting and fluttering the receiver's playout. /// /// Echo cancellation / noise suppression / AGC come from Apple's Voice-Processing I/O unit (VPIO), /// which `inputNode.setVoiceProcessingEnabled(true)` enables. VPIO forces mono, so it is engaged @@ -119,6 +131,45 @@ final class IOSAudioEngine { private var micStreamId: UInt32 = 0 private var captureChannels: UInt32 = 1 + // Mic feed pacing. The core sends each captured frame SYNCHRONOUSLY as it arrives + // (on_capture_frame → encode → sendto, client.cpp) — there is no send pacer in the core. On + // desktop miniaudio capture fires one 960-sample frame every 20 ms, so packets leave at a + // steady 20 ms. On iOS the AVAudioEngine input tap fires at the hardware IO-buffer period + // (often ~40 ms under VPIO), delivering ~2 frames at once: feeding those straight to the core + // bursts 2 packets out then goes quiet for ~40 ms, and the receiver's ~40 ms jitter buffer + // underruns on every gap → PLC fade ("talking through a slow fan" + ~40–60 ms flutter). + // + // Fix: pace the feed to a steady 20 ms. The tap converts to int16 and writes to a lock-free + // SPSC ring (producer, audio clock); a 20 ms timer releases ONE 960-sample frame per tick to + // feedPcm (consumer). The producer's average rate is locked to 48 kHz = exactly one frame per + // 20 ms, so it matches the consumer; the ring just absorbs the tap's 2-at-a-time bursts. + // + // Two correctness rules learned the hard way (these caused the earlier crackle + octave): + // 1. NEVER read a partial frame — `read` consumes whatever it returns, so reading <960 would + // silently discard those samples (crackle). The timer checks `availableSamples` first and + // only reads when a full frame is present; an underrun just skips the tick (nothing lost). + // 2. NEVER freeze the channel count in the timer — mono↔stereo preset switches change it. The + // timer is torn down and recreated inside `rebuild()`, so it always captures the current + // `captureChannels`; the ring is reset while the timer is stopped (no cross-thread race). + private let micRing = PCMRing(capacitySamples: 48000 * 2) // ~1 s stereo — ample elastic slack + private var micTimer: DispatchSourceTimer? + private let micQueue = DispatchQueue(label: "cat.voice.mic.feedPump") + private let micDrainScratch: UnsafeMutablePointer + private static let micFrameSamplesPerChannel = 960 // 20 ms @ 48 kHz — core's frame size + + /// Feed-pump state, touched only on `micQueue` (the pump's serial queue). A reference type so + /// the timer closure mutates it without capturing `self` (which is @MainActor). `targetFrames` + /// is the prebuffer depth: the pump fills this many frames before it starts releasing, so the + /// tap's bursty delivery (~2 frames at once) can't drain it to empty between bursts. It persists + /// across rebuilds and self-heals upward (capped) on an underrun, so it tunes to whatever IO + /// buffer size the active route/VPIO actually uses without a hard-coded guess. + private final class PumpState { + var primed = false + var targetFrames = 3 // ~60 ms initial cushion; grows on underrun up to maxTargetFrames + static let maxTargetFrames = 6 // ~120 ms cap — bounds added latency + } + private let pumpState = PumpState() + // 48 kHz stereo Float32 (deinterleaved) — the format the source node renders. The core // delivers 48 kHz stereo int16 via the mixed-output sink; mainMixerNode adapts to the route. private let outFormat = AVAudioFormat( @@ -134,6 +185,8 @@ final class IOSAudioEngine { private init() { renderScratch = UnsafeMutablePointer.allocate(capacity: renderScratchFrames * 2) renderScratch.initialize(repeating: 0, count: renderScratchFrames * 2) + micDrainScratch = UnsafeMutablePointer.allocate(capacity: 960 * 2) + micDrainScratch.initialize(repeating: 0, count: 960 * 2) } // MARK: - Lifecycle @@ -164,6 +217,7 @@ final class IOSAudioEngine { func stop() { guard isConnected else { return } micActive = false + stopMicTimer() isConnected = false client?.setMixedOutputSink(nil, user: nil) engine.inputNode.removeTap(onBus: 0) @@ -175,6 +229,7 @@ final class IOSAudioEngine { sourceNode = nil } ring.reset() + micRing.reset() client = nil } @@ -219,6 +274,9 @@ final class IOSAudioEngine { /// AVAudioSession config (category/mode/route) first (`IOSAudioRouter.applyConfiguration`). private func rebuild() { guard isConnected else { return } + // Stop the feed pump before touching the tap / ring so the timer (on micQueue) can't race + // the ring reset in installMicTap. It is restarted at the end with the current channel count. + stopMicTimer() if engine.isRunning { engine.stop() } engine.inputNode.removeTap(onBus: 0) @@ -252,6 +310,10 @@ final class IOSAudioEngine { } catch { logger.error("engine start failed: \(error.localizedDescription)") } + + // Start the feed pump last, with the current channel count, so it never carries a stale + // (frozen) channel count across a mono↔stereo switch. + if micActive { startMicTimer() } } /// Detach any previous source node and attach a fresh one pulling mixed PCM from the ring. @@ -286,10 +348,17 @@ final class IOSAudioEngine { } /// Install the mic tap: convert the input node's native format to 48 kHz int16 (mono or - /// stereo per `captureChannels`) and feed it to the core. Rebuilds the converter each time - /// because the input format depends on the VPIO state and the active route. + /// stereo per `captureChannels`) and write it to the pacing ring. The 20 ms feed pump + /// (`startMicTimer`) releases steady 960-sample frames to `feedPcm` — see the mic-feed comment + /// above for why the tap must NOT call feedPcm directly (it bursts packets → receiver flutter). + /// Rebuilds the converter each time because the input format depends on the VPIO state and the + /// active route. private func installMicTap() { - guard let client else { return } + guard client != nil else { return } + // Fresh ring on every (re)install — a rebuild must not feed stale pre-roll into the new tap. + // Safe here: the feed pump was stopped at the top of rebuild(), so no consumer is running. + micRing.reset() + let ring = micRing // captured by the closure as a `let` — no self capture (see mic-feed comment) let inFormat = engine.inputNode.outputFormat(forBus: 0) guard inFormat.sampleRate > 0 else { logger.error("input format unavailable (\(inFormat)) — mic will not transmit") @@ -303,8 +372,7 @@ final class IOSAudioEngine { return } - let sid = micStreamId - let c = client + let chInt = Int(targetCh) engine.inputNode.installTap(onBus: 0, bufferSize: 960, format: inFormat) { buffer, _ in // Convert this tap buffer to 48 kHz int16. Output capacity scaled for any upsample. let ratio = target.sampleRate / buffer.format.sampleRate @@ -319,9 +387,68 @@ final class IOSAudioEngine { } guard status != .error, outBuf.frameLength > 0, let chData = outBuf.int16ChannelData else { return } - // int16 interleaved → channelData[0] is the interleaved buffer. - c.feedPcm(streamId: sid, pcm: chData[0], - samplesPerChannel: Int(outBuf.frameLength), channels: targetCh) + // int16 interleaved → channelData[0] is the interleaved buffer. Write the converter's + // variable-length output to the pacing ring; the 20 ms feed pump releases steady + // 960-sample frames to feedPcm so packets leave the core at a steady 20 ms cadence. + ring.write(chData[0], count: Int(outBuf.frameLength) * chInt) } } + + // MARK: - Mic feed pump (paces feedPcm at a steady 20 ms cadence) + + /// Start the 20 ms feed pump. After priming a small cushion (`pumpState.targetFrames`), it + /// releases ONE 960-sample frame per tick from `micRing` to `feedPcm`, so the core (which sends + /// synchronously per captured frame) emits packets at a steady 20 ms — the cadence its receivers + /// expect. The cushion is essential: the receiver's playout deliberately keeps near-zero + /// buffering (low latency), so it tolerates a steady stream but not bursts; the iOS tap delivers + /// ~2 frames at once, and without the cushion the pump runs at ~0 depth and underruns on every + /// tap/timer phase beat (crackle). Recreated on every `rebuild()` so `ch` always reflects the + /// current `captureChannels` (mono↔stereo switches). Captures only locals + the reference-type + /// ring/client/state (no `self`, which is @MainActor). + private func startMicTimer() { + stopMicTimer() + guard let client else { return } + let ring = micRing + let scratch = micDrainScratch + let state = pumpState + let sid = micStreamId + let ch = max(1, min(2, Int(captureChannels))) + let frameSamples = Self.micFrameSamplesPerChannel + let full = frameSamples * ch + let chU32 = UInt32(ch) + // The ring was just reset in installMicTap, so the cushion must be refilled before sending. + state.primed = false + let feed: () -> Void = { + _ = ring.read(into: scratch, count: full) // caller guarantees a full frame is present + _ = client.feedPcm(streamId: sid, pcm: scratch, + samplesPerChannel: frameSamples, channels: chU32) + } + let t = DispatchSource.makeTimerSource(queue: micQueue) + t.schedule(deadline: .now(), repeating: .milliseconds(20), leeway: .milliseconds(2)) + t.setEventHandler { + let frames = ring.availableSamples / full // whole frames currently buffered + if !state.primed { + if frames < state.targetFrames { return } // still filling the cushion (into silence) + state.primed = true + } else if frames == 0 { + // Underrun: the cushion drained. Grow it (capped) so it won't recur, then re-prime. + // Never read a partial frame — `read` consumes what it returns, so that would + // discard samples (the old crackle bug); skipping loses nothing, the samples wait. + if state.targetFrames < PumpState.maxTargetFrames { state.targetFrames += 1 } + state.primed = false + return + } + feed() // one steady frame per tick (frames >= 1 here) + // Catch-up: if the backlog grew past the cushion (pump descheduled, or producer ran + // ahead via a burst), release one extra frame to drain it and keep latency bounded. + if frames - 1 > state.targetFrames + 1 { feed() } + } + t.resume() + micTimer = t + } + + private func stopMicTimer() { + micTimer?.cancel() + micTimer = nil + } }