> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/yin-pin-yu-yu-yin/chatterbox-tts.md).

# Chatterbox 声音克隆

在 Clore.ai GPU 上运行 Resemble AI 的 Chatterbox TTS，用于零样本声音克隆和多语言语音合成。

Chatterbox 是由以下团队推出的一系列最先进的开源文本转语音模型： [Resemble AI](https://resemble.ai)。它可通过一段简短的参考音频（约 10 秒）进行零样本语音克隆，支持诸如 `[laugh]` 以及 `[cough]`之类的副语言标签，并提供覆盖 23 种以上语言的多语言版本。提供三种模型变体：Turbo（350M，低延迟）、Original（500M，创意控制）和 Multilingual（500M，23+ 种语言）。

{% hint style="info" %}
**Multilingual V3 现在是推荐的多语言检查点。** 与上一个版本相同的 0.5B 规模，但说话人相似度更好、幻觉更少，并且在所有支持的语言中都能生成更自然的语音。以下内容均无需更改——拉取当前权重即可获得 V3。
{% endhint %}

**GitHub：** [resemble-ai/chatterbox](https://github.com/resemble-ai/chatterbox) **PyPI：** [chatterbox-tts](https://pypi.org/project/chatterbox-tts/) **许可证：** MIT

## 主要特性

* **零样本声音克隆** —— 仅需约 10 秒参考音频即可克隆任何声音
* **副语言标签** （Turbo）— `[laugh]`, `[cough]`, `[chuckle]`, `[sigh]` 用于逼真的语音
* **23+ 种语言** （Multilingual）— 阿拉伯语、中文、法语、德语、日语、韩语、俄语、西班牙语等
* **CFG 与夸张度调节** （Original）— 对表现力的创意控制
* **三种模型大小** — Turbo（350M）、Original（500M）、Multilingual（500M）
* **MIT 许可证** —— 可完全用于商业用途

## 需求

| 组件     | 最低             | 推荐                  |
| ------ | -------------- | ------------------- |
| GPU    | RTX 3060 12 GB | RTX 3090 / RTX 4090 |
| 显存     | 6 GB           | 10 GB+              |
| 内存     | 8 GB           | 16 GB               |
| 磁盘     | 5 GB           | 15 GB               |
| Python | 3.10+          | 3.11                |
| CUDA   | 12.8+          | 12.8+               |

**Clore.ai 推荐：** RTX 3090（$0.07–0.21/小时），可提供舒适的显存余量。RTX 3060 可用于 Turbo 模型。对于长文本的 Multilingual 模型，建议使用 RTX 4090（$0.14–0.42/小时）。

## 安装

```bash
# 从 PyPI 安装
pip install chatterbox-tts

# 或从源码安装
git clone https://github.com/resemble-ai/chatterbox.git
cd chatterbox
pip install -e .

# 验证
python -c "from chatterbox.tts import ChatterboxTTS; print('Chatterbox 已就绪')"
```

## 快速开始

### Turbo 模型（最低延迟）

```python
import torchaudio as ta
from chatterbox.tts_turbo import ChatterboxTurboTTS

model = ChatterboxTurboTTS.from_pretrained(device="cuda")

# 使用副语言标签进行基础 TTS
text = "嘿，欢迎回来！[chuckle] 今天我给你带来了一个好消息。"

# 语音克隆——提供一段 10 秒以上的参考片段
wav = model.generate(text, audio_prompt_path="reference_voice.wav")

ta.save("output_turbo.wav", wav, model.sr)
print(f"已保存于 {model.sr} Hz")
```

### Original 模型（英文，创意控制）

```python
import torchaudio as ta
from chatterbox.tts import ChatterboxTTS

model = ChatterboxTTS.from_pretrained(device="cuda")

text = "敏捷的棕狐狸跳过懒狗。那是一个美丽的早晨。"

# 生成时不进行语音克隆（使用默认声音）
wav = model.generate(text)
ta.save("output_default.wav", wav, model.sr)

# 使用语音克隆生成
wav = model.generate(text, audio_prompt_path="my_voice_sample.wav")
ta.save("output_cloned.wav", wav, model.sr)
```

## 使用示例

### 多语言语音克隆

```python
import torchaudio as ta
from chatterbox.mtl_tts import ChatterboxMultilingualTTS

model = ChatterboxMultilingualTTS.from_pretrained(device="cuda")

# 法语
french_text = "Bonjour, comment allez-vous? Bienvenue dans notre démonstration."
wav_fr = model.generate(french_text, language_id="fr")
ta.save("output_french.wav", wav_fr, model.sr)

# 日语
japanese_text = "こんにちは、这是文本转语音演示。"
wav_ja = model.generate(japanese_text, language_id="ja")
ta.save("output_japanese.wav", wav_ja, model.sr)

# 带语音克隆的俄语
russian_text = "你好！这是俄语语音合成演示。"
wav_ru = model.generate(
    russian_text,
    language_id="ru",
    audio_prompt_path="russian_speaker.wav"
)
ta.save("output_russian.wav", wav_ru, model.sr)

print("多语言生成完成")
```

### 副语言标签（Turbo）

```python
import torchaudio as ta
from chatterbox.tts_turbo import ChatterboxTurboTTS

model = ChatterboxTurboTTS.from_pretrained(device="cuda")

samples = [
    ("greeting", "嗨！[laugh] 很高兴再次见到你。"),
    ("nervous", "嗯，呃 [cough] 我其实不太确定。"),
    ("excited", "天哪！[chuckle] 这消息太棒了！"),
]

for name, text in samples:
    wav = model.generate(text, audio_prompt_path="speaker_ref.wav")
    ta.save(f"para_{name}.wav", wav, model.sr)
    print(f"已生成：{name}")
```

### 批处理脚本

```python
import torchaudio as ta
from chatterbox.tts import ChatterboxTTS
import os

model = ChatterboxTTS.from_pretrained(device="cuda")

# 处理一组文本行（例如用于有声书章节）
lines = [
    "第一章。冒险开始了。",
    "那是一个漆黑而暴风雨肆虐的夜晚。",
    "英雄站在十字路口，对前方的道路感到不确定。",
]

os.makedirs("output_batch", exist_ok=True)

for i, line in enumerate(lines):
    wav = model.generate(line, audio_prompt_path="narrator_voice.wav")
    ta.save(f"output_batch/line_{i:03d}.wav", wav, model.sr)
    print(f"[{i+1}/{len(lines)}] {line[:40]}...")

print("批处理完成")
```

## 给 Clore.ai 用户的建议

* **模型选择** —— 低延迟语音代理使用 Turbo，英语创作使用 Original，非英语内容使用 Multilingual
* **参考音频质量** —— 使用干净、无噪声的 10–30 秒片段以获得最佳语音克隆效果
* **Docker 设置** —— 基础镜像 `pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime`，暴露端口 `7860/http` 供 Gradio 使用
* **内存管理** —— 调用 `torch.cuda.empty_cache()` 在大型批次之间以释放 VRAM
* **支持的语言** —— ar、da、de、el、en、es、fi、fr、he、hi、it、ja、ko、ms、nl、no、pl、pt、ru、sv、sw、tr、zh
* **HuggingFace Space** —— 在租用之前先试用： [huggingface.co/spaces/ResembleAI/Chatterbox](https://huggingface.co/spaces/ResembleAI/Chatterbox)

## 故障排查

| 问题                    | 解决方案                                                         |
| --------------------- | ------------------------------------------------------------ |
| `CUDA 内存不足`           | 使用 Turbo（350M）代替 Original/Multilingual（500M），或者租用更大的 GPU     |
| 克隆的声音不匹配              | 使用更长（15–30 秒）、更干净且背景噪音更少的参考片段                                |
| `numpy` 版本冲突          | 运行 `pip install numpy==1.26.4 --force-reinstall`             |
| 模型下载缓慢                | 模型在首次运行时会从 HuggingFace 获取（约 2 GB）；可预先下载： `huggingface-cli`   |
| 音频有瑕疵                 | 减少每次生成的文本长度；非常长的文本会降低质量                                      |
| `ModuleNotFoundError` | 确保 `pip install chatterbox-tts` 已无错误完成；请检查与 Python 3.11 的兼容性 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/yin-pin-yu-yu-yin/chatterbox-tts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.