Chatterbox-TTS-Server — AI 语音合成工具中文文档

🔩 System Prerequisites

• Operating System: Windows 10/11 (64-bit) or Linux (Debian/Ubuntu recommended).
• Python: Version 3.10 required (Download). Python 3.10 is the only version with pre-built wheels for all dependencies (torch, torchvision, ONNX, ONNXRuntime). Python 3.11+ is not supported — key dependencies lack pre-built wheels, causing build failures. On Windows, the launcher's Portable Mode automatically uses an embedded Python 3.10 runtime regardless of your system Python version. When using Portable Mode, Python is only needed on the machine where you first set up the application.
• Git: For cloning the repository (Download).
• Internet: For downloading dependencies and models from Hugging Face Hub.
• Disk Space: 10GB+ recommended (for dependencies and model cache).
• (Optional but HIGHLY Recommended for Performance):
• NVIDIA GPU (CUDA 12.1): CUDA-compatible (Maxwell architecture or newer, RTX 20/30/40 series). Check NVIDIA CUDA GPUs.
• NVIDIA GPU (CUDA 12.8): RTX 5090 or other Blackwell-based GPUs, driver version 570+.
• NVIDIA Drivers: Latest version for your GPU/OS (Download).
• AMD GPU: ROCm-compatible (e.g., RX 6000/7000 series). Check AMD ROCm GPUs.
• AMD Drivers: Latest ROCm-compatible drivers for your GPU/OS (Linux only).
• Apple Silicon: M1, M2, M3, M4, or newer Apple Silicon chips with macOS 12.3+ for MPS acceleration.
• (Linux Only):
• libsndfile1: Audio library needed by soundfile. Install via package manager (e.g., sudo apt install libsndfile1).
• ffmpeg: For robust audio operations (optional but recommended). Install via package manager (e.g., sudo apt install ffmpeg).

Reinstall with fresh dependencies

python start.py --reinstall

Step 1: Install dependencies with PyTorch 2.9.0+cu128 (includes sm_120 support)

pip install -r requirements-nvidia-cu128.txt

Step 2: Install chatterbox without dependencies (prevents PyTorch downgrade)

pip install --no-deps git+https://github.com/devnen/chatterbox-v2.git@master

⚠️ **Critical:** The `--no-deps` flag is required to prevent PyTorch from being downgraded to a version that doesn't support Blackwell GPUs.

**After installation, verify that PyTorch supports sm_120:**

You should see sm_120 in the architectures list!

<details> <summary><strong>💡 Why CUDA 12.8?</strong></summary>

NVIDIA's Blackwell GPUs (RTX 5060 Ti, 5070, 5070 Ti, 5080, 5090) use compute capability sm_120. PyTorch 2.9.0 with CUDA 12.8 includes support for this architecture. Earlier versions (including CUDA 12.1) will fail with the error: CUDA error: no kernel image is available for execution on the device.

See README_CUDA128.md for detailed setup instructions and troubleshooting. </details>

---

Step 2: Install remaining dependencies

pip install -r requirements-rocm.txt

Step 3: Install chatterbox without dependencies (prevents ROCm torch overwrite)

pip install --no-deps git+https://github.com/devnen/chatterbox-v2.git@master

⚠️ **Critical:** The `--no-deps` flag on chatterbox-tts is required to prevent pip from replacing the ROCm PyTorch wheels with CPU-only versions from PyPI. The `start.py` launcher handles this automatically.

**After installation, verify that PyTorch can see your GPU:**

<details> <summary><strong>💡 How This Works</strong></summary>

ROCm installation uses a two-step process: 1. requirements-rocm-init.txt installs PyTorch from the official ROCm 6.1 wheel index (torch==2.5.1+rocm6.1), ensuring you get AMD GPU-accelerated builds. 2. requirements-rocm.txt installs remaining server dependencies without touching PyTorch. 3. Chatterbox is installed with --no-deps to prevent pip's dependency resolver from replacing the ROCm torch with a CPU-only version.

For APU/iGPU users: If you encounter "HIP error: invalid device function", you may need to set HSA_OVERRIDE_GFX_VERSION. See AMD ROCm Support Details below. </details>

---

Install chatterbox-tts without its dependencies to avoid conflicts

pip install --no-deps git+https://github.com/devnen/chatterbox-v2.git@master

Install core server dependencies

pip install fastapi 'uvicorn[standard]' librosa safetensors soundfile pydub audiotsm praat-parselmouth python-multipart requests aiofiles PyYAML watchdog unidecode inflect tqdm

Install missing chatterbox dependencies

pip install conformer==0.3.2 diffusers==0.29.0 resemble-perth==1.0.1 transformers==4.46.3

Install s3tokenizer without its problematic dependencies

pip install --no-deps s3tokenizer

Then upgrade dependencies using the launcher

🖥️ Installation fixes across all platforms

• All platforms: Chatterbox is now installed with --no-deps across all installation paths (CPU, NVIDIA, cu128, ROCm). This eliminates ONNX source build failures, torch version conflicts, and CMake errors that affected many users. Chatterbox's dependencies (conformer, diffusers, transformers, s3tokenizer, etc.) are now listed explicitly in each requirements file with onnx==1.16.0 pinned to guarantee pre-built wheels.
• Apple Silicon / MPS: Fixed Turbo model crash ("Cannot convert a MPS Tensor to float64 dtype") by forcing float32 in s3tokenizer and voice_encoder. Fix applied in the chatterbox-v2 fork and also as an automatic post-install patch in start.py for users of other chatterbox versions. Thanks to @jonas3245 (#93).
• Docker CPU: New lightweight Dockerfile.cpu based on python:3.10-slim instead of the 4GB+ NVIDIA CUDA base image. docker-compose-cpu.yml now uses this smaller image. Removed deprecated version tags from all docker-compose files.
• config.yaml: Default device changed from cuda to auto for correct auto-detection on all hardware (CUDA, MPS, CPU).
• Python version: Python 3.10 is required — it is the only version with pre-built wheels for all dependencies (torch, torchvision, ONNX). Python 3.11+ may fail due to missing wheels. The Windows launcher's Portable Mode handles this automatically by using an embedded Python 3.10 runtime.
• Blackwell (CUDA 12.8): Fixed requirements-nvidia-cu128.txt to properly install PyTorch 2.9.0 with CUDA 12.8 (sm_120 support) for RTX 5060 Ti, 5070, 5070 Ti, 5080, and 5090 GPUs. The Dockerfile.cu128 now correctly installs chatterbox with --no-deps to prevent PyTorch downgrade.
• AMD ROCm: Fixed ROCm installation by switching to PyTorch's official ROCm 6.1 wheel index (torch==2.5.1+rocm6.1), which resolves the previous torch==2.6.0 / torchaudio==2.5.1 version conflict. A new requirements-rocm-init.txt installs the ROCm PyTorch stack before other dependencies. Both Dockerfile.rocm and start.py now use a two-step install to prevent pip from replacing ROCm torch wheels with CPU-only versions.
• Thanks to community contributors in issues #20, #23, #44, #58, #64, #79, #89, #92, #93, #98, #105, #107, #109, #113, #114, #121, and #122 for testing and reporting solutions.

💻 Installation and Setup

This project uses specific dependency files to ensure a smooth installation for your hardware. You can choose between the automated launcher (recommended for most users) or manual installation (for advanced users).

1. Clone the Repository

git clone https://github.com/devnen/Chatterbox-TTS-Server.git
cd Chatterbox-TTS-Server

---

Skip menu and install NVIDIA CUDA 12.1 directly

python start.py --nvidia

Install in portable mode (Windows) - skip prompt

python start.py --portable

📋 Manual Installation

For users who prefer manual control over the installation process.

2. Create a Python Virtual Environment

Using a virtual environment is crucial to avoid conflicts with other projects.

* Windows (PowerShell):

    python -m venv venv
    .\venv\Scripts\activate
    

* Linux (Bash):

    python3 -m venv venv
    source venv/bin/activate
    

3. Choose Your Installation Path

Pick one of the following commands based on your hardware. This single command will install all necessary dependencies with compatible versions.

---

**Option 1: CPU-Only Installation**

This is the most straightforward option and works on any machine without a compatible GPU.

```bash

**Option 2: NVIDIA GPU Installation (CUDA 12.1)**

For users with NVIDIA GPUs. This provides the best performance for RTX 20/30/40 series.

Prerequisite: Ensure you have the latest NVIDIA drivers installed. Python 3.10 required (3.11+ is not supported — pre-built wheels for torchvision and ONNX are unavailable).

```bash

Build and start with CUDA 12.8 support

docker compose -f docker-compose-cu128.yml up -d

**Option 3: AMD GPU Installation (ROCm)**

For users with modern, ROCm-compatible AMD GPUs.

Prerequisite: Ensure you have the latest ROCm drivers installed on a Linux system.

```bash

Step 1: Install ROCm PyTorch stack first

pip install -r requirements-rocm-init.txt

**Option 4: Apple Silicon (MPS) Installation**

For users with Apple Silicon Macs (M1, M2, M3, M4, etc.).

Prerequisite: Ensure you have macOS 12.3 or later for MPS support.

Step 1: Install PyTorch with MPS support first ```bash

Install a compatible version of ONNX and audio codec

pip install onnx==1.16.0 descript-audio-codec

**After installation, verify that PyTorch can see your GPU:**

If `MPS available:` shows `True`, your setup is correct!

<details>
<summary><strong>💡 Why This Process Is Different</strong></summary>
Apple Silicon requires a specific installation sequence due to dependency conflicts between the pinned PyTorch versions in chatterbox-tts and the latest PyTorch versions that support MPS. By installing PyTorch first with MPS support, then carefully installing dependencies while avoiding version conflicts, we ensure MPS acceleration works properly. The server's automatic device detection will use MPS when configured and available.
</details>

---

**Option 5: AMD Strix Halo (Ryzen AI MAX+) Installation**

Note: Use this for AMD Strix Halo APUs (Ryzen AI MAX+ 395 / "Ryzen AI Max" with integrated Radeon 8060S, GFX 11.5.0). Standard discrete Radeon GPUs use Option 3 (ROCm).

Prerequisites: - AMD Strix Halo APU on Linux - ROCm 7.2+ stack installed on the host

Using Docker (recommended): ```bash docker compose -f docker-compose-strixhalo.yml up -d

**Method 2: Stash and Pop (Recommended for Manual Installation)**

If you installed manually without using the launcher, this is the standard and safest way to update using Git. It automatically handles your local changes (like to config.yaml) without needing to manually copy files.

First, activate your virtual environment:

```bash

🚀 Quick Start with Automated Launcher (Recommended)

The automated launcher handles virtual environment creation, hardware detection, dependency installation, and server startup - all in one step.

Windows

```bash

Quick Start:

1. Click the badge above to open the notebook in Google Colab
2. Select GPU runtime: Runtime → Change runtime type → T4 GPU → Save
3. Run Cell 1: Click the play button to install dependencies (~1-5 minutes)
4. Run Cell 2: Start the server and access the Web UI via the provided links
5. Wait for "Server ready! Click below" message: Locate the "localhost:8004" link and click. This starts the Web UI in your browser
6. Generate speech: Use the web interface to create high-quality TTS audio

🚀 Live Demo - Try It Now! (Google Colab)

Want to test Chatterbox TTS Server immediately without any installation?

Why Try the Demo?

• ✅ Full Web UI with all controls and features
• ✅ Voice cloning with uploaded audio files
• ✅ Predefined voices included
• ✅ Large text processing with chunking (perfect for audiobooks)
• ✅ Free GPU acceleration (T4 GPU)
• ✅ No installation or setup required
• ✅ Works on any device with a web browser

Force standard virtual environment (skip portable prompt)

python start.py --no-portable

#### Subsequent Runs

Subsequent Runs

After the first installation, simply run the launcher again to start the server:

```bash

Make sure your (venv) is active

pip install --upgrade pip pip install -r requirements.txt pip install --no-deps git+https://github.com/devnen/chatterbox-v2.git@master ```

<details> <summary><strong>💡 How This Works</strong></summary> The requirements.txt file installs CPU PyTorch and all server dependencies. Chatterbox is installed separately with --no-deps to prevent pip from pulling in conflicting torch versions or triggering ONNX source builds. </details>

---

Make sure your (venv) is active

pip install --upgrade pip pip install -r requirements-nvidia.txt pip install --no-deps git+https://github.com/devnen/chatterbox-v2.git@master

**After installation, verify that PyTorch can see your GPU:**

<details> <summary><strong>💡 How This Works</strong></summary> The requirements-nvidia.txt file installs PyTorch with CUDA 12.1 support plus all server dependencies. Chatterbox is installed separately with --no-deps to prevent pip from downgrading the CUDA torch to a CPU version or triggering ONNX source builds. </details>

---

**Option 2b: NVIDIA GPU with CUDA 12.8 (RTX 5090 / Blackwell)**

Note: Only use this if you have a Blackwell-based GPU (RTX 5060 Ti, 5070, 5070 Ti, 5080, 5090). For RTX 2000/3000/4000 series, use Option 2 above.

For users with NVIDIA Blackwell architecture GPUs that require CUDA 12.8 and sm_120 support.

Prerequisites: - NVIDIA RTX 5060 Ti, 5070, 5070 Ti, 5080, 5090 or other Blackwell-based GPU - CUDA 12.8+ drivers (driver version 570+)

Using Docker (Recommended for RTX 5090): ```bash

Make sure your (venv) is active

pip install --upgrade pip

**Option 2c: NVIDIA GPU with CUDA 13.0 (DGX Spark / sm_121)**

Note: Use this for NVIDIA DGX Spark / GB10 hardware (compute capability sm_121). RTX 5090 stays on cu128 (Option 2b); RTX 30/40 stays on cu121 (Option 2).

For users on the very latest NVIDIA stack who need CUDA 13.0 and PyTorch 2.10.

Prerequisites: - NVIDIA DGX Spark / GB10 or other sm_121-capable hardware - CUDA 13.0+ drivers (driver version 580+)

Using Docker (recommended): ```bash docker compose -f docker-compose-cu130.yml up -d

Make sure your (venv) is active

pip install --upgrade pip

Make sure your (venv) is active

pip install --upgrade pip pip install torch torchvision torchaudio

**Step 2: Configure the server to use MPS**
Update your `config.yaml` to use MPS instead of CUDA:

**Step 3: Install remaining dependencies**

⚙️ Configuration

The server relies exclusively on config.yaml for runtime configuration.

• config.yaml: Located in the project root. This file stores all server settings, model paths, generation defaults, and UI state. It is created automatically on the first run (using defaults from config.py) if it doesn't exist. This is the main file to edit for persistent configuration changes.
• UI Configuration: The "Server Configuration" and "Generation Parameters" sections in the Web UI allow direct editing and saving of values into config.yaml.

Key Configuration Areas (in config.yaml or UI):

• server: host, port, logging settings.
• model: repo_id (e.g., "ResembleAI/chatterbox").
• tts_engine: device ('auto', 'cuda', 'mps', 'cpu'), predefined_voices_path, reference_audio_path, default_voice_id.
• paths: model_cache (for download_model.py), output.
• generation_defaults: Default UI values for temperature, exaggeration, cfg_weight, seed, speed_factor, language.
• audio_output: format, sample_rate, max_reference_duration_sec.
• ui_state: Stores the last used text, voice mode, file selections, etc., for UI persistence.
• ui: title, show_language_select, max_predefined_voices_in_dropdown.
• debug: save_intermediate_audio.

⭐ Remember: Changes made to server, model, tts_engine, or paths sections in config.yaml (or via the UI's Server Configuration section) require a server restart to take effect. Changes to generation_defaults or ui_state are applied dynamically or on the next page load.

Model selection: set model.repo_id to one of:

• chatterbox (or original) — Original 0.5B English model with emotion exaggeration.
• chatterbox-turbo (or turbo) — 350M Turbo model with paralinguistic tags ([laugh], [cough], [chuckle]).
• chatterbox-multilingual (or multilingual) — 0.5B multilingual model with 23-language support.

All three are hot-swappable from the Web UI engine dropdown without a server restart.

Chatterbox TTS Server: OpenAI-Compatible API with Web UI, Large Text Handling & Built-in Voices

Self-host Resemble AI's Chatterbox open-source TTS family (Original + Multilingual + Turbo) behind an OpenAI‑compatible API and a modern Web UI. The complete lineup includes the original high-quality model, multilingual support for 23 languages, and Chatterbox‑Turbo—a streamlined 350M-parameter model with dramatically improved throughput and native paralinguistic tags like [laugh], [cough], and [chuckle] for more expressive voice agents and narration. Features voice cloning, large text processing via intelligent chunking, audiobook generation, and consistent, reproducible voices using built-in ready-to-use voices and a generation seed feature.

🚀 Try it now! Test the full TTS server with voice cloning and audiobook generation in Google Colab - no installation required! To use it, please run cells 1 through 4 one at a time. After running cell 4, click on the "https://localhost:8004" link that appears in the output, and your web browser will open the UI from the .colab.dev domain. Read the instructions here.

This server is based on the architecture and UI of our Dia-TTS-Server project but uses the distinct chatterbox-tts engine. Runs accelerated on NVIDIA (CUDA), AMD (ROCm), and Apple Silicon (MPS) GPUs, with a fallback to CPU. Make sure you also check our Kitten-TTS-Server project.

-blue.svg?style=for-the-badge)

📦 Portable Mode (Windows): This application supports a fully portable installation — the entire folder, including Python and all dependencies, is self-contained. Copy it to a USB drive, share it as a zip, or move it anywhere. Just double-click start.bat — no Python installation needed on the target machine. Learn more →

---

**Method 3: Manual Backup (Alternative)**

This method involves manually backing up and restoring your configuration file.

First, activate your virtual environment:

```bash

Install with verbose output for troubleshooting

python start.py --reinstall --nvidia --verbose