Voice Clone Mini Lab

Laboratorio educativo, local y multiplataforma (macOS, Linux, Windows, Docker) para clonar la voz del propio estudiante a partir de una muestra corta y estudiar las diferencias entre audio humano y sintético.

Todo el procesamiento ocurre en tu máquina: ninguna grabación se envía a una API externa.

Funciones

• Grabación desde el navegador o carga de WAV/MP3.
• Hasta 3 muestras de referencia (~10 s cada una) para mejorar la fidelidad del clon.
• Clonación zero-shot con Coqui XTTS v2.
• Salida multilingüe, incluida voz en español.
• Forma de onda, espectrograma, MFCC y métricas acústicas.
• Comparación entre audio original y sintético.
• JSON de procedencia para cada resultado.

Requisitos

• Python 3.10-3.12 (3.11 recomendado; 3.13+ todavía no es compatible con las librerías de este proyecto).
• 8 GB de RAM como mínimo; 16 GB recomendado.
• ~4 GB libres en disco (PyTorch + el modelo XTTS v2, que se descarga en el primer uso).
• Internet durante la instalación y la primera generación de voz.
• CPU funciona, pero la generación puede ser lenta. CUDA acelera el proceso. En Apple Silicon se usa MPS automáticamente, con CPU como respaldo.

No necesitas instalar FFmpeg por separado: las versiones de PyTorch usadas aquí están fijadas a propósito por debajo de la 2.9 para que la carga de audio no dependa de él.

Instalación rápida

Elige tu sistema operativo.

macOS / Linux

git clone https://github.com/accp08/voice-clone-mini-lab.git
cd voice-clone-mini-lab
chmod +x install_mac_linux.sh run_mac_linux.sh
./install_mac_linux.sh
./run_mac_linux.sh

install_mac_linux.sh busca automáticamente un Python 3.10-3.12 instalado (probando python3.11, python3.12, python3.10 y por último python3) y te avisa con el comando exacto si no encuentra ninguno (brew install python@3.11 en macOS, apt install python3.11 python3.11-venv en Ubuntu/Debian).

Windows

Instala Python 3.11 marcando Add Python to PATH, luego en PowerShell o CMD:

git clone https://github.com/accp08/voice-clone-mini-lab.git
cd voice-clone-mini-lab
install_windows.bat
run_windows.bat

Docker (cualquier SO con Docker Desktop)

git clone https://github.com/accp08/voice-clone-mini-lab.git
cd voice-clone-mini-lab
docker compose up --build

No necesitas instalar Python ni dependencias en tu máquina; todo corre dentro del contenedor. models/ y outputs/ quedan mapeados a tu disco para conservar el modelo descargado y los resultados entre reinicios.

Cuando el servidor arranque (con cualquiera de las opciones anteriores), abre http://127.0.0.1:7860 en tu navegador.

Primer uso

1. En la pestaña 1. Clonar mi voz, graba o carga entre 1 y 3 muestras de tu voz (~10 s cada una, en un lugar silencioso, con tono natural).
2. Escribe la frase a sintetizar, marca la casilla de consentimiento y pulsa Generar clon educativo.
3. La primera vez, esto descarga el modelo XTTS v2 (~1.9 GB) y pide aceptar su licencia no comercial (CPML) en la terminal donde corre la app — responde y. Las siguientes generaciones son mucho más rápidas.
   • Con Docker no hay terminal interactiva para responder: docker-compose.yml ya acepta la licencia por ti (COQUI_TOS_AGREED=1); revisa ese archivo si prefieres aceptarla manualmente.

Verificar que todo funciona

# con el entorno activado (macOS/Linux: `. .venv/bin/activate`; Windows: `.venv\Scripts\activate`)
pip install -r requirements-dev.txt
pytest -q

Los mismos tests corren automáticamente en GitHub Actions en macOS, Linux y Windows (ver el badge arriba).

Solución de problemas

Síntoma	Causa probable	Solución
El instalador dice que no encuentra Python 3.10-3.12	Solo tienes una versión más nueva (p. ej. 3.13/3.14)	Instala 3.11 con el comando que te sugiere el propio script
No está instalado coqui-tts al generar	El entorno no terminó de instalar requirements.txt	Vuelve a correr install_mac_linux.sh / install_windows.bat
Se queda colgado la primera vez que generas	Está esperando que aceptes la licencia CPML en la terminal	Escribe y y Enter en la terminal donde corre python app.py
El navegador no pide permiso de micrófono	El sitio no se abrió como http://127.0.0.1:7860 (http, no https)	Usa esa URL exacta; los navegadores bloquean el micrófono en otros orígenes
La voz clonada no suena con tu acento regional	Limitación conocida de XTTS v2: usa un modelo de español genérico	Usa 2-3 muestras claras de referencia; no hay forma de forzar acento regional

Estructura del proyecto

app.py                 # UI de Gradio (4 pestañas)
src/voice_clone.py      # Preparación de referencia + clonación con XTTS v2
src/audio_lab.py        # Métricas acústicas y gráficos (forma de onda, espectrograma, MFCC)
tests/                  # pytest
docs/                   # Guía docente y taller para el alumno

Uso responsable

El estudiante debe confirmar que la voz le pertenece o que dispone de autorización expresa. No se deben generar frases de autenticación, solicitudes de dinero, instrucciones engañosas ni contenido atribuido falsamente a otra persona.

Los audios generados se guardan en outputs/ con un JSON que declara su origen sintético. No publiques muestras de voz ni resultados sin consentimiento.

Nota sobre modelos

XTTS v2 se descarga la primera vez que se utiliza, bajo la licencia no comercial CPML de Coqui. Revisa sus términos antes de usar este proyecto fuera del aula o con fines comerciales.