HyperFrames
HyperFrames é um renderizador HTML → MP4 (Apache 2.0). As composições são arquivos HTML comuns com atributos data-start, data-duration, data-track-index; o renderizador controla um Chrome headless percorrendo a linha do tempo com precisão de quadros e envia os quadros para o FFmpeg. A skill hyperframes-prompt-builder é o ponto de entrada do dispatcher de marketing; esta skill contém as regras de autoria.
Quando invocar
- Uma peça é roteada (via
PROVIDERS.mdou umprovider_override.video: hyperframesno frontmatter) para o provedor HyperFrames. - A tarefa é
motion-typography,data-viz-reel,programmatic-short, ou qualquer composição que precise de saída determinística a partir de variáveis declaradas (ex.: reel semanal de KPIs que re-renderiza inalterado com novos números). - Uma imagem estática aprovada (cartão de citação, slide de carrossel) precisa ser promovida a uma peça curta em movimento sem alterar o sistema tipográfico.
- O orquestrador precisa de um artefato re-renderizável: mesma composição,
--variablesdiferentes, linha de base byte-idêntica.
Entradas
composition_id: string. Slug curto usado para o diretório do projeto e paradata-composition-id.aspect:9:16|1:1|16:9|4:5.duration_seconds: inteiro. Duração total da composição.scenes: array. Cada{ id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }.design_tokens: objeto. Cores da marca, famílias tipográficas primária/secundária, escala de espaçamento. Obtidos declients/<slug>/design.mdquando presente.variables: array, opcional. Parâmetros declarados que os chamadores podem sobrescrever no momento da renderização{ id, type, label, default }.assets: objeto, opcional.{ video?, audio?, images[] }— caminhos locais dentro do projeto.output_dir: string. Onde o renderizador escreve o MP4 (padrão:outputs/<client>/<date>/<piece-id>/).
Processo
- Leia o contexto da marca primeiro. Carregue
clients/<active-client>/design.md(ou os tokens de design recebidos). Recuse-se a criar HTML antes de conhecer os tokens — recorra aos padrões do repositório apenas se o cliente não tiver nenhum. - Planeje o arco narrativo em voz alta (cenas, ritmo, transições, batida) antes de escrever a marcação. Gancho (hook) nos primeiros 1.5s, corpo, CTA no final.
- Layout antes da animação. Escreva primeiro o layout final na tela — posicione os elementos onde eles terminam. Anima para dentro dessas posições com
gsap.from(); apenas a cena final pode usargsap.to()para saídas. - Componha o HTML. A raiz
<html>carregadata-composition-id,data-width,data-height. Cada clipe carregaid,data-start,data-duration,data-track-index. Parametrize comdata-composition-variables(array JSON no<html>); leia em tempo de execução comwindow.__hyperframes.getVariables(). - Registre cada timeline como pausada.
const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl;— o framework controla a reprodução. Sem repetições infinitas, semMath.random(), sem lógica baseada em tempo, sem construção assíncrona de timeline. - Transições entre todas as cenas. Sem cortes secos. Use as transições catalogadas (fade, wipe, masked, shader) listadas na referência
references/transitions.md. - Vídeo e áudio.
<video>deve estar mudo; o áudio vive em um elemento<audio>separado em sua própria trilha. - Valide localmente com
npx hyperframes lint, depoisnpx hyperframes inspect(extravasamento de texto, recorte de contêiner). Renderize apenas quando ambos passarem. Delegado à skillhyperframes-cli. - Emita o manifesto. Escreva
manifest.jsonao lado do MP4 com{ composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }. Obrigatório pela Definição de Pronto emCLAUDE.md.
Saídas
project_path: string. Caminho para o diretório do projeto HyperFrames.composition_html: string. O conteúdo doindex.htmlcriado (ou o caminho para ele dentro deproject_path).render_args: objeto. As flags a serem passadas paranpx hyperframes render(--fps,--quality,--variables,--strict).expected_artifact: string. O caminho do MP4 que aparecerá emoutput_dirapós a renderização.cost_estimate_usd: número. Renderização local — apenas tempo de computação; informe 0 para DRY_RUN, caso contrário estime a partir de--workers× duração.
Regras inegociáveis
- Todo elemento tem uma animação de entrada (
gsap.from()). - Todas as timelines iniciam pausadas e são registradas em
window.__timelines. - Nenhum
Math.random(), nenhumDate.now()na lógica da composição, nenhuma animação baseada em setTimeout. - Trilhas de vídeo mudas; nunca incorpore áudio em
<video>. - Nunca coloque o texto do cliente diretamente na marcação se ele puder ser uma variável — declare-o em
data-composition-variablespara que a mesma composição re-renderize para novas peças. - Nunca edite um MP4 renderizado em
outputs/; executehyperframes rendernovamente.
Exemplos
Exemplo 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 }] }
Saída: um projeto em outputs/<client>/<date>/kpi-weekly-w21/ cujo index.html lê as duas variáveis numéricas e as anima; render_args.--variables as resolve para cada peça.
Exemplo 2: cartão de citação motion (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." }] }
Saída: uma composição de tipografia cinética que respeita o par tipográfico do cliente ativo, com entrada de texto mascarada e uma pausa suave no quadro final.
Modos de falha
design.mdausente e nenhum token de design passado: pare e pergunte. Não invente uma paleta.npx hyperframes lintrelata erros (data-composition-idausente, trilhas sobrepostas, timelines não registradas): bloqueie a renderização até corrigir.npx hyperframes inspectrelata extravasamento de texto em qualquer cena: prefira reorganizar o layout a reduzir a fonte abaixo do mínimo do sistema.- Trilha de áudio mais longa que
duration_secondsda composição: corte o áudio, nunca estendaduration_secondspara caber. - Composição usa
Math.random()ou hora do relógio em qualquer lugar: refatore para uma variável declarada ou um gerador determinístico com semente antes de renderizar.
Skills relacionadas
hyperframes-cli: comandos lint, inspect, preview, render. Sempre invocado após a autoria.hyperframes-prompt-builder: especialista do motor de marketing que traduz um briefing de peça no formato de entrada que esta skill espera, chamado porvideo-prompt-builderquando a matriz resolve parahyperframes.video-prompt-builder: dispatcher genérico.qa-tech-specs: valida o MP4 renderizado contra as especificações da plataforma (aspecto, duração, áreas seguras).compliance-<active client>: executado após a renderização contra o artefato renderizado e o texto na tela resolvido a partir das variáveis.
Referência upstream
Skill upstream completa (padrões de composição, catálogo de transições, áudio-reativo, legendas, dados em movimento): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes