Communitygithub.com

Simplicio Loop Marketing - Composición con HyperFrames

Crea composiciones animadas HTML a MP4 (tipografía cinética, tarjetas con citas animadas, videos programáticos de datos) usando el renderizador HyperFrames. Se invoca cuando el proveedor de video resuelto por la matriz de enrutamiento es `hyperframes`.

¿Qué es Simplicio Loop Marketing - Composición con HyperFrames?

Esta habilidad contiene las reglas de autoría para HyperFrames, un renderizador HTML → MP4 de código abierto (Apache 2.0). Se utiliza para generar composiciones animadas deterministas como tipografía cinética, tarjetas con citas animadas o reels programáticos de visualización de datos. El flujo de trabajo comienza leyendo el contexto de marca (archivo `design.md`), planificando el arco narrativo, y luego escribiendo el HTML con atributos `data-start`, `data-duration`, `data-track-index`. Las animaciones se construyen con `gsap.from()` para entradas y `gsap.to()` solo en la escena final para salidas; todas las líneas de tiempo se registran en `window.__timelines` y comienzan en pausa para que el framework controle la reproducción. Se aplican transiciones entre cada escena, y se valida localmente con `npx hyperframes lint` e `inspect` antes de renderizar. Los parámetros variables se declaran en `data-composition-variables` para permitir re-renderizados con nuevos datos sin tocar el código. Las plataformas compatibles son HyperFrames, y la habilidad se integra con `hyperframes-cli` y `hyperframes-prompt-builder`. Está prohibido usar `Math.random()`, `Date.now()`, o lógica basada en tiempo de pared. El resultado incluye un manifiesto JSON con metadatos de la composición.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/hyperframes

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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.md o un provider_override.video: hyperframes en 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 y data-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 de clients/<slug>/design.md cuando 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 defecto outputs/<client>/<date>/<piece-id>/).

Proceso

  1. 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.
  2. 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.
  3. 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 con gsap.to().
  4. Componer el HTML. El <html> raíz lleva data-composition-id, data-width, data-height. Cada clip lleva id, data-start, data-duration, data-track-index. Parametrizar con data-composition-variables (arreglo JSON en <html>); leer en tiempo de ejecución con window.__hyperframes.getVariables().
  5. 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, sin Math.random(), sin lógica basada en tiempo, sin construcción asíncrona de líneas de tiempo.
  6. Transiciones entre cada escena. Sin cortes abruptos. Usar las transiciones catalogadas (fundido, barrido, enmascarado, shader) listadas en el references/transitions.md upstream.
  7. Video y audio. El <video> debe estar silenciado; el audio vive en un elemento <audio> separado en su propia pista.
  8. Validar localmente con npx hyperframes lint, luego npx hyperframes inspect (desbordamiento de texto, recorte de contenedor). Solo renderizar una vez que ambos pasen. Delegado a la habilidad hyperframes-cli.
  9. Emitir el manifiesto. Escribir manifest.json junto al MP4 con { composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }. Requerido por la Definición de Hecho en CLAUDE.md.

Salidas

  • project_path: cadena. Ruta al directorio del proyecto HyperFrames.
  • composition_html: cadena. El contenido del index.html creado (o la ruta hacia él dentro de project_path).
  • render_args: objeto. Las banderas a pasar a npx hyperframes render (--fps, --quality, --variables, --strict).
  • expected_artifact: cadena. La ruta del MP4 que aparecerá bajo output_dir despué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(), sin Date.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-variables para que la misma composición se re-renderice para nuevas piezas.
  • Nunca editar un MP4 renderizado bajo outputs/; en su lugar, volver a ejecutar hyperframes 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.md y no se pasaron tokens de diseño: detenerse y preguntar. No inventar una paleta.
  • npx hyperframes lint reporta errores (falta data-composition-id, pistas superpuestas, líneas de tiempo no registradas): bloquear el renderizado hasta que se solucione.
  • npx hyperframes inspect reporta 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_seconds de la composición: recortar el audio, nunca extender duration_seconds para 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 por video-prompt-builder cuando la matriz resuelve a hyperframes.
  • 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

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Skills relacionados