# Клонирование голоса Chatterbox

Chatterbox — это семейство современных open-source моделей синтеза речи от [Resemble AI](https://resemble.ai). Она выполняет нулевое клонирование голоса по короткому эталонному фрагменту (\~10 секунд), поддерживает паралингвистические теги, такие как `[laugh]` и `[cough]`, и предлагает мультилингвальный вариант, охватывающий более 23 языков. Доступны три варианта модели: Turbo (350M, низкая задержка), Original (500M, креативные настройки) и Multilingual (500M, 23+ языков).

**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 ГБ | RTX 3090 / RTX 4090 |
| VRAM      | 6 GB           | 10 ГБ+              |
| ОЗУ       | 8 ГБ           | 16 ГБ               |
| Диск      | 5 ГБ           | 15 ГБ               |
| Python    | 3.10+          | 3.11                |
| CUDA      | 11.8+          | 12.1+               |

**Рекомендация Clore.ai:** RTX 3090 (~~$0.30–1.00/день) для комфортного запаса VRAM. RTX 3060 подходит для модели Turbo. Для Multilingual с длинными текстами рассмотрите RTX 4090 (~~$0.50–2.00/день).

## Установка

```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 ready')"
```

## Быстрый старт

### Модель Turbo (наименьшая задержка)

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

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

# Базовый TTS с паралингвистическими тегами
text = "Hey, welcome back! [chuckle] I've got some great news for you today."

# Клонирование голоса — предоставьте эталонный клип длительностью 10+ секунд
wav = model.generate(text, audio_prompt_path="reference_voice.wav")

ta.save("output_turbo.wav", wav, model.sr)
print(f"Saved at {model.sr} Hz")
```

### Модель Original (английский, креативный контроль)

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

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

text = "The quick brown fox jumps over the lazy dog. It was a beautiful morning."

# Генерация без клонирования голоса (используется голос по умолчанию)
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
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("Multilingual generation complete")
```

### Паралингвистические теги (Turbo)

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

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

samples = [
    ("greeting", "Hi there! [laugh] It's so good to see you again."),
    ("nervous", "Um, well [cough] I'm not really sure about that."),
    ("excited", "Oh my gosh! [chuckle] That's absolutely incredible news!"),
]

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("Batch processing complete")
```

## Советы для пользователей Clore.ai

* **Выбор модели** — используйте Turbo для агентов с низкой задержкой, Original для креативной работы на английском, Multilingual для контента на других языках
* **Качество эталонного аудио** — используйте чистый, безшумный клип длительностью 10–30 секунд для лучшего результата клонирования голоса
* **Настройка Docker** — базовое изображение `pytorch/pytorch:2.5.1-cuda12.4-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 ГБ); предварительно скачайте с помощью `huggingface-cli` |
| В аудио присутствуют артефакты   | Уменьшите длину текста на одну генерацию; очень длинные тексты могут ухудшать качество                            |
| `ModuleNotFoundError`            | Убедитесь, что `pip install chatterbox-tts` завершено без ошибок; проверьте совместимость с Python 3.11           |