tts

Run a local TTS (Text-to-Speech) server with two backend options:

• Kokoro - High-quality neural TTS with GPU acceleration (CUDA/MPS/CPU)
• Piper - Fast, CPU-friendly ONNX-based synthesis

pip install "agent-cli[kokoro]"
agent-cli server tts --backend kokoro

pip install "agent-cli[piper]"
agent-cli server tts --backend piper

Features

• OpenAI-compatible API at /v1/audio/speech - drop-in replacement for OpenAI's TTS API
• Wyoming protocol for Home Assistant voice integration
• TTL-based memory management - models unload after idle period
• Multiple backends - Kokoro (GPU) or Piper (CPU)
• Auto-download - Models and voices download automatically on first use
• Multiple voices - Run different voices with independent TTLs

Usage

agent-cli server tts [OPTIONS]

Examples

# Run with Kokoro (auto-downloads model and voice from HuggingFace)
agent-cli server tts --backend kokoro

# Run with Piper (CPU-friendly)
agent-cli server tts --backend piper

# Piper with specific voice and 10-minute TTL
agent-cli server tts --backend piper --model en_US-ryan-high --ttl 600

# Run multiple Piper voices
agent-cli server tts --backend piper --model en_US-lessac-medium --model en_GB-alan-medium

# Preload models at startup
agent-cli server tts --preload

Options

Options

General Options

API Endpoints

Using the API

curl Example

# Synthesize speech (JSON body, OpenAI-compatible)
curl -X POST http://localhost:10201/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello, world!", "model": "tts-1", "voice": "alloy", "response_format": "wav"}' \
  --output speech.wav

# With speed adjustment
curl -X POST http://localhost:10201/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "This is faster speech", "voice": "echo", "speed": 1.5, "response_format": "wav"}' \
  --output fast.wav

Python Example (OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="http://localhost:10201/v1", api_key="not-needed")

# Synthesize speech
response = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Hello, this is a test of the local TTS server.",
)
response.write_to_file("output.wav")

Streaming Synthesis (Kokoro)

The Kokoro backend supports streaming synthesis following OpenAI's API convention:

• stream_format=audio enables streaming
• response_format=pcm is required (this is the default)

This enables lower latency for real-time playback.

Streaming Example

# Stream audio directly to speaker (pcm is the default format)
curl -X POST http://localhost:10201/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello world. This is a streaming test.", "voice": "af_heart", "stream_format": "audio"}' \
  --output - | aplay -r 24000 -f S16_LE -c 1

Python Streaming Example (OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="http://localhost:10201/v1", api_key="not-needed")

# Stream audio chunks as they're generated
with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="af_heart",
    input="Hello, this is a streaming test.",
    extra_body={"stream_format": "audio"},
) as response:
    for chunk in response.iter_bytes():
        # Process audio chunk (24kHz, 16-bit signed PCM, mono)
        process_audio(chunk)

Response Format

• Content-Type: audio/pcm
• Headers: X-Sample-Rate: 24000, X-Sample-Width: 2, X-Channels: 1
• Body: Raw 16-bit signed PCM audio chunks (same as OpenAI's PCM format)

Wyoming Protocol Streaming

When using the Kokoro backend via Wyoming protocol (port 10200), streaming is automatic - audio chunks are sent as they're generated via AudioChunk messages.

Architecture

The Kokoro backend runs synthesis in an isolated subprocess. This design provides:

• Memory cleanup: When the model is unloaded (via TTL or /v1/model/unload), the subprocess terminates and all GPU/CPU memory is immediately released
• Low latency: Streaming delivers audio chunks as Kokoro generates them, reducing time-to-first-audio
• Stability: Subprocess isolation prevents memory leaks from affecting the main server process

Voice Selection

Kokoro Voices

Kokoro voices are specified per-request via the API voice parameter. Voices auto-download from HuggingFace on first use.

The voice name prefix indicates accent: af_ = American Female, am_ = American Male, bf_ = British Female, bm_ = British Male.

Browse all 30+ voices at hexgrad/Kokoro-82M.

Piper Voices

With Piper, the model name IS the voice. Use --model to specify.

Browse all voices at rhasspy/piper.

Installation

Kokoro (GPU-accelerated)

pip install "agent-cli[kokoro]"
# or
uv sync --extra kokoro

Kokoro requires PyTorch. For GPU acceleration: - CUDA: Install PyTorch with CUDA support - Apple Silicon: PyTorch automatically uses MPS

Piper (CPU-friendly)

pip install "agent-cli[piper]"
# or
uv sync --extra piper