HyperFrames
O HTML é a fonte da verdade para vídeo. Uma composição é um arquivo HTML com atributos data-* para temporização, uma timeline GSAP para animação e CSS para aparência. O framework gerencia a visibilidade dos clipes, reprodução de mídia e sincronização da timeline.
Abordagem
Descoberta (apenas para solicitações exploratórias)
Para pedidos abertos ("faça um vídeo de lançamento de produto", "crie algo para nossa marca") onde o usuário não se comprometeu com uma direção, entenda a intenção antes de escolher cores:
- Público — quem assiste isso? Desenvolvedores? Executivos? Consumidores em geral?
- Plataforma — onde será exibido? Redes sociais (15s), herói do site, demonstração de produto, interno?
- Prioridade — o que é mais importante? Qualidade do movimento? Precisão do conteúdo? Fidelidade da marca? Velocidade?
- Variações — o usuário quer opções, ou uma única melhor versão?
Para solicitações específicas ("adicione uma cartela de título", "corrija o tempo na cena 3"), pule a descoberta.
Para solicitações exploratórias, considere oferecer 2-3 variações que diferem de forma significativa — não apenas trocas de cor, mas ritmos diferentes, níveis de energia ou abordagens estruturais. Uma segura/esperada, uma ambiciosa. Não torne isso obrigatório — é uma ferramenta disponível quando apropriado.
Passo 1: Sistema de design
Se design.md ou DESIGN.md existir no projeto, leia-o primeiro (verifique ambas as grafias — são arquivos diferentes no Linux). É a fonte da verdade para cores da marca, fontes e restrições. Use seus valores exatos — não invente cores nem substitua fontes. Qualquer formato funciona (frontmatter YAML, prosa, tabelas — apenas extraia os valores).
Se ele nomear fontes que não podem ser encontradas localmente (nenhum diretório fonts/ com arquivos .woff2, nem uma fonte embutida), avise o usuário antes de escrever HTML: "design.md especifica [nome da fonte] mas nenhum arquivo de fonte encontrado. Adicione arquivos .woff2 em fonts/ ou vou usar [alternativa embutida mais próxima]."
Se nenhum design.md existir, ofereça ao usuário uma escolha:
- O usuário nomeou um estilo ou clima? → Leia visual-styles.md para os 8 presets nomeados. Escolha o mais próximo.
- Quer navegar por opções visualmente? → Execute o seletor de design: leia references/design-picker.md para o fluxo completo. Isso serve uma página visual de seletor. O usuário configura clima, paleta, tipografia e movimento no navegador, então copia o design.md gerado e cola de volta na conversa.
- Quer pular e ir rápido? → Pergunte: clima, claro ou escuro, alguma cor/fonte da marca? Então escolha uma paleta de house-style.md.
design.md define a marca. Não define regras de composição de vídeo. Essas vêm de references/video-composition.md e house-style.md. Use cores da marca em escala apropriada para vídeo — não na opacidade da interface web.
Passo 2: Expansão de prompt
Sempre execute em cada composição (exceto peças de uma única cena e edições triviais). Este passo ancora a intenção do usuário em relação a design.md e house-style.md e produz um intermediário consistente que todo agente downstream lê da mesma forma.
Leia references/prompt-expansion.md para o processo completo e formato de saída.
Passo 3: Planejamento
Antes de escrever HTML, pense em alto nível:
- O quê — o que o espectador deve experimentar? Identifique o arco narrativo, momentos-chave e batidas emocionais.
- Estrutura — quantas composições, quais são sub-composições vs inline, quais faixas carregam o quê (vídeo, áudio, sobreposições, legendas).
- Ritmo — declare seu ritmo de cena antes de implementar. Quais cenas são rápidas, quais são pausadas, onde os shaders aparecem, onde a energia atinge o pico. Nomeie o padrão: rápido-rápido-DEVAGAR-rápido-SHADER-pausa. Leia references/beat-direction.md para modelos de ritmo.
- Tempo — quais clipes determinam a duração, onde as transições acontecem, qual é o ritmo.
- Layout — construa o estado final primeiro. Veja "Layout antes da Animação" abaixo.
- Animar — então adicione movimento usando as regras abaixo.
Construa o que foi pedido. Um pedido de "uma cartela de título" não é um pedido de "uma cartela de título + 3 cenas de apoio + música ambiente + legendas." Cada cena, cada elemento, cada interpolação deve merecer seu lugar. Se cenas ou elementos adicionais melhorariam genuinamente a peça, proponha-os — não os adicione.
Para pequenas edições (corrigir uma cor, ajustar o tempo, adicionar um elemento), vá direto para as regras.
Layout antes da Animação
Posicione cada elemento onde ele deve estar em seu momento mais visível — o quadro onde ele entrou completamente, está corretamente colocado e ainda não está saindo. Escreva isso como HTML+CSS estático primeiro. Sem GSAP ainda.
Por que isso importa: Se você posicionar elementos em seu estado inicial animado (fora da tela, escalados para 0, opacidade 0) e interpolar para onde você acha que eles devem chegar, você está adivinhando o layout final. Sobreposições são invisíveis até o vídeo renderizar. Ao construir o estado final primeiro, você pode ver e corrigir problemas de layout antes de adicionar qualquer movimento.
O processo
- Identifique o quadro herói para cada cena — o momento em que o maior número de elementos está simultaneamente visível. Este é o layout que você constrói.
- Escreva CSS estático para esse quadro. O contêiner
.scene-contentDEVE preencher a cena inteira usandowidth: 100%; height: 100%; padding: Npx;comdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Use padding para empurrar o conteúdo para dentro — NUNCA useposition: absolute; top: Npxem um contêiner de conteúdo. Contêineres de conteúdo com posicionamento absoluto transbordam quando o conteúdo é mais alto que o espaço restante. Reserveposition: absoluteapenas para elementos decorativos. - Adicione entradas com
gsap.from()— anime DE fora da tela/invisível PARA a posição CSS. A posição CSS é a verdade absoluta; a interpolação descreve a jornada para chegar lá. (Em sub-composições carregadas viadata-composition-src, prefiragsap.fromTo()— veja regras GSAP de suporte de carga em references/motion-principles.md.) - Adicione saídas com
gsap.to()— anime PARA fora da tela/invisível DA posição CSS.
Exemplo
/* scene-content preenche a cena, padding posiciona o conteúdo */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* O contêiner preenche qualquer tamanho de cena (1920x1080, 1080x1920, etc.).
O padding posiciona o conteúdo. Flex + gap cuidam do espaçamento. */
ERRADO — dimensões fixas e posicionamento absoluto:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Passo 3: Anime PARA essas posições
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// Passo 4: Anime PARA FORA dessas posições
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
Quando elementos compartilham espaço ao longo do tempo
Se o elemento A sai antes do elemento B entrar na mesma área, ambos devem ter posições CSS corretas para seus respectivos quadros heróis. A ordenação da timeline garante que eles nunca coexistam visualmente — mas se você pular a etapa de layout, não perceberá o caso em que eles acidentalmente se sobrepõem devido a um erro de temporização.
O que conta como sobreposição intencional
Efeitos em camadas (brilho atrás do texto, elementos de sombra, padrões de fundo) e designs empilhados em z (pilhas de cartões, camadas de profundidade) são intencionais. A etapa de layout é para detectar sobreposição não intencional — dois títulos principais caindo um em cima do outro, uma estatística cobrindo um rótulo, conteúdo vazando para fora do quadro.
Atributos de Dados
Todos os Clipes
| Atributo | Obrigatório | Valores |
|---|---|---|
id | Sim | Identificador único |
data-start | Sim | Segundos ou referência de ID do clipe ("el-1", "intro + 2") |
data-duration | Obrigatório para img/div/composições | Segundos. Vídeo/áudio usa a duração da mídia por padrão. |
data-track-index | Sim | Inteiro. Clipes na mesma faixa não podem se sobrepor. |
data-media-start | Não | Deslocamento de corte na fonte (segundos) |
data-volume | Não | 0-1 (padrão 1) |
data-track-index não afeta a camada visual — use CSS z-index.
Clipes de Composição
| Atributo | Obrigatório | Valores |
|---|---|---|
data-composition-id | Sim | ID único da composição |
data-start | Sim | Tempo de início (composição raiz: use "0") |
data-duration | Sim | Tem precedência sobre a duração da timeline GSAP |
data-width / data-height | Sim | Dimensões em pixels (1920x1080 ou 1080x1920) |
data-composition-src | Não | Caminho para arquivo HTML externo |
data-variable-values | Não | Objeto JSON de substituições de variáveis por instância em um host de sub-comp |
No elemento <html> raiz:
| Atributo | Obrigatório | Valores |
|---|---|---|
data-composition-variables | Não | Array JSON de variáveis declaradas (id/type/label/default) — impulsiona a UI de edição do Studio e fornece padrões para getVariables() |
Estrutura da Composição
Sub-composições carregadas via data-composition-src usam um invólucro <template>. Composições independentes (o index.html principal) NÃO usam <template> — elas colocam o div data-composition-id diretamente no <body>. Usar <template> em um arquivo independente esconde todo o conteúdo do navegador e quebra a renderização.
Estrutura da sub-composição:
<template id="minha-comp-template">
<div data-composition-id="minha-comp" data-width="1920" data-height="1080">
<!-- conteúdo -->
<style>
[data-composition-id="minha-comp"] {
/* estilos com escopo */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// interpolações...
window.__timelines["minha-comp"] = tl;
</script>
</div>
</template>
Carregar na raiz: <div id="el-1" data-composition-id="minha-comp" data-composition-src="compositions/minha-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Variáveis (Composições Parametrizadas)
Renderize a mesma composição com conteúdo diferente — título, cor do tema, preços, legendas — sem editar o HTML de origem.
Padrão de três etapas:
- Declare variáveis na raiz
<html>da composição comdata-composition-variables. Cada entrada precisa deid,type(um destring,number,color,boolean,enum),labeledefault. Entradas enum também precisam deoptions: [{value, label}, ...]. - Leia os valores resolvidos dentro do script da composição com
window.__hyperframes.getVariables(). Retorna o resultado mesclado dos padrões declarados + substituições por instância + substituições da CLI. - Substitua no momento da renderização com
npx hyperframes render --variables '{...}'(nível superior) ou comdata-variable-values='{...}'no elemento host (por instância para sub-comps).
<!doctype html>
<html
data-composition-variables='[
{"id":"titulo","type":"string","label":"Título","default":"Olá"},
{"id":"tema","type":"enum","label":"Tema","default":"claro","options":[
{"value":"claro","label":"Claro"},
{"value":"escuro","label":"Escuro"}
]}
]'
>
<body>
<div data-composition-id="raiz" data-width="1920" data-height="1080">
<h1 id="heroi" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { titulo, tema } = window.__hyperframes.getVariables();
document.getElementById("heroi").textContent = titulo;
document.body.dataset.tema = tema;
</script>
</div>
</body>
</html>
# Pré-visualização de desenvolvimento usa os padrões declarados
npx hyperframes preview
# Renderizar com substituições
npx hyperframes render --variables '{"titulo":"Relatório Q4","tema":"escuro"}' --output q4.mp4
# Ou de um arquivo JSON
npx hyperframes render --variables-file ./vars.json
Valores por instância da sub-composição: o mesmo getVariables() funciona dentro de sub-comps carregadas via data-composition-src. Cada elemento host passa seus próprios valores:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"titulo":"Pro","preco":"$29"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
data-variable-values='{"titulo":"Enterprise","preco":"$99"}'
></div>
Substituições da CLI têm a maior precedência, depois data-variable-values no host, depois padrões de data-composition-variables.
Sub-composições
Composições dentro de composições. O HTML de cada sub-comp está em seu próprio arquivo (compositions/nome.html), usa o wrapper <template> e exporta uma timeline. A composição raiz (index.html) as carrega como elementos <div> com data-composition-src.
Por que sub-composições: Reutilização (mesmo cartão com dados diferentes), Isolamento (estilos e scripts com escopo), Paralelismo (cada <script src="gsap"> dentro do template cria seu próprio timeline, evitando conflitos de variáveis globais) e Delegação (diferentes agentes podem trabalhar em sub-composições diferentes).
Carga em lote: Para muitas sub-composições, carregue GSAP uma vez na raiz e não dentro de cada template. Isso reduz solicitações HTTP e tamanho total do HTML. A raiz precisa de <script src="gsap.min.js"></script> antes de qualquer div de composição. Os templates de sub-comp omitem o script do GSAP e dependem da instância global da raiz.
Quando Sub-composições vs Inline
- Inline: Clipes de curta duração (1-4s de duração, especialmente clipes sem script), cenas onde você precisa de transições CSS visíveis entre clipes HTML (sub-comps são carregadas de forma assíncrona e podem não estar disponíveis quando a transição começa) e prototipagem rápida onde mover para um arquivo separado não vale o atrito.
- Sub-composição: Cenas reutilizáveis entre projetos, cenas com script intenso (manter o script da raiz enxuto), cenas longas (50+ linhas de HTML/CSS), e qualquer cena que se beneficie de escopo isolado ou carregamento paralelo.
Gerenciamento de Clipes e Mídia
Tipos de clipe: <video>, <audio>, <img>, <div> (para animações GSAP), e composições aninhadas.
Clipes não cronometrados: Elementos com data-start mas sem data-duration herdam a duração da composição. Elementos sem data-start ou data-duration são exibidos durante toda a duração da composição. Isso é útil para fundos, decorações persistentes e música que preenche o espaço restante. Faixas de áudio sem duração são tratadas como "loop para preencher seu espaço alocado".
truncado para tradução