🎬 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.

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

HTML → frames 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 funciona localmente mediante Python (kokoro-onnx). Genera archivos WAV de alta calidad sin ninguna llamada a servicios externos.

Elimina los costos variables 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 miedo a que los costos se disparen y garantiza que el proyecto se pueda reproducir en cualquier máquina con los requisitos previos instalados.

Primero sin conexión, 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, reaprovechamiento.

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 + narración; no sustituye la grabación 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 en Windows que bloquea el render en silencio.

Node 22+, FFmpeg en el 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 y guarda en caché automáticamente. Las siguientes ejecuciones son offline.

Sin Kokoro instalado, falla la generación de la narración. La descarga tarda la primera vez: tenlo en cuenta durante la configuración.

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

El comando npx hyperframes doctor verifica Node, FFmpeg, Chrome y Kokoro de una 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 momento del render.

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 de la skill al proyecto y haz referencia a él en las instrucciones para Claude.

Sin un design.md, cada video puede tener un aspecto 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 base) → avanzado (detalle práctico) → CTA (próximo paso).

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

SCRIPT.md, 6–9 escenas, arco de hook a 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.

El TTS lee el texto literalmente. Escribe "SKILL punto M D" en vez de "SKILL.md", "M J S" en vez de ".mjs", "N P X" en vez de "npx"; de lo contrario, el resultado suena extraño.

Es uno de los gotchas más comunes. Oír "SKILL punto MD" de forma natural, en lugar de que el modelo intente pronunciar literalmente "skill-dot-md", marca una gran diferencia 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/.

Después de generar los WAV, usa ffprobe -show_entries format=duration en cada archivo para obtener la duración exacta en segundos. Estos 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 necesita HyperFrames.

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

Además de la voz predeterminada pf_dora, Kokoro ofrece pm_alex (masculina neutra) y pm_santa (masculina, de tono más grave) para variar o personalizar el canal.

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

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. Cópialo de la plantilla y edítalo.

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

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

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

Es la única fuente de verdad del timing. Todos los cálculos de animación se 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 0 inicial, GSAP anima.

La función anim(i, t) recibe el índice de la escena y el timeline de GSAP, y agrega 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 tiempos deterministas: el mismo fotograma siempre es igual, algo esencial para la captura sin interfaz.

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

El array CAPTIONS[] define el texto de los 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 (pausa después del final de la voz) y FADE=0.45 (la duración del fundido entre escenas). Cambiarla 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 codifiques segundos directamente 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 audio, cortados o con escenas faltantes. Hacer lint ahora cuesta poco y evita un render caro después.

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

O npx hyperframes inspect --samples 16 abre Chrome 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 pantalla o las superposiciones solo se ven visualmente. El inspect los detecta antes de desperdiciar minutos de render.

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

El modo --quality draft se renderiza a menor resolución y mayor velocidad, para obtener 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 al render completo. Corrige en el draft, no en el high.

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

Extrae fotogramas del borrador 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 render final detecta problemas subjetivos (texto muy pequeño, colores inadecuados, orden incorrecto) que el lint no detecta.

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

Después de 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 de antemano garantiza que el esfuerzo de render se invierta en el archivo correcto.

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

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

YouTube y Shorts tienen alcances diferentes. 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.