⚙️ Node 22+ y FFmpeg
Dos binarios obligatorios: Node.js en la versión 22 o superior y FFmpeg accesible en el PATH. Sin ellos, HyperFrames no puede renderizar ni un solo frame.
HyperFrames usa ESM nativo y API de fs/promises presentes a partir de Node 18, pero la versión 22 trae el --experimental-strip-types y el V8 actualizado que acelera el parse de las composiciones. Las versiones antiguas (16, 18) pueden funcionar parcialmente, pero causan avisos y comportamientos inesperados en el build-index.mjs.
- ✓ FFmpeg en
C:\ffmpeg\bin\ffmpeg.exe - ✓ PATH configurado en la variable de sistema (no usuario)
- ✓ Node 22+ verificado con
node --version - ✓ Abrir una nueva terminal después de modificar PATH
- ✗ Usar FFmpeg instalado por
chocosin verificar PATH - ✗ Node 16 o 18: causa errores en ESM nativo
- ✗ Probar
ffmpegen el terminal antiguo (PATH no actualizado) - ✗ ffmpeg.exe fuera del subdirectorio
bin
⌨️ ffmpeg -nostdin en git-bash
El gotcha más silencioso de la configuración: ejecutar FFmpeg dentro de git-bash sin -nostdin causa exit 0 sin generar ningún archivo. No hay ningún error visible: simplemente no se crea nada.
⚠️ Gotcha crítico: termina con exit 0 sin archivo
En git-bash (MinTTY), FFmpeg intenta leer stdin y se bloquea silenciosamente. El proceso termina con código 0 (éxito), pero no se genera ningún MP4. Es el bug más difícil de diagnosticar porque todo parece haber funcionado.
El CLI de HyperFrames (npx hyperframes render) pasa -nostdin automáticamente en las llamadas internas a FFmpeg. Solo tienes que preocuparte si vas a invocar FFmpeg directamente en git-bash para el posprocesamiento manual, script de concatenación, etc.
🌐 Chrome headless de HyperFrames
HyperFrames incluye su propio Chrome headless; no depende de Chrome instalado en el sistema. Un solo comando descarga y vincula la versión exacta probada con el CLI.
Las diferentes versiones de Chrome renderizan CSS y animaciones GSAP con diferencias sutiles de píxeles. Para que el output sea determinista (el mismo HTML → el mismo MP4), HyperFrames fija una versión específica de Chromium mediante Puppeteer, descargada y administrada internamente. No necesitas tocar el Chrome del sistema.
Lee la versión bloqueada en el package.json de HyperFrames
El campo puppeteer.chromiumRevision define exactamente qué build de Chromium usar — nada de "latest".
Verifica la caché local (~/.cache/puppeteer/)
Si el build ya existe, omite la descarga. El segundo proyecto creado no espera nada: es instantáneo.
Descarga ~170MB del CDN de Chromium si es necesario
Solo la primera vez o cuando se actualiza la versión de HyperFrames. Se recomienda una conexión estable.
🔊 TTS Kokoro
Narración en PT-BR 100% local, sin clave de API. Kokoro tiene su propio fonemizador de portugués, así que no necesitas espeak-ng. En la primera ejecución, descarga ~340MB de modelo.
- ✓
pip install kokoro-onnx soundfile - ✓ Python 3.10+ en el PATH
- ✓ Primera ejecución: espera una descarga de ~340MB
- ✓ Voz predeterminada:
pf_doracon--speed 0.98
- ✗ espeak-ng — Kokoro no lo necesita y crea conflictos
- ✗ Otros paquetes TTS que dependen de espeak
- ✗ Interrumpir la primera descarga del modelo
- ✗ Usar
speed 1.0+— suena mecánico en PT-BR
espeak-ng fonemiza mal el portugués: la pronunciación de las palabras técnicas suena robótica. Kokoro tiene su propio fonemizador de PT-BR, entrenado específicamente para el idioma.
El modelo (~340MB) se almacena en caché en ~/.cache/kokoro/. A partir de la segunda invocación, generar un fragmento de 10s tarda menos de 2 segundos.
🩺 npx hyperframes doctor
El comando de diagnóstico verifica todo el stack de una sola vez: Node, FFmpeg, Chrome y Kokoro. Si algo está mal, te dice exactamente qué falta.
Especialmente en un entorno nuevo o después de actualizar HyperFrames. El npx hyperframes render falla a mitad del proceso si falta una dependencia — el doctor detecta eso antes.
Node.js — versión mínima 18, recomendada 22+
Lee process.version y compara con el campo engines del package.json.
FFmpeg — ejecuta ffmpeg -version y parsea la salida
Verifica si el binario está disponible mediante PATH y muestra la ruta completa encontrada.
Chrome — verifica la caché de Puppeteer
Verifica si el build bloqueado está en ~/.cache/puppeteer/. Si no, sugiere ejecutar browser ensure.
Kokoro — importa el módulo Python y verifica
Ejecuta python -c "import kokoro_onnx" e import soundfile. Versiones mínimas verificadas.
📦 Iniciar un proyecto
Con el entorno listo, el siguiente paso es crear la estructura del proyecto. La plantilla blank + --non-interactive genera todo sin preguntas: ideal para scripts y CI.
O --example blank crea un proyecto mínimo con la estructura de carpetas correcta, pero sin escenas preconstruidas; empiezas desde cero. Es el punto de entrada recomendado para aprender el pipeline, ya que cada archivo que aparece se creó intencionalmente.
init blank- ✓ Lee el
design.mdpara entender la paleta - ✓ Ejecuta
node scripts/fetch-fonts.mjsantes del render - ✓ Usa
narration-template.shcomo base del guion - ✓ Ejecuta
doctoruna vez en el proyecto nuevo
- ✗ Renderizar sin ejecutar
fetch-fonts.mjs→ fuente no encontrada - ✗ Ignorar el
design.mde inventar una paleta - ✗ Saltar el
npm installdespués del init - ✗ Usar espacios en el nombre del proyecto (ej.:
meu video)
Cada proyecto tiene un design.md con la paleta principal, la tipografía y el estilo visual. Para los videos de INEMA.CLUB, la paleta predeterminada es: fondo #0D1321, acento ámbar #FACC15, textos en blanco/gris. Claude lee este archivo antes de escribir cualquier escena.
📋 Resumen del Módulo 2.2
Qué aprendiste en este módulo
- ✓ Node.js 22+ instalado y verificado con
node --version - ✓ FFmpeg en
C:\ffmpeg\binagregado al PATH del sistema - ✓ Chrome headless instalado mediante
npx hyperframes browser ensure - ✓ TTS Kokoro instalado (
pip install kokoro-onnx soundfile), sin espeak-ng - ✓
npx hyperframes doctordevolviendo "All systems go" - ✓ Primer proyecto creado con
npx hyperframes init <nome> --example blank --non-interactive - ✓
fetch-fonts.mjsejecutado, fuentes descargadas - ✓ Entendido por qué
-nostdines necesario en git-bash
narration-template.sh, genera los archivos de audio con Kokoro (pf_dora --speed 0.98) y mide las duraciones con ffprobe para sincronizar con las escenas.