Skip to content

feat(kokoro-tts): dual-engine ONNX support with HuggingFace model download - #1825

Open
Jehu wants to merge 4 commits into
agent0ai:mainfrom
Jehu:feature/kokoro-tts-onnx-dual-engine
Open

feat(kokoro-tts): dual-engine ONNX support with HuggingFace model download#1825
Jehu wants to merge 4 commits into
agent0ai:mainfrom
Jehu:feature/kokoro-tts-onnx-dual-engine

Conversation

@Jehu

@Jehu Jehu commented Aug 13, 2026

Copy link
Copy Markdown

Summary

Extends the built-in Kokoro TTS plugin with a second inference engine: kokoro_onnx (ONNX Runtime) alongside the existing kokoro_py (PyTorch/KPipeline). This enables community ONNX exports from HuggingFace, e.g. the German voice model Godelaune/Kokoro-82M-ONNX-German-Martin, without touching the default experience.

Changes

  • Dual engine: new engine config selects kokoro_py (default, backward compatible) or kokoro_onnx
  • Language support: lang config (espeak-ng code, e.g. en-us, de) mapped to KPipeline lang codes for kokoro_py and passed through to ONNX synthesis
  • HuggingFace download: ONNX model + voices files auto-download into usr/models/ cache on first use
  • Repo auto-detect: new API endpoint POST /api/plugins/_kokoro_tts/resolve_hf_repo detects the .onnx model and voices (.npz/.bin) filenames from a HF repo ID; runtime auto-detects when filenames are left empty
  • WebUI: engine dropdown, language input, conditional ONNX section with "Detect files" button in plugin settings; frontend store syncs all new fields
  • Status API: reports active engine plus kokoro/kokoro-onnx package versions

Testing

  • ONNX German synthesis verified end-to-end on live server (engine=kokoro_onnx, voice=martin, lang=de, ~200k chars base64 WAV)
  • Auto-detect verified for Godelaune/Kokoro-82M-ONNX-German-Martin (model=kokoro-martin.onnx, voices=voices-martin.npz)
  • Backward compatibility: default config normalizes to kokoro_py/en-us; existing voice/speed/weights behavior unchanged
  • Status and synthesize endpoints verified against running WebUI with CSRF session

Notes for reviewers

  • kokoro-onnx and onnxruntime are optional runtime dependencies for the ONNX engine; the plugin degrades gracefully when only kokoro_py is installed
  • System dependency espeak-ng is already required by the existing kokoro pipeline path

Jehu added 4 commits August 13, 2026 12:10
- Add kokoro_onnx engine alongside existing kokoro_py (KPipeline)
- Auto-download ONNX models from HuggingFace repos
- Config: engine, lang, onnx_hf_repo, onnx_model_file, onnx_voices_file
- WebUI: engine dropdown, language input, ONNX config section
- Refactor: extract _encode_wav_base64, _pkg_version helper
- Backward compatible: defaults to kokoro_py/en-us
- New API endpoint POST /api/plugins/_kokoro_tts/resolve_hf_repo
- Backend auto-detects .onnx and .npz/.bin files from HF repo API
- _detect_hf_files() in runtime.py queries HF API when filenames empty
- WebUI: "Detect files" button next to repo input with auto-fill
- Backward compatible: explicit filenames still take precedence
refreshStatus() dropped engine, lang, onnx_hf_repo, onnx_model_file,
onnx_voices_file when rebuilding config, losing ONNX settings on
status refresh. Sync all fields now.
- Add optional secondary language term list for ONNX synthesis
- Phonemize matched in-sentence terms with the secondary language
- Pass composed phonemes to kokoro_onnx with is_phonemes=True
- Add WebUI settings and frontend store persistence for mixed terms
@Jehu

Jehu commented Aug 13, 2026

Copy link
Copy Markdown
Author

Added a follow-up commit for intra-sentence mixed-language pronunciation:

  • New optional ONNX settings: onnx_mixed_lang and onnx_mixed_lang_terms
  • Matched terms are phonemized with the secondary language (e.g. en-us) while the rest of the sentence uses the primary language (e.g. de)
  • The composed phoneme string is passed to kokoro_onnx.create(..., is_phonemes=True)
  • Added WebUI fields and frontend store persistence for the new settings

Verified locally with German Martin + English technical terms (API, Machine Learning, Performance, Deployment, Kubernetes, Docker, Frontend, React, TypeScript); generated a WAV successfully.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant