Módulo 3.3 — Render en HyperFrames

🚀 npx hyperframes init <nome>

El punto de partida: crear un proyecto HyperFrames aislado donde se montará y renderizará el video.

crear el proyecto

npx hyperframes init <nome> --example blank --non-interactive

💡Requisitos previos

Node 22+ y FFmpeg; el Chrome de HyperFrames (npx hyperframes browser ensure); Kokoro (pip install kokoro-onnx soundfile) e o agent-browser en el PATH. La aplicación objetivo debe estar en línea (p. ej.: localhost:8000).

📦 Copiar scripts + assets/fonts

La skill es autocontenida: copias los scripts y las fuentes al proyecto y ya está lista para ejecutarse.

qué copiar al proyecto

capture.mjs                       ← dirige o agent-browser
composition-template.mjs  →  build-demo.mjs   ← renomear
narration-template.sh             ← gera os WAVs
assets/fonts/                     ← Sora/Inter/JetBrains (.woff2 + fonts.css)
# ou, em vez de copiar fonts:
node fetch-fonts.mjs              ← baixa as fontes

📊

Auto contenida

La skill incluye sus propias fuentes y su house style. No depende de ningún otro proyecto, repositorio o skill para funcionar: genera todo desde cero en cualquier proyecto.

📸 node capture.mjs actions.json

La captura genera las tomas y el steps.json: el enlace con la Trilha 2 y la entrada de la composición.

captura + narración

node capture.mjs actions.json     # -> assets/shots/*.png + steps.json
bash narration-template.sh        # -> assets/audio/sN.wav (voz pf_dora)

⚡

El viewport fijo es sagrado

Las bounding boxes y las capturas de pantalla deben salir del MISMO viewport (ancho ≤ ~1280 para que quepa en 16:9); de lo contrario, el cursor no acierta el objetivo. Tipos de acción: fill, click, clickText, setValue, wait.

📊

Captura manual cuando la app es impredecible

Para iniciar sesión o manejar estados dinámicos, puedes controlar agent-browser manualmente (snapshot, fill, screenshot y obtener el bbox mediante eval) y armar el steps.json: el resultado es el mismo.

🧱 build-demo + lint + inspect

Genera el index.html y valídalo antes de dedicar tiempo al render: lint e inspect son baratos.

node build-demo.mjs

Lee el steps.json, mide los WAV y escribe el index.html (16:9).

npx hyperframes lint0 errores

Obtiene fuentes vía CDN, animación en .clip incorrecto y reglas del framework incumplidas.

npx hyperframes inspect --samples 140 problemas

Muestrea frames y detecta problemas de diseño (crop, fuera del canvas sin data-layout-ignore).

🎬 render --quality high

Primero un Draft para revisar y luego en alta calidad, siempre validando los frames y la locución con el usuario.

render

# 1) conferir rápido
npx hyperframes render --quality draft
# extrair 1 frame por passo e mostrar ao usuário
ffmpeg -nostdin -y -ss <t> -i video.mp4 -vframes 1 -update 1 frame.png

# 2) render final
npx hyperframes render --quality high --fps 30 \
  --output renders/<nome>-16x9.mp4

🚨

No escuchas el audio

Siempre revisa los frames con el usuario y pídele que valide la locución antes del render final: no puedes escuchar el audio de tu lado.

🧯 Problemas finales

Las reglas de oro innegociables que evitan horas de depuración en el inspect.

✓HACER

✓Capturar antes, animar después (renderizado determinista)
✓Mantener fijo el viewport = espacio de las coordenadas
✓Animar el .scene-inner, nunca el .clip
✓Elementos decorativos y marco con data-layout-ignore

✗NO HACER

✗Cargar el sitio en vivo dentro del video (sin fetch durante el renderizado)
✗Usar fuentes de CDN; solo las locales de assets/fonts/
✗Escribir un AUDIO[] manual — el timing se mide
✗Editar el index.html a mano

📊

Límites conocidos (sé honesto)

El estado dinámico (animaciones, video, datos en vivo) se convierte en una captura estática. Una app con inicio de sesión necesita credenciales de prueba (o captura solo las pantallas públicas). El formato natural es 16:9: las pantallas de las apps son apaisadas.

🗺️ Hoja de ruta (futuro)

Lo que la skill todavía no hace — elementos de evolución, claramente marcados como futuros.

🔮No implementado — backlog

①Desplazamiento durante la captura — hoy las páginas largas exigen manejar agent-browser manualmente; la idea es una acción scroll + scrollIntoView por paso.
②Inputs controlados por React/Vue — usar el fill nativo de Playwright en vez de configurar .value.
③Esperar una condición (waitFor) en lugar de un tiempo fijo, para flujos asíncronos.
④9:16 / Shorts — las pantallas de apps son apaisadas; exigiría reajustar el encuadre (zoom/paneo en la región activa).
⑤v3 — grabación de pantalla real (agent-browser record) con narración/zoom encima, para apps con mucho movimiento.
⑥Pulido del cursor — recorrido en curva (no lineal) y «escritura» (typewriter) al completar campos.

⚡

Hoy (v1, predeterminado)

Capturas de pantalla estáticas + cursor/zoom animados, 16:9, narración local. Todo lo anterior está en el roadmap; no prometas lo que la skill todavía no ofrece.

🎯 Lo que aprendiste

✓init del proyecto + copiar scripts y assets/fonts de la skill autocontenida
✓capture.mjs genera capturas + steps.json; la narración genera los WAV
✓build-demo.mjs genera index.html; lint + inspect validan (0/0)
✓render draft → high; revisar los frames y validar la locución
✓gotchas no negociables y lo que está en el roadmap (9:16, v3, cursor en curva)

Completaste la Ruta 3. De la captura al MP4 narrado con CTA de INEMA.CLUB — el walkthrough completo.

← Módulo 3.2: Narración y composición Volver a la Ruta 3 →