chatterbox-tts/README.md

Chatterbox TTS

An OpenAI-compatible, CUDA-backed FastAPI wrapper for ResembleAI Chatterbox.

The deployed service is available on the DimensionLab local network at https://chatterbox.dimensionlab.net.

API

POST /v1/audio/speech accepts the familiar OpenAI speech fields:

{
  "model": "chatterbox",
  "input": "Hello from Chatterbox.",
  "voice": "reference.wav",
  "response_format": "wav",
  "speed": 1.0
}

The response is WAV audio. voice is a relative path below the service's local voices/ directory; absolute paths, traversal, symlink escapes, and unreadable files are rejected. Reference clips are operational data and are intentionally not part of this repository.

Other endpoints:

• GET /health
• GET /v1/models

Runtime behavior

• Uses the English Chatterbox model on CUDA.
• Serializes synthesis through one GPU lock.
• Unloads the model after 300 seconds of inactivity.
• Caps text input at 2,000 characters.
• Listens locally on 127.0.0.1:8881; Caddy provides the HTTPS route.

Development

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
PYTHONPATH=. .venv/bin/pytest -q tests/test_app.py

The CUDA smoke test requires a valid local reference clip at voices/reference.wav:

PYTHONPATH=. .venv/bin/pytest -q tests/test_synthesis.py