feat(enhancement): LocalVQE echo cancellation + noise suppression (beta)

[Alex-Wengg]

Closes the LocalVQE request in #49 (#49 (comment)).

Core ML port of LocalVQE (Apache-2.0): joint acoustic echo cancellation + noise suppression + dereverberation for 16 kHz speech. Models on HF at FluidInference/localvqe-coreml; conversion in mobius (FluidInference/mobius PR: feat/localvqe-coreml).

• LocalVqeManager (whole-clip / file) and LocalVqeStream (push any buffer size, 16 ms algorithmic latency, sample-aligned + length-preserving after flush()); state tensors discovered from the model description and fed back call to call
• v1.3 (4.8M, default) and v1.2 (1.3M) checkpoints, each as a 256 ms and a 16 ms chunk export; identical audio, different per-call overhead
• CLI fluidaudiocli enhance mic.wav --reference speaker.wav --output clean.wav (--streaming reports per-call latency, --model-dir loads local bundles)
• Docs: Documentation/Enhancement/LocalVQE.md, README / Models.md / CLI.md entries; tests skip in CI and when the bundle is absent

Quality verification — port fidelity validated; published benchmark substantially reproduced, with unresolved v1.2 far-end differences. (ICASSP 2022 AEC-Challenge blind set, 800 real clips, AECMOS + ERLE + DNSMOS): the Swift port scores identically to the upstream GGML engine on identical aligned samples (per-scenario means equal to two decimals, per-clip echo-MOS delta mean +0.0002, p95 0.017). Under the HF model card's own protocol (legacy AECMOS model over the first 20 s) the port reproduces the card's unprocessed baseline exactly and every doubletalk / near-end cell within 0.02 (v1.3 doubletalk 4.73 / 2.62); v1.3 far-end within 0.15 echo from aligned output (0.04 from raw GGML output), 0.8 dB gated ERLE, 0.01 OVRL; the v1.2 far-end rows: rendering at the pre-v1.2 delay window (dmax 32) reproduces the card's ERLE and deg, while its echo MOS cells are not reproduced by any local hypothesis and are reported as unexplained. Both protocols tabulated in Documentation/Enhancement/LocalVQE.md.

Recall benchmark (fluidaudiocli enhance-benchmark, AEC-Challenge synthetic 200-file subset, ASR-scored, M5 Pro): exploratory, 167 scored examples): near-end word recall 44.1% unprocessed → 77.6% (v1.3) / 73.0% (v1.2); far-end word leakage 34.0% → 1.1%; with a silent reference v1.3 only reaches 42.3% / 23.9%, so the loopback is required for AEC. Earlier figures (87.5%/86.3%) were inflated by swapped insertion/deletion labels in the shared WERCalculator, fixed in this PR with tests. Dataset at FluidInference/aec-challenge-synthetic-mini.

Parity on the upstream double-talk demo (M5 Pro, release): Swift vs upstream GGML CLI 80 dB SNR; v1.3 256 ms chunk 7.1 ms/call (36x RTFx) on CPU, 16 ms chunk 1.2 ms/call.

Reviewer notes:

• fp32 only, CPU default: fp16 drops parity from 102 dB to 5 dB (CPU) / 33 dB (ANE) — front-end epsilons underflow and the S4D recurrence accumulates error; the per-hop graph is call-overhead bound so ANE is not a win.
• Output level follows the shipped GGML engine (2x the upstream PyTorch reference's overlap-add convention).
• Upstream's GGUF-only v1.4-AEC / GTCRN line depends on a C++ adaptive-filter front-end and is not ported.

🤖 Generated with Claude Code

https://claude.ai/code/session_015S4u7dmbe4skFjUNMpodud

[github-actions]

PocketTTS Smoke Test ✅

Check	Result
Build	✅
Model download	✅
Model load	✅
Synthesis pipeline	✅
Output WAV	✅ (165.0 KB)

_{Runtime: 0m7s}

_{Note: PocketTTS uses CoreML MLState (macOS 15) KV cache + Mimi streaming state. CI VM lacks physical GPU — audio quality and performance may differ from Apple Silicon.}

[github-actions]

Parakeet EOU Benchmark Results ✅

Status: Benchmark passed
Chunk Size: 320ms
Files Tested: 100/100

Performance Metrics

Metric	Value	Description
WER (Avg)	7.03%	Average Word Error Rate
WER (Med)	4.17%	Median Word Error Rate
RTFx	9.94x	Real-time factor (higher = faster)
Total Audio	470.6s	Total audio duration processed
Total Time	49.6s	Total processing time

Streaming Metrics

Metric	Value	Description
Avg Chunk Time	0.050s	Average chunk processing time
Max Chunk Time	0.099s	Maximum chunk processing time
EOU Detections	0	Total End-of-Utterance detections

_{Test runtime: 0m57s • 09/18/2026, 06:49 PM EST}

_{RTFx = Real-Time Factor (higher is better) • Processing includes: Model inference, audio preprocessing, state management, and file I/O}

[github-actions]

Offline VBx Pipeline Results

Speaker Diarization Performance (VBx Batch Mode)

Optimal clustering with Hungarian algorithm for maximum accuracy

Metric	Value	Target	Status	Description
DER	10.4%	<20%	✅	Diarization Error Rate (lower is better)
RTFx	11.77x	>1.0x	✅	Real-Time Factor (higher is faster)

Offline VBx Pipeline Timing Breakdown

Time spent in each stage of batch diarization

Stage	Time (s)	%	Description
Model Download	16.896	19.0	Fetching diarization models
Model Compile	7.241	8.1	CoreML compilation
Audio Load	0.062	0.1	Loading audio file
Segmentation	24.560	27.6	VAD + speech detection
Embedding	88.867	99.7	Speaker embedding extraction
Clustering (VBx)	0.111	0.1	Hungarian algorithm + VBx clustering
Total	89.128	100	Full VBx pipeline

Speaker Diarization Research Comparison

Offline VBx achieves competitive accuracy with batch processing

Method	DER	Mode	Description
FluidAudio (Offline)	10.4%	VBx Batch	On-device CoreML with optimal clustering
FluidAudio (Streaming)	17.7%	Chunk-based	First-occurrence speaker mapping
Research baseline	18-30%	Various	Standard dataset performance

Pipeline Details:

• Mode: Offline VBx with Hungarian algorithm for optimal speaker-to-cluster assignment
• Segmentation: VAD-based voice activity detection
• Embeddings: WeSpeaker-compatible speaker embeddings
• Clustering: PowerSet with VBx refinement
• Accuracy: Higher than streaming due to optimal post-hoc mapping

_{🎯 Offline VBx Test • AMI Corpus ES2004a • 1049.0s meeting audio • 113.5s processing • Test runtime: 1m 57s • 09/18/2026, 06:55 PM EST}

[github-actions]

Sortformer High-Latency Benchmark Results

ES2004a Performance (30.4s latency config)

Metric	Value	Target	Status
DER	30.3%	<35%	✅
Miss Rate	28.2%	-	-
False Alarm	0.9%	-	-
Speaker Error	1.2%	-	-
RTFx	19.9x	>1.0x	✅
Speakers	4/4	-	-

_{Sortformer High-Latency • ES2004a • Runtime: 2m 15s • 2026-09-18T23:03:00.728Z}

[github-actions]

VAD Benchmark Results

Performance Comparison

Dataset	Accuracy	Precision	Recall	F1-Score	RTFx	Files
MUSAN	94.0%	89.3%	100.0%	94.3%	542.2x faster	50
VOiCES	94.0%	89.3%	100.0%	94.3%	635.5x faster	50

Dataset Details

• MUSAN: Music, Speech, and Noise dataset - standard VAD evaluation
• VOiCES: Voices Obscured in Complex Environmental Settings - tests robustness in real-world conditions

✅: Average F1-Score above 70%

[github-actions]

ASR Benchmark Results ✅

Status: All benchmarks passed

Parakeet v3 (multilingual)

Dataset	WER Avg	WER Med	RTFx	Status
test-clean	0.57%	0.00%	4.52x	✅
test-other	1.19%	0.00%	3.02x	✅

Parakeet v2 (English-optimized)

Dataset	WER Avg	WER Med	RTFx	Status
test-clean	0.80%	0.00%	3.65x	✅
test-other	1.00%	0.00%	3.08x	✅

Streaming (v3)

Metric	Value	Description
WER	0.00%	Word Error Rate in streaming mode
RTFx	0.47x	Streaming real-time factor
Avg Chunk Time	1.919s	Average time to process each chunk
Max Chunk Time	2.306s	Maximum chunk processing time
First Token	2.379s	Latency to first transcription token
Total Chunks	31	Number of chunks processed

Streaming (v2)

Metric	Value	Description
WER	0.00%	Word Error Rate in streaming mode
RTFx	0.56x	Streaming real-time factor
Avg Chunk Time	1.612s	Average time to process each chunk
Max Chunk Time	1.943s	Maximum chunk processing time
First Token	1.591s	Latency to first transcription token
Total Chunks	31	Number of chunks processed

_{Streaming tests use 5 files with 0.5s chunks to simulate real-time audio streaming}

_{25 files per dataset • Test runtime: 7m40s • 09/18/2026, 06:57 PM EST}

_{RTFx = Real-Time Factor (higher is better) • Calculated as: Total audio duration ÷ Total processing time
Processing time includes: Model inference on Apple Neural Engine, audio preprocessing, state resets between files, token-to-text conversion, and file I/O
Example: RTFx of 2.0x means 10 seconds of audio processed in 5 seconds (2x faster than real-time)}

Expected RTFx Performance on Physical M1 Hardware:

• M1 Mac: ~28x (clean), ~25x (other)
• CI shows ~0.5-3x due to virtualization limitations

_{Testing methodology follows HuggingFace Open ASR Leaderboard}

[github-actions]

Supertonic3 Smoke Test ✅

Check	Result
Build	✅
Model download (incl. VectorEstimatorVariants/ int4 buckets)	✅
Model load	✅
Synthesis pipeline (--ve-variant int4)	✅
Output WAV	✅ (364.7 KB)

_{Runtime: 0m30s}

_{Note: CI VMs lack a physical Neural Engine; the ANE-bucketed VectorEstimator falls back to CPU here. This validates download + variant resolution + synthesis, not ANE residency/perf.}

[github-actions]

Speaker Diarization Benchmark Results

Speaker Diarization Performance

Evaluating "who spoke when" detection accuracy

Metric	Value	Target	Status	Description
DER	15.1%	<30%	✅	Diarization Error Rate (lower is better)
JER	24.9%	<25%	✅	Jaccard Error Rate
RTFx	20.33x	>1.0x	✅	Real-Time Factor (higher is faster)

Diarization Pipeline Timing Breakdown

Time spent in each stage of speaker diarization

Stage	Time (s)	%	Description
Model Download	13.726	26.6	Fetching diarization models
Model Compile	5.883	11.4	CoreML compilation
Audio Load	0.085	0.2	Loading audio file
Segmentation	15.480	30.0	Detecting speech regions
Embedding	25.800	50.0	Extracting speaker voices
Clustering	10.320	20.0	Grouping same speakers
Total	51.629	100	Full pipeline

Speaker Diarization Research Comparison

Research baselines typically achieve 18-30% DER on standard datasets

Method	DER	Notes
FluidAudio	15.1%	On-device CoreML
Research baseline	18-30%	Standard dataset performance

Note: RTFx shown above is from GitHub Actions runner. On Apple Silicon with ANE:

• M2 MacBook Air (2022): Runs at 150 RTFx real-time
• Performance scales with Apple Neural Engine capabilities

_{🎯 Speaker Diarization Test • AMI Corpus ES2004a • 1049.0s meeting audio • 51.6s diarization time • Test runtime: 2m 30s • 09/18/2026, 06:50 PM EST}