Reduce TTS model boilerplate: ~1,000 lines of duplicated loading infrastructure

[beshkenadze]

Code Duplication Report: TTS Models

Overview

Analysis of all 9 TTS model implementations on main (22,478 lines across 50 files) reveals significant infrastructure boilerplate repeated across every model.

Codebase Inventory

Model	Files	Lines	Largest File
Chatterbox	15	7,512	ChatterboxModel (1,374)
Qwen3TTS	6	3,987	SpeechTokenizer (1,455)
Soprano	4	1,994	Soprano (1,045)
EchoTTS	6	1,841	EchoDiT (710)
FishSpeech	4	1,721	FishSpeechModel (1,033)
Marvis	3	1,684	MarvisTTSModel (672)
PocketTTS	8	1,534	PocketTTSModel (375)
Llama	2	1,148	LlamaTTS (982)
Qwen3	2	1,057	Qwen3 (943)
Total	50	22,478

Infrastructure Boilerplate

Every model reimplements the same loading pipeline with minor variations:

Pattern	Models	Avg Lines	Similarity
fromPretrained()	9/9	~63	95% identical
Quantization setup	7/9	~15	90% identical
sanitize() weights	8/9	~50	70% similar
generate()/generateStream()	9/9	~35	85% identical
Config structs (Decodable)	9/9	~235	60% similar

The fromPretrained flow is nearly copy-paste across all models:

1. Resolve/download HF repo → 2. Decode config.json → 3. Load .safetensors → 4. Sanitize keys → 5. Apply quantization → 6. Update parameters → 7. Post-load hooks

Estimated duplicated lines: ~1,000+ across all models combined.

Examples

fromPretrained — compare any two models (e.g. Soprano.swift:894-961 vs FishSpeechModel.swift:994-1032 vs LlamaTTS.swift:917-966): identical structure, only config type and post-load hooks differ.

Quantization — 7 models check config.quantization, extract (groupSize, bits), call quantize() with the same 3-line pattern.

sanitize() — all models filter/rename weight keys. Common operations: strip prefixes, rename gamma→weight/beta→bias, skip position_ids. Model-specific rules added on top.

Possible Approach

Extract common fromPretrained / quantization / sanitization patterns into a shared protocol or base implementation. This would eliminate ~1,000 lines of copy-paste boilerplate while preserving model-specific customization via hooks.

Open to discussion on the best approach — protocol with default extension, base class, or something else entirely.

[beshkenadze]

Automated Analysis: jscpd Results

Ran jscpd (copy-paste detector) across the entire Sources/ directory:

Metric	Value
Files analyzed	239 Swift
Total lines	57,579
Clones found	246
Duplicated lines	3,362 (5.84%)
Duplicated tokens	38,018 (6.35%)

Largest Duplication Clusters

Cluster	Clones	~Lines	Module
LlamaTTS ↔ Qwen3	~15	200+	TTS — nearly identical model code
Llama ↔ Marvis/CSMLlama	~8	150+	TTS — config + Llama model code
Qwen3TTS CodePredictor ↔ Talker	~10	130+	TTS — internal duplication
Descript ↔ FishS1DAC quantization	~8	120+	Codecs
FishS1DACLayers (encoder/decoder mirror)	~10	200+	Codecs — internal
Vocos ↔ SopranoDecoder	5	80+	Codecs ↔ TTS
FireRedASR2 ↔ SenseVoice audio	4	60+	STT
VoxtralRealtime Encoder ↔ Decoder	4	60+	STT — internal
EchoTTSSampling (internal)	6	80+	TTS — internal
CLI tools (App.swift duplication)	~8	100+	Tools
LID: EcapaTdnn ↔ Wav2Vec2	3	70+	LID

Note on Structural Duplication

jscpd detects exact copy-paste blocks (min 5 lines). It does not catch structural duplication where the pattern is identical but type names differ — e.g., all 9 fromPretrained() methods follow the same 7-step flow but use different config types, so jscpd sees them as distinct. The ~1,000 lines of infrastructure boilerplate estimated in the issue description is largely structural duplication that tools like jscpd undercount.

Reproduction

npx jscpd Sources/ --min-lines 5 --min-tokens 50 --reporters console

[beshkenadze]

PMD CPD Results (token-based analysis)

PMD CPD uses token-level comparison (more precise than line-based jscpd):

Metric	Value
Duplications found	367
Duplicated lines	5,398 (~9.4% of 57,579)

PMD detects 60% more duplication than jscpd (5,398 vs 3,362 lines) because it uses token-level matching that catches structurally identical code even with minor formatting differences.

Tool Comparison

Tool	Approach	Clones	Dup Lines	%
jscpd	Line-based, min 5 lines	246	3,362	5.8%
PMD CPD	Token-based, min 50 tokens	367	5,398	9.4%
Manual analysis (structural)	Pattern matching	—	~1,000+ (infra only)	—

Note: Even PMD CPD undercounts structural duplication (same pattern, different type names) like the 9 nearly-identical fromPretrained() methods. The true duplication including structural patterns is likely 10-12%.

Reproduction

# jscpd (line-based)
npx jscpd Sources/ --min-lines 5 --min-tokens 50 --reporters console

# PMD CPD (token-based, more thorough)
pmd cpd --dir Sources/ --language swift --minimum-tokens 50 --format text

periphery (dead code detector) was also tested but fails on this project's SPM configuration — may be worth revisiting separately.

[beshkenadze]

CI Integration: PMD CPD GitHub Action

The official pmd/pmd-github-action (48 stars, maintained) supports CPD with SARIF reports and PR annotations.

Example workflow for duplication checks on PRs:

name: Code Duplication Check
on: [pull_request]

jobs:
  cpd:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pmd/pmd-github-action@v2
        with:
          analyzeModifiedFilesOnly: false
          rulesets: ''  # CPD only, no PMD rules
          version: '7.22.0'
        env:
          PMD_CPD: true
      # Or run CPD directly:
      - name: Run PMD CPD
        run: |
          pmd cpd --dir Sources/ --language swift --minimum-tokens 50 --format sarif > cpd-report.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: cpd-report.sarif

PMD CPD found 367 duplications / 5,398 lines (9.4%) across Sources/ — more thorough than line-based tools since it uses token-level matching.

[beshkenadze]

@lucasnewman What do you think about adding https://github.com/marketplace/actions/pmd for reviewing new PRs?

[lucasnewman]

I'm a little bit skeptical of this analysis for a couple of reasons:

1. Model implementations aren't the same as typical software -- they are generally very fixed with respect to model compatibility, and someone e.g. changing a shared module default could easily and unintentionally break an existing model.
2. Having all the code for a model colocated in a big benefit for human comprehension, because you can map a paper / concepts onto the code much more easily if you don't have to jump around to shared components, and it's much easier to port implementations from one framework or language to another.
3. Some of the things are like sanitize() are necessarily different for each model, so I'm also not totally confident that the analysis itself here is accurate.

Now this is obviously somewhat subjective, and there are some broad exceptions we've embraced (like neural audio codecs, which are more frequently reused across different model families), but overall I really don't think pushing for max reuse is the right choice.

I do think there are a few opportunities available to simplify or abstract some of the common interfaces, so I'm open to targeted changes that would make things simpler in general, but I'd like a human being to decide that it's a good choice and be able to rationalize it first :)