Audio Sync — Texto sincronizado con audio
App web que convierte texto en una narración con ElevenLabs y resalta palabra por palabra lo que suena, con la palabra activa sincronizada al milisegundo.
Resumen del proyecto
Audio Sync es una aplicación web que toma un texto, genera su narración con la API de texto a voz de ElevenLabs y muestra la transcripción con la palabra activa resaltada mientras el audio se reproduce. Tocar cualquier palabra salta a ese punto del audio.
El reto técnico está en la sincronización: los textos largos se dividen en fragmentos que conservan la prosodia entre uno y otro, y la línea de tiempo final se compone con la duración real del audio decodificado —no con los timestamps de la API—, con un respaldo a WAV cuando la unión de fragmentos MP3 se desfasa.
Nació como una SPA pequeña con un audio fijo y creció con un backlog de 26 issues en 11 milestones: pruebas, accesibilidad, endurecimiento de Docker, escaneo de secretos y vulnerabilidades, e identidad visual propia.
Características principales
- Generación de narración desde texto con voces de ElevenLabs a elegir
- Resaltado de la palabra activa en tiempo real y salto al punto del audio al tocar una palabra
- Textos largos divididos en fragmentos con contexto previo y siguiente para mantener la prosodia
- Respaldo a WAV cuando la unión de fragmentos MP3 se desfasa de la duración real
- Accesibilidad: palabras operables por teclado, captions y respeto a prefers-reduced-motion
- Identidad visual propia inspirada en el VU-meter, el medidor de nivel de la producción de radio
Stack
Problema
Sincronizar texto y audio generado por TTS es frágil: los timestamps de la API no incluyen el relleno que agregan los encoders MP3, y unir fragmentos de audio acumula desfases que se notan al leer.
Enfoque
Se separó la lógica de mayor riesgo en funciones puras (normalizado y división del texto, conversión de la alineación por carácter a palabras, compensación de offsets y palabra activa) y se orquesta el pipeline midiendo la duración real de cada fragmento decodificado. Un proxy Express mantiene la API key de ElevenLabs en el servidor y sirve la SPA desde el mismo proceso.
Resultados
- Más de 80 pruebas automatizadas con Vitest y Testing Library sobre el pipeline de sincronización, el proxy y la UI
- Backlog de 26 issues en 11 milestones implementado y cerrado, con CI en GitHub Actions y Dependabot con Socket Firewall
- Imagen de producción endurecida: usuario no-root, versión de Node fijada por digest, healthcheck y escaneo con Trivy antes de cada push a main
Cliente
Proyecto personal
Cronología
Julio 2026
Rol
Desarrollador Full-Stack
© 2026 Cuauhtémoc Bautista