# Chatterbox TTS

An OpenAI-compatible, CUDA-backed FastAPI wrapper for
[ResembleAI Chatterbox](https://huggingface.co/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:

```json
{
  "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

```bash
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`:

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