Provider Tts Overview - thekaveh/atlas GitHub Wiki

5.3.5. TTS Provider Overview

Pluggable text-to-speech layer. All backends expose an OpenAI-compatible /v1/audio/speech endpoint, so Open WebUI, n8n, JupyterHub and Hermes can use them interchangeably. The backend receives TTS_ENDPOINT but does not use it.

1. Available backends

TTS_PROVIDER_SOURCE Engine License Runs on
speaches-container-cpu Speaches (Kokoro + Piper) MIT Linux + macOS Docker, CPU
speaches-container-gpu Speaches (CUDA build) MIT Not usable yet: no GPU device is attached (#1373)
chatterbox-container-gpu Resemble AI Chatterbox AGPL-3.0 (API server); model MIT NVIDIA (upstream recommends 8 GB+ memory)
chatterbox-localhost Chatterbox natively AGPL-3.0 (API server); model MIT macOS MPS / Linux (any)
disabled none — —

The default for fresh installs is speaches-container-cpu. It works on every platform with no host setup. Speaches ships with no preloaded models and does not download them itself. In speaches v0.9.0-rc.3, /v1/audio/* looks only in the cache and returns 404 for a missing model. Download Kokoro before the first synthesis (see the quick start below).

For zero-shot voice cloning, pick a Chatterbox variant: chatterbox-container-gpu for a container on NVIDIA, or chatterbox-localhost for a host install. On Apple Silicon, only the host install can use MPS; see localhost/README.md.

2. Quick start

Speaches (default — already enabled in .env.example):

./start.sh
# Speaches is healthy as soon as Uvicorn is up, but has no model yet —
# download the Kokoro ONNX build first (one-time; persists in speaches-cache):
curl -X POST http://localhost:63060/v1/models/speaches-ai/Kokoro-82M-v1.0-ONNX
curl http://localhost:63060/v1/audio/speech \
  -X POST -H "Content-Type: application/json" \
  -d '{"model":"speaches-ai/Kokoro-82M-v1.0-ONNX","input":"hello","voice":"af_heart"}' \
  --output speech.wav

Chatterbox (voice cloning, GPU required):

./start.sh --tts-provider-source chatterbox-container-gpu

Chatterbox on host (macOS native via MPS / Linux):

# Terminal 1 — install from git (no PyPI package):
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api && uv sync
PORT=63044 uv run main.py

# Terminal 2
./start.sh --tts-provider-source chatterbox-localhost

Disable:

./start.sh --tts-provider-source disabled

3. How Open WebUI is wired

The bootstrapper sets these env vars on the open-web-ui container based on the chosen source:

  • AUDIO_TTS_ENGINE=openai
  • AUDIO_TTS_OPENAI_API_BASE_URL=${TTS_ENDPOINT}/v1
  • AUDIO_TTS_MODEL = SPEACHES_TTS_MODEL (Speaches — use an executor-valid id like speaches-ai/Kokoro-82M-v1.0-ONNX) or chatterbox-tts-1 (Chatterbox)
  • AUDIO_TTS_VOICE=af_heart or alloy

You can override the model / voice in the Open WebUI admin panel after startup — Audio settings.

4. Full configuration reference

See services/tts-provider/README.md.

5. References