Chatterbox TTS permite clonar cualquier voz con 10 segundos de audio. Esta guía cubre instalación en Windows, solución de errores comunes y uso recurrente.

Chatterbox TTS es una herramienta de síntesis de voz de código abierto desarrollada por Resemble AI que permite clonar cualquier voz a partir de un fragmento de audio de apenas 10 segundos. A diferencia de soluciones comerciales como ElevenLabs, funciona completamente de forma local sin enviar datos a servidores externos y sin costo mensual. Esta guía documenta el proceso completo de instalación en Windows, incluyendo la solución a los errores más comunes, el uso del modelo de clonación y cómo retomar el trabajo en sesiones posteriores.

¿Por qué Windows requiere configuración especial?

Chatterbox TTS requiere Python 3.11 de forma específica. Las versiones más recientes como Python 3.12 o 3.14 son incompatibles con la dependencia NumPy menor a 1.26 que el modelo necesita. Sumado a esto, la versión de Python distribuida por la Microsoft Store no incluye el lanzador de versiones py.exe ni permisos completos de escritura en directorios del sistema, lo que genera errores durante la instalación. La solución es instalar Python 3.11 desde el sitio oficial y crear un entorno virtual aislado.

Requisitos previos

• Sistema operativo: Windows 10 u 11 de 64 bits
• Python 3.11: instalado desde python.org (no desde la Microsoft Store)
• GPU compatible con CUDA: recomendada para generación en tiempo razonable; CPU funciona pero es significativamente más lenta
• Espacio en disco: mínimo 5 GB libres para el modelo y dependencias
• Conexión a internet: solo para la descarga inicial; el uso posterior es completamente local
• Audio de referencia: un archivo WAV o MP3 de 5 a 10 segundos de la voz que se desea clonar, grabado en ambiente silencioso

Paso 1: instalar Python 3.11 correctamente

Descarga el instalador oficial desde esta dirección:

https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe

Durante la instalación es obligatorio configurar estas opciones:

1. En la primera pantalla, marca “Add Python 3.11 to PATH” antes de continuar.
2. Selecciona “Customize installation” en lugar de la instalación rápida.
3. En la pantalla de opciones avanzadas, marca “Install for all users”.
4. Verifica que la ruta de destino sea C:\Program Files\Python311\
5. Completa la instalación y cierra el instalador.

Cierra PowerShell completamente y ábrelo de nuevo. Verifica que Python 3.11 sea visible para el sistema:

where.exe python

El resultado debe incluir la ruta C:\Program Files\Python311\python.exe entre las opciones listadas. Si no aparece, repite la instalación marcando correctamente la opción “Install for all users”.

Paso 2: crear el entorno virtual aislado

Un entorno virtual es un directorio independiente que contiene su propia instalación de Python y paquetes, completamente separado del Python del sistema. Esto evita conflictos de versiones y permite que Chatterbox funcione con sus dependencias exactas sin afectar otros proyectos.

Abre PowerShell y ejecuta:

& "C:\Program Files\Python311\python.exe" -m venv C:\chatterbox-env

El operador & es necesario en PowerShell para ejecutar programas cuya ruta contiene espacios. Este comando crea la carpeta C:\chatterbox-env\ con una copia funcional de Python 3.11 y herramientas base.

Paso 3: activar el entorno virtual

Antes de activar por primera vez, es necesario permitir la ejecución de scripts en PowerShell. Este ajuste aplica solo al usuario actual y no afecta la seguridad del sistema:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Luego activa el entorno:

C:\chatterbox-env\Scripts\Activate.ps1

El prompt de PowerShell cambiará para mostrar el nombre del entorno al inicio:

(chatterbox-env) PS C:\Users\usuario>

Confirma que el entorno usa Python 3.11:

python --version

Debe responder Python 3.11.9. Si muestra otra versión, el entorno no está activo correctamente.

Paso 4: instalar Chatterbox TTS

Con el entorno activo, actualiza las herramientas base e instala el modelo:

python -m pip install --upgrade pip setuptools wheel
pip install chatterbox-tts

La instalación descarga aproximadamente 4-5 GB entre dependencias y el modelo base. El tiempo varía según la velocidad de conexión. Al finalizar sin errores, el entorno está listo para usarse.

¿Cómo clonar una voz por primera vez?

El proceso de clonación requiere un archivo de audio de referencia de la voz que se desea replicar. La calidad del resultado depende directamente de la calidad de ese audio: grabaciones limpias, sin ruido de fondo, música o voces superpuestas producen resultados notablemente mejores.

Requisitos del audio de referencia

• Duración: entre 5 y 10 segundos (más no siempre es mejor)
• Formato: WAV preferido; MP3 también funciona
• Contenido: una sola persona hablando con claridad
• Ambiente: sin eco, música de fondo ni ruido excesivo
• Frecuencia de muestreo: 22,050 Hz o 44,100 Hz recomendado

¿Cómo ejecutar la clonación paso a paso?

Crea un archivo llamado clonar.py en cualquier carpeta, por ejemplo C:\chatterbox\, con el siguiente contenido:

import torch
import torchaudio
from chatterbox.tts import ChatterboxTTS

# Cargar el modelo (la primera vez descarga pesos adicionales)
model = ChatterboxTTS.from_pretrained(device="cuda")  # cambiar a "cpu" si no hay GPU

# Texto que la voz clonada pronunciará
texto = "Este es un ejemplo de clonación de voz con Chatterbox TTS."

# Ruta al audio de referencia
audio_referencia = "C:/chatterbox/muestra.wav"

# Generar el audio clonado
# exaggeration: 0.5 = neutro, 1.0 = más expresivo y dramático
# cfg_weight: 0.5 = balance natural, valores altos priorizan similitud con la voz original
wav = model.generate(
    texto,
    audio_prompt_path=audio_referencia,
    exaggeration=0.5,
    cfg_weight=0.5
)

# Guardar el resultado
torchaudio.save("C:/chatterbox/resultado.wav", wav, model.sr)
print("Audio generado correctamente en C:/chatterbox/resultado.wav")

Ejecuta el script desde PowerShell con el entorno activo:

python C:\chatterbox\clonar.py

La primera ejecución descarga los pesos del modelo, lo que puede tardar varios minutos. Las ejecuciones posteriores son significativamente más rápidas porque los pesos quedan almacenados en caché local.

Ajuste de parámetros de expresividad

Chatterbox ofrece dos parámetros principales para controlar la naturalidad del resultado. Ajustarlos según el tipo de contenido marca una diferencia notable en la calidad final:

• exaggeration=0.3: voz calmada, ideal para narraciones técnicas o educativas
• exaggeration=0.5: tono neutro y natural, recomendado como punto de partida
• exaggeration=0.8: voz expresiva, útil para publicidad, personajes o ficción
• cfg_weight=0.3: habla más lenta y clara, prioriza inteligibilidad
• cfg_weight=0.5: balance entre claridad y similitud con la voz original
• cfg_weight=0.8: máxima similitud con la voz de referencia

Cómo retomar el trabajo en sesiones posteriores

El entorno virtual y el modelo quedan instalados de forma permanente en C:\chatterbox-env\. No es necesario reinstalar nada. Cada vez que se quiera usar Chatterbox en una nueva sesión, solo se deben ejecutar dos comandos antes de usar el modelo:

1 — Abrir PowerShell y activar el entorno:

C:\chatterbox-env\Scripts\Activate.ps1

2 — Navegar a la carpeta de trabajo y ejecutar el script:

cd C:\chatterbox
python clonar.py

Si PowerShell muestra el error de permisos de ejecución de scripts en una sesión nueva, ejecuta primero:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Este ajuste solo es necesario una vez por perfil de usuario, pero en algunos equipos con políticas de grupo se restablece al reiniciar.

Errores comunes y soluciones

• “Cannot import setuptools.build_meta”: el entorno virtual no está activo o se está usando Python 3.12/3.14. Verifica con python –version antes de instalar.
• “CUDA out of memory”: la GPU no tiene suficiente memoria de video. Cambia device=”cuda” por device=”cpu” en el script, asumiendo tiempos de generación más largos.
• Audio de salida con ruido o calidad baja: el audio de referencia tiene ruido de fondo. Usa un editor de audio para limpiar la muestra antes de procesarla.
• El script no encuentra el archivo de audio: verifica que la ruta use barras diagonales simples / o barras invertidas dobles \\ en Python. Las barras invertidas simples causan errores de interpretación.
• “Activate.ps1 cannot be loaded”: ejecuta primero el comando Set-ExecutionPolicy indicado en el paso 3.

Casos de uso prácticos

• Doblaje de videos: graba 10 segundos de tu propia voz como referencia y genera narraciones completas para videos sin necesidad de grabar cada línea manualmente.
• Audiolibros: convierte textos largos dividiéndolos en fragmentos de hasta 2,000 caracteres y procésalos secuencialmente con el mismo audio de referencia para mantener consistencia de voz.
• Videojuegos independientes: genera cientos de líneas de diálogo para personajes secundarios usando una sola grabación por personaje como referencia.
• Accesibilidad: convierte documentos a audio manteniendo la identidad sonora de un locutor institucional en múltiples idiomas usando la variante multilingüe.

El repositorio oficial con documentación actualizada está disponible en github.com/resemble-ai/chatterbox.