Self-host the powerful Chatterbox TTS model. This server offers a user-friendly Web UI, flexible API endpoints (incl. OpenAI compatible), predefined voices, voice cloning, and large audiobook-scale text processing. Runs accelerated on NVIDIA (CUDA), AMD (ROCm), and CPU.

This repository is empty

Auto Translate

Chatterbox TTS Server：兼容 OpenAI API，具备 Web UI、大文本处理及内置语音功能

将 Resemble AI 的 Chatterbox 开源 TTS 系列（原版 + 多语言版 + Turbo 版）部署在本地，通过兼容 OpenAI 的 API 和现代化 Web UI 提供服务。该系列模型完整包含：原版高质量模型、支持 23 种语言的多语言模型，以及 Chatterbox-Turbo——这是一款精简的 3.5 亿参数模型，其吞吐量显著提升，并原生支持 [laugh]、[cough]、[chuckle] 等副语言标签，可用于创建更具表现力的语音代理和旁白。此外，还具备语音克隆、通过智能分块处理大文本、有声书生成功能，并能借助内置即用型语音和生成种子功能，确保语音的一致性和可复现性。

🚀 立即试用！ 在 Google Colab 中测试完整的 TTS 服务器，体验语音克隆和有声书生成功能，无需安装。使用时，请依次运行第 1 至第 4 个单元格。运行完第 4 个单元格后，点击输出中显示的 "https://localhost:8004" 链接，您的网络浏览器将从 .colab.dev 域打开 UI。点击此处阅读使用说明。

本服务器基于我们 Dia-TTS-Server 项目的架构和 UI 构建，但使用独特的 chatterbox-tts 引擎。可在 NVIDIA（CUDA）、AMD（ROCm）和 Apple Silicon（MPS）GPU 上加速运行，也可回退至 CPU 运行。您也可以查看我们的 Kitten-TTS-Server 项目。

📦 便携模式（Windows）： 本应用支持完全便携安装——整个文件夹（包括 Python 和所有依赖项）均为自包含。您可以将其复制到 USB 驱动器、压缩后分享，或移动到任何位置。只需双击 start.bat 即可运行——目标机器无需预先安装 Python。了解更多 →

🆕 新增功能

🚀 v2.0.0 亮点（新）

v2.0 版本在所有主流 GPU 平台上提供完整的 Chatterbox 系列模型，通过统一的 OpenAI 兼容 API 和 Web UI 进行访问。主要亮点包括：

DGX Spark / sm_121 支持：通过新增的 docker-compose-cu130.yml（CUDA 13.0，PyTorch 2.10）实现。RTX 30/40/50 系列显卡继续使用 cu121 / cu128。
AMD Strix Halo 支持：通过 docker-compose-strixhalo.yml（ROCm 7.2，HSA_OVERRIDE_GFX_VERSION=11.0.0）实现。
流式 /tts 端点：可选参数 stream: true 返回 StreamingResponse，按块刷新 WAV 字节并带有 20 毫秒交叉淡入淡出。默认行为保持不变。
语音条件缓存：针对相同参考语音的重复请求将跳过重新编码。这为批量处理和 OpenAI 端点工作流带来了显著的延迟改善。
可选 BF16 推理：设置 TTS_BF16=on（或 =auto）可将 T3 转换为 bfloat16 并在自动混合精度模式下运行，在支持 bf16 的 GPU 上可提升约 40% 的吞吐量。默认值为 off，以保持升级后的现有行为。
HTTPS / SSL 支持：在 config.yaml 中可选择配置 ssl_certfile 和 ssl_keyfile，无需反向代理即可直接启用 HTTPS。
安全增强：修复了 /tts 和 /v1/audio/speech 语音文件参数中的 CWE-22 路径遍历漏洞。遍历尝试将返回 HTTP 400 错误。
新增端点：/api/unload（无需重启即可释放 GPU 内存）和 /v1/audio/voices（OpenAI 兼容的语音列表）。
动态语言选择器：UI 中的语言下拉菜单会根据多语言引擎公开的 SUPPORTED_LANGUAGES 自动填充。
分块器修复：叙述文本中的孤立短横线不再被视为项目符号，避免吞噬后续段落内容（#144）。

完整列表及贡献者致谢请参见 v2.0.0 发布说明。

📦 Windows 便携模式（新）

启动器现在为所有 Windows 用户在首次设置时提供便携模式，并默认选中。
创建完全独立的安装：整个项目文件夹可以复制到 USB 驱动器、压缩分享或移动到文件系统的任何位置。
接收者只需双击 start.bat 即可运行——目标机器上无需安装 Python。
可与任何系统 Python 3.10+ 配合使用，但嵌入式运行时始终使用 Python 3.10——这是唯一完全支持的版本。如果您的系统 Python 是 3.11+，便携模式是在 Windows 上避免依赖问题的最简单方法。
使用 --portable 可跳过提示直接以便携模式安装，或使用 --no-portable 进行标准虚拟环境安装。
Linux 和 macOS 使用标准虚拟环境，需 Python 3.10。这些平台不支持便携模式，因此系统必须安装 Python 3.10。

🌍 Chatterbox 多语言支持（新增）

全面支持 Chatterbox Multilingual，现已完整覆盖 Resemble AI 的 Chatterbox 系列全部三款模型。
多语言版本带来 23 种语言支持，包括阿拉伯语、中文、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、希伯来语、印地语、意大利语、日语、韩语、马来语、挪威语、波兰语、葡萄牙语、俄语、西班牙语、瑞典语、斯瓦希里语和土耳其语。
采用与原版 Chatterbox 相同的 0.5B 参数架构，具备情感夸张控制和零样本语音克隆功能。
非常适合国际项目、多语言有声读物以及服务全球用户的语音代理。

⚡ Chatterbox‑Turbo 支持（新增）

全面支持 Chatterbox‑Turbo，这是 Resemble AI 最新推出的注重效率的 Chatterbox 模型。
Turbo 基于 精简的 350M 参数架构 构建，旨在减少计算资源/显存占用的同时保持高保真输出。
Turbo 将语音令牌到梅尔频谱的“音频扩散解码器”步骤从 10 步精简至 1 步，消除了一个主要的推理瓶颈。
Resemble 将 Turbo 定位用于实时/代理工作流，并强调其在 GPU 上实现显著快于实时的性能（性能因硬件/设置而异）。

🔁 热插拔 TTS 引擎（UI）

Web UI 顶部新增 引擎选择器 下拉菜单。
可即时在 Original Chatterbox、Chatterbox Multilingual 和 Chatterbox‑Turbo 之间热切换；后端会自动加载所选引擎。
三款模型均支持 热插拔——只需从下拉菜单中选择，后端便会自动加载您的选择，无需重启或更改配置。
所有 UI 和 API 请求均通过活动引擎路由，因此您可以在不修改客户端代码的情况下对质量、语言支持和延迟进行 A/B 测试。

🎭 副语言标签（Turbo）

Turbo 新增 原生副语言标签，您可以直接将其写入文本，例如 …calling you back [chuckle]…。
支持的标签包括 [laugh]、[cough] 和 [chuckle]，以及用于表示叹息、喘气和咳嗽等反应的文本提示。
ui/presets.yaml 中新增 预设示例，展示了用于代理风格脚本和富有表现力朗读的副语言提示。

✅ 原版 Chatterbox 依旧是一流之选

原版 Chatterbox 模型仍然可用，支持高质量英语输出，具备0.5B LLaMA 骨干网络、情感夸张控制，并在50 万小时的清洗数据上进行了训练。

🎯 全面支持 Chatterbox 系列模型

您现在可以使用整个 Chatterbox 系列模型：

原版 Chatterbox — 具有情感控制的高质量英语输出（0.5B 参数，50 万小时训练数据）
Chatterbox 多语言版 — 支持 23 种语言，具备声音克隆和情感控制功能（0.5B 参数）
Chatterbox Turbo — 推理速度最快，支持 [laugh] 和 [cough] 等副语言标签（350M 参数，1 步扩散）

切换模型毫不费力： 只需从 Web UI 顶部的引擎选择器下拉菜单中选择您偏好的模型。无需重启，无需更改配置——即时热切换，即可测试整个 Chatterbox 系列模型的质量、速度和语言支持。

🖥️ 全平台安装修复

所有平台： 现在所有安装路径（CPU、NVIDIA、cu128、ROCm）都使用 --no-deps 安装 Chatterbox。这消除了影响许多用户的 ONNX 源构建失败、torch 版本冲突和 CMake 错误。Chatterbox 的依赖项（conformer、diffusers、transformers、s3tokenizer 等）现在在每个 requirements 文件中明确列出，并固定 onnx==1.16.0 以确保使用预构建的 wheel 包。
Apple Silicon / MPS： 通过在 s3tokenizer 和 voice_encoder 中强制使用 float32，修复了 Turbo 模型崩溃问题（“无法将 MPS 张量转换为 float64 数据类型”）。此修复已应用于 chatterbox-v2 分支，并作为 start.py 中的自动安装后补丁，供使用其他 chatterbox 版本的用户使用。感谢 @jonas3245（#93）。
Docker CPU： 全新轻量级 Dockerfile.cpu，基于 python:3.10-slim 而非 4GB 以上的 NVIDIA CUDA 基础镜像。docker-compose-cpu.yml 现在使用此更小的镜像。所有 docker-compose 文件中已移除已弃用的 version 标签。
config.yaml： 默认设备从 cuda 更改为 auto，以便在所有硬件（CUDA、MPS、CPU）上正确自动检测。
Python 版本： 需要 Python 3.10 — 这是唯一为所有依赖项（torch、torchvision、ONNX）提供预构建 wheel 包的版本。Python 3.11+ 可能因缺少 wheel 包而失败。Windows 启动器的便携模式通过使用嵌入式 Python 3.10 运行时自动处理此问题。
Blackwell（CUDA 12.8）： 修复了 requirements-nvidia-cu128.txt，以正确安装支持 CUDA 12.8 的 PyTorch 2.9.0（支持 sm_120），适用于 RTX 5060 Ti、5070、5070 Ti、5080 和 5090 GPU。Dockerfile.cu128 现在正确使用 --no-deps 安装 chatterbox，以防止 PyTorch 降级。
AMD ROCm： 通过切换到 PyTorch 官方 ROCm 6.1 wheel 索引（torch==2.5.1+rocm6.1）修复了 ROCm 安装问题，解决了之前 torch==2.6.0 / torchaudio==2.5.1 的版本冲突。新增的 requirements-rocm-init.txt 会在安装其他依赖项之前安装 ROCm PyTorch 栈。Dockerfile.rocm 和 start.py 现在都采用两步安装法，以防止 pip 将 ROCm torch wheel 包替换为仅 CPU 版本。
感谢社区贡献者在 issues #20、#23、#44、#58、#64、#79、#89、#92、#93、#98、#105、#107、#109、#113、#114、#121 和 #122 中进行测试并提供解决方案。

🧰 自动化启动器 + 轻松更新

全新自动化启动器（支持 Windows + Linux），可创建/激活虚拟环境、安装正确依赖、下载模型文件、启动服务器并打开 Web UI。
便捷的维护命令：
- --upgrade：更新代码和依赖。
- --reinstall：当环境出现问题时，执行全新重装。

🗣️ 概述：增强版 Chatterbox TTS 生成

Resemble AI 的 Chatterbox TTS 模型具备生成高质量语音的能力。本项目在此基础上构建了一个功能强大的 FastAPI 服务器，使 Chatterbox 的使用和集成变得更加简单。

🚀 想立即体验？ 在 Google Colab 中启动实时演示 - 无需安装！

服务器接收纯文本输入进行语音合成，我们通过以下方式解决模型设置和运行的复杂性：

现代化 Web UI：便于进行实验、加载预设、管理参考音频以及调整生成参数。
多引擎支持（原版 + Turbo）：可在 Web UI 中直接选择 TTS 引擎，然后通过相同的 UI/API 界面进行生成。
副语言提示（Turbo）：原生标签如 [laugh]、[cough] 和 [chuckle]，可在同一生成语音中加入自然的非语音反应。
Chatterbox 原版优势：高质量英语输出，独特的“情感夸张控制”以及 0.5B LLaMA 基础模型。
多平台加速：全面支持 NVIDIA (CUDA)、AMD (ROCm) 和 Apple Silicon (MPS) GPU，并自动回退至 CPU，确保您可以在任何硬件上运行。
长文本处理：根据句子结构智能地将长文本输入分割成可管理的片段，按顺序处理，并无缝拼接音频。
📚 有声书生成：非常适合创建完整的有声书 - 只需粘贴整本书的文本，服务器会自动将其处理为单个无缝音频文件，并保持全程一致的语音质量。
预定义语音：从精选的即用型合成语音中选择，无需克隆设置即可获得一致可靠的输出。
语音克隆：使用与上传的参考音频文件相似的声音生成语音。
一致生成：通过使用“预定义语音”或“语音克隆”模式（可选结合固定整数Seed），在多次生成或文本片段之间实现一致的语音输出。
Docker 支持：便于在任何平台上进行简单、可重现的容器化部署。

本服务器是您无缝利用 Chatterbox TTS 能力的门户，它增强了稳定性、语音一致性，并支持纯文本输入的长文本处理。

✨ 本服务器的核心功能

🔥 提供在线演示：

🚀 一键 Google Colab 演示： 直接在浏览器中体验完整服务器功能，包括声音克隆和有声书生成 - 无需本地安装！

此服务器应用在基础 chatterbox-tts 引擎上增强了以下功能：

🚀 核心功能：

多引擎支持：
- 通过 Web UI 中的热切换引擎选择器，可在 Original Chatterbox、Chatterbox Multilingual 和 Chatterbox‑Turbo 之间进行选择。
- Original Chatterbox 提供高质量英文输出，并支持情感夸张控制（0.5B 参数）。
- Chatterbox Multilingual 支持 23 种语言，具备声音克隆和情感控制功能（0.5B 参数）。
- Chatterbox Turbo 采用精简的 350M 参数架构和副语言标签，推理速度显著提升。
- 这三种模型均可热切换 — 只需从下拉菜单中选择，无需重启或更改配置。
副语言标签（Turbo）：
- 使用 Chatterbox‑Turbo 时，可在文本中直接写入原生标签，如 [laugh]、[cough] 和 [chuckle]。
- 新增预设展示了用于智能体风格脚本和富有表现力叙述的副语言提示。
大文本处理（分块）：
- 智能地根据句子边界将长文本输入分割成更小的块，自动处理长文本。
- 对每个块单独处理，并将生成的音频无缝拼接，克服 TTS 引擎可能存在的生成限制。
- 非常适合有声书生成 - 粘贴整本书文本，即可获得具有一致叙述风格的专业级有声书。
- 可通过 UI 开关（“将文本分割成块”）和块大小滑块进行配置。
预设声音：
- 允许使用存储在 ./voices 目录中的精选即用型合成声音。
- 可通过 UI 下拉菜单（“预设声音”模式）选择。
- 无需手动设置克隆，即可提供稳定的声音输出。
声音克隆：
- 支持使用参考音频文件（.wav 或 .mp3）进行声音克隆。
- 服务器会为引擎处理参考音频。
生成种子： 在 UI 和 API 中添加了 seed 参数，用于影响生成结果。将固定整数种子结合预设声音或声音克隆使用，有助于保持一致性。
API 端点 (/tts)：
- 主要 API 端点，提供对 TTS 生成的精细控制。
- 支持的参数包括：文本、声音模式（预设/克隆）、参考/预设声音选择、分块控制（split_text、chunk_size）、生成设置（temperature、exaggeration、CFG weight、seed、speed factor、language）以及输出格式。
UI 配置管理： 添加了 UI 部分，用于查看/编辑 config.yaml 设置（服务器、模型、路径）并保存生成默认值。
配置系统： 使用 config.yaml 进行所有运行时配置，通过 config.py（YamlConfigManager）进行管理。如果 config.yaml 缺失，将使用 config.py 中的默认值创建。
音频后处理（可选）： 包含用于静音修剪、内部静音减少以及（如果安装了 parselmouth）去除非浊音段的工具，以提高音频质量。这些功能均可配置。
UI 状态持久化： Web UI 现在会将文本输入、声音模式选择、文件选择和生成参数（seed、分块、滑块）保存在 config.yaml 的 ui_state 部分，并在下次加载时恢复。

🔧 常规增强：

轻松安装与管理：
- 🚀 自动化启动器（start.bat / start.sh）- 一键设置，自动硬件检测
- 🔧 多 GPU 支持 - NVIDIA CUDA 12.1、NVIDIA CUDA 12.8（Blackwell）、AMD ROCm、Apple MPS
- 🔄 便捷更新 - 简单的 --upgrade 和 --reinstall 命令
- 📦 便携模式（Windows） - 自包含、可移动的安装 — 复制到 USB、压缩分享、无需 Python 即可在任何地方运行
- 🎯 跳过菜单选项 - 使用 --cpu、--nvidia、--nvidia-cu128、--rocm、--portable 标志进行直接安装
性能： 针对 GPU 上的速度和高效 VRAM 使用进行了优化。
Web 界面： 现代化、响应式 UI，支持纯文本输入、参数调整、预设加载、参考/预设音频管理以及音频播放。
模型加载： 使用 ChatterboxTTS.from_pretrained() 从 Hugging Face Hub 稳健加载模型，利用标准 HF 缓存。
依赖管理： 清晰的 requirements.txt。
工具集： 全面的 utils.py，用于音频处理、文本处理和文件管理。

✅ 功能摘要

核心 Chatterbox 功能（通过 Resemble AI Chatterbox）：
- 🗣️ 从纯文本合成高质量单说话人语音。
- 🎤 使用参考音频提示进行语音克隆。
- 🎯 完整模型系列： 原始 Chatterbox（英语，情感控制）、Chatterbox 多语言版（23 种语言）和 Chatterbox‑Turbo（速度最快，支持副语言标签）。
- 🔄 热插拔引擎： 通过下拉菜单即时切换所有三种模型 — 无需重启。
增强型服务器与 API：
- ⚡ 基于高性能 FastAPI 框架构建。
- ⚙️ 自定义 API 端点 (/tts) 作为程序生成的主要方法，公开所有关键参数。
- 📄 通过 Swagger UI (/docs) 提供交互式 API 文档。
- 🩺 健康检查端点（/api/ui/initial-data 同时用作全面状态检查）。
高级生成功能：
- 🔁 热插拔引擎： 直接在 Web UI 中切换原始 Chatterbox、Chatterbox 多语言版和 Chatterbox‑Turbo — 无需重启。
- 🌍 多语言支持： 通过 Chatterbox 多语言版支持 23 种语言，包括阿拉伯语、中文、法语、德语、日语、西班牙语等。
- 🎭 副语言标签（Turbo）： 原生支持 [laugh]、[cough]、[chuckle] 等表达性标签。
- 📚 长文本处理： 智能地将长纯文本输入按句子分割成块，为每个块生成音频，并将结果无缝拼接。可通过 split_text 和 chunk_size 进行配置。
- 📖 有声书创建： 非常适合从全长度文本生成完整有声书，具有一致的语音质量和自动章节处理。
- 🎤 预定义语音： 从 ./voices 目录中选择精选的合成语音。
- ✨ 语音克隆： 使用上传的参考音频文件进行简单的语音克隆。
- 🌱 一致生成： 使用预定义语音或语音克隆模式，可选择使用固定整数 Seed，以获得一致的语音输出。
- 🔇 音频后处理： 可选的自动步骤，用于修剪静音、修复内部停顿以及去除长段无声部分/伪影（可通过 config.yaml 配置）。
直观的 Web 用户界面：
- 🖱️ 现代、易用的界面。
- 🔁 引擎选择器： 通过简单的下拉菜单热切换原始 Chatterbox、Chatterbox 多语言版和 Chatterbox‑Turbo — 无需重启。
- 💡 预设： 从 ui/presets.yaml 动态加载示例文本和设置。
- 🎤 参考/预定义音频上传： 轻松上传 .wav/.mp3 文件。
- 🗣️ 语音模式选择： 在预定义语音或语音克隆之间选择。
- 🎛️ 参数控制： 通过滑块和输入框调整生成设置（Temperature、Exaggeration、CFG Weight、Speed Factor、Seed 等）。
- 💾 配置管理： 直接在 UI 中查看和保存服务器设置 (config.yaml) 以及默认生成参数。
- 💾 会话持久性： 通过 config.yaml 记住您上次使用的设置。
- ✂️ 分块控制： 启用/禁用文本拆分并调整大致块大小。
- ⚠️ 警告模态框： 针对分块语音一致性和一般生成质量的可选警告。
- 🌓 明暗模式： 切换主题，偏好设置本地保存。
- 🔊 音频播放器： 集成波形播放器 (WaveSurfer.js)，用于生成的音频，并提供下载选项。
- ⏳ 加载指示器： 显示生成过程中的状态。
灵活高效的模型处理：
- ☁️ 使用 ChatterboxTTS.from_pretrained() 从 Hugging Face Hub 自动下载模型。
- 🔄 通过 config.yaml 轻松指定模型仓库。
- 📄 可选的 download_model.py 脚本可用于将特定模型组件预下载到本地目录（这与运行时使用的主 HF 缓存分开）。
性能与配置：
- 💻 GPU 加速： 如果可用，自动使用 NVIDIA CUDA、Apple MPS 或 AMD ROCm，否则回退到 CPU。
- ⚙️ 所有配置通过 config.yaml 完成。
- 📦 使用标准 Python 虚拟环境。
- 📦 便携模式（Windows）： 自包含安装，可复制、移动或共享 — 目标机器上无需安装 Python。
Docker 支持：
- 🐳 通过 Docker 和 Docker Compose 进行容器化部署。
- 🔌 集成 Container Toolkit 的 NVIDIA GPU 加速。
- 💾 用于模型（HF 缓存）、自定义语音、输出、日志和配置的持久卷。
- 🚀 一键设置和部署（docker compose up -d）。

🔩 系统先决条件

操作系统： Windows 10/11（64位）或 Linux（推荐 Debian/Ubuntu）。
Python： 需 3.10 版本（下载）。Python 3.10 是唯一为所有依赖项（torch、torchvision、ONNX、ONNXRuntime）提供预构建 wheel 的版本。不支持 Python 3.11+——关键依赖项缺乏预构建 wheel，会导致构建失败。在 Windows 上，启动器的便携模式会自动使用嵌入式 Python 3.10 运行时，无论您的系统 Python 版本如何。使用便携模式时，仅在首次设置应用程序的机器上需要 Python。
Git： 用于克隆仓库（下载）。
互联网： 用于从 Hugging Face Hub 下载依赖项和模型。
磁盘空间： 推荐 10GB 以上（用于依赖项和模型缓存）。
（可选但强烈推荐以获得最佳性能）：
- NVIDIA GPU (CUDA 12.1)： 兼容 CUDA（Maxwell 架构或更新，RTX 20/30/40 系列）。查看 NVIDIA CUDA GPUs。
- NVIDIA GPU (CUDA 12.8)： RTX 5090 或其他 Blackwell 架构 GPU，驱动版本 570+。
- NVIDIA 驱动程序： 适用于您的 GPU/操作系统的最新版本（下载）。
- AMD GPU： 兼容 ROCm（例如，RX 6000/7000 系列）。查看 AMD ROCm GPUs。
- AMD 驱动程序： 适用于您的 GPU/操作系统的最新 ROCm 兼容驱动程序（仅 Linux）。
- Apple Silicon： M1、M2、M3、M4 或更新的 Apple Silicon 芯片，搭配 macOS 12.3+ 以支持 MPS 加速。
（仅 Linux）：
- libsndfile1：soundfile 所需的音频库。通过包管理器安装（例如 sudo apt install libsndfile1）。
- ffmpeg：用于稳健的音频操作（可选但推荐）。通过包管理器安装（例如 sudo apt install ffmpeg）。

硬件兼容性矩阵

硬件	安装选项	需求文件	驱动要求
仅 CPU	`--cpu`	requirements.txt	无
NVIDIA RTX 20/30/40 系列	`--nvidia`	requirements-nvidia.txt	525+
NVIDIA RTX 5090 / Blackwell (sm_120)	`--nvidia-cu128`	requirements-nvidia-cu128.txt (torch 2.9, CUDA 12.8)	570+
NVIDIA DGX Spark / GB10 (sm_121)	仅支持 Docker	requirements-nvidia-cu130.txt (torch 2.10, CUDA 13.0)	580+
AMD RX 6000/7000 系列 (Linux)	`--rocm`	requirements-rocm.txt	ROCm 6.4+
AMD Strix Halo (Ryzen AI MAX+)	仅支持 Docker	requirements-strixhalo.txt (ROCm 7.2)	ROCm 7.2+
Apple Silicon (M1/M2/M3/M4)	手动安装	参见选项 4	macOS 12.3+

💻 安装与设置

本项目通过特定的依赖文件确保在您的硬件上顺利安装。您可以选择 自动启动器（推荐大多数用户使用）或 手动安装（适用于高级用户）。

1. 克隆仓库

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

🚀 使用自动化启动器快速开始（推荐）

自动化启动器可一站式完成虚拟环境创建、硬件检测、依赖项安装和服务器启动等所有步骤。

Windows

# Double-click start.bat or run from command prompt:
start.bat

Linux / macOS

# Make the launcher executable and run it
chmod +x start.sh
./start.sh

运行流程

启动器会检查您的 Python 安装情况（需 3.10 版本；在 Windows 系统上，若要引导便携模式则需 3.10 以上版本）
在 Windows 系统上：提供便携模式（推荐）—— 创建一个完全独立、可移动的安装环境。详情参见便携模式。使用 --portable 可跳过此提示，或使用 --no-portable 以创建标准虚拟环境。
设置 Python 环境（便携环境或标准虚拟环境）
检测您的 GPU 硬件（NVIDIA、AMD 或仅支持 CPU）
显示安装菜单，并预先选择推荐选项：

══════════════════════════════════════════════════════════════
   Hardware Detection
══════════════════════════════════════════════════════════════

   NVIDIA GPU: Detected (NVIDIA GeForce RTX 4090)
   AMD GPU:    Not detected

══════════════════════════════════════════════════════════════
   Select Installation Type
══════════════════════════════════════════════════════════════

   [1] CPU Only
       No GPU acceleration - works on any system

   [2] NVIDIA GPU (CUDA 12.1) [DEFAULT]
       Standard for RTX 20/30/40 series

   [3] NVIDIA GPU (CUDA 12.8)
       For RTX 5090 / Blackwell GPUs only

   [4] AMD GPU (ROCm 6.4)
       For AMD GPUs on Linux

   Enter choice [2]:

按 Enter 键接受推荐的默认选项，或输入数字选择其他选项
依赖项将自动安装（首次运行可能需要几分钟时间）
服务器启动并显示访问 URL

启动器命令行选项

选项	描述
`--reinstall` 或 `-r`	删除现有安装并重新全新安装（显示菜单）
`--upgrade` 或 `-u`	升级到最新版本（保留当前硬件选择）
`--cpu`	安装仅 CPU 版本（跳过菜单）
`--nvidia`	安装 NVIDIA CUDA 12.1 版本（跳过菜单）
`--nvidia-cu128`	为 RTX 5090/Blackwell 安装 NVIDIA CUDA 12.8 版本（跳过菜单）
`--rocm`	安装 AMD ROCm 版本（跳过菜单）
`--portable`	在 Windows 上使用便携 Python 环境（跳过提示）
`--no-portable`	在 Windows 上使用标准虚拟环境（跳过提示）
`--verbose` 或 `-v`	显示详细的安装输出
`--help` 或 `-h`	显示帮助信息

示例：

# Skip menu and install NVIDIA CUDA 12.1 directly
python start.py --nvidia

# Reinstall with fresh dependencies
python start.py --reinstall

# Upgrade to latest version (keeps your hardware selection)
python start.py --upgrade

```bash
# Install with verbose output for troubleshooting
python start.py --reinstall --nvidia --verbose

# Install in portable mode (Windows) - skip prompt
python start.py --portable

# Switch from standard to portable mode
python start.py --reinstall --portable

# Force standard virtual environment (skip portable prompt)
python start.py --no-portable

后续运行


#### Subsequent Runs

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

```bash
# Windows
start.bat

# Linux/macOS
./start.sh

启动器会检测已有的安装，直接启动服务器，无需重新安装。

📦 便携模式（Windows）

在 Windows 系统上，启动器提供 便携模式 —— 这是一种完全独立的安装方式，整个项目文件夹（包括其专用的 Python 运行时和所有依赖项）都位于一个位置。与标准的 Python 虚拟环境（使用硬编码的绝对路径，移动后会失效）不同，便携安装仅使用相对路径，可在任何位置运行。

便携模式的用途

首次设置完成后，整个项目文件夹可以：

复制到同一台机器的不同目录 —— 仍然可以正常运行。
复制到 USB 驱动器 并在另一台 Windows 电脑上运行 —— 目标机器无需安装 Python。
压缩后分享 给他人 —— 对方解压缩后，双击 start.bat 即可运行。
移动到文件系统的任何位置，不会出现任何问题。

接收者无需安装 Python，无需运行任何设置，也无需互联网连接即可启动服务器（有关模型的说明见下文）。

首次运行与后续运行

首次运行：启动器会设置便携 Python 环境并安装所有依赖项（PyTorch、CUDA 库等）。这需要互联网连接，且需要几分钟时间。由于 PyTorch 和 GPU 库的存在，生成的文件夹将有几个 GB。
后续运行：启动器会检测到已有的便携环境，并在几秒钟内启动服务器。无需互联网，也不会重复设置过程。

关于模型下载的说明

TTS 模型（约 2+ GB）在任何机器上首次启动服务器时，会从 Hugging Face Hub 下载到一个 单独的缓存文件夹 中。这是每台机器一次性的下载，与便携应用程序文件夹无关。

如果您要分享便携安装，接收者在其首次运行时需要互联网连接来进行初始模型下载。要在便携包中预先包含模型，您可以在 config.yaml 中将 model_cache 路径设置为项目目录内的一个文件夹，然后在分享时包含该文件夹。

何时会出现便携模式提示？

在 Windows 系统上首次设置时，启动器会提供选择：

便携模式（推荐，默认）：在项目文件夹内创建一个独立的 python_embedded/ 环境，使用 Python 3.10。任何系统 Python 3.10+ 都可以引导此过程，但嵌入式运行时始终是 Python 3.10。
标准安装：使用常规的 Python 虚拟环境 (venv/)。需要系统 Python 3.10 —— Python 3.11+ 会因关键依赖项缺少预构建的 wheel 而失败。

如果您的系统 Python 是 3.11+，在 Windows 上必须使用便携模式，因为它使用嵌入式 Python 3.10 运行时，完全绕过了依赖项问题。

您可以使用命令行标志完全跳过提示：

python start.py --portable —— 直接进入便携模式
python start.py --no-portable —— 直接进入标准虚拟环境
python start.py --reinstall --portable —— 将现有安装切换为便携模式

Linux / macOS 系统不支持

便携模式是 Windows 特有的。在 Linux 和 macOS 上，使用标准虚拟环境。所有平台都需要 Python 3.10 —— 依赖项兼容性问题（torchvision、ONNX 缺少 wheel）影响所有操作系统，而不仅仅是 Windows。

仍需 GPU 驱动

便携模式包含 Python 和所有 Python 包，但 不包含 GPU 驱动。如果目标机器有 NVIDIA GPU 且您希望使用 GPU 加速，则必须在该机器上安装相应的 NVIDIA 驱动。CPU 模式无需任何驱动即可运行。

🔧 技术细节（面向开发者/贡献者）

其工作原理：

便携模式使用 python.org 提供的官方 CPython 3.10.11 嵌入式发行版 —— 一个最小的、独立的 Python 运行时（安装依赖项前约 8 MB）。
嵌入式发行版的 python310._pth 文件被修补为使用 相对路径（., .., Lib\site-packages）。.. 条目解析为项目根目录，因为 python_embedded/ 始终位于一级深度。这就是实现便携性的关键 —— 不会写入任何绝对路径。
没有虚拟环境激活步骤。没有 activate.bat、activate.ps1，也没有硬编码路径。启动器直接运行 python_embedded/python.exe。
启动器通过 get-pip.py 引导 pip，显式安装 setuptools（perth 水印库在运行时需要），生成用于 DLL 搜索路径配置的 sitecustomize.py，并修补 TTS 引擎的水印初始化以提高弹性。
start.bat 批处理文件找到任何系统 Python 来启动 start.py，然后 start.py 会检测现有的 python_embedded/ 目录并使用它 —— 无论启动器是由哪个系统 Python 版本调用的。

📋 手动安装

适用于希望手动控制安装过程的用户。

2. 创建 Python 虚拟环境

使用虚拟环境对于避免与其他项目发生冲突至关重要。

Windows (PowerShell):

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

Linux (Bash):
```
python3 -m venv venv
source venv/bin/activate
```
您的命令提示符现在应以 (venv) 开头。

3. 选择安装路径

根据您的硬件选择以下命令之一。此单一命令将安装所有必要的依赖项及其兼容版本。

选项 1: 仅 CPU 安装

这是最简单的选项，适用于任何没有兼容 GPU 的机器。

# 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

💡 工作原理

`requirements.txt` 文件会安装 CPU 版 PyTorch 以及所有服务器依赖项。Chatterbox 会通过 `--no-deps` 参数单独安装，以防止 pip 引入冲突的 torch 版本或触发 ONNX 源码构建。

选项 2：NVIDIA GPU 安装（CUDA 12.1）

适用于拥有 NVIDIA GPU 的用户。此选项为 RTX 20/30/40 系列显卡提供最佳性能。

前提条件： 确保已安装最新的 NVIDIA 驱动程序。需要 Python 3.10（不支持 3.11+ 版本 — torchvision 和 ONNX 的预构建 wheel 不可用）。

# 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

安装完成后，请验证 PyTorch 是否能识别您的 GPU：

python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}'); print(f'Device name: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else None}')"

如果 CUDA available: 显示 True，说明您的设置正确！

💡 工作原理

`requirements-nvidia.txt` 文件会安装支持 CUDA 12.1 的 PyTorch 以及所有服务器依赖项。Chatterbox 会单独使用 `--no-deps` 选项安装，以防止 pip 将 CUDA 版本的 PyTorch 降级为 CPU 版本或触发 ONNX 源码构建。

选项 2b：搭载 CUDA 12.8 的 NVIDIA GPU（RTX 5090 / Blackwell）

注意： 仅当您拥有基于 Blackwell 架构的 GPU（RTX 5060 Ti、5070、5070 Ti、5080、5090）时才使用此选项。对于 RTX 2000/3000/4000 系列，请使用上述选项 2。

适用于需要 CUDA 12.8 和 sm_120 支持的 NVIDIA Blackwell 架构 GPU 用户。

前提条件：

NVIDIA RTX 5060 Ti、5070、5070 Ti、5080、5090 或其他基于 Blackwell 架构的 GPU
CUDA 12.8+ 驱动程序（驱动版本 570+）

使用 Docker（RTX 5090 推荐）：

# Build and start with CUDA 12.8 support
docker compose -f docker-compose-cu128.yml up -d

# Access the web UI at http://localhost:8004

手动安装：

# Make sure your (venv) is active
pip install --upgrade pip

# 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

⚠️ 重要提示： 必须使用 --no-deps 标志，以防止 PyTorch 被降级到不支持 Blackwell GPU 的版本。

安装完成后，请验证 PyTorch 是否支持 sm_120：

python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}'); print(f'GPU: {torch.cuda.get_device_name(0)}'); print(f'Architectures: {torch.cuda.get_arch_list()}')"

你应该能在架构列表中看到 sm_120！

💡 为什么选择 CUDA 12.8？

NVIDIA 的 Blackwell GPU（RTX 5060 Ti、5070、5070 Ti、5080、5090）采用计算能力 sm_120。搭配 CUDA 12.8 的 PyTorch 2.9.0 包含对该架构的支持。早期版本（包括 CUDA 12.1）会失败并显示错误：CUDA error: no kernel image is available for execution on the device。

有关详细的设置说明和故障排除，请参见 README_CUDA128.md。

选项 2c：搭载 CUDA 13.0 的 NVIDIA GPU（DGX Spark / sm_121）

注意： 此选项适用于 NVIDIA DGX Spark / GB10 硬件（计算能力 sm_121）。RTX 5090 请使用 cu128（选项 2b）；RTX 30/40 系列请使用 cu121（选项 2）。

适用于需要 CUDA 13.0 和 PyTorch 2.10 的最新 NVIDIA 技术栈用户。

前提条件：

NVIDIA DGX Spark / GB10 或其他支持 sm_121 的硬件
CUDA 13.0+ 驱动程序（驱动版本 580+）

使用 Docker（推荐）：

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

# Access the web UI at http://localhost:8004

Dockerfile.cu130 通过 --no-deps 选项安装 PyTorch 2.10.0+cu130 和 chatterbox-v2，以避免 PyTorch 版本降级。

选项 3：AMD GPU 安装（ROCm）

适用于配备现代、支持 ROCm 的 AMD GPU 的用户。

前提条件： 确保在 Linux 系统上已安装最新的 ROCm 驱动程序。

# Make sure your (venv) is active
pip install --upgrade pip

# Step 1: Install ROCm PyTorch stack first
pip install -r requirements-rocm-init.txt

# 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

⚠️ 重要提示： 在安装chatterbox-tts时，必须使用--no-deps标志，以防止pip将ROCm PyTorch wheel替换为PyPI上的仅CPU版本。start.py启动器会自动处理此问题。

安装完成后，请验证PyTorch能否识别您的GPU：

python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'ROCm available: {torch.cuda.is_available()}'); print(f'Device name: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else None}')"

如果 ROCm available: 显示 True，说明您的设置正确！

💡 工作原理

ROCm 安装采用两步流程：

requirements-rocm-init.txt 从官方 ROCm 6.1 wheel 索引安装 PyTorch（torch==2.5.1+rocm6.1），确保您获得 AMD GPU 加速版本。
requirements-rocm.txt 安装其余的服务器依赖项，不涉及 PyTorch。
Chatterbox 通过 --no-deps 选项安装，以防止 pip 的依赖解析器将 ROCm 版本的 torch 替换为仅 CPU 版本。

对于 APU/iGPU 用户： 如果遇到“HIP error: invalid device function”错误，您可能需要设置 HSA_OVERRIDE_GFX_VERSION。请参阅下方的AMD ROCm 支持详情。

选项 4：Apple Silicon (MPS) 安装

适用于搭载 Apple Silicon 芯片的 Mac 用户（M1、M2、M3、M4 等）。

前提条件： 确保您的 macOS 版本为 12.3 或更高，以支持 MPS。

步骤 1：首先安装支持 MPS 的 PyTorch

# Make sure your (venv) is active
pip install --upgrade pip
pip install torch torchvision torchaudio

步骤 2：将服务器配置为使用 MPS
更新您的 config.yaml 以使用 MPS 而非 CUDA：

tts_engine:
  device: mps  # Changed from 'cuda' to 'mps'

步骤 3：安装剩余依赖项

# 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

# Install a compatible version of ONNX and audio codec
pip install onnx==1.16.0 descript-audio-codec

安装完成后，请验证 PyTorch 是否能识别您的 GPU：

python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'MPS available: {torch.backends.mps.is_available()}'); print(f'Device will use: {\"mps\" if torch.backends.mps.is_available() else \"cpu\"}')"

如果 MPS available: 显示 True，则说明你的设置正确！

💡 此过程为何与众不同

由于 chatterbox-tts 中固定的 PyTorch 版本与支持 MPS 的最新 PyTorch 版本之间存在依赖冲突，Apple Silicon 需要特定的安装顺序。通过先安装支持 MPS 的 PyTorch，然后小心安装依赖项并避免版本冲突，我们可以确保 MPS 加速正常工作。服务器的自动设备检测会在配置并可用时使用 MPS。

```

选项 5：AMD Strix Halo（Ryzen AI MAX+）安装

注意： 此选项适用于 AMD Strix Halo APU（Ryzen AI MAX+ 395 / 集成 Radeon 8060S、GFX 11.5.0 的“Ryzen AI Max”）。标准独立 Radeon GPU 请使用选项 3（ROCm）。

前提条件：

Linux 系统上的 AMD Strix Halo APU
主机上已安装 ROCm 7.2+ 堆栈

使用 Docker（推荐）：

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

# Access the web UI at http://localhost:8004

compose 文件设置了 HSA_OVERRIDE_GFX_VERSION=11.0.0 和 HSA_XNACK=1，以便 ROCm 7.2 轮能够在 Strix Halo 的 GFX 11.5.0 芯片上运行，并启用了 TTS_BF16=on 以在该硬件上实现吞吐量提升。

🚀 在线演示 - 立即体验！（Google Colab）

想立即测试 Chatterbox TTS Server 而无需任何安装吗？

为什么尝试演示？

✅ 完整 Web UI，包含所有控件和功能
✅ 语音克隆，支持上传音频文件
✅ 内置预定义语音
✅ 大文本处理，支持分块（非常适合有声书）
✅ 免费 GPU 加速（T4 GPU）
✅ 无需安装或设置
✅ 适用于任何具有网页浏览器的设备

快速开始：

点击上方徽章在 Google Colab 中打开笔记本
选择 GPU 运行时：运行时 → 更改运行时类型 → T4 GPU → 保存
运行单元格 1：点击播放按钮安装依赖项（约 1-5 分钟）
运行单元格 2：启动服务器并通过提供的链接访问 Web UI
等待 "Server ready! Click below" 消息：找到 "localhost:8004" 链接并点击。这将在您的浏览器中启动 Web UI
生成语音：使用 Web 界面创建高质量 TTS 音频

注意事项：

首次运行：下载模型需要几分钟时间（仅需一次）
会话限制：Colab 免费版有使用限制；闲置后会话可能会超时
生产环境：请使用下面的本地安装或 Docker 部署方法

更喜欢本地安装？继续阅读下面的完整设置说明。

⚙️ 配置

服务器完全依赖 config.yaml 进行运行时配置。

config.yaml: 位于项目根目录。此文件存储所有服务器设置、模型路径、生成默认值和 UI 状态。如果不存在，首次运行时会自动创建（使用 config.py 中的默认值）。这是用于编辑持久化配置更改的主要文件。
UI 配置： Web UI 中的“服务器配置”和“生成参数”部分允许直接编辑值并将其保存到 config.yaml 中。

关键配置区域（在 config.yaml 或 UI 中）：

server: host、port、日志设置。
model: repo_id（例如，"ResembleAI/chatterbox"）。
tts_engine: device（'auto'、'cuda'、'mps'、'cpu'）、predefined_voices_path、reference_audio_path、default_voice_id。
paths: model_cache（用于 download_model.py）、output。
generation_defaults: UI 默认值，用于 temperature、exaggeration、cfg_weight、seed、speed_factor、language。
audio_output: format、sample_rate、max_reference_duration_sec。
ui_state: 存储上次使用的文本、语音模式、文件选择等，用于 UI 持久性。
ui: title、show_language_select、max_predefined_voices_in_dropdown。
debug: save_intermediate_audio。

⭐ 请记住： 在 config.yaml 中（或通过 UI 的“服务器配置”部分）对 server、model、tts_engine 或 paths 部分所做的更改需要重启服务器才能生效。对 generation_defaults 或 ui_state 的更改会动态应用或在下次页面加载时应用。

模型选择： 将 model.repo_id 设置为以下之一：

chatterbox（或 original）— 原始 0.5B 英文模型，支持情感夸张。
chatterbox-turbo（或 turbo）— 350M Turbo 模型，支持副语言标签（[laugh]、[cough]、[chuckle]）。
chatterbox-multilingual（或 multilingual）— 0.5B 多语言模型，支持 23 种语言。

这三种模型都可以从 Web UI 引擎下拉菜单中热切换，无需重启服务器。

🔐 安全性

/tts 接口的语音文件参数（predefined_voice_id、reference_audio_filename）和 /v1/audio/speech 接口的语音参数（voice）通过 utils.safe_resolve_within() 函数限制在其配置的目录范围内。
路径遍历尝试（..、绝对路径、指向沙箱外部的符号链接）将返回 HTTP 400 错误，且不会进行文件系统访问。此修复针对 CWE-22 漏洞，并已在 v2.0.0 版本中发布。
漏洞报告：请使用仓库的“安全”选项卡 → “报告漏洞”进行私密披露，而非公开创建 issue。

⚡ 性能调优

服务器默认设置兼顾了安全性和广泛的兼容性。若您了解自身硬件情况，可通过以下设置牺牲部分安全性以换取速度提升：

BF16 推理 — 设置环境变量 TTS_BF16=on（或 =auto，表示“仅当 GPU 报告 is_bf16_supported() 时启用”），将 T3 转换为 bfloat16 并在自动混合精度模式下运行 generate()。在支持 bf16 的 GPU（RTX 30/40/50 系列、A100、H100、Strix Halo）上，吞吐量大约提升 40%。默认值为 off，以保持升级后的现有行为。输出结果与 float32 在数值上略有差异，但通常无法通过听觉分辨。
语音条件缓存 — 对相同参考语音的重复请求将跳过重新编码。缓存以 (路径, 修改时间, 夸张程度) 为键，并在执行 reload_model() 或调用 /api/unload 时自动清除。无需额外配置。
** chunk 大小** — /tts 接口的 chunk_size 参数（取值范围 50–500，默认值 120）。较大的 chunk 意味着请求次数减少，但每次调用会占用更多显存。无论 chunk 大小如何，分块器都会尊重句子边界。
流式传输 — 对于长文本输入（有声书、多段落内容），可在 /tts 接口设置 stream: true。有关 chunk 级别的注意事项，请参见上文的 API 部分。
HTTPS — 在 config.yaml 中设置 server.ssl_certfile 和 server.ssl_keyfile，即可直接启用 HTTPS，无需在前端部署反向代理。

▶️ 运行服务器

关于模型下载的重要说明（首次运行）： 首次启动服务器时，它需要从 Hugging Face Hub 下载 chatterbox-tts 模型文件。这是一个自动的一次性过程（针对每个模型版本，或在 Hugging Face 缓存被清除之前）。

⏳ 请耐心等待：根据您的互联网速度和模型文件大小（通常为几 GB），此下载过程可能需要几分钟时间。
📝 监控终端：您将看到与下载相关的进度指示或日志。只有在这些必要的模型文件成功下载并加载后，服务器才能完全正常运行并可供访问。
✔️ 后续启动将快得多，因为服务器将使用本地 Hugging Face 缓存中已下载的模型。

您可以选择使用 python download_model.py 脚本将特定的模型组件预下载到 config.yaml 中定义的 ./model_cache 目录。但请注意，运行时引擎（engine.py）主要直接从 Hugging Face Hub 的主缓存加载模型，而非此特定的本地 model_cache 目录。

使用自动启动器（推荐）

运行服务器最简单的方法是使用自动启动器：

Windows：

start.bat

Linux / macOS：

./start.sh

启动器会自动执行以下操作：

激活虚拟环境
验证安装是否完成
启动服务器
等待服务器准备就绪（包括首次运行时的模型下载）
准备就绪后显示访问 URL

手动启动服务器

如果您希望手动启动服务器：

运行步骤：

激活虚拟环境（如果尚未激活）：
- Linux/macOS：source venv/bin/activate
- Windows：.\venv\Scripts\activate
运行服务器：
```
python server.py
```
访问 UI： 服务器启动后（并完成所有初始模型下载），会自动尝试在您的默认浏览器中打开 Web UI。如果未自动打开，请手动导航至 http://localhost:PORT（例如，如果您配置的端口是 8004，则为 http://localhost:8004）。
访问 API 文档： 打开 http://localhost:PORT/docs 可查看交互式 API 文档。
停止服务器： 在运行服务器的终端中按 CTRL+C。


## 🔄 Updating to the Latest Version

Follow these steps to update your local installation to the latest version from GitHub. This guide provides multiple methods: using the automated launcher, the recommended `git stash` workflow, and a manual backup alternative. All methods preserve your local `config.yaml`.

**First, Navigate to Your Project Directory**

Before starting, open your terminal and go to the project folder.

```bash
cd Chatterbox-TTS-Server

方法 1：使用自动启动器（最简单）

启动器提供简单的升级功能，可自动处理所有事宜。

升级（保留硬件选择）：

# First, pull the latest code
git pull origin main

# Then upgrade dependencies using the launcher
# Windows
python start.py --upgrade

# Linux/macOS
python3 start.py --upgrade

完全重新安装（选择新硬件选项）：

git pull origin main

# Windows
python start.py --reinstall

# Linux/macOS
python3 start.py --reinstall

--upgrade 标志会保留您当前的硬件选择（CPU、NVIDIA 等）并重新安装依赖项。

--reinstall 标志会完全移除现有安装，并重新显示硬件选择菜单。

更改硬件配置：

要切换到不同的硬件配置（例如，从 CPU 切换到 NVIDIA，或从 CUDA 12.1 切换到 CUDA 12.8）：

# Shows menu to select new hardware
python start.py --reinstall

# Or specify directly
python start.py --reinstall --nvidia
python start.py --reinstall --nvidia-cu128
python start.py --reinstall --cpu
python start.py --reinstall --rocm

方法 2：暂存与恢复（推荐手动安装用户使用）

如果您未通过启动器手动安装，这是使用 Git 进行更新的标准且最安全的方法。它会自动处理您的本地更改（例如对 config.yaml 的修改），无需手动复制文件。

首先，激活您的虚拟环境：

# On Windows (PowerShell):
.\venv\Scripts\activate

# On Linux (Bash):
source venv/bin/activate

步骤 1：暂存本地更改 此命令会将您的修改安全地存储在临时“暂存区”中。
```
git stash
```
步骤 2：拉取最新版本 现在您的本地更改已安全存储，可以从 GitHub 下载最新代码了。
```
git pull origin main
```
步骤 3：重新应用您的更改 此命令会从暂存区取出您的更改，并将其应用到更新后的代码中。
```
git stash pop
```
您的 config.yaml 现在将保留您的设置，而项目的其他文件将是最新的。您现在可以继续执行下面的 “最终步骤” 部分。

方法 3：手动备份（替代方案）

此方法涉及手动备份和恢复您的配置文件。

首先，激活您的虚拟环境：

# On Windows (PowerShell):
.\venv\Scripts\activate

# On Linux (Bash):
source venv/bin/activate

步骤 1：备份配置 ⚠️ 重要提示： 请为您的 config.yaml 创建备份，以保存您的自定义设置。
```
# 为当前配置创建备份
cp config.yaml config.yaml.backup
```
步骤 2：更新仓库 根据您的需求选择以下命令之一：
- 标准更新（推荐）：
```
git pull origin main
```
  如果您遇到 config.yaml 的合并冲突，可能需要手动解决。
- 强制更新（若存在冲突或希望确保更新干净）：
```
# 获取最新更改并重置以完全匹配远程仓库
git fetch origin
git reset --hard origin/main
```
步骤 3：恢复配置
```
# 恢复备份的配置
cp config.yaml.backup config.yaml
```
现在，请继续执行 “最终步骤” 部分。

最终步骤（适用于方法 2 和 3）

使用方法 2 或 3 更新代码后，请完成以下最终步骤。

1. 检查新配置选项

⭐ 推荐： 将您恢复的 config.yaml 与新的默认配置进行比较，查看是否有您可能需要采用的新选项。服务器会添加带有默认值的新键，但您可能需要对其进行检查。

2. 更新依赖项

⭐ 重要提示： 拉取新代码后，请务必更新依赖项，以确保您拥有正确的版本。选择与您硬件匹配的命令：

对于仅 CPU 系统：
```
pip install -r requirements.txt
```
对于 NVIDIA GPU 系统（CUDA 12.1）：
```
pip install -r requirements-nvidia.txt
```

对于 NVIDIA GPU 系统（CUDA 12.8 / Blackwell）：

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

对于 AMD GPU 系统：
```
pip install -r requirements-rocm.txt
```

3. 重启服务器

如果服务器正在运行，请停止它（CTRL+C）并重启，以应用所有更新。

python server.py

⭐ 注意： 通过此方法，您在 config.yaml 中的自定义设置将被保留。服务器会在需要时自动添加任何带有默认值的新配置选项。一旦确认所有功能正常工作，您可以安全删除 config.yaml.backup。

⭐ Docker 用户： 如果您使用 Docker 且已将本地 config.yaml 作为卷挂载，则在运行前同样适用上述备份/恢复流程：

docker compose down
docker compose pull  # if using pre-built images
docker compose up -d --build

对于 RTX 5090 / Blackwell GPU： 使用 CUDA 12.8 配置：

docker compose -f docker-compose-cu128.yml down
docker compose -f docker-compose-cu128.yml pull
docker compose -f docker-compose-cu128.yml up -d --build

💡 使用方法

Web UI（`http://localhost:PORT`）

使用服务器最直观的方式：

引擎选择器：通过顶部的下拉菜单在Original Chatterbox和Chatterbox‑Turbo之间切换。后端会自动加载所选引擎。
文本输入：输入您的纯文本脚本。对于有声书：只需粘贴整本书的文本 - 分块系统会自动处理长文本并创建无缝的音频输出。
语音模式：选择：
- Predefined Voices（预设语音）：从 ./voices 目录中选择一个精选语音。
- Voice Cloning（语音克隆）：从 ./reference_audio 中选择一个已上传的参考文件。
预设：从 ui/presets.yaml 加载示例。新的预设展示了Turbo的副语言标签功能。
参考/预设音频管理：导入新文件并刷新列表。
生成参数：调整温度（Temperature）、夸张度（Exaggeration）、CFG权重（CFG Weight）、速度因子（Speed Factor）、种子值（Seed）。将默认值保存到 config.yaml。
分块控制：切换“将文本分割成块”并为长文本调整“块大小”。
服务器配置：查看/编辑 config.yaml 的部分内容（某些更改需要重启服务器）。
音频播放器：播放生成的音频并带有波形可视化。

使用副语言标签（Turbo）

当引擎选择器设置为Chatterbox‑Turbo时，您可以在文本中内联包含副语言标签：

Hi there [chuckle] — thanks for calling back.
One moment… [cough] sorry about that. Let's get this fixed.

Turbo 支持 [laugh]、[cough] 和 [chuckle] 等原生标签，可实现更逼真、更富表现力的语音。使用 Original Chatterbox 时，这些标签会被忽略。

API 端点（详情可通过 `/docs` 交互查看）

TTS 生成的主要端点是 /tts。为了能直接替代 OpenAI 的 TTS API，还提供了与 OpenAI 兼容的 /v1/audio/speech 和 /v1/audio/voices 端点。

端点	方法	用途
`/tts`	POST	自定义 TTS，完整参数集，支持 `stream: true`（mp3 / wav / opus）
`/v1/audio/speech`	POST	与 OpenAI 兼容的 TTS
`/v1/audio/voices`	GET	与 OpenAI 兼容的语音列表
`/api/ui/initial-data`	GET	UI 引导程序 + 全面健康检查
`/api/model-info`	GET	已加载模型状态、类型、支持的语言
`/api/unload`	POST	释放 GPU 内存，无需重启服务器
`/save_settings`	POST	将部分更新持久化到 `config.yaml`
`/reset_settings`	POST	将 `config.yaml` 重置为默认值
`/get_reference_files`	GET	列出 `reference_audio/` 中的文件
`/get_predefined_voices`	GET	列出 `voices/` 中的格式化语音
`/upload_reference`	POST	上传参考音频文件
`/upload_predefined_voice`	POST	上传预定义语音文件
`/docs`	GET	交互式 Swagger UI

/tts 请求体（CustomTTSRequest）：

text（字符串，必填）—— 待合成的纯文本。
voice_mode（"predefined" | "clone"，默认 "predefined"）。
predefined_voice_id（字符串）—— 当 voice_mode=predefined 时的语音文件名。
reference_audio_filename（字符串）—— 当 voice_mode=clone 时的参考文件名。
output_format（"wav" | "mp3" | "opus"，默认 "wav"）。当 stream=true 时忽略（流式传输始终使用 WAV）。
split_text（布尔值，默认 true）—— 按句子分割长文本。
chunk_size（整数 50–500，默认 120）。
stream（布尔值，默认 false）—— 若为 true，则返回 StreamingResponse，在合成每个 chunk 时刷新 WAV 字节。
temperature、exaggeration、cfg_weight、seed、speed_factor、language —— 用于覆盖默认值的生成参数。

流式传输注意事项： 底层 Chatterbox 模型通过一次前向传播合成完整的 chunk，因此 stream=true 是chunk 级的，而非 token 级。对于短文本（1 个 chunk），它不会带来首字节时间的优势。对于长篇/有声书输入（多个 chunks），客户端可以在 chunk 1 准备就绪后立即开始播放，同时后台渲染后续 chunks。

示例 — 流式 TTS：

curl -X POST http://localhost:8004/tts \
  -H "Content-Type: application/json" \
  -d '{"text":"The first chunk arrives quickly, the rest stream behind.","stream":true}' \
  --output stream.wav

🐳 Docker 安装

使用 Docker 可轻松运行 Chatterbox TTS Server。推荐使用 Docker Compose 方法，它已针对不同 GPU 类型进行预配置。

前提条件

已安装 Docker。
已安装 Docker Compose（通常随 Docker Desktop 一起包含）。
（如需 GPU 加速）
- NVIDIA： 已安装最新驱动程序和 NVIDIA Container Toolkit。
- AMD： 在 Linux 主机上已安装最新的 ROCm 驱动程序。用户必须属于 video 和 render 用户组。

使用 Docker Compose（推荐）

此方法使用提供的 docker-compose.yml 文件来轻松管理容器、卷和配置。

1. 克隆仓库

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

2. 根据您的硬件启动容器

适用于 NVIDIA GPU：

默认的 docker-compose.yml 配置适用于 NVIDIA RTX 20/30/40 系列（CUDA 12.1）。

docker compose up -d --build

对于 RTX 50 系列 / Blackwell (sm_120)，请使用 cu128 组合文件：

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

对于 DGX Spark / GB10 (sm_121)，请使用 cu130 组合文件：

docker compose -f docker-compose-cu130.yml up -d --build

适用于 AMD ROCm GPU（仅 Linux）：

前提条件： 确保您的主机系统已安装 ROCm 驱动程序，并且您的用户属于所需组：

# Add your user to required groups (one-time setup)
sudo usermod -a -G video,render $USER
# Log out and back in for changes to take effect

启动容器：

docker compose -f docker-compose-rocm.yml up -d --build

对于 AMD Strix Halo (Ryzen AI MAX+)，请使用专用的 compose 文件：

docker compose -f docker-compose-strixhalo.yml up -d --build

仅 CPU 版本：

现已为仅使用 CPU 的用户提供专用的 compose 文件，以避免 GPU 驱动程序错误。

docker compose -f docker-compose-cpu.yml up -d --build

⭐ 注意： 首次运行时，Docker 会构建镜像并下载模型文件，此过程可能需要一些时间。后续启动速度会快很多。

3. 访问应用程序

在 Web 浏览器中打开 http://localhost:PORT（例如 http://localhost:8004 或您配置的主机端口）。

4. 验证 GPU 访问权限

对于 NVIDIA GPU：

# Check if container can see NVIDIA GPU
docker compose exec chatterbox-tts-server nvidia-smi

# Verify PyTorch can access the GPU
docker compose exec chatterbox-tts-server python3 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU count: {torch.cuda.device_count()}')"

适用于 AMD ROCm GPU：

# Check if container can see AMD GPU
docker compose -f docker-compose-rocm.yml exec chatterbox-tts-server rocm-smi

# Verify PyTorch can access the GPU  
docker compose -f docker-compose-rocm.yml exec chatterbox-tts-server python3 -c "import torch; print(f'ROCm available: {torch.cuda.is_available()}'); print(f'Device name: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"No GPU detected\"}')"

5. 查看日志和管理容器

# 查看日志

```bash
docker compose logs -f                                    # For NVIDIA
docker compose -f docker-compose-rocm.yml logs -f         # For AMD
docker compose -f docker-compose-cpu.yml logs -f          # For CPU

停止容器

docker compose down                                       # For NVIDIA
docker compose -f docker-compose-rocm.yml down            # For AMD
docker compose -f docker-compose-cpu.yml down             # For CPU

重启容器

docker compose restart chatterbox-tts-server              # For NVIDIA
docker compose -f docker-compose-rocm.yml restart chatterbox-tts-server # For AMD
docker compose -f docker-compose-cpu.yml restart chatterbox-tts-server # For CPU

AMD ROCm 支持详情

GPU 架构覆盖（高级用户）

如果您的 AMD GPU 未获得 ROCm 的官方支持，但与受支持的架构相似，您可以覆盖检测到的架构：

# For RX 5000/6000 series (gfx10xx) - override to gfx1030
HSA_OVERRIDE_GFX_VERSION=10.3.0 docker compose -f docker-compose-rocm.yml up -d

# For RX 7000 series (gfx11xx) - override to gfx1100  
HSA_OVERRIDE_GFX_VERSION=11.0.0 docker compose -f docker-compose-rocm.yml up -d

# For Vega cards - override to gfx906
HSA_OVERRIDE_GFX_VERSION=9.0.6 docker compose -f docker-compose-rocm.yml up -d

检查您的 GPU 架构：

# Method 1: Using rocminfo (if ROCm installed on host)
rocminfo | grep "Name:"

# Method 2: Using lspci
lspci | grep VGA

常见 GPU 架构映射：

Ryzen AI Max+ 395 (Strix Halo)、RX 7900 XTX/XT、RX 7800 XT、RX 7700 XT： gfx1100/gfx1150 → 使用 HSA_OVERRIDE_GFX_VERSION=11.0.0
RX 6900 XT、RX 6800 XT、RX 6700 XT、RX 6600 XT： gfx1030-1032 → 使用 HSA_OVERRIDE_GFX_VERSION=10.3.0
RX 5700 XT、RX 5600 XT： gfx1010 → 使用 HSA_OVERRIDE_GFX_VERSION=10.3.0
Vega 64、Vega 56： gfx900-906 → 使用 HSA_OVERRIDE_GFX_VERSION=9.0.6

ROCm 兼容性说明

支持的 GPU： AMD Instinct 数据中心 GPU 和部分 Radeon GPU。请查看 ROCm 兼容性列表。
操作系统： ROCm 目前仅支持 Linux 系统。
性能： 配备 ROCm 的 AMD GPU 为机器学习工作负载提供出色性能，并支持混合精度训练。
PyTorch 版本： 使用来自 PyTorch 官方 wheel 索引的 PyTorch 2.5.1 与 ROCm 6.1，以获得最佳兼容性。

🔍 故障排除

启动器问题

“Python not found” 错误：
- 确保已安装 Python 3.10 并将其添加到 PATH（标准安装不支持 3.11+ 版本）
- Windows：重新安装 Python，并在安装过程中勾选“Add Python to PATH”
- Linux：使用 sudo apt install python3 python3-venv python3-pip 命令安装
“venv module not found”（Linux）：
```
sudo apt install python3-venv
```
安装卡住或失败：
- 以详细模式运行以获取更多信息：python start.py --reinstall --verbose
- 检查网络连接
- 确保有足够的磁盘空间（建议 10GB 以上）
删除虚拟环境时出现权限错误（Windows）：
- 关闭所有可能打开了虚拟环境文件夹中文件的终端和编辑器
- 尝试以管理员身份运行
- 手动删除虚拟环境文件夹：rmdir /s /q venv
如何在便携模式和标准模式之间切换？
- 使用 --reinstall 移除现有环境并重新选择
- 或直接指定：python start.py --reinstall --portable 或 python start.py --reinstall --no-portable
我共享了便携文件夹，但模型再次下载：
- TTS 模型与应用程序文件夹分开缓存（位于 Hugging Face 缓存中）
- 每台机器在首次运行时会下载一次模型
- 要将模型包含在便携包中，请在 config.yaml 中将 model_cache 设置为项目文件夹内的路径
未提供便携模式 / 我使用的是 Linux：
- 便携模式仅适用于 Windows。在 Linux 和 macOS 上，请使用 Python 3.10 创建标准虚拟环境
硬件检测错误：
- 启动器通过 nvidia-smi 检测 NVIDIA GPU，通过 rocm-smi 检测 AMD GPU
- 如果检测失败，请使用直接安装标志：--cpu、--nvidia、--nvidia-cu128、--rocm

检查安装类型：

# 安装类型存储在 venv/.install_type 中
cat venv/.install_type  # Linux/macOS
type venv\.install_type  # Windows

Apple Silicon（MPS）问题

MPS不可用：确保您使用的是macOS 12.3或更高版本以及Apple Silicon芯片的Mac。可通过命令python -c "import torch; print(torch.backends.mps.is_available())"进行验证。
Turbo模型Float64错误：如果您看到“Cannot convert a MPS Tensor to float64 dtype”错误，请更新到最新版本。此问题已在chatterbox-v2分支中修复（s3tokenizer和voice_encoder强制使用float32）。start.py启动器也会自动应用此补丁。
安装冲突：如果遇到版本冲突，请按照选项4中针对Apple Silicon的准确安装步骤操作，先安装PyTorch，再安装其他依赖项。
ONNX构建错误：现已解决——所有 requirements 文件中均固定了onnx==1.16.0以使用预构建的wheels。如果仍然遇到问题，请确保您使用的是Python 3.10。
模型加载错误：确保config.yaml的tts_engine部分中设置了device: auto（或device: mps）。

NVIDIA GPU问题

CUDA不可用/运行缓慢：检查NVIDIA驱动程序（使用nvidia-smi命令），确保安装了正确的支持CUDA的PyTorch（参见安装选项）。
“No kernel image available”错误：
- 对于RTX 5090/Blackwell：使用--nvidia-cu128或requirements-nvidia-cu128.txt，而非标准的NVIDIA安装方式。
- 对于较旧的GPU（RTX 20/30/40系列）：使用--nvidia或requirements-nvidia.txt。
显存不足（OOM）：
- 确保您的GPU满足Chatterbox的最低要求。
- 关闭其他占用GPU资源的应用程序。
- 如果即使使用分块处理超长文本时仍出现问题，请尝试减小chunk_size（例如，100-150）。

AMD GPU问题

Windows系统上ROCm无法工作：
- ROCm仅支持Linux系统——在Windows系统上使用AMD GPU时，请使用CPU模式。
- 如果您在Windows系统上选择了ROCm，启动器会发出警告。

常见问题

ONNX/wheel构建失败：这通常是由于使用Python 3.11或更高版本，而该版本缺乏预构建的wheels。请使用Python 3.10，并确保固定安装onnx==1.16.0。更新后的requirements文件会自动处理此问题。
“No matching distribution found for torchvision”或“torch==2.5.1+cu121”：您可能使用的是Python 3.11或更高版本，该版本并非所有固定依赖项都有预构建的wheels。请使用Python 3.10，或使用Windows启动器的便携模式，它会自动处理此问题。
导入错误（例如chatterbox-tts、librosa）：确保虚拟环境已激活且依赖项已成功安装。尝试重新安装：python start.py --reinstall。
libsndfile错误（Linux）：运行sudo apt install libsndfile1。
模型下载失败：检查网络连接。ChatterboxTTS.from_pretrained()将尝试从Hugging Face Hub下载模型。确保config.yaml中的model.repo_id正确无误。
语音克隆/预定义语音问题：
- 确保文件存在于正确的目录中（./reference_audio、./voices）。
- 检查服务器日志，查看与文件加载或处理相关的错误。
权限错误（保存文件/配置）：检查./config.yaml、./logs、./outputs、./reference_audio、./voices以及使用Docker卷时的Hugging Face缓存目录的写入权限。
UI问题/设置不保存：清除浏览器缓存/本地存储。检查浏览器开发者控制台（F12）中的JavaScript错误。确保服务器进程对config.yaml具有写入权限。
端口冲突（“Address already in use”）：有其他进程正在使用该端口。请停止该进程或在config.yaml中修改server.port（需要重启服务器）。
- 查找占用端口的进程：Windows系统使用netstat -ano | findstr :8004，Linux系统使用lsof -i :8004。
生成取消按钮：这是一个“UI取消”——它会停止前端的等待，但不会立即终止正在进行的后端模型推理。再次点击“生成”按钮会取消之前的UI等待。

在多GPU系统上选择GPU

在运行 python server.py（或运行启动器）之前，设置 CUDA_VISIBLE_DEVICES 环境变量，以指定 PyTorch 应识别哪些 GPU。服务器将使用第一个可见的 GPU（从 PyTorch 的角度看，实际为 cuda:0）。

示例（仅使用物理 GPU 1）：
- Linux/macOS：CUDA_VISIBLE_DEVICES="1" python server.py
- Windows 命令提示符：set CUDA_VISIBLE_DEVICES=1 && python server.py
- Windows PowerShell：$env:CUDA_VISIBLE_DEVICES="1"; python server.py
示例（使用物理 GPU 6 和 7 - 服务器使用 GPU 6）：
- Linux/macOS：CUDA_VISIBLE_DEVICES="6,7" python server.py
- Windows 命令提示符：set CUDA_VISIBLE_DEVICES=6,7 && python server.py
- Windows PowerShell：$env:CUDA_VISIBLE_DEVICES="6,7"; python server.py

注意： CUDA_VISIBLE_DEVICES 用于选择 GPU；如果所选 GPU 内存不足，它不能解决内存溢出（OOM）错误。

验证命令

检查 Python 版本：

python --version

检查 PyTorch 和 CUDA：

python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}')"

检查 PyTorch 架构（以支持 Blackwell）：

python -c "import torch; print(torch.cuda.get_arch_list())"

手动测试服务器：

# Activate venv first, then:
python server.py

Docker 配置

主配置文件：服务器使用 config.yaml 进行设置。docker-compose 文件会将您本地的 config.yaml 挂载到容器内的 /app/config.yaml。
首次运行：如果本地不存在 config.yaml，应用程序将自动创建一个包含合理默认值的配置文件。
编辑配置：您可以直接编辑本地的 config.yaml。若修改了服务器/模型/路径相关设置，需重启容器：
```
docker compose restart chatterbox-tts-server
```
UI 设置：生成默认值和 UI 状态的更改通常由应用程序自动保存。

Docker 卷

持久化数据通过卷挂载存储在您的主机上：

./config.yaml:/app/config.yaml - 应用程序主配置文件
./voices:/app/voices - 预定义的语音音频文件
./reference_audio:/app/reference_audio - 您上传的用于克隆的参考音频文件
./outputs:/app/outputs - 从 UI/API 保存的生成音频文件
./logs:/app/logs - 服务器日志文件
hf_cache:/app/hf_cache - Hugging Face 模型缓存的命名卷（用于持久化下载内容）

卷管理：

# Remove all data (including downloaded models)
docker compose down -v

# Remove only application data (keep model cache)
docker compose down
sudo rm -rf voices/ reference_audio/ outputs/ logs/ config.yaml

# View volume usage
docker system df

🔍 故障排除

Apple Silicon (MPS) 问题：
- MPS 不可用： 确保您使用的是 macOS 12.3 或更高版本以及 Apple Silicon 芯片的 Mac。可通过 python -c "import torch; print(torch.backends.mps.is_available())" 命令进行验证。
- 安装冲突： 如果遇到版本冲突，请按照选项 3 中精确的 Apple Silicon 安装步骤操作，先安装 PyTorch，再安装其他依赖项。
- ONNX 构建错误： 按照安装步骤中所示，使用特定的 ONNX 版本 pip install onnx==1.16.0。
- 模型加载错误： 确保 config.yaml 的 tts_engine 部分中设置了 device: mps。
CUDA 不可用/运行缓慢： 检查 NVIDIA 驱动程序（使用 nvidia-smi 命令），确保已安装正确的支持 CUDA 的 PyTorch（安装步骤 4）。
显存不足 (OOM)：
- 确保您的 GPU 满足 Chatterbox 的最低要求。
- 关闭其他占用大量 GPU 资源的应用程序。
- 如果即使使用分块处理超长文本仍出现问题，尝试减小 chunk_size（例如，100-150）。
导入错误（例如 chatterbox-tts、librosa）： 确保虚拟环境已激活，并且 pip install -r requirements.txt 命令已成功完成。
libsndfile 错误 (Linux)： 运行 sudo apt install libsndfile1。
模型下载失败： 检查网络连接。ChatterboxTTS.from_pretrained() 将尝试从 Hugging Face Hub 下载模型。确保 config.yaml 中的 model.repo_id 正确无误。
语音克隆/预定义语音问题：
- 确保文件存在于正确的目录中（./reference_audio、./voices）。
- 检查服务器日志，查找与文件加载或处理相关的错误。
权限错误（保存文件/配置）： 检查 ./config.yaml、./logs、./outputs、./reference_audio、./voices 以及使用 Docker 卷时的 Hugging Face 缓存目录的写入权限。
UI 问题/设置不保存： 清除浏览器缓存/本地存储。检查浏览器开发者控制台（F12）是否有 JavaScript 错误。确保服务器进程对 config.yaml 具有写入权限。
端口冲突（Address already in use）： 该端口已被其他进程占用。停止该进程或在 config.yaml 中更改 server.port（需要重启服务器）。
生成取消按钮： 这是一个“UI 取消”功能 - 它会停止前端的等待，但不会立即终止正在进行的后端模型推理。再次点击“生成”按钮会取消之前的 UI 等待。

在多 GPU 系统中选择 GPU

在运行 python server.py 之前，设置 CUDA_VISIBLE_DEVICES 环境变量，以指定 PyTorch 应识别哪些 GPU。服务器将使用第一个可见的 GPU（从 PyTorch 的角度来看，实际上是 cuda:0）。

示例（仅使用物理 GPU 1）：
- Linux/macOS：CUDA_VISIBLE_DEVICES="1" python server.py
- Windows 命令提示符：set CUDA_VISIBLE_DEVICES=1 && python server.py
- Windows PowerShell：$env:CUDA_VISIBLE_DEVICES="1"; python server.py
示例（使用物理 GPU 6 和 7 - 服务器使用 GPU 6）：
- Linux/macOS：CUDA_VISIBLE_DEVICES="6,7" python server.py
- Windows 命令提示符：set CUDA_VISIBLE_DEVICES=6,7 && python server.py
- Windows PowerShell：$env:CUDA_VISIBLE_DEVICES="6,7"; python server.py

注意： CUDA_VISIBLE_DEVICES 用于选择 GPU；如果所选 GPU 内存不足，它不能解决内存溢出（OOM）错误。

🤝 贡献

欢迎贡献！如果发现错误或有功能建议，请随时提交 issue，或提交 Pull Request 进行改进。

📜 许可证

本项目采用 MIT 许可证 授权。

您可以在此处查看：https://opensource.org/licenses/MIT

🙏 致谢

核心模型： 本项目使用了 Resemble AI 开发的 Chatterbox TTS 模型。
UI 灵感： 特别感谢 Lex-au，其 Orpheus-FastAPI 项目为 Web 界面设计提供了灵感。
类似项目： 本服务器与我们的 Dia-TTS-Server 和 Kitten-TTS-Server 项目在架构上相似，这些项目使用不同的 TTS 引擎。
容器化技术： Docker 和 NVIDIA Container Toolkit。
核心库：
- FastAPI
- Uvicorn
- PyTorch
- Hugging Face Hub & SafeTensors
- Descript Audio Codec (DAC)
- SoundFile & libsndfile
- Jinja2
- WaveSurfer.js

Introduction

自行托管强大的Chatterbox TTS模型。此服务器提供用户友好的Web界面，灵活的API端点（包括兼容OpenAI），预设语音、语音克隆、大文本处理以及GPU/CPU执行功能。【此简介由AI生成】

Customize your domain

README

101.44 K354Visit GitHub

Chatterbox-TTS-Server:基于 Chatterbox TTS 引擎的语音合成服务器项目

Chatterbox TTS Server：兼容 OpenAI API，具备 Web UI、大文本处理及内置语音功能

🆕 新增功能

🚀 v2.0.0 亮点（新）

📦 Windows 便携模式（新）

🌍 Chatterbox 多语言支持（新增）

⚡ Chatterbox‑Turbo 支持（新增）

🔁 热插拔 TTS 引擎（UI）

🎭 副语言标签（Turbo）

✅ 原版 Chatterbox 依旧是一流之选

🎯 全面支持 Chatterbox 系列模型

🖥️ 全平台安装修复

🧰 自动化启动器 + 轻松更新

🗣️ 概述：增强版 Chatterbox TTS 生成

✨ 本服务器的核心功能

✅ 功能摘要

🔩 系统先决条件

硬件兼容性矩阵

💻 安装与设置

🚀 使用自动化启动器快速开始（推荐）

Windows

Linux / macOS

运行流程

启动器命令行选项

后续运行

📦 便携模式（Windows）

便携模式的用途

首次运行与后续运行

关于模型下载的说明

何时会出现便携模式提示？

Linux / macOS 系统不支持

仍需 GPU 驱动

📋 手动安装

选项 1: 仅 CPU 安装

选项 2：NVIDIA GPU 安装（CUDA 12.1）

选项 2b：搭载 CUDA 12.8 的 NVIDIA GPU（RTX 5090 / Blackwell）

选项 2c：搭载 CUDA 13.0 的 NVIDIA GPU（DGX Spark / sm_121）

选项 3：AMD GPU 安装（ROCm）

选项 4：Apple Silicon (MPS) 安装

选项 5：AMD Strix Halo（Ryzen AI MAX+）安装

🚀 在线演示 - 立即体验！（Google Colab）

为什么尝试演示？

快速开始：

注意事项：

⚙️ 配置

🔐 安全性

⚡ 性能调优

▶️ 运行服务器

使用自动启动器（推荐）

手动启动服务器

方法 1：使用自动启动器（最简单）

方法 2：暂存与恢复（推荐手动安装用户使用）

方法 3：手动备份（替代方案）

最终步骤（适用于方法 2 和 3）

💡 使用方法

Web UI（http://localhost:PORT）

使用副语言标签（Turbo）

API 端点（详情可通过 /docs 交互查看）

🐳 Docker 安装

前提条件

使用 Docker Compose（推荐）

1. 克隆仓库

2. 根据您的硬件启动容器

适用于 NVIDIA GPU：

适用于 AMD ROCm GPU（仅 Linux）：

仅 CPU 版本：

3. 访问应用程序

4. 验证 GPU 访问权限

对于 NVIDIA GPU：

适用于 AMD ROCm GPU：

5. 查看日志和管理容器

停止容器

重启容器

AMD ROCm 支持详情

GPU 架构覆盖（高级用户）

ROCm 兼容性说明

🔍 故障排除

启动器问题

Apple Silicon（MPS）问题

NVIDIA GPU问题

Web UI（`http://localhost:PORT`）

API 端点（详情可通过 `/docs` 交互查看）