# Clonación de voz Chatterbox

Chatterbox es una familia de modelos de texto a voz de última generación y código abierto de [Resemble AI](https://resemble.ai). Realiza clonación de voz en cero disparos a partir de un breve clip de referencia (\~10 segundos), admite etiquetas paralingüísticas como `[risa]` y `[tos]`, y ofrece una variante multilingüe que cubre más de 23 idiomas. Hay tres variantes de modelos disponibles: Turbo (350M, baja latencia), Original (500M, controles creativos) y Multilingual (500M, 23+ idiomas).

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

## Características clave

* **Clonación de voz zero-shot** — clona cualquier voz a partir de \~10 segundos de audio de referencia
* **Etiquetas paralingüísticas** (Turbo) — `[risa]`, `[tos]`, `[risita]`, `[suspiro]` para discurso realista
* **Más de 23 idiomas** (Multilingual) — árabe, chino, francés, alemán, japonés, coreano, ruso, español y más
* **Ajuste de CFG y exageración** (Original) — control creativo sobre la expresividad
* **Tres tamaños de modelo** — Turbo (350M), Original (500M), Multilingual (500M)
* **Licencia MIT** — completamente abierto para uso comercial

## Requisitos

| Componente | Mínimo         | Recomendado         |
| ---------- | -------------- | ------------------- |
| GPU        | RTX 3060 12 GB | RTX 3090 / RTX 4090 |
| VRAM       | 6 GB           | 10 GB+              |
| RAM        | 8 GB           | 16 GB               |
| Disco      | 5 GB           | 15 GB               |
| Python     | 3.10+          | 3.11                |
| CUDA       | 11.8+          | 12.1+               |

**Recomendación de Clore.ai:** RTX 3090 (~~$0.30–1.00/día) para un margen cómodo de VRAM. RTX 3060 funciona para el modelo Turbo. Para el modelo Multilingual con textos largos, considere una RTX 4090 (~~$0.50–2.00/día).

## Instalación

```bash
# Instalar desde PyPI
pip install chatterbox-tts

# O instalar desde el código fuente
git clone https://github.com/resemble-ai/chatterbox.git
cd chatterbox
pip install -e .

# Verificar
python -c "from chatterbox.tts import ChatterboxTTS; print('Chatterbox listo')"
```

## Inicio rápido

### Modelo Turbo (Latencia más baja)

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

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

# TTS básico con etiquetas paralingüísticas
text = "¡Hey, bienvenido de nuevo! [risita] Tengo grandes noticias para ti hoy."

# Clonación de voz — proporciona un clip de referencia de más de 10 segundos
wav = model.generate(text, audio_prompt_path="reference_voice.wav")

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

### Modelo Original (Inglés, Controles Creativos)

```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."

# Generar sin clonación de voz (usa la voz predeterminada)
wav = model.generate(text)
ta.save("output_default.wav", wav, model.sr)

# Generar con clonación de voz
wav = model.generate(text, audio_prompt_path="my_voice_sample.wav")
ta.save("output_cloned.wav", wav, model.sr)
```

## Ejemplos de uso

### Clonación de voz multilingüe

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

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

# Francés
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)

# Japonés
japanese_text = "こんにちは、テキスト読み上げのデモンストレーションです。"
wav_ja = model.generate(japanese_text, language_id="ja")
ta.save("output_japanese.wav", wav_ja, model.sr)

# Ruso con clonación de voz
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("Generación multilingüe completada")
```

### Etiquetas paralingüísticas (Turbo)

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

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

samples = [
    ("greeting", "¡Hola! [risa] Es tan bueno verte de nuevo."),
    ("nervous", "Eh, bueno [tos] No estoy muy seguro sobre eso."),
    ("excited", "¡Dios mío! [risita] ¡Esa es una noticia absolutamente increíble!"),
]

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"Generado: {name}")
```

### Script de procesamiento por lotes

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

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

# Procesar una lista de líneas (por ejemplo, para capítulos de audiolibros)
lines = [
    "Capítulo uno. La aventura comienza.",
    "Era una noche oscura y tormentosa.",
    "El héroe se paró en la encrucijada, incierto del camino por delante.",
]

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("Procesamiento por lotes completado")
```

## Consejos para usuarios de Clore.ai

* **Elección de modelo** — use Turbo para agentes de voz de baja latencia, Original para trabajos creativos en inglés, Multilingual para contenido en otros idiomas
* **Calidad del audio de referencia** — utilice un clip limpio y sin ruido de 10–30 segundos para obtener los mejores resultados de clonación de voz
* **Configuración con Docker** — imagen base `pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime`, exponer puerto `7860/http` para Gradio
* **Gestión de memoria** — llama a `torch.cuda.empty_cache()` entre lotes grandes para liberar VRAM
* **Idiomas compatibles** — ar, da, de, el, en, es, fi, fr, he, hi, it, ja, ko, ms, nl, no, pl, pt, ru, sv, sw, tr, zh
* **Espacio de HuggingFace** — prueba antes de alquilar en [huggingface.co/spaces/ResembleAI/Chatterbox](https://huggingface.co/spaces/ResembleAI/Chatterbox)

## Solución de problemas

| Problema                     | Solución                                                                                                        |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `CUDA fuera de memoria`      | Use Turbo (350M) en lugar de Original/Multilingual (500M), o alquile una GPU más grande                         |
| La voz clonada no coincide   | Use un clip de referencia más largo (15–30s) y más limpio con ruido de fondo mínimo                             |
| `numpy` conflicto de versión | Ejecuta `pip install numpy==1.26.4 --force-reinstall`                                                           |
| Descarga lenta del modelo    | Los modelos se obtienen de HuggingFace en la primera ejecución (\~2 GB); pre-descárguelos con `huggingface-cli` |
| El audio tiene artefactos    | Reduzca la longitud del texto por generación; textos muy largos pueden degradar la calidad                      |
| `ModuleNotFoundError`        | Asegúrate de `pip install chatterbox-tts` completado sin errores; verifique la compatibilidad con Python 3.11   |