Install Kokoro TTS
Install the Kokoro TTS engine: Apple Silicon verification, Python 3.13 venv, MLX-Audio dependencies, model download, and verification synthesis.
Platform: macOS Apple Silicon (M1+) only. Fails fast on Intel/Linux.
Prerequisites
Component Required Check
Apple Silicon Yes uname -m = arm64
uv Yes uv --version
Python 3.13 Yes uv python list
Workflow
Step 1: Preflight
Check Apple Silicon
[[ "$(uname -m)" == "arm64" ]] && echo "OK: Apple Silicon" || echo "FAIL: Requires Apple Silicon (M1+)"
Check uv
command -v uv && echo "OK: uv found" || echo "FAIL: Install with 'brew install uv'"
Step 2: Install
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/kokoro-tts}" bash "$PLUGIN_DIR/scripts/kokoro-install.sh" --install
This performs:
-
Verifies Apple Silicon (fails fast on Intel/Linux)
-
Creates Python 3.13 venv at ~/.local/share/kokoro/.venv via uv
-
Installs MLX-Audio dependencies (mlx-audio, soundfile, numpy)
-
Copies kokoro_common.py , tts_generate.py from plugin bundle
-
Downloads Kokoro-82M-bf16 MLX model from HuggingFace
-
Writes version.json with mlx_audio version and model ID
-
Runs verification synthesis ("Warm up.")
Step 3: Verify
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/cc-skills/plugins/kokoro-tts}" bash "$PLUGIN_DIR/scripts/kokoro-install.sh" --health
All 6 checks should pass. Print "Installation complete — run /kokoro-tts:health to verify".
Troubleshooting
Issue Cause Solution
Not Apple Silicon Intel Mac or Linux MLX-Audio requires M1+ Mac
uv not found Not installed brew install uv
Model download slow Large first download Wait for HuggingFace download
Permission denied Script not +x chmod +x scripts/kokoro-install.sh
Venv already exists Previous install Run --uninstall then --install