Add KittenTTS backend (Nano 15M + Mini 82M)

[Alex-Wengg]

Summary

• Adds KittenTTS as a third TTS backend alongside Kokoro and PocketTTS
• Supports two variants: Nano (15M params) and Mini (82M params, with speed control)
• Reuses Kokoro G2P pipeline for phonemization — no espeak dependency
• CoreML models auto-download from alexwengg/kittentts-coreml on first use
• 8 voices available: expr-voice-{2,3,4,5}-{m,f}
• 21 unit tests (tokenizer + manager)

Usage

# Nano
swift run fluidaudiocli tts "Hello world" --backend kitten-nano --voice expr-voice-3-f -o output.wav

# Mini with speed control
swift run fluidaudiocli tts "Hello world" --backend kitten-mini --speed 0.8 -o output.wav

Benchmarks (M2, warm cache, longer text)

	Nano	Mini
Inference	7.48s	2.81s
Audio duration	8.35s	8.80s
Inference RTFx	1.12x	3.13x

New files

Sources/FluidAudio/TTS/KittenTTS/
├── KittenTTSError.swift
├── KittenTtsConstants.swift
├── KittenTtsManager.swift
└── Pipeline/
    ├── KittenTtsModelStore.swift
    └── KittenTtsSynthesizer.swift
Tests/FluidAudioTests/TTS/KittenTTS/
├── KittenTtsManagerTests.swift
└── KittenTtsTokenizerTests.swift

Modified files

• ModelNames.swift — repos, filenames, voices for KittenTTS
• TtsBackend.swift — .kittenTts(KittenTtsVariant) case
• TTSCommand.swift — CLI dispatch + --speed flag

Closes #49 (requested by @Josscii)

---

[claude]

Claude finished @Alex-Wengg's task —— View job

---

KittenTTS Backend PR Review ✅

I've completed a comprehensive review of this KittenTTS integration PR and submitted my feedback through GitHub's review system.

Final Assessment

✅ APPROVED - This is a high-quality implementation that adds KittenTTS as a third TTS backend alongside Kokoro and PocketTTS.

Key Strengths

• Clean Architecture: Proper actor-based concurrency, smart reuse of Kokoro G2P pipeline
• Strong Performance: 1.12x RTFx (Nano), 3.13x RTFx (Mini) with good benchmarks
• Consistent API: Follows established FluidAudio patterns with speed control for Mini variant
• Comprehensive Testing: 21 unit tests covering tokenizer and manager functionality
• Good Documentation: Clear Swift docs with usage examples

Minor Considerations Noted

• Logging subsystem could be more specific (com.fluidaudio.tts.kittentts)
• Speed parameter validation could be added for Mini variant
• Overall very clean implementation following project standards

The PR adds valuable functionality without technical debt or breaking changes. The single-shot StyleTTS2 approach with two model variants (15M Nano, 82M Mini) provides good options for different use cases.

---

[claude]

Overall Assessment

This is a well-architected and high-quality implementation that adds KittenTTS as a third TTS backend. The code follows FluidAudio's established patterns and maintains consistency with existing TTS backends.

Strengths

🏗️ Architecture

• Clean separation of concerns with proper actor-based concurrency
• Smart reuse of Kokoro's G2P pipeline (no espeak dependency)
• Efficient model selection based on token count (5s vs 10s variants)

🚀 Performance

• Strong benchmarks: 1.12x RTFx (Nano), 3.13x RTFx (Mini)
• CPU+GPU configuration avoids ANE float16 precision artifacts
• Single-shot synthesis for low latency

🎛️ API Design

• Consistent interface matching Kokoro/PocketTTS patterns
• Speed control for Mini variant (nice feature addition)
• Comprehensive error handling with descriptive messages

✅ Code Quality

• Proper Swift documentation with examples
• 21 unit tests covering tokenizer and manager
• Follows project's coding standards and patterns

Minor Considerations

Logging Subsystem:

KittenTtsModelStore.swift:10 - Consider using com.fluidaudio.tts.kittentts instead of com.fluidaudio.tts for better log filtering

Error Handling:

Speed parameter validation could be added for Mini variant to prevent extreme values

CLI Integration:

The --speed flag is nicely integrated but only applies to Mini - this is clearly documented

Recommendation

✅ APPROVE - This PR is ready to merge. The implementation is solid, well-tested, and follows all established patterns. It adds valuable functionality without introducing technical debt or breaking changes.

[devin-ai-integration]

Devin Review found 1 potential issue.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🔴 Long text silently truncated: phonemize flattens all chunks but inference drops tokens beyond maxTokens

The phonemize function at Sources/FluidAudio/TTS/KittenTTS/Pipeline/KittenTtsSynthesizer.swift:193-210 uses KokoroChunker.chunk with targetTokens: 70 to split text into chunks, then flattens ALL chunk phonemes into a single [String] array. For any text that produces multiple chunks (e.g., a paragraph), the flattened phoneme count can easily exceed 140 tokens. However, the inference functions runNanoInference and runMiniInference allocate a fixed-size input of n = maxTokens (70 or 140) and silently drop all tokens beyond that limit via inputIdsPtr[i] = i < tokenIds.count ? tokenIds[i] : padTokenId (lines 236, 303). This means the user gets truncated audio with no error or warning. By contrast, Kokoro's synthesizer (KokoroSynthesizer.swift:499-508) correctly synthesizes each chunk independently and concatenates the results. KittenTTS should either synthesize each chunk separately and concatenate, or reject/warn when the token count exceeds the model's capacity.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[github-actions]

Qwen3-ASR int8 Smoke Test ✅

Check	Result
Build	✅
Model download	✅
Model load	✅
Transcription pipeline	✅
Decoder size	571 MB (vs 1.1 GB f32)

_{Runtime: 3m8s}

_{Note: CI VM lacks physical GPU — CoreML MLState (macOS 15) KV cache produces degraded results on virtualized runners. On Apple Silicon: ~1.3% WER / 2.5x RTFx.}

[github-actions]

VAD Benchmark Results

Performance Comparison

Dataset	Accuracy	Precision	Recall	F1-Score	RTFx	Files
MUSAN	92.0%	86.2%	100.0%	92.6%	669.5x faster	50
VOiCES	92.0%	86.2%	100.0%	92.6%	682.6x 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	33.4%	<35%	✅
Miss Rate	24.4%	-	-
False Alarm	0.2%	-	-
Speaker Error	8.8%	-	-
RTFx	12.4x	>1.0x	✅
Speakers	4/4	-	-

_{Sortformer High-Latency • ES2004a • Runtime: 5m 9s • 2026-03-22T17:10:17.191Z}

[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	14.5%	<20%	✅	Diarization Error Rate (lower is better)
RTFx	4.82x	>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	9.688	4.5	Fetching diarization models
Model Compile	4.152	1.9	CoreML compilation
Audio Load	0.033	0.0	Loading audio file
Segmentation	21.249	9.8	VAD + speech detection
Embedding	216.490	99.5	Speaker embedding extraction
Clustering (VBx)	0.883	0.4	Hungarian algorithm + VBx clustering
Total	217.598	100	Full VBx pipeline

Speaker Diarization Research Comparison

Offline VBx achieves competitive accuracy with batch processing

Method	DER	Mode	Description
FluidAudio (Offline)	14.5%	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 • 238.6s processing • Test runtime: 4m 9s • 03/22/2026, 01:07 PM EST}

[github-actions]

PocketTTS Smoke Test ✅

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

_{Runtime: 0m24s}

_{Note: PocketTTS uses CoreML MLState (macOS 15) KV cache + Mimi streaming state. CI VM lacks physical GPU — audio quality 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)	0.00%	Average Word Error Rate
WER (Med)	0.00%	Median Word Error Rate
RTFx	0.00x	Real-time factor (higher = faster)
Total Audio	0.0s	Total audio duration processed
Total Time	0.0s	Total processing time

Streaming Metrics

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

_{Test runtime: 0m17s • 03/22/2026, 12:56 PM EST}

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

[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	24.52x	>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	9.374	21.9	Fetching diarization models
Model Compile	4.017	9.4	CoreML compilation
Audio Load	0.047	0.1	Loading audio file
Segmentation	12.834	30.0	Detecting speech regions
Embedding	21.390	50.0	Extracting speaker voices
Clustering	8.556	20.0	Grouping same speakers
Total	42.796	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 • 42.8s diarization time • Test runtime: 5m 33s • 03/22/2026, 01:10 PM EST}

[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.90x	✅
test-other	1.19%	0.00%	3.90x	✅

Parakeet v2 (English-optimized)

Dataset	WER Avg	WER Med	RTFx	Status
test-clean	0.80%	0.00%	5.99x	✅
test-other	1.40%	0.00%	3.72x	✅

Streaming (v3)

Metric	Value	Description
WER	0.00%	Word Error Rate in streaming mode
RTFx	0.69x	Streaming real-time factor
Avg Chunk Time	1.309s	Average time to process each chunk
Max Chunk Time	1.391s	Maximum chunk processing time
First Token	1.581s	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.61x	Streaming real-time factor
Avg Chunk Time	1.419s	Average time to process each chunk
Max Chunk Time	1.577s	Maximum chunk processing time
First Token	1.388s	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: 6m19s • 03/22/2026, 01:00 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}

[Josscii]

Hi, I tested it, and it failed with following:

Building for debugging...
[1/1] Write swift-version--3CB7CFEC50E0D141.txt
Build of product 'fluidaudiocli' complete! (0.24s)
[23:20:22.052] [INFO] [FluidAudio.Main] Host environment: macOS Version 26.3.1 (a) (Build 25D771280a), arch=arm64, chip=Apple M2 Pro, cores=10/10, mem=32 GB, rosetta=false
[23:20:22.053] [INFO] [FluidAudio.KittenTtsModelStore] KittenTTS nano models found in cache
[23:20:22.175] [INFO] [FluidAudio.KittenTtsModelStore] Loaded kittentts_5s.mlmodelc
[23:20:22.287] [INFO] [FluidAudio.KittenTtsModelStore] Loaded kittentts_10s.mlmodelc
[23:20:22.287] [INFO] [FluidAudio.KittenTtsModelStore] KittenTTS nano models loaded in 0.23s
[23:20:22.287] [NOTICE] [FluidAudio.KittenTtsManager] KittenTtsManager initialized
[23:20:22.287] [INFO] [FluidAudio.KittenTtsSynthesizer] KittenTTS synthesizing: 'Hello world'
[23:20:22.288] [INFO] [FluidAudio.KokoroVocabulary] Loaded 114 vocabulary entries from integer map
[23:20:22.291] [ERROR] [FluidAudio.TTSCommand] KittenTTS synthesis failed: processingFailed("Missing lexicon cache (expected us_lexicon_cache.json)")
[23:20:22.291] [INFO] [FluidAudio.Main] Peak memory usage (process-wide): 0.205 GB

[github-actions]

KittenTTS Smoke Test

Test Results

Variant	Status	Output Size
Nano (15M)	✅	55.1 KB
Mini (82M)	✅	178.2 KB

Dependencies

Component	Status	Size
Build	✅	-
Lexicon cache (us_lexicon_cache.json)	✅	10.0 MB
Kokoro G2P pipeline	✅	-

_{Note: KittenTTS reuses Kokoro's G2P pipeline for phonemization. This test verifies the lexicon cache auto-downloads correctly and both Nano/Mini variants can synthesize audio.}

[Josscii]

Another issue I found is that some simple words is spoken weirdly. For example, the test phrase Hello world, the Hello is wrong. Is this the model issue?

[Alex-Wengg]

Another issue I found is that some simple words is spoken weirdly. For example, the test phrase Hello world, the Hello is wrong. Is this the model issue?

could you give me the wav file for examination and which model type. Mini has more parameters vs nano

[Josscii]

I'm using the mini model.

Hello world
the hello is wrong.

One day, a little girl named Lily found a needle in her room. She knew it was difficult to play with it because it was sharp.
the day is wrong.