🎬 Pipeline: HTML → MP4

HyperFrames renderiza una página HTML escena por escena, captura cada frame como imagen PNG y usa FFmpeg para montar el video final, con audio WAV sincronizado.

Comprender el flujo de principio a fin evita sorpresas: cada etapa tiene un artefacto concreto (HTML, WAV, MP4) que puedes inspeccionar.

HTML → fotogramas PNG → FFmpeg → MP4; cada escena es un estado de la página.

El Chrome headless administrado por HyperFrames renderiza cada frame de la animación. FFmpeg combina los frames con los audios WAV y genera el archivo MP4 final.

Saber que son dos procesos separados ayuda a diagnosticar: problemas visuales → Chrome; problemas de audio/timing → FFmpeg.

Puppeteer/Chrome, FFmpeg, pipeline de dos etapas.

Kokoro es un modelo TTS que se ejecuta localmente mediante Python (kokoro-onnx). Genera archivos WAV de alta calidad sin ninguna llamada a servicios externos.

Elimina el costo variable y la dependencia de Internet. El modelo (~340 MB) se descarga una vez y queda en la máquina.

kokoro-onnx, voz pf_dora, ONNX runtime, WAV local.

Todo el pipeline (TTS, render, encode) se ejecuta localmente. Después de la configuración inicial, produces videos sin internet y sin costos por uso.

Elimina el temor a que los costos se disparen y garantiza que el proyecto pueda reproducirse en cualquier máquina con los requisitos previos instalados.

Offline-first, costo cero por video, reproducible.

HyperFrames admite los dos formatos principales. El mismo guion genera automáticamente un video 16:9 (YouTube, horizontal) y uno 9:16 (Shorts, TikTok, Reels).

Una producción, dos entregas. El CSS de la escena adapta el diseño a cada formato mediante una media query o una variable.

1920×1080, 1080×1920, multiformato, reutilización.

Ideal para videos explicativos animados con narración (tutoriales, onboarding, lanzamientos). No es para capturas de pantalla en vivo, entrevistas o videos con face-cam.

Saber cuál es el alcance adecuado evita frustraciones. HyperFrames destaca en contenido de motion graphics con narración; no sustituye las grabaciones en vivo.

Motion-graphics, narración TTS, contenido técnico estructurado.

Node 22 LTS es el mínimo requerido. En Windows, FFmpeg va en C:\ffmpeg\bin y, en git-bash, usa siempre ffmpeg -nostdin para evitar bloqueos de stdin.

Las versiones antiguas de Node pueden romper el CLI. La flag -nostdin es un gotcha clásico de Windows que bloquea el renderizado silenciosamente.

Node 22+, FFmpeg en PATH, -nostdin en git-bash.

HyperFrames usa un Chrome aislado, descargado mediante npx hyperframes browser ensure. Queda en la caché local y no interfiere con el Chrome que usas a diario.

Usar Chrome personal puede causar conflictos de perfil. El navegador aislado garantiza un entorno limpio y reproducible.

npx hyperframes browser ensure, caché local, Puppeteer aislado.

Instala con pip install kokoro-onnx soundfile. En la primera ejecución, el modelo (~340 MB) se descarga automáticamente y se guarda en la caché. Las ejecuciones siguientes son sin conexión.

Sin Kokoro instalado, falla la generación de narración. La descarga tarda la primera vez: planifícalo durante la configuración.

pip install kokoro-onnx soundfile, descarga única de ~340 MB, caché local.

El comando npx hyperframes doctor comprueba Node, FFmpeg, Chrome y Kokoro de una sola vez e imprime el estado de cada dependencia. Todo en verde = listo para crear.

Ahorra tiempo de depuración: en vez de descubrir el fallo a mitad del renderizado, identificas el problema antes de empezar.

npx hyperframes doctor, checklist de dependencias, diagnóstico rápido.

Crea el scaffolding con npx hyperframes init <nome> --example blank. Genera las carpetas audio/, frames/, los scripts y el HTML de entrada ya con la estructura correcta.

Partir de la plantilla correcta evita errores de estructura que solo aparecen al renderizar.

npx hyperframes init, --example blank, carpetas audio/ e frames/.

O design.md define la paleta, la tipografía y las reglas visuales de tu canal. Cópialo de la referencia del skill al proyecto y menciónalo en las instrucciones para Claude.

Sin un design.md, cada video puede tener una apariencia diferente. Tener el archivo garantiza la coherencia de la identidad visual.

design.md, house-style, paleta #0D1321, identidad visual.

SCRIPT.md es un Markdown con una sección por escena. El arco ideal: hook (por qué mirar) → principio (concepto básico) → avanzado (detalle práctico) → CTA (siguiente paso).

Un guion bien estructurado antes de programar evita retrabajo de animación. La narrativa guía lo visual, no al revés.

SCRIPT.md, 6–9 escenas, arco de hook→CTA, una idea por escena.

Con 6–9 escenas y ~100 segundos de narración en total, el video dura ~1:50 — ideal para Shorts y videos cortos en YouTube.

Los textos largos por escena generan audios largos que alargan la animación más allá de lo permitido. Cada escena debe tener como máximo 3–4 frases cortas.

~100s en total, 3–4 frases por escena, ritmo de atención.

TTS lee el texto literalmente. Escribe "SKILL punto M D" en lugar de "SKILL.md", "M J S" en lugar de ".mjs", "N P X" en lugar de "npx", o el resultado sonará extraño.

Es uno de los errores más comunes. La diferencia entre oír "SKILL punto MD" de forma natural y que el modelo intente pronunciar "skill-dot-md" literalmente es enorme en la calidad percibida.

Texto fonético, expansión de siglas, revisar la narración en voz alta.

Usa la voz pf_dora con --speed 0.98 para una voz natural y un poco más pausada. El resultado es un archivo WAV por escena en audio/.

La velocidad predeterminada (1.0) puede sonar acelerada. El ajuste 0.98 es sutil, pero mejora la claridad sin perder el ritmo.

voz pf_dora, --speed 0.98, WAV por escena, carpeta audio/.

Tras generar los WAVs, usa ffprobe -show_entries format=duration en cada archivo para obtener la duración exacta en segundos. Esos valores alimentan el array AUDIO[] en build-index.

Las duraciones estimadas generan videos con el audio cortado o con silencio al final. ffprobe da el número exacto que HyperFrames necesita.

ffprobe -show_entries format=duration, duración real en segundos, array AUDIO[].

Más allá de la voz predeterminada pf_dora, Kokoro ofrece pm_alex (masculino neutro) y pm_santa (masculino más grave) para variedad o personalización del canal.

Elegir la voz antes de grabarlo todo evita retrabajo. Prueba las tres con 2–3 frases del guion y decide antes de generar todos los WAV.

pf_dora, pm_alex, pm_santa, prueba antes de generar todo.

O build-index.mjs es el generador: lee AUDIO[], llama a las funciones de escena y produce el index.html final que HyperFrames va a renderizar. Copia desde la plantilla y edita.

Comprender la estructura del generador te permite personalizarlo sin miedo. Cada parte tiene una responsabilidad clara: datos, HTML de escena, animación.

build-index.mjs, generador, plantilla copiada y editada.

El array AUDIO[] asigna cada escena a su archivo WAV y a la duración exacta (en segundos, con decimales) obtenida con ffprobe. Ej.: { file: 'audio/scene1.wav', dur: 12.34 }.

Es la única fuente de verdad del timing. Todos los cálculos de animación derivan de las duraciones reales de AUDIO[] —nunca las estimes.

AUDIO[], duraciones reales, fuente única de verdad, ffprobe.

Cada escena es una función sceneN() que devuelve HTML posicionado absolutamente dentro del contenedor de video. Los elementos comienzan invisibles y GSAP los anima.

Separar el HTML de cada escena en funciones mantiene el código organizado y facilita editar una escena sin afectar las demás.

sceneN(), posición absoluta, opacity inicial 0, GSAP anima.

La función anim(i, t) recibe el índice de la escena y el timeline de GSAP y añade las animaciones. GSAP interpola los valores cuadro a cuadro, lo que garantiza que Chrome capture movimientos fluidos.

GSAP es el estándar en HyperFrames porque garantiza un timing determinista — siempre el mismo frame, esencial para la captura headless.

anim(i, t), timeline de GSAP, timing determinista, precisión de fotograma.

El array CAPTIONS[] define el texto de subtítulos de cada escena, que se muestra en la franja inferior del video. Puede ser el texto completo de la narración o un resumen en viñetas.

Los subtítulos mejoran la accesibilidad y aumentan la retención en plataformas donde el video se reproduce sin sonido de forma predeterminada.

CAPTIONS[], franja inferior, accesibilidad, video sin sonido.

Tres constantes controlan el timing de toda animación: LEAD=0.5 (pausa antes de la narración), TAIL=0.9 (hold después del final de la voz) y FADE=0.45 (duración del fade entre escenas). Cambiar esto aquí afecta todo de manera uniforme.

Tener una única fuente de timing es lo que garantiza que el audio y la animación estén siempre sincronizados. Nunca hard-code segundos en las funciones de escena.

LEAD=0.5, TAIL=0.9, FADE=0.45, fuente única, sincronización de audio y visual.

El comando npx hyperframes lint verifica el HTML generado: duraciones, referencias de audio, estructura de la línea de tiempo y errores de sintaxis. Debe devolver 0 errores antes de continuar.

Un render con errores de lint puede producir videos sin sonido, cortados o con escenas faltantes. Hacer un lint barato ahora evita un render costoso después.

npx hyperframes lint, 0 errores, validación previa al render.

O npx hyperframes inspect --samples 16 abre Chrome en modo headless, captura 16 frames distribuidos a lo largo del video y muestra miniaturas para una inspección visual rápida del diseño.

El texto cortado, los elementos fuera de la pantalla o las superposiciones solo se ven visualmente. El inspect los detecta antes de perder minutos de render.

npx hyperframes inspect --samples 16, miniaturas, problemas de diseño.

El modo --quality draft renderiza en resolución reducida y a mayor velocidad para ofrecer una vista previa rápida del video completo antes del render final.

El draft permite revisar la secuencia, las transiciones y el timing sin esperar el render completo. Corrige en el draft, no en el high.

--quality draft, vista previa rápida, iteración económica.

Extrae frames del draft con FFmpeg (ffmpeg -i draft.mp4 -vf fps=1 frames/%04d.png) y compártelo con el usuario para la validación visual. Claude no puede escuchar el audio.

La validación humana antes del renderizado final detecta problemas subjetivos (texto demasiado pequeño, colores incorrectos, orden equivocado) que el lint no detecta.

ffmpeg -vf fps=1, frames PNG, validación humana, Claude no escucha.

Tras aprobar el draft, ejecuta --quality high --fps 30 para el render completo. Genera el MP4 final en resolución completa, listo para subir.

El render high tarda más y no debe repetirse. Aprobar el draft antes garantiza que el esfuerzo de render se dedique al archivo correcto.

--quality high --fps 30, renderizado final, no repetir sin validar.

Ejecuta el render dos veces con parámetros de formato diferentes (o usa la flag --both si está disponible en tu proyecto). El resultado son los archivos horizontal (16:9) y vertical (9:16) listos para distribuir.

YouTube y Shorts tienen alcances distintos. Generar ambas versiones en el mismo render maximiza la distribución sin rehacer el contenido.

16:9 YouTube, 9:16 Shorts, dos versiones, distribución multiplataforma.