Spaces:
Running
Running
| title: Chatterbox TTS API | |
| sdk: docker | |
| app_port: 7860 | |
| # Chatterbox TTS API 服务 | |
| 这是一个基于 [Chatterbox-TTS](https://github.com/resemble-ai/chatterbox) 的高性能文字转语音（TTS）服务。它提供了一个与 OpenAI TTS 兼容的 API 接口、一个支持声音克隆的增强接口，以及一个简洁的 Web 用户界面。 | |
| 本项目旨在为开发者和内容创作者提供一个私有化部署、功能强大且易于集成的 TTS 解决方案。 | |
|  | |
| ## ✨ 功能特性 | |
| - **支持 23种语言** | |
| - **两种 API 接口**: | |
| 1. **OpenAI 兼容接口**: `/v1/audio/speech`，可无缝对接到任何支持 OpenAI SDK 的现有工作流中。 | |
| 2. **声音克隆接口**: `/v2/audio/speech_with_prompt`，通过上传一小段参考音频，即可生成具有相同音色的语音。 | |
| - **Web 用户界面**: 提供一个直观的前端页面，用于快速测试和使用 TTS 功能，无需编写任何代码。 | |
| - **灵活的输出格式**: 支持生成 `.mp3` 和 `.wav` 格式的音频。 | |
| - **跨平台支持**: 提供在 Windows, macOS 和 Linux 上的详细安装指南。 | |
| - **一键式 Windows 部署**: 为 Windows 用户提供了包含所有依赖和启动脚本的压缩包，实现开箱即用。 | |
| - **GPU 加速**: 支持 NVIDIA GPU（CUDA），并为 Windows 用户提供了一键升级脚本。 | |
| - **无缝集成**: 可作为后端服务，与 [pyVideoTrans](https://github.com/jianchang512/pyvideotrans) 等工具轻松集成。 | |
| --- | |
| ## 🚀 快速开始 | |
| ### 方式一：Windows 用户（推荐，一键启动） | |
| 我们为 Windows 用户准备了包含所有依赖的便携包 `win.7z`，大大简化了安装过程。 | |
| 1. **下载并解压**: | |
| - 百度网盘下载地址【内置模型共5.9G】： https://pan.baidu.com/s/12Le6rhOQnBL-sNd0uGZ91A?pwd=t55t | |
| > 压缩包内含模型和所需环境文件，体积较大，分2个压缩卷下载，下载后全部选中解压即可，解压路径中最好不要包含中文 | |
| - 百度网盘下载地址【不含模型460MB启动后自动下载，需科学上网】： https://pan.baidu.com/s/1g3w1jFHxe_IjqgasoiVB6w?pwd=nf8v | |
| - GitHub 下载地址【不含模型460MB启动后自动下载，需科学上网】：https://github.com/jianchang512/chatterbox-api/releases/download/0.2/1020-chatterbox-win-NO-Models.7z | |
| 2. **启动服务**: | |
| - 双击运行根目录下的 **`启动服务.bat`** 脚本。 | |
| 当您在命令行窗口看到类似以下信息时，表示服务已成功启动： | |
|  | |
| ``` | |
| ✅ 模型加载完成. | |
| 服务启动完成，http地址是： http://127.0.0.1:5093 | |
| ``` | |
| ### 方式二：macOS, Linux 和手动安装用户 | |
| 对于 macOS, Linux 用户，或者希望手动设置环境的 Windows 用户，请按照以下步骤操作。 | |
| > ### 纯CPU运行注意 | |
| > | |
| > 在 Windows和Linux上，如果想CPU运行，需要修改源码，虚拟环境下/Lib/site-packages/chatterbox/mtl_tts.py` | |
| > | |
| > 搜索`torch.load(ckpt_dir / "ve.pt",` 改为 `torch.load(ckpt_dir / "ve.pt", map_location=device,` | |
| > | |
| > 搜索 `torch.load(ckpt_dir / "s3gen.pt",` 改为 `torch.load(ckpt_dir / "s3gen.pt", map_location=device,` | |
| #### 1. 前置依赖 | |
| - **Python**: 确保已安装 Python 3.10 或更高版本。 | |
| - **ffmpeg**: 这是一个必需的音视频处理工具。 | |
| - **macOS (使用 Homebrew)**: `brew install ffmpeg` | |
| - **Debian/Ubuntu**: `sudo apt-get update && sudo apt-get install ffmpeg` | |
| - **Windows (手动)**: 下载 [ffmpeg](https://ffmpeg.org/download.html) ，并将其添加到系统环境变量 `PATH` 中。 | |
| #### 2. 安装步骤 | |
| ```bash | |
| # 1. 克隆项目仓库 | |
| git clone https://github.com/jianchang512/chatterbox-api.git | |
| cd chatterbox-api | |
| # 2. 创建并激活 Python 虚拟环境 (推荐) | |
| python3 -m venv venv | |
| # on Windows: | |
| # venv\Scripts\activate | |
| # on macOS/Linux: | |
| source venv/bin/activate | |
| # 3. 安装依赖 | |
| pip install -r requirements.txt | |
| # 4. 启动服务 | |
| python app.py | |
| ``` | |
| 当服务成功启动后，您将在终端看到服务地址 `http://127.0.0.1:5093`。 | |
| --- | |
| ## ☁️ 部署到 Hugging Face Spaces（免费 CPU，API 对外） | |
| 1. 新建 Space，选择 `Docker`。 | |
| 2. 直接上传本仓库代码（`chatterbox-api` 目录内容）到 Space。 | |
| 3. Space 构建完成后即可访问： | |
| - Web UI: `https://<your-space>.hf.space/` | |
| - OpenAI 兼容 API: `https://<your-space>.hf.space/v1/audio/speech` | |
| - 声音克隆 API: `https://<your-space>.hf.space/v2/audio/speech_with_prompt` | |
| 如果你是用一键脚本部署（同 `whisperx-api` 的方式），直接用 `chatterbox-api/chouxiang/deploy.py`，并在 `chatterbox-api/chouxiang/.env` 里设置： | |
| - `DEFAULT_STEPS=200`（CPU 建议 100–300，越小越快） | |
| - `TORCH_NUM_THREADS=2` | |
| - `TORCH_NUM_INTEROP_THREADS=1` | |
| ## ⚡ 升级到 GPU 版本 (可选) | |
| 如果您的电脑配备了支持 CUDA 的 NVIDIA 显卡，并已正确安装 [NVIDIA 驱动](https://www.nvidia.com/Download/index.aspx) 和 [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit-archive)，您可以升级到 GPU 版本以获得显著的性能提升。 | |
| ### Windows 用户 (一键升级) | |
| 1. 请先确保您已经成功运行过一次 `启动服务.bat`，以完成基础环境的安装。 | |
| 2. 双击运行 **`安装N卡GPU支持.bat`** 脚本。 | |
| 3. 脚本会自动卸载 CPU 版本的 PyTorch，并安装与 CUDA 12.8 兼容的 GPU 版本。 | |
| ### Linux 手动升级 | |
| 在激活虚拟环境后，执行以下命令： | |
| ```bash | |
| # 1. 卸载现有的 CPU 版本 PyTorch | |
| pip uninstall -y torch torchaudio | |
| # 2. 安装与您的 CUDA 版本匹配的 PyTorch | |
| # 以下命令适用于 CUDA 12.6，请根据您的 CUDA 版本从 PyTorch 官网获取正确的命令 | |
| pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu126 | |
| ``` | |
| *您可以访问 [PyTorch 官网](https://pytorch.org/get-started/locally/) 来获取适合您系统的安装命令。* | |
| 升级后，重新启动服务，您将在启动日志中看到 `Using device: cuda`。 | |
| --- | |
| ## 📖 使用指南 | |
| ### 1. Web 界面 | |
| 服务启动后，在浏览器中打开 **`http://127.0.0.1:5093`** 即可访问 Web UI。 | |
| - **输入文本**: 在文本框中输入您想要转换的文字。 | |
| - **调整参数**: | |
| - `cfg_weight`: (范围 0.0 - 1.0) 控制语音的节奏。值越低，语速越慢、越从容。对于快节奏的参考音频，可适当降低此值（如 0.3）。 | |
| - `exaggeration`: (范围 0.25 - 2.0) 控制语音的情感和语调夸张程度。值越高，情感越丰富，语速也可能越快。 | |
| - **声音克隆**: 点击 "选择文件" 上传一段参考音频（如 .mp3, .wav）。如果提供了参考音频，服务将使用克隆接口。 | |
| - **生成语音**: 点击 "生成语音" 按钮，稍等片刻即可在线试听和下载生成的 MP3 文件。 | |
| ### 2. API 调用 | |
| #### 接口 1: OpenAI 兼容接口 (`/v1/audio/speech`) | |
| 此接口无需参考音频，可使用 OpenAI SDK 直接调用。 | |
| **Python 示例 (`openai` SDK):** | |
| ```python | |
| from openai import OpenAI | |
| import os | |
| # 将客户端指向我们的本地服务 | |
| client = OpenAI( | |
| base_url="http://127.0.0.1:5093/v1", | |
| api_key="not-needed" # API密钥不是必需的，但SDK要求提供 | |
| ) | |
| response = client.audio.speech.create( | |
| model="chatterbox-tts", # 此参数会被忽略 | |
| voice="en", # | |
| speed=0.5, # 对应 cfg_weight 参数 | |
| input="Hello, this is a test from the OpenAI compatible API.", | |
| instructions="0.5" # (可选) 对应 exaggeration 参数, 注意需要是字符串 | |
| response_format="mp3" # 可选 'mp3' 或 'wav' | |
| ) | |
| # 将音频流保存到文件 | |
| response.stream_to_file("output_api1.mp3") | |
| print("音频已保存到 output_api1.mp3") | |
| ``` | |
| #### 接口 2: 声音克隆接口 (`/v2/audio/speech_with_prompt`) | |
| 此接口需要通过 `multipart/form-data` 格式同时上传文本和参考音频文件。 | |
| **Python 示例 (`requests` 库):** | |
| ```python | |
| import requests | |
| API_URL = "http://127.0.0.1:5093/v2/audio/speech_with_prompt" | |
| REFERENCE_AUDIO = "path/to/your/reference.mp3" # 替换为您的参考音频路径 | |
| form_data = { | |
| 'input': 'This voice should sound like the reference audio.', | |
| 'cfg_weight': '0.5', | |
| 'exaggeration': '0.5', | |
| 'response_format': 'mp3' # 可选 'mp3' 或 'wav' | |
| } | |
| with open(REFERENCE_AUDIO, 'rb') as audio_file: | |
| files = {'audio_prompt': audio_file} | |
| response = requests.post(API_URL, data=form_data, files=files) | |
| if response.ok: | |
| with open("output_api2.mp3", "wb") as f: | |
| f.write(response.content) | |
| print("克隆音频已保存到 output_api2.mp3") | |
| else: | |
| print("请求失败:", response.text) | |
| ``` | |
| ### 3. 在 pyVideoTrans 中使用 | |
| 本项目可以作为强大的 TTS 后端，为 [pyVideoTrans](https://github.com/jianchang512/pyvideotrans) 提供高质量的英文配音。 | |
| 1. **启动本项目**: 确保 Chatterbox TTS API 服务正在本地运行 (`http://127.0.0.1:5093`)。 | |
| 2. **更新 pyVideoTrans**: 确保您的 pyVideoTrans 版本升级到 `v3.73` 或更高。 | |
| 3. **配置 pyVideoTrans**: | |
|  | |
| - 在 pyVideoTrans 菜单中，进入 `TTS设置` -> `Chatterbox TTS`。 | |
| - **API 地址**: 填写本服务的地址，默认为 `http://127.0.0.1:5093`。 | |
| - **参考音频** (可选): 如果您想使用声音克隆，请在此处填写参考音频的文件名（例如 `my_voice.wav`）。请确保该音频文件已放置在 pyVideoTrans 根目录下的 `chatterbox` 文件夹内。 | |
| - **调整参数**: 根据需要调整 `cfg_weight` 和 `exaggeration` 以获得最佳效果。 | |
| **参数调整建议**: | |
| - **通用场景 (TTS, 语音助手)**: 默认设置 (`cfg_weight=0.5`, `exaggeration=0.5`) 适用于大多数情况。 | |
| - **快语速参考音频**: 如果参考音频的语速较快，可以尝试将 `cfg_weight` 降低到 `0.3` 左右，以改善生成语音的节奏。 | |
| - **富有表现力/戏剧性演讲**: 尝试较低的 `cfg_weight` (如 `0.3`) 和较高的 `exaggeration` (如 `0.7` 或更高)。通常提高 `exaggeration` 会加快语速，降低 `cfg_weight` 有助于平衡，使节奏更从容、更清晰。 | |
| --- | |
| ## 致谢 | |
| [Chatterbox-TTS](https://github.com/resemble-ai/chatterbox) | |