fix(tts/kokoro-ane): adopt COLA-corrected KokoroTail_v2 + native output level for all variants

[Alex-Wengg]

Closes #852. Completes the follow-up scoped in #699.

Background

#699 found that CoreMLCustomSTFT (KokoroTail) omits the overlap-add/COLA normalization torch.istft applies — the interior envelope is a constant sum(w²) = 1.5 (periodic Hann, win 20 / hop 5), so raw output is exactly 1.5× the PyTorch reference. The PR fixed the conversion and moved .japanese to native output level, but as #852 correctly reports, the corrected tail never made it to HuggingFace (and the script fix never made it into mobius): .japanese has been shipping unmasked 1.5×-hot audio, while English/Mandarin were protected only by peak normalization.

The fix is a pure weight rescale (iSTFT deconv kernels ÷ 1.5) — model.mil is unchanged, which is why the issue's mil-graph analysis couldn't see it; it shows only in the weight.bin LFS oid.

What landed where

• FluidInference/kokoro-82m-coreml commit acac8811 — corrected tails published as KokoroTail_v2.mlmodelc alongside the originals in ANE/, ANE-ja/, ANE-zh/ (originals kept; consumers opt in by pointer change). The en/ja tail is the artifact feat(tts/kokoro-ane): Japanese variant + PyTorch-matched output level #699 measured at 1.02× PyTorch; the zh tail carries the same corrected kernel spans (the iSTFT deconv constants are deterministic DFT×window kernels, byte-identical between en and zh).
• mobius#83 — the conversion-script fix, reconstructed and committed (matches the feat(tts/kokoro-ane): Japanese variant + PyTorch-matched output level #699-measured artifact to 1 ulp).
• This PR — points all three variants at KokoroTail_v2.mlmodelc and drops peak normalization for English/Mandarin (normalize: false in KokoroAneManager.wavData and the CLI), so all variants write at reference-accurate native level.

The _v2 rename (same pattern as KokoroNoise_v2) doubles as cache invalidation: DownloadUtils skips files that already exist and the weight.bin size is unchanged, so a same-path replacement would never reach existing caches. With the rename, existing caches fetch just the missing file on the next ensureModels.

Validation

• CoreML A/B (CPU_ONLY, fixed input) of v1 vs v2 tails, both en/ja and zh: interior per-sample ratio 1.500000, correlation 1.000000000 — pure scalar, no spectral change.
• E2E on M5 Pro from an existing cache: self-heal downloaded only KokoroTail_v2.mlmodelc per variant; native render peaks en 0.343 / zh 0.400 / ja 0.354 (reference territory — feat(tts/kokoro-ane): Japanese variant + PyTorch-matched output level #699 measured PyTorch jf_alpha at 0.299), vs the 1.0 previously forced by 0 dBFS normalization.
• swift build + swift format lint clean.

Behavior change

KokoroAne WAV output is no longer slammed to 0 dBFS for English/Mandarin — output now sits at the model's native (PyTorch-matched) level, consistent with .japanese, LuxTTS, and NeuTTS. Downstream code that assumed peak-normalized output will hear quieter (correct) levels.

🤖 Generated with Claude Code

[github-actions]

PocketTTS Smoke Test ✅

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

_{Runtime: 0m32s}

_{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	5.63x	Real-time factor (higher = faster)
Total Audio	470.6s	Total audio duration processed
Total Time	83.9s	Total processing time

Streaming Metrics

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

_{Test runtime: 2m21s • 08/19/2026, 10:53 AM 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	9.61x	>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	31.626	29.0	Fetching diarization models
Model Compile	13.554	12.4	CoreML compilation
Audio Load	0.096	0.1	Loading audio file
Segmentation	30.362	27.8	VAD + speech detection
Embedding	108.889	99.8	Speaker embedding extraction
Clustering (VBx)	0.113	0.1	Hungarian algorithm + VBx clustering
Total	109.161	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 • 139.4s processing • Test runtime: 2m 43s • 08/19/2026, 10:55 AM EST}

[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	15.34x	>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	18.696	27.3	Fetching diarization models
Model Compile	8.013	11.7	CoreML compilation
Audio Load	0.148	0.2	Loading audio file
Segmentation	20.494	30.0	Detecting speech regions
Embedding	34.156	49.9	Extracting speaker voices
Clustering	13.662	20.0	Grouping same speakers
Total	68.409	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 • 68.3s diarization time • Test runtime: 4m 50s • 08/19/2026, 10:56 AM EST}

[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: 0m37s}

_{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]

VAD Benchmark Results

Performance Comparison

Dataset	Accuracy	Precision	Recall	F1-Score	RTFx	Files
MUSAN	94.0%	89.3%	100.0%	94.3%	665.5x faster	50
VOiCES	94.0%	89.3%	100.0%	94.3%	658.9x 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]

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	13.1x	>1.0x	✅
Speakers	4/4	-	-

_{Sortformer High-Latency • ES2004a • Runtime: 4m 30s • 2026-08-19T15:06:17.316Z}

[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%	5.09x	✅
test-other	1.80%	0.00%	2.77x	✅

Parakeet v2 (English-optimized)

Dataset	WER Avg	WER Med	RTFx	Status
test-clean	0.80%	0.00%	3.93x	✅
test-other	1.38%	0.00%	2.85x	✅

Streaming (v3)

Metric	Value	Description
WER	0.00%	Word Error Rate in streaming mode
RTFx	0.46x	Streaming real-time factor
Avg Chunk Time	2.098s	Average time to process each chunk
Max Chunk Time	3.726s	Maximum chunk processing time
First Token	2.239s	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.58x	Streaming real-time factor
Avg Chunk Time	1.578s	Average time to process each chunk
Max Chunk Time	1.953s	Maximum chunk processing time
First Token	1.608s	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: 13m59s • 08/19/2026, 11:06 AM 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}