docs: README with quick start, deploy notes, model table
Browse files
README.md
CHANGED
|
@@ -1 +1,79 @@
|
|
| 1 |
-
#
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Chatterbox Voice Studio
|
| 2 |
+
|
| 3 |
+
A multi-platform browser-based voice cloning studio for the Chatterbox TTS family
|
| 4 |
+
(English, Turbo, Multilingual). Runs locally on macOS (MPS), Linux (CUDA/CPU),
|
| 5 |
+
and Windows (CUDA/CPU). Deploys to Hugging Face Spaces (Free CPU by default,
|
| 6 |
+
ZeroGPU-decorator-ready).
|
| 7 |
+
|
| 8 |
+
## Quick start (local)
|
| 9 |
+
|
| 10 |
+
### macOS / Linux
|
| 11 |
+
|
| 12 |
+
./scripts/start.sh
|
| 13 |
+
|
| 14 |
+
### Windows
|
| 15 |
+
|
| 16 |
+
scripts\start.bat
|
| 17 |
+
|
| 18 |
+
The script creates a venv, installs Python and Node deps, builds the SPA,
|
| 19 |
+
and opens the studio at http://127.0.0.1:7860.
|
| 20 |
+
|
| 21 |
+
## Hugging Face Spaces
|
| 22 |
+
|
| 23 |
+
This repo's `Dockerfile` is what HF Spaces uses to build the image.
|
| 24 |
+
On Free CPU it runs as-is — generation will be slow (30–90s per clip).
|
| 25 |
+
|
| 26 |
+
To get GPU on Spaces:
|
| 27 |
+
|
| 28 |
+
- Subscribe to HF Pro and pick "ZeroGPU" hardware in your Space settings.
|
| 29 |
+
No code change needed; the `@spaces.GPU` decorator activates.
|
| 30 |
+
- Or pick a paid GPU (T4 small / A10G).
|
| 31 |
+
|
| 32 |
+
## Environment variables
|
| 33 |
+
|
| 34 |
+
| Var | Default | Purpose |
|
| 35 |
+
|---|---|---|
|
| 36 |
+
| `CHATTERBOX_DEVICE` | (auto) | Force `cuda` / `mps` / `cpu`. |
|
| 37 |
+
| `HF_HOME` | `/tmp/hf` | Hugging Face cache. |
|
| 38 |
+
| `CORS_ORIGINS` | `http://localhost:5173,...` | Comma list of allowed CORS origins. |
|
| 39 |
+
| `PYTORCH_ENABLE_MPS_FALLBACK` | `1` (mac) | CPU fallback for unimplemented MPS ops. |
|
| 40 |
+
|
| 41 |
+
## Models
|
| 42 |
+
|
| 43 |
+
| ID | Source | Languages | Tags |
|
| 44 |
+
|---|---|---|---|
|
| 45 |
+
| `chatterbox-en` | `chatterbox.tts.ChatterboxTTS` | English | — |
|
| 46 |
+
| `chatterbox-turbo` | `chatterbox.tts_turbo.ChatterboxTurboTTS` | English | `[laugh]` `[cough]` `[chuckle]` |
|
| 47 |
+
| `chatterbox-mtl` | `chatterbox.mtl_tts.ChatterboxMultilingualTTS` | 23 langs | (TBD) |
|
| 48 |
+
|
| 49 |
+
## Development
|
| 50 |
+
|
| 51 |
+
Backend tests:
|
| 52 |
+
|
| 53 |
+
.venv/bin/pytest
|
| 54 |
+
|
| 55 |
+
Frontend tests:
|
| 56 |
+
|
| 57 |
+
cd web && npm run test
|
| 58 |
+
|
| 59 |
+
Frontend dev server (with API proxy):
|
| 60 |
+
|
| 61 |
+
cd web && npm run dev # http://localhost:5173
|
| 62 |
+
|
| 63 |
+
## Smoke test
|
| 64 |
+
|
| 65 |
+
With the server running:
|
| 66 |
+
|
| 67 |
+
scripts/smoke.sh
|
| 68 |
+
|
| 69 |
+
## Architecture
|
| 70 |
+
|
| 71 |
+
- **Backend:** FastAPI + uvicorn. Three Chatterbox model adapters behind a
|
| 72 |
+
swap-on-demand registry. Server is **stateless**; nothing user-visible
|
| 73 |
+
persists across server restarts.
|
| 74 |
+
- **Frontend:** React + Vite + Tailwind + shadcn/ui. Voice library and
|
| 75 |
+
generation history live in the browser via IndexedDB (Dexie).
|
| 76 |
+
- **One-click:** `scripts/start.sh` (mac/linux) or `scripts/start.bat`
|
| 77 |
+
(windows) handles venv, install, build, serve, and opens Chrome.
|
| 78 |
+
- **HF Spaces:** Dockerfile multi-stage build — Node stage builds the SPA,
|
| 79 |
+
Python stage runs uvicorn with the bundled static files.
|