Cómo entrenamos la voz de Esteban

1. Resumen ejecutivo (TL;DR)

El modelo activo se llama esteban-v1. Es un fine-tune de XTTS v2 (Coqui TTS) sobre 19.483 clips de audio real de Esteban, extraídos automáticamente de 159 videos de Google Drive con un pipeline de diarización + identificación por embedding de voz. Vive en eom/brain/voice/ y se usa hoy a través del skill /eom --voz, que dispara los 12 agentes eom-* de Claude Code (DM, Slack, email, coaching, etc.).

El audio final suena conciso, con ritmo natural, con menos pausas artificiales que el modelo previo de 622 clips, y captura el timbre y la cadencia argentina de Esteban. Toda la inferencia es local — sin API, sin costo por llamada.

2. Objetivo del proyecto

Crear una voz clonada de Esteban que pudiera ser usada por los agentes eom-* de Claude Code para devolver audio cuando Esteban redactara mensajes con /eom --voz, o leyera contenido con /eom --voz --leer.

Tres requisitos no negociables:

• Calidad indistinguible en samples cortos (≤30s). El audio tenía que servir para mandar mensajes reales al equipo y a clientes, no para una demo.
• Inferencia local. Sin enviar audio a APIs externas (privacidad + cero costo marginal).
• Replicable. El mismo pipeline tenía que poder usarse para clonar la voz de otra persona del equipo más adelante.

Restricciones de hardware: una RTX 2060 SUPER de 8 GB VRAM. Eso forzó decisiones durante el entrenamiento (batch size pequeño, gradient accumulation, float32 en vez de mixed precision por bugs específicos de XTTS v2).

3. Cronología del proceso

4. Tecnologías evaluadas y descartadas

Antes de elegir XTTS v2 fine-tuned, evaluamos cinco arquitecturas alternativas. Todas ellas siguen instaladas en eom/brain/voice/ para referencia y para que cualquiera pueda volver a probarlas. Los scripts de test (test-*.py) generan un mismo texto de prueba con cada modelo.

Escuchá los outputs descartados

Todos los modelos descartados generaron el mismo texto: "Bueno, lo que necesitamos es que el equipo entienda que esto no es solo un proyecto más. Es la base de todo lo que viene después."

5. La tecnología elegida: XTTS v2

Por qué XTTS v2 ganó

La arquitectura del fine-tune

No se reentrena todo el modelo. Sólo se fine-tunea el GPT encoder (la parte que aprende la prosodia y la entonación). El vocoder y el DVAE quedan congelados — son agnósticos al hablante.

Se parte del checkpoint base de XTTS v2 (~1.8 GB) y se sigue entrenando sobre el dataset propio. El resultado es un best_model.pth de ~5.3 GB que contiene el GPT encoder ajustado.

6. El dataset: pipeline de extracción

Sin datos no hay fine-tune. El primer modelo con 622 clips dio un resultado funcional pero limitado. Para llegar a calidad real necesitábamos un orden de magnitud más. Construimos un pipeline automatizado para extraer voz de Esteban de 159 videos de Google Drive sin tener que cortar manualmente.

6.1 Selección de fuentes (las 5 prioridades P0–P5)

P4 (titulos con "SEO CX-driven") resultó ser duplicado de P1. P6 (todo lo demás operativo) se descartó: el corpus ya era más que suficiente y P6 tiene videos con muchos speakers donde Esteban habla poco — la relación señal/ruido bajaba.

6.2 Pipeline técnico

El script principal es nmc-dev/scripts/extract-esteban-audio.py. Hace cuatro cosas en cadena:

1. Descarga del video desde Google Drive vía Drive API (con service account + domain-wide delegation, Esteban como subject).
2. Diarización con pyannote/speaker-diarization-3.1: identifica cuántos speakers hay y en qué timestamps habla cada uno.
3. Identificación: para cada speaker, se genera un embedding de voz con wespeaker-voxceleb-resnet34-LM y se compara por similitud coseno contra un embedding de referencia de Esteban (promediado sobre 622 clips originales). Threshold: 0.65.
4. Extracción: cuando un segmento es Esteban y dura entre 3 y 15 segundos, se exporta como WAV a 22.050 Hz mono.

El estado del pipeline se persiste en extracted-clips/_progress.json — fuente de verdad — y permite resumir cualquier corrida. El reporte de presencia se genera en _presencia-esteban.md.

Referencias de voz "limpia" (las 3 sesiones P0)

Estos son los audios de Esteban hablando solo, con micrófono, que sirvieron de semilla para el embedding y para el tuning posterior:

6.3 Transcripción

XTTS necesita pares audio | texto. Transcribimos los 18.866 clips con faster-whisper large-v3 en GPU.

• Aceptados: 18.861 (99,97%)
• Filtrados: 5 clips con no_speech_prob > 0.7 o texto < 4 chars.
• Calidad media: avg_logprob = -0.172 (whisper considera bueno todo lo que esté arriba de -1).
• Tiempo: ~1 hora total en GPU.

El merge final entre los 622 clips originales y los 18.861 nuevos vive en xtts-dataset/metadata.csv con formato Coqui:

audio_file|text|speaker_name
wavs/resultados2025_0000.wav|Bueno equipo, hoy quiero compartirles...|esteban
extracted/P3/L10-2025-09-15_0014.wav|Lo que necesitamos es que el equipo entienda...|esteban
...

7. El entrenamiento en detalle

7.1 Hiperparámetros

7.2 Hardware y duración

• GPU: RTX 2060 SUPER (8 GB VRAM, ~7 TFLOPS).
• Duración total: 22.9 horas continuas.
• Steps: 16.562 (2 epochs × ~8.281 steps/epoch).
• Step time medio: 5,8 s.
• Loss final (train): 0.93 — bajó desde 1.06 al inicio.
• Crashes: 0. El watchdog con auto-restart desde último checkpoint nunca tuvo que activarse.

7.3 Fixes que tuvimos que hacer al training loop

7.4 Loss curve (resumen del log de training)

# Inicio (step 0)
loss: 1.06    loss_text_ce: 0.024    loss_mel_ce: 4.08

# Step 1.400 (1ª epoch)
loss: 0.85    loss_text_ce: 0.023    loss_mel_ce: 3.44

# Step 8.000 (2ª epoch comienza)
loss: 0.94    loss_text_ce: 0.022    loss_mel_ce: 3.45

# Step final (~16.562)
loss: 0.93    loss_text_ce: 0.022    loss_mel_ce: 3.50

8. Tuning de inferencia (6 fases A/B)

Una vez entrenado el modelo, los parámetros de inferencia mueven mucho la calidad percibida sin re-entrenar nada. Corrimos 6 fases A/B sobre el mismo modelo esteban-v1. El script tune-voice.py automatiza P1, P2 y P3.

Fase 1 · Elección del clip de referencia

XTTS v2 necesita un clip de speaker (3-30s) en cada inferencia. Probamos 9 clips: 3 sesiones × 3 segmentos (inicio, medio, final) cada una. Ganador: resultados2025_0000.wav (mejor tono, voz más relajada).

Fase 2 · Multi-referencia

XTTS acepta varios clips a la vez (promedia los embeddings). Probamos combos de 3 a 5 clips. Conclusión: multi-ref no superó al single-ref ganador. Más estable pero menos "personal" — el promedio limaba los rasgos distintivos de Esteban. Descartado.

Fase 3 · Parámetros de inferencia

8 variaciones de temperature, top_p y length_penalty. Ganador final: temp=0.6, top_p=0.75, lp=1.15 ("natural").

Fase 4 · Pitch correction

El audio del modelo a veces sonaba apenas más agudo que la voz real de Esteban. Probamos bajar el pitch -1 y -2 semitonos con ffmpeg rubberband:

-1 semitono ayuda levemente, -2 ya suena artificial. Descartado por complejidad operativa (cada inferencia requeriría un pase extra de ffmpeg). Decisión basada en feedback explícito de Esteban: «no modificar la voz — adaptar canal es sólo pausas, no pitch ni speed».

Fase 5 · EQ paramétrico

3 niveles de EQ (boost 3 kHz / dip 1,5 kHz) para "abrir" la voz. Mejora marginal, no justifica el post-proceso. Descartado por el mismo principio.

Fase 6 · Splitting de texto largo

Para textos largos, hay dos opciones: dejar que XTTS haga el split automático (enable_text_splitting=True) o hacerlo manualmente y concatenar con pausas. Auto-splitting de XTTS ganó: mejor flujo, sin cortes abruptos. Manual splitting (con pausas insertadas) se usa sólo cuando hace falta control fino sobre la respiración entre oraciones — caso --leer para textos largos.

9. A/B: modelo viejo (622 clips) vs esteban-v1 (19.483 clips)

Para confirmar que el corpus expandido valía las 23 horas de GPU, generamos el mismo set de frases con los dos modelos. Cinco estilos para cubrir el rango expresivo de Esteban:

Más samples del modelo final

10. Uso actual en producción

10.1 Cómo se invoca el modelo

El modelo está integrado al skill /eom de Claude Code. Tres formas principales:

10.2 Los 12 agentes eom-*

El skill /eom tiene flags de canal que disparan agentes específicos. Cada agente sabe cómo redactar para su contexto, y todos pueden ser combinados con --voz:

10.3 Inferencia (script de producción)

Toda generación de audio pasa por infer-xtts-ft.py:

cd C:/Users/seoli/Desktop/cursorgit/eom/brain/voice
.venv311/Scripts/python.exe infer-xtts-ft.py \
  --text "Hola equipo, les paso el update..." \
  --output output/eom-20260511-001.wav

Lo que hace internamente:

1. Busca el último checkpoint en xtts-finetune-output/run_v2/ automáticamente.
2. Carga el clip de referencia resultados2025_0000.wav.
3. Si el texto es largo, lo splitea en oraciones <200 chars.
4. Genera cada chunk con temperature=0.6, top_p=0.75, repetition_penalty=2.0.
5. Trimea silencios y concatena con pausas de 250 ms entre oraciones.
6. Exporta WAV a 24 kHz.

11. Dónde está cada cosa (estructura de repos)

Todo el trabajo vive en el repo personal de Esteban (eom/) y el repo de Nomadic (nmc-dev/). El equipo tiene acceso a nmc-dev/; eom/ es privado, pero los scripts de extracción viven en nmc-dev/ y son los que importan para replicar.

Mapa completo de archivos

12. Receta para replicar con otra voz

Si querés clonar la voz de otra persona del equipo (ej: un líder al que quieras poder citar en audio), seguí estos pasos. Toma ~30 horas de cómputo total (extracción + transcripción + fine-tune) sobre la misma GPU.

Paso 0 · Pre-requisitos

• GPU NVIDIA con >=8 GB VRAM (RTX 2060 SUPER alcanza).
• Python 3.11 + venv. Instalar: pip install TTS[all] trainer faster-whisper pyannote.audio wespeaker-python torchaudio
• HuggingFace token con licencias aceptadas para pyannote/speaker-diarization-3.1 y XTTS v2.
• Service account de Google con domain-wide delegation + scope drive.readonly.

Paso 1 · Conseguir 1-3 referencias "limpias"

Buscá 1-3 audios de la persona hablando sola con micrófono decente y ≥10 min de duración. Workshops, presentaciones, monólogos. Sin ruido de fondo, sin otra gente. Estos audios cumplen dos funciones: generar el embedding de referencia y servir como clip de referencia en inferencia.

Paso 2 · Generar el embedding de referencia

Cortá los audios limpios en clips de 5-10 segundos (puede ser manual o con un script basado en VAD). Generá un embedding promedio con wespeaker:

from wespeaker import load_model
model = load_model('english')  # también sirve para español
embeddings = [model.extract_embedding(clip) for clip in clips]
avg_embedding = np.mean(embeddings, axis=0)
np.save('persona-embedding.npy', avg_embedding)

Paso 3 · Pipeline de extracción masiva

Adaptá nmc-dev/scripts/extract-esteban-audio.py cambiando:

• EXPLICIT_VIDEO_IDS y EXPLICIT_FOLDER_IDS → IDs de Drive de la persona objetivo.
• SA_SUBJECT → email de la persona (para que el SA pueda leer sus drives).
• EMBEDDINGS_FILE → tu nuevo embedding.
• Threshold de similitud: empezá en 0.65. Si tenés pocos clips, bajá a 0.60. Si tenés muchos clips de baja calidad, subí a 0.70.

Apuntá a 15.000-20.000 clips de 3-15 segundos para tener calidad alta. Menos de 5.000 clips dará resultados similares al modelo viejo de Esteban (funcional pero mediocre).

Paso 4 · Transcripción

Pasá los clips por transcribe-clips.py. Filtrá clips con no_speech_prob > 0.7 o texto < 4 chars. Generá el metadata.csv en formato Coqui (audio_file|text|speaker_name).

Paso 5 · Fine-tuning

Copiá finetune-xtts.py y ajustá las constantes:

NUM_EPOCHS = 2           # con 15-20k clips
BATCH_SIZE = 2           # NO subir si tenés 8 GB VRAM
GRAD_ACCUM_STEPS = 4
MAX_AUDIO_LENGTH_SEC = 13
LANGUAGE = "es"          # o "en", "pt", etc
LEARNING_RATE = 5e-6
NUM_LOADER_WORKERS = 0   # Windows

Lanzá python finetune-xtts.py. Esperá ~24 hs. El script tiene resume automático: si se corta, relanzar y sigue.

Paso 6 · Tuning

Una vez entrenado el modelo, corré tune-voice.py --prueba all para generar variantes de referencia, multi-ref y parámetros. Escuchá y elegí. El punto de partida razonable es temperature=0.6, top_p=0.75, length_penalty=1.15 — el ganador de Esteban — pero cada voz puede preferir otra combinación.

Paso 7 · Integración

Si querés exponerlo como agente Claude Code:

1. Copiá infer-xtts-ft.py apuntándolo al nuevo checkpoint.
2. Creá un agente en ~/.claude/agents/persona-X.md con la voz y tono de esa persona (estilo, vocabulario, valores).
3. Creá un skill persona-X que combine el agente + invoque infer-xtts-ft.py con la flag --voz.

Checklist final antes de declarar la voz "lista"

• ✅ A/B test con >=5 frases de distintos estilos vs un modelo previo (o vs Edge TTS si no hay previo).
• ✅ Sample largo (30+ segundos) para verificar coherencia en textos extensos.
• ✅ Validación humana de la propia persona (¿se reconoce a sí misma? ¿le incomoda?).
• ✅ Documento MODELO-PERSONA-V1.md con dataset, hiperparámetros, ganadores de tuning, y comparativa A/B.

13. Calibración de identificación por voz (corte 0,65)

El dataset de entrenamiento sale de videos de reuniones donde Esteban aparece. Para extraer solo su voz hay que identificar qué hablante de la diarización es él, comparando el embedding de voz (wespeaker, similitud coseno) de cada cluster contra una referencia. El problema: un umbral que parece validado puede no estarlo, porque el set de validación nunca vio la zona gris.

La recalibración con ground-truth real (el oído del dueño de la voz) llevó el corte a 0,65 —precisión poblacional 0,99— a un costo acotado (~30 min de escucha + ~50 descargas). El método es replicable para cualquier voz con corpus de referencia.

Las 6 etapas

1. Triangulación gratis — sin descargar nada, cruzar cada video contra señales independientes del embedding: ¿la persona era attendee en el calendario esa fecha? ¿hay más de un cluster etiquetado como ella (señal de diarización mixta)? Salida: lista de sospechosos.
2. Muestra de escucha estratificada — ~50 videos (≈6 por banda de 0,05 en la zona gris 0,35–0,70 + anclas de sim alta como control + falsos conocidos). Descargar solo esos, recortar ~25 s del segmento más largo del cluster atribuido.
3. Escucha ciega (~30 min, la persona) — reproductor con orden aleatorio y la similitud oculta (para no sesgar el oído): botones ÉL / NO ÉL / DUDOSO, export a CSV.
4. Curva real y corte — cruzar ground-truth × similitud. Clave: la muestra es estratificada, así que se calcula la curva poblacional (ponderada por banda), no la cruda. Se elige el corte por su precisión/recall reales.
5. Detección de diarización mixta — el modo de falla que el umbral no ve: un cluster SPEAKER_XX con más de una voz (la diarización mezcló personas). El promedio por-cluster diluye la señal. Se valida y filtra por segmento.
6. Aplicación en dos carriles — videos "limpios" (un solo cluster, se extraen directo) y "mixtos" (se filtran los segmentos de voz ajena antes de extraer).