Server

Kokoro TTS Server

Manage the Kokoro TTS HTTP server — an OpenAI-compatible /v1/audio/speech endpoint on localhost:8779.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

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

Troubleshooting

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Kokoro TTS Server API Reference

OpenAI-compatible HTTP API at http://127.0.0.1:8779.

Endpoints

GET /health

Returns server status.

{
  "status": "ok",
  "provider": "kokoro-tts-mlx",
  "model": "mlx-community/Kokoro-82M-bf16",
  "device": "mlx-metal",
  "default_voice": "af_heart",
  "default_lang": "en-us"
}

GET /v1/models

Returns available models.

{
  "object": "list",
  "data": [{ "id": "kokoro-82m", "object": "model", "owned_by": "kokoro" }]
}

POST /v1/audio/speech

Synthesize text to audio.

Request body:

{
  "input": "Hello world",
  "voice": "af_heart",
  "language": "en-us",
  "speed": 1.0,
  "response_format": "wav"
}

Parameters:

Response: Audio bytes with appropriate Content-Type header.

Response headers:

Format support (requires ffmpeg for mp3/opus):

Usage Examples

# Synthesize WAV
curl -X POST http://127.0.0.1:8779/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello world", "voice": "af_heart"}' \
  -o output.wav

# Synthesize MP3
curl -X POST http://127.0.0.1:8779/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello world", "response_format": "mp3"}' \
  -o output.mp3

Service Management Reference

Managing the Kokoro TTS server as a macOS launchd service.

Launchd Policy

Per the macOS launchd policy, all launchd services must use compiled Swift binaries — no bash scripts. This applies to the Kokoro TTS server.

Swift Launcher Binary

The launcher is a minimal Swift program that executes the Python server:

import Foundation

let python = ProcessInfo.processInfo.environment["KOKORO_PYTHON"]
    ?? "\(NSHomeDirectory())/.local/share/kokoro/.venv/bin/python"
let script = "\(NSHomeDirectory())/.local/share/kokoro/tts_server.py"

let process = Process()
process.executableURL = URL(fileURLWithPath: python)
process.arguments = [script]
process.environment = ProcessInfo.processInfo.environment

try process.run()
process.waitUntilExit()
exit(process.terminationStatus)

Compile: swiftc -O -o kokoro-tts-server KokoroTTSServer.swift

Plist Template

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.terryli.kokoro-tts-server</string>
    <key>Program</key>
    <string>/path/to/compiled/kokoro-tts-server</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>ThrottleInterval</key>
    <integer>30</integer>
    <key>EnvironmentVariables</key>
    <dict>
        <key>KOKORO_SERVER_PORT</key>
        <string>8779</string>
        <key>KOKORO_SERVER_HOST</key>
        <string>127.0.0.1</string>
        <key>KOKORO_DEFAULT_VOICE</key>
        <string>af_heart</string>
    </dict>
</dict>
</plist>

Lifecycle Commands

# Start
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

# Restart
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist

# Status
launchctl print gui/$(id -u)/com.terryli.kokoro-tts-server