wyoming-chatterbox

A production-quality Wyoming protocol text-to-speech server for Resemble AI Chatterbox, designed for use with Home Assistant.

Features

• Four model variants — standard, multilingual, turbo, and nano, served individually or together as selectable Wyoming programs.
• Device selection — auto, cpu, cuda, or mps. Explicit accelerators fail fast if unavailable instead of silently falling back.
• Segmented streaming synthesis — incremental text segmentation with a bounded, ordered, parallel synthesis pipeline for low time-to-first-audio.
• Named reference voices — drop *.wav files into the voices directory and select them by name (with path-traversal protection).
• Multilingual — the multilingual backend exposes per-request language selection.
• Fully mockable — the Chatterbox dependency is imported lazily so the package (and its test suite) runs without downloading any models.

Installation

pip install wyoming-chatterbox
# plus the runtime model dependencies:
pip install "wyoming-chatterbox[torch,chatterbox]"

Usage

Configuration is entirely environment-variable driven (see .env.example):

CHATTERBOX_VARIANT=multilingual CHATTERBOX_DEVICE=auto wyoming-chatterbox

The server listens on tcp://0.0.0.0:10200 by default.

Docker

docker compose up -d          # CPU image

Build the CUDA image by setting target: cuda in compose.yaml and enabling the GPU deploy block. Published images are available at ghcr.io/wyoming-chatterbox/wyoming-chatterbox with -cpu / -cuda tags.

Home Assistant

Add the Wyoming integration and point it at host:10200. Each configured variant appears as a selectable TTS program; each *.wav in the voices directory appears as a voice.

Configuration

See .env.example for the full list including generation and audio-boundary parameters.

Streaming modes

• off / buffered — synthesize the whole utterance, then stream it out in chunks.
• segmented — split text into sentence-like segments, synthesize them with a bounded parallel worker pool, and emit audio strictly in order with short pauses at sentence and clause boundaries. This minimizes time-to-first-audio for longer responses.

Development

pip install -e ".[dev]"
ruff check .
ruff format --check .
pyright src/
pytest

The test suite mocks Chatterbox entirely and never downloads models.

License

MIT