HyperFrames
HyperFrames es un renderizador HTML → MP4 (Apache 2.0). Las composiciones son archivos HTML simples con atributos data-start, data-duration, data-track-index; el renderizador controla un Chrome sin interfaz gráfica a través de la línea de tiempo con precisión de fotograma y envía los fotogramas a FFmpeg. La habilidad hyperframes-prompt-builder es el punto de entrada del despachador de marketing; esta habilidad contiene las reglas de autoría.
Cuándo invocar
- Una pieza se enruta (a través de
PROVIDERS.mdo unprovider_override.video: hyperframesen el frontmatter) al proveedor HyperFrames. - La tarea es
motion-typography,data-viz-reel,programmatic-short, o cualquier composición que necesite una salida determinista a partir de variables declaradas (ej. reel semanal de KPIs que se re-renderiza sin cambios con nuevos números). - Una imagen fija aprobada (tarjeta con cita, slide de carrusel) necesita ser promovida a una pieza corta animada sin cambiar el sistema tipográfico.
- El orquestador necesita un artefacto re-renderizable: misma composición, diferentes
--variables, línea base byte-idéntica.
Entradas
composition_id: cadena. Slug corto usado para el directorio del proyecto ydata-composition-id.aspect:9:16|1:1|16:9|4:5.duration_seconds: entero. Duración total de la composición.scenes: arreglo. Cada{ id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }.design_tokens: objeto. Colores de marca, familias tipográficas primarias/secundarias, escala de espaciado. Se obtiene declients/<slug>/design.mdcuando existe.variables: arreglo, opcional. Parámetros declarados que los llamadores pueden sobrescribir en tiempo de renderizado{ id, type, label, default }.assets: objeto, opcional.{ video?, audio?, images[] }— rutas locales bajo el proyecto.output_dir: cadena. Donde el renderizador escribe el MP4 (por defectooutputs/<client>/<date>/<piece-id>/).
Proceso
- Leer el contexto de marca primero. Cargar
clients/<active-client>/design.md(o los tokens de diseño pasados). Rechazar crear HTML antes de que los tokens sean conocidos — recurrir a los valores por defecto del repositorio solo si el cliente no tiene ninguno. - Planificar el arco narrativo en voz alta (escenas, ritmo, transiciones, compás) antes de escribir el marcado. Hook en los primeros 1.5s, cuerpo, CTA al final.
- Diseño antes de animación. Escribir primero el diseño final en pantalla — posicionar los elementos donde terminan. Animar hacia esas posiciones con
gsap.from(); solo la escena final puede usar salidas congsap.to(). - Componer el HTML. El
<html>raíz llevadata-composition-id,data-width,data-height. Cada clip llevaid,data-start,data-duration,data-track-index. Parametrizar condata-composition-variables(arreglo JSON en<html>); leer en tiempo de ejecución conwindow.__hyperframes.getVariables(). - Registrar cada línea de tiempo en pausa.
const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl;— el framework controla la reproducción. Sin repeticiones infinitas, sinMath.random(), sin lógica basada en tiempo, sin construcción asíncrona de líneas de tiempo. - Transiciones entre cada escena. Sin cortes abruptos. Usar las transiciones catalogadas (fundido, barrido, enmascarado, shader) listadas en el
references/transitions.mdupstream. - Video y audio. El
<video>debe estar silenciado; el audio vive en un elemento<audio>separado en su propia pista. - Validar localmente con
npx hyperframes lint, luegonpx hyperframes inspect(desbordamiento de texto, recorte de contenedor). Solo renderizar una vez que ambos pasen. Delegado a la habilidadhyperframes-cli. - Emitir el manifiesto. Escribir
manifest.jsonjunto al MP4 con{ composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }. Requerido por la Definición de Hecho enCLAUDE.md.
Salidas
project_path: cadena. Ruta al directorio del proyecto HyperFrames.composition_html: cadena. El contenido delindex.htmlcreado (o la ruta hacia él dentro deproject_path).render_args: objeto. Las banderas a pasar anpx hyperframes render(--fps,--quality,--variables,--strict).expected_artifact: cadena. La ruta del MP4 que aparecerá bajooutput_dirdespués del renderizado.cost_estimate_usd: número. Renderizado local — solo tiempo de cómputo; reportar 0 para DRY_RUN, de lo contrario estimar desde--workers× duración.
Reglas no negociables
- Cada elemento tiene una animación de entrada (
gsap.from()). - Todas las líneas de tiempo comienzan en pausa y se registran en
window.__timelines. - Sin
Math.random(), sinDate.now()en la lógica de la composición, sin animaciones impulsadas por setTimeout. - Pistas de video silenciadas; nunca incrustar audio en
<video>. - Nunca codificar el copy del cliente directamente en el marcado si podría ser una variable — declararlo en
data-composition-variablespara que la misma composición se re-renderice para nuevas piezas. - Nunca editar un MP4 renderizado bajo
outputs/; en su lugar, volver a ejecutarhyperframes render.
Ejemplos
Ejemplo 1: reel semanal de KPIs (programmatic-short)
Entrada: { composition_id: "kpi-weekly-w21", aspect: "9:16", duration_seconds: 12, scenes: [{ id: "hook", start_s: 0, duration_s: 2, role: "hook", copy: "Semana 21" }, { id: "metric", start_s: 2, duration_s: 8, role: "body" }, { id: "cta", start_s: 10, duration_s: 2, role: "cta", copy: "Veja o detalhamento" }], variables: [{ id: "leads", type: "number", label: "Novos leads", default: 0 }, { id: "delta_pct", type: "number", label: "Variação %", default: 0 }] }
Salida: un proyecto bajo outputs/<client>/<date>/kpi-weekly-w21/ cuyo index.html lee las dos variables numéricas y las anima; render_args.--variables las resuelve por pieza.
Ejemplo 2: tarjeta con cita animada (motion-typography)
Entrada: { composition_id: "quote-marcos-2026-05", aspect: "1:1", duration_seconds: 6, scenes: [{ id: "main", start_s: 0, duration_s: 6, role: "body", copy: "Coloque a sua marca onde os olhos já estão." }] }
Salida: una composición de tipografía cinética que respeta la combinación tipográfica del cliente activo, con entrada de texto enmascarado y una pausa suave en el fotograma final.
Modos de fallo
- Falta
design.mdy no se pasaron tokens de diseño: detenerse y preguntar. No inventar una paleta. npx hyperframes lintreporta errores (faltadata-composition-id, pistas superpuestas, líneas de tiempo no registradas): bloquear el renderizado hasta que se solucione.npx hyperframes inspectreporta desbordamiento de texto en alguna escena: preferir reajustar el diseño antes de reducir el tamaño de la fuente por debajo del mínimo del sistema.- Pista de audio más larga que la
duration_secondsde la composición: recortar el audio, nunca extenderduration_secondspara que coincida. - La composición usa
Math.random()o tiempo de reloj de pared en cualquier lugar: refactorizar a una variable declarada o a un generador determinista con semilla antes de renderizar.
Habilidades relacionadas
hyperframes-cli: comandos lint, inspect, preview, render. Siempre se invoca después de la autoría.hyperframes-prompt-builder: especialista del motor de marketing que traduce un brief de pieza en la forma de entrada que esta habilidad espera, llamado porvideo-prompt-buildercuando la matriz resuelve ahyperframes.video-prompt-builder: despachador genérico.qa-tech-specs: valida el MP4 renderizado contra las especificaciones de la plataforma (aspecto, duración, áreas seguras).compliance-<active client>: se ejecuta después del renderizado contra el artefacto renderizado y el copy en pantalla resuelto a partir de las variables.
Referencia upstream
Habilidad upstream completa (patrones de composición, catálogo de transiciones, audio-reactivo, subtítulos, datos en movimiento): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes