Rename 1.env.example to .env.example

.env.example

@@ -0,0 +1,14 @@
+# port exposed on the host — default 10800 (piper=10200, whisper=10300, wakeword=10400)
+WYOMING_PORT=10800
+
+# absolute path to the directory containing your voice reference wav
+VOICE_REF_DIR=/path/to/your/voice
+
+# filename of the wav inside that directory
+VOICE_REF_FILE=reference.wav
+
+# volume multiplier applied to output audio (3.0 = louder, 1.0 = raw)
+VOLUME_BOOST=3.0
+
+# torch device: cuda or cpu
+TORCH_DEVICE=cuda

Dockerfile

@@ -0,0 +1,25 @@
+FROM pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime
+
+WORKDIR /app
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    HF_HOME=/cache/huggingface \
+    PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libsndfile1 \
+    ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml .
+COPY wyoming_chatterbox/ ./wyoming_chatterbox/
+
+RUN pip install --no-cache-dir . && \
+    pip install --no-cache-dir chatterbox-tts
+
+VOLUME ["/cache", "/voice"]
+
+ENTRYPOINT ["wyoming-chatterbox"]
+CMD ["--uri", "tcp://0.0.0.0:10800", "--voice-ref", "/voice/reference.wav"]

README.md

@@ -2,61 +2,100 @@
 
 [wyoming protocol](https://github.com/rhasspy/wyoming) server for [chatterbox tts](https://github.com/resemble-ai/chatterbox) with voice cloning.
 
-clone any voice with a 10-30 second audio sample.
+clone any voice with a 10-30 second audio sample. integrates directly with home assistant as a tts provider.
 
 ## requirements
 
-- nvidia gpu with 4gb+ vram
+- nvidia gpu with 4gb+ vram (3.5gb used at runtime)
-- cuda 12.x
+- cuda 12.x host driver (≥550.54.14)
-- python 3.10+
+- [nvidia container toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) installed on host
+- docker + docker compose v2
 
-## install
+## docker (recommended)
+
+### 1. configure
 
-from source:
 ```bash
 git clone https://github.com/sudoxreboot/wyoming-chatterbox
 cd wyoming-chatterbox
+cp .env.example .env
+```
+
+edit `.env`:
+
+```env
+WYOMING_PORT=10800          # host port — change if 10800 is taken
+VOICE_REF_DIR=/path/to/dir  # directory containing your reference wav
+VOICE_REF_FILE=reference.wav
+VOLUME_BOOST=3.0
+TORCH_DEVICE=cuda
+```
+
+### 2. build and run
+
+```bash
+docker compose build
+docker compose up -d
+```
+
+first run downloads ~3.5gb of chatterbox model weights into a named docker volume (`chatterbox-cache`). this only happens once.
+
+### 3. check logs
+
+```bash
+docker compose logs -f
+# you should see: "starting server at tcp://0.0.0.0:10800"
+```
+
+### voice reference tips
+
+- 10-30 seconds of clean speech
+- no background music or noise
+- consistent speaking style
+- wav format (any sample rate)
+
+---
+
+## install from source (no docker)
+
+```bash
+git clone https://github.com/sudoxreboot/wyoming-chatterbox
+cd wyoming-chatterbox
+python3 -m venv .venv
+source .venv/bin/activate
 pip install .
 ```
 
-## usage
-
 ```bash
-wyoming-chatterbox --uri tcp://0.0.0.0:10201 --voice-ref /path/to/voice_sample.wav
+wyoming-chatterbox --uri tcp://0.0.0.0:10800 --voice-ref /path/to/voice.wav
 ```
 
 ### options
 
 | option | default | description |
 |--------|---------|-------------|
-| `--uri` | required | server uri (e.g., `tcp://0.0.0.0:10201`) |
+| `--uri` | required | server uri (e.g., `tcp://0.0.0.0:10800`) |
 | `--voice-ref` | required | path to voice reference wav (10-30s of speech) |
 | `--volume-boost` | 3.0 | output volume multiplier |
 | `--device` | cuda | torch device (`cuda` or `cpu`) |
 | `--debug` | false | enable debug logging |
 
-## voice reference tips
+---
 
-for best results:
+## systemd service (source install)
-- 10-30 seconds of clean speech
-- no background music or noise
-- consistent speaking style
-- wav format (any sample rate)
-
-## systemd service
 
 ```bash
-sudo tee /etc/systemd/system/wyoming-chatterbox.service << 'EOF'
+sudo tee /etc/systemd/system/wyoming-chatterbox.service << EOF
 [Unit]
 Description=Wyoming Chatterbox TTS
 After=network-online.target
 
 [Service]
 Type=simple
-User=YOUR_USER
+User=$(whoami)
 Environment=PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
-ExecStart=/path/to/venv/bin/wyoming-chatterbox \
+ExecStart=$(pwd)/.venv/bin/wyoming-chatterbox \
-  --uri tcp://0.0.0.0:10201 \
+  --uri tcp://0.0.0.0:10800 \
   --voice-ref /path/to/voice_reference.wav \
   --volume-boost 3.0
 Restart=always
@@ -70,25 +109,33 @@ sudo systemctl daemon-reload
 sudo systemctl enable --now wyoming-chatterbox
 ```
 
+---
+
 ## home assistant
 
 1. settings → devices & services → add integration
-2. search "wyoming protocol"
+2. search **wyoming protocol**
-3. host: `YOUR_IP`, port: `10201`
+3. host: your server ip, port: `10800` (or whatever you set in `.env`)
-4. use in your voice assistant pipeline as tts
+4. select it as your tts provider in the voice assistant pipeline
+
+---
 
 ## gpu memory
 
-chatterbox uses ~3.5gb vram. if you get oom errors:
+chatterbox uses ~3.5gb vram at runtime. if you get oom errors:
 
 ```bash
-# check gpu usage
 nvidia-smi
 
-# kill zombie processes
+# docker
+docker compose restart
+
+# source
 pkill -f wyoming-chatterbox
 ```
 
+---
+
 ## license
 
 mit

compose.yaml

@@ -0,0 +1,28 @@
+services:
+  wyoming-chatterbox:
+    build: .
+    image: wyoming-chatterbox:latest
+    container_name: wyoming-chatterbox
+    restart: unless-stopped
+    ports:
+      - "${WYOMING_PORT:-10800}:10800"
+    volumes:
+      - chatterbox-cache:/cache
+      - ${VOICE_REF_DIR}:/voice:ro
+    environment:
+      - PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
+    command: >
+      --uri tcp://0.0.0.0:10800
+      --voice-ref /voice/${VOICE_REF_FILE}
+      --volume-boost ${VOLUME_BOOST:-3.0}
+      --device ${TORCH_DEVICE:-cuda}
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+
+volumes:
+  chatterbox-cache: