Kokoro TTS Server
Manage the Kokoro TTS HTTP server — an OpenAI-compatible /v1/audio/speech endpoint on localhost:8779.
Server Overview
The server provides:
-
GET /health — Health status JSON
-
GET /v1/models — List available models
-
POST /v1/audio/speech — Synthesize text to audio (WAV, MP3, Opus, PCM)
Quick Start
Start (foreground, for testing)
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_server.py
Start (launchd, for production)
Per the macOS launchd policy, the launchd plist must launch a compiled Swift binary (not a bash script). Guide the user through:
-
Compile Swift launcher binary
-
Create launchd plist at ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
-
Bootstrap: launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
Stop
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
Verify
curl -s http://127.0.0.1:8779/health | python3 -m json.tool
Expected: {"status": "ok", "provider": "kokoro-tts-mlx", "model": "mlx-community/Kokoro-82M-bf16", "device": "mlx-metal"}
Environment Variables
Variable Default Purpose
KOKORO_SERVER_PORT
8779
Listen port
KOKORO_SERVER_HOST
127.0.0.1
Bind address
KOKORO_DEFAULT_VOICE
af_heart
Default voice
KOKORO_DEFAULT_LANG
en-us
Default language
KOKORO_DEFAULT_SPEED
1.0
Speech speed (0.1–5.0)
KOKORO_PLAY_LOCAL
0
Play via afplay
Troubleshooting
Issue Cause Solution
Port already in use Another server running lsof -i :8779 to find, kill it
Model load fails Not installed Run /kokoro-tts:install first
Slow first request Warmup synthesis Normal — first request triggers model load