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:

1. Compile Swift launcher binary
2. Create launchd plist at ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
3. 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