Back to Details

diagnose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Diagnose Kokoro TTS

诊断Kokoro TTS

Troubleshoot Kokoro TTS engine issues through systematic diagnostics.
通过系统化诊断排查Kokoro TTS引擎的相关问题。

Known Issues

已知问题

IssueLikely CauseDiagnosticFix
Import errorVenv corrupted
python -c "from mlx_audio.tts.utils import load_model"
kokoro-install.sh --uninstall && --install
Model not foundDownload incomplete
ls ~/.cache/huggingface/hub/models--mlx-community--Kokoro-82M-bf16/
kokoro-install.sh --install
to re-download
Slow synthesisFirst-run warmupTime a test synthesisNormal — subsequent runs use cached model
Not Apple SiliconIntel/Linux system
uname -m
!= 
arm64
MLX-Audio requires Apple Silicon (M1+)
Wrong PythonNot 3.13
~/.local/share/kokoro/.venv/bin/python --version
Rebuild venv with 
--uninstall && --install
Server won't startPort in use
lsof -i :8779
Kill existing process or change port
No audio from CLIEmpty textCheck 
--text
argument		Provide non-empty text
问题可能原因诊断方法修复方案
导入错误虚拟环境损坏
python -c "from mlx_audio.tts.utils import load_model"
kokoro-install.sh --uninstall && --install
模型未找到下载不完整
ls ~/.cache/huggingface/hub/models--mlx-community--Kokoro-82M-bf16/
执行
kokoro-install.sh --install
重新下载
合成速度慢首次运行预热对测试合成任务计时正常现象 —— 后续运行会使用已缓存的模型
非Apple Silicon设备Intel/Linux系统
uname -m
!= 
arm64
MLX-Audio要求使用Apple Silicon（M1及以上芯片）
Python版本错误非3.13版本
~/.local/share/kokoro/.venv/bin/python --version
使用
--uninstall && --install
命令重建虚拟环境
服务无法启动端口被占用
lsof -i :8779
终止现有进程或修改端口
CLI调用无音频输出文本为空检查
--text
参数		传入非空文本

Diagnostic Workflow

诊断工作流

Step 1: Collect symptoms

步骤1：收集症状

Use AskUserQuestion:
  • What happened? (import error, no audio, slow, server won't start)
  • When? (after upgrade, first time, suddenly)
使用AskUserQuestion工具询问：
  • 发生了什么问题？（导入错误、无音频输出、速度慢、服务无法启动）
  • 问题什么时候出现的？（升级后、首次使用时、突然出现）

Step 2: Run automated diagnostics

步骤2：运行自动化诊断

bash
undefined
bash
undefined

Platform check

Platform check

echo "Arch: $(uname -m)" echo "macOS: $(sw_vers -productVersion)"
echo "Arch: $(uname -m)" echo "macOS: $(sw_vers -productVersion)"

Venv check

Venv check

[[ -d ~/.local/share/kokoro/.venv ]] && echo "Venv: OK" || echo "Venv: MISSING"
[[ -d ~/.local/share/kokoro/.venv ]] && echo "Venv: OK" || echo "Venv: MISSING"

Python version

Python version

~/.local/share/kokoro/.venv/bin/python --version 2>/dev/null || echo "Python: NOT FOUND"
~/.local/share/kokoro/.venv/bin/python --version 2>/dev/null || echo "Python: NOT FOUND"

MLX-Audio import

MLX-Audio import

~/.local/share/kokoro/.venv/bin/python -c "from mlx_audio.tts.utils import load_model; print('MLX-Audio: OK')" 2>&1 || echo "MLX-Audio: FAIL"
~/.local/share/kokoro/.venv/bin/python -c "from mlx_audio.tts.utils import load_model; print('MLX-Audio: OK')" 2>&1 || echo "MLX-Audio: FAIL"

Scripts present

Scripts present

for f in kokoro_common.py tts_generate.py tts_server.py; do [[ -f ~/.local/share/kokoro/$f ]] && echo "$f: OK" || echo "$f: MISSING" done
for f in kokoro_common.py tts_generate.py tts_server.py; do [[ -f ~/.local/share/kokoro/$f ]] && echo "$f: OK" || echo "$f: MISSING" done

Version info

Version info

cat ~/.local/share/kokoro/version.json 2>/dev/null || echo "version.json: MISSING"
undefined
cat ~/.local/share/kokoro/version.json 2>/dev/null || echo "version.json: MISSING"
undefined

Step 3: Map to known issue and apply fix

步骤3：匹配已知问题并应用修复方案

Use the Known Issues table above to identify the root cause and apply the targeted fix.
参考上方的已知问题表格定位根本原因，然后应用对应的修复方案。

Step 4: Verify

步骤4：验证修复结果

bash
undefined
bash
undefined

Quick synthesis test

Quick synthesis test

~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py
--text "Diagnostic test" --voice af_heart --lang en-us --speed 1.0
--output /tmp/kokoro-diag-test.wav && echo "Synthesis: OK"
undefined
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py
--text "Diagnostic test" --voice af_heart --lang en-us --speed 1.0
--output /tmp/kokoro-diag-test.wav && echo "Synthesis: OK"
undefined