HyperFrames
O HTML é a fonte única 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, a reprodução de mídia e a 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? Desenvolvedores? Executivos? Consumidores em geral?
- Plataforma — onde é reproduzido? Rede social (15s), site principal, demonstração de produto, interno?
- Prioridade — o que é mais importante? Qualidade do movimento? Precisão do conteúdo? Fidelidade à marca? Velocidade?
- Variações — o usuário quer opções ou uma única tomada?
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 significativamente — não apenas trocas de cores, mas ritmos, níveis de energia ou abordagens estruturais diferentes. 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 capitalizações — 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 ou substitua fontes. Qualquer formato funciona (frontmatter YAML, prosa, tabelas — apenas extraia os valores).
Se ele nomear fontes que você não encontra localmente (sem diretório fonts/ com arquivos .woff2, não é uma fonte embutida), avise o usuário antes de escrever HTML: "design.md especifica [nome da fonte] mas nenhum arquivo de fonte foi encontrado. Adicione arquivos .woff2 em fonts/ ou vou usar [alternativa embutida mais próxima] como fallback."
Se não houver design.md, ofereça ao usuário uma escolha:
- O usuário nomeou um estilo ou clima? → Leia visual-styles.md para os 8 estilos nomeados. Escolha o mais próximo.
- Quer navegar pelas opções visualmente? → Execute o seletor de design: leia references/design-picker.md para o fluxo completo. Isso exibe uma página de seleção visual. O usuário configura clima, paleta, tipografia e movimento no navegador, 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? Depois escolha uma paleta de house-style.md.
design.md define a marca. Ele não define regras de composição de vídeo. Essas vêm de references/video-composition.md e house-style.md. Use as cores da marca em escala apropriada para vídeo — não na opacidade de UI web.
Passo 2: Expansão de prompt
Sempre execute em todas as composições (exceto peças de cena única 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 todos os agentes downstream leem 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, os momentos-chave e os batimentos 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 de espera, onde os shaders chegam, onde a energia atinge o pico. Nomeie o padrão: rápido-rápido-LENTO-rápido-SHADER-espera. Leia references/beat-direction.md para modelos de ritmo.
- Temporização — quais clipes determinam a duração, onde as transições caem, qual é o ritmo.
- Layout — construa o estado final primeiro. Veja "Layout Antes da Animação" abaixo.
- Animar — depois adicione movimento usando as regras abaixo.
Construa o que foi solicitado. Um pedido de "uma cartela de título" não é um pedido de "uma cartela de título + 3 cenas de suporte + música ambiente + legendas." Toda cena, todo elemento, todo tween deve merecer seu lugar. Se cenas ou elementos adicionais melhorariam genuinamente a peça, proponha-os — não os adicione.
Para edições pequenas (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 posicionado e ainda não está saindo. Escreva isso como HTML+CSS estático primeiro. Sem GSAP ainda.
Por que isso é importante: Se você posicionar os elementos em seu estado inicial animado (fora da tela, escala 0, opacidade 0) e animá-los para onde você acha que devem ficar, você está adivinhando o layout final. Sobreposições são invisíveis até o vídeo ser renderizado. Construindo o estado final primeiro, você pode ver e corrigir problemas de layout antes de adicionar qualquer movimento.
O processo
- Identifique o quadro herói de cada cena — o momento em que mais elementos estão simultaneamente visíveis. 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 — NUNCAposition: 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 fundamental; o tween descreve a jornada para chegar lá. (Em sub-composições carregadas viadata-composition-src, prefiragsap.fromTo()— veja as regras de GSAP de suporte 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 lidam com 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ói. 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 se sobrepõem acidentalmente 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 com empilhamento z (pilhas de cartões, camadas de profundidade) são intencionais. A etapa de layout serve para detectar sobreposições não intencionais — dois títulos 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 de 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 origem (segundos) |
data-volume | Não | 0-1 (padrão 1) |
data-track-index não afeta a camada visual — use z-index do CSS.
Clipes de Composição
| Atributo | Obrigatório | Valores |
|---|---|---|
data-composition-id | Sim | ID de composição único |
data-start | Sim | Tempo inicial (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 |
Estrutura de Composição
Sub-composições carregadas via data-composition-src usam um wrapper <template>. Composições independentes (o index.html principal) NÃO usam <template> — elas colocam o div data-composition-id diretamente em <body>. Usar <template> em um arquivo independente esconde todo o conteúdo do navegador e quebra a renderização.
Estrutura de sub-composição:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- conteúdo -->
<style>
[data-composition-id="my-comp"] {
/* estilos escopados */
}
</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 });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Carregar na raiz: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Vídeo e Áudio
O vídeo deve ter muted playsinline. O áudio é sempre um elemento <audio> separado:
<video
id="el-v"
data-start="0"
data-duration="30"
data-track-index="0"
src="video.mp4"
muted
playsinline
></video>
<audio
id="el-a"
data-start="0"
data-duration="30"
data-track-index="2"
src="video.mp4"
data-volume="1"
></audio>
Contrato da Timeline
- Todas as timelines começam
{ paused: true }— o player controla a reprodução - Registre cada timeline:
window.__timelines["<id-da-composição>"] = tl - O framework aninha automaticamente sub-timelines — NÃO as adicione manualmente
- A duração vem de
data-duration, não do comprimento da timeline GSAP - Nunca crie tweens vazios para definir a duração
Regras (Inegociáveis)
Determinístico: Sem Math.random(), Date.now() ou lógica baseada em tempo. Use um PRNG com semente se precisar de valores pseudo-aleatórios (ex.: mulberry32).
GSAP: Anime apenas propriedades visuais (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transforms). NÃO anime visibility, display ou chame video.play()/audio.play().
Conflitos de animação: Nunca anime a mesma propriedade no mesmo elemento de múltiplas timelines simultaneamente.
Sem repeat: -1: Timelines com repetição infinita quebram o mecanismo de captura. Calcule o número exato de repetições a partir da duração da composição: repeat: Math.ceil(duração / duraçãoDoCiclo) - 1.
Construção síncrona de timeline: Nunca construa timelines dentro de async/await, setTimeout ou Promises. O mecanismo de captura lê window.__timelines de forma síncrona após o carregamento da página. As fontes são embutidas pelo compilador, então estão disponíveis imediatamente — não é necessário esperar pelo carregamento de fontes.
Nunca faça:
- Esqueça o registro de
window.__timelines - Use vídeo para áudio — sempre vídeo mudo +
<audio>separado - Aninhe vídeo dentro de um div temporizado — use um wrapper não temporizado
- Use
data-layer(usedata-track-index) oudata-end(usedata-duration) - Anime as dimensões do elemento de vídeo — anime um wrapper div
- Chame play/pause/seek em mídia — o framework possui a reprodução
- Crie um contêiner de nível superior sem
data-composition-id - Use
repeat: -1em qualquer timeline ou tween — sempre repetições finitas - Construa timelines de forma assíncrona (dentro de
async,setTimeout,Promise) - Use
gsap.set()em elementos de clipe de cenas posteriores — eles não existem no DOM no carregamento da página. Usetl.set(selector, vars, timePosition)dentro da timeline no momentodata-startdo clipe ou depois. - Use
<br>em texto de conteúdo — quebras de linha forçadas não consideram a largura real da fonte renderizada. Texto que quebra naturalmente +<br>produz uma quebra extra indesejada, causando sobreposição. Deixe o texto quebrar viamax-width. Exceção: títulos curtos de exibição onde cada palavra está deliberadamente em sua própria linha (ex.: "O JOGO IMORTAL" a 130px).
Transições de Cena (Inegociáveis)
Toda composição com várias cenas DEVE seguir TODAS estas regras. Violar qualquer uma delas quebra a composição.
- Fechar íris do cartão de título:
clip-path: circle(0%)→clip-path: circle(100%)sobre uma tela de fundo. Duração: 1,5s. Easing:power3.out. Título e subtítulo aparecem na íris. - Abrir íris para cena: A cena começa com
clip-path: circle(0%)sobre o elemento de cena inteiro. Duração: 1,0s. Easing:power3.inOut. - Desvanecer para tela de fundo: O elemento de cena anterior sai com
opacity: 0para revelar uma tela contínua de fundo por 2-3 segundos. A próxima cena entra comopacity: 1sobre a mesma tela de fundo. - Transição de lâmina: Um elemento de lâmina (div de cor sólida) desliza na tela, cobrindo a cena antiga, revelando a nova.
x: 0%→x: 100%da esquerda para a direita.scaleY: 1.2para uma borda mais suave. O conteúdo da nova cena começa comclip-path: inset(0 0 0 0)e a lâmina abre. - Transição de piscada de olho: A cena escala para
scale: 1.1, opacity: 0com uma curvaease: power3.inOut. A nova cena escala descale: 0.9, opacity: 0para o estado normal. Ambas duram 0,5s. - Transição de varredura: Uma varredura (um gradiente linear estreito com largura igual a largura do clipe) varre da esquerda para a direita. Duração: 0,2s.
- Transição de revelação: Um elemento de varredura (máscara ou recorte) revela a próxima cena. Movendo-se da esquerda → direita, cima → baixo, diagonal ou de dentro (círculo, diamante). Duração: 1,0s. Easing:
power3.inOut. - Transição de cena shader: Uma
<div class="shader-overlay">transita usando um efeito de pixel, ruído, padrão de varredura ou deformação. A cena shader é uma faixa separada comdata-track-index: 999que cobre toda a saída. A transição shader é sempre uma composição independente. Aqui estão as transições shader disponíveis:
<template id="shader-alpha-template">
<div data-composition-id="shader-alpha">
<style>
[data-composition-id="shader-alpha"] {
position: absolute;
width: 100%;
height: 100%;
top: 0;
left: 0;
pointer-events: none;
z-index: 9999;
}
.shader-canvas {
width: 100%;
height: 100%;
display: block;
}
</style>
<canvas class="shader-canvas" id="c"></canvas>
<script>
const canvas = document.getElementById('c');
const gl = canvas.getContext('webgl');
if (!gl) { document.querySelector('[data-composition-id="shader-alpha"]').style.display = 'none'; }
else {
const vs = `
attribute vec2 a_position;
varying vec2 vUv;
void main() {
vUv = a_position * 0.5 + 0.5;
gl_Position = vec4(a_position, 0.0, 1.0);
}
`;
const fs = `
precision highp float;
varying vec2 vUv;
uniform float uProgress;
uniform vec2 uResolution;
void main() {
vec2 uv = vUv;
float d = distance(uv, vec2(0.5));
float r = 0.5;
float alpha = smoothstep(r, r - 0.2, d - uProgress * 1.2);
gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0 - alpha);
}
`;
const program = (() => {
const p = gl.createProgram();
const vsShader = gl.createShader(gl.VERTEX_SHADER);
gl.shaderSource(vsShader, vs);
gl.compileShader(vsShader);
const fsShader = gl.createShader(gl.FRAGMENT_SHADER);
gl.shaderSource(fsShader, fs);
gl.compileShader(fsShader);
gl.attachShader(p, vsShader);
gl.attachShader(p, fsShader);
gl.linkProgram(p);
return p;
})();
gl.useProgram(program);
const posBuf = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, posBuf);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1,-1, 1,-1, -1,1, 1,1]), gl.STATIC_DRAW);
const posLoc = gl.getAttribLocation(program, 'a_position');
gl.enableVertexAttribArray(posLoc);
gl.vertexAttribPointer(posLoc, 2, gl.FLOAT, false, 0, 0);
const uRes = gl.getUniformLocation(program, 'uResolution');
const uProg = gl.getUniformLocation(program, 'uProgress');
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.to({}, {
duration: 1,
onUpdate: function() {
const progress = this.progress();
gl.uniform2f(uRes, canvas.width, canvas.height);
gl.uniform1f(uProg, progress);
gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
}
}, 0);
window.__timelines['shader-alpha'] = tl;
}
</script>
</div>
</template>
Regras de transição shader:
- A composição shader executa na faixa
data-track-index: 999e cobre toda a saída. - O shader recebe
uProgressde 0 (início) a 1 (fim) e desenha diretamente em um canvas WebGL. - Coloque a composição shader sobre as cenas para que ela cubra a saída.
- Salve em um arquivo separado e carregue via
data-composition-src. - A duração da composição shader deve corresponder à duração da transição.
Regras combinadas de transição (para cada transição entre cenas):
- Escolha EXATAMENTE UM tipo de transição para cada transição e use SOMENTE esse tipo. Não combine múltiplos tipos de transição (íris + desvanecer + lâmina) na mesma transição de cena.
- A duração total da transição entre cenas deve ser de 0,5 a 1,5 segundos.
- O elemento de cena que está saindo deve ser um contêiner
<div>comdata-composition-id="scene-name". NÃO aplique transições ao elemento de composição raiz. - A transição DEVE ser implementada usando os elementos de cena, não afetando a composição.
- Para transições shader: O shader DEVE usar seu próprio canvas WebGL e timeline. NÃO modifique as cenas para transições shader.
- A transição das cenas DEVE usar a timeline da composição ou sua própria timeline para animação.
- Todas as transições entre cenas devem obedecer ao seguinte formato de temporização:
- Cena A termina em
tsegundos - Transição começa:
t - transiçãoDurationsegundos - Transição termina:
tsegundos - Cena B começa:
tsegundos - Cena A termina completamente a saída em
t - (transiçãoDuration / 2)segundos
- Cena A termina em
Overlays e Decorações
Sombras e Brilhos
text-shadow: 2px 2px 4px rgba(0,0,0,0.5);
box-shadow: 0 4px 20px rgba(0,0,0,0.3);
filter: drop-shadow(0 0 10px rgba(0,0,0,0.4));
Grades e Padrões
Sobreposições de grade (pontos, linhas, guias de terços) para textura de fundo. Use pseudo-elementos CSS, gradientes, background-image com dados SVG inline.
Elementos de moldura
Bordas, cantos, formas geométricas para enquadrar conteúdo.
Partículas e Efeitos de Fundo
Camadas de partículas, efeitos de partículas de fundo usando CSS, e se necessário canvas animado.
Legendas
As legendas são compostas por segmentos de áudio com texto e carimbos de data/hora:
[
{
"start": 0,
"end": 2.5,
"text": "Bem-vindo ao nosso produto."
},
{
"start": 3.0,
"end": 5.8,
"text": "Deixe-me mostrar como ele funciona."
}
]
Cada segmento de legenda VAI renderizar como um cartão de título estilizado — não como texto simples. Aplique estilos de cartão de título: fundo, padding, animação de entrada/saída, posicionamento.
LEGENDA NÃO É UMA SOBREPOSIÇÃO DE CINEMA. É UM CARTÃO DE TÍTULO ESTILIZADO. NÃO A FAÇA PARECER UMA LEGENDA DE FILME.
Estilos de legenda
As legendas usam uma combinação de:
- Fundo: retângulo sólido, vidro fosco, gradiente ou nenhum
- Posição: inferior, superior, centro
- Alinhamento: esquerda, centro, direita
- Animação de entrada/saída: deslizar, aparecer, escala
- Padding: 16-24px, bordas arredondadas
- Efeitos de texto: destaque, sublinhado, brilho
Configuração de estilo de legenda (exemplo para uma legenda):
{
"id": "cc-1",
"backgroundColor": "rgba(0,0,0,0.8)",
"textColor": "#ffffff",
"position": "bottom",
"align": "center",
"enter": { "y": 40, "opacity": 0, "duration": 0.3 },
"exit": { "y": -20, "opacity": 0, "duration": 0.2 },
"padding": "16px 24px",
"borderRadius": "8px"
}
Animações de Destaque de Texto
Destaque de marcador
Um sweep de marcador amarelo atrás do texto. Use um pseudo-elemento com background: linear-gradient animado de scaleX(0) para scaleX(1).
Círculo desenhado à mão
Um círculo SVG com stroke-dasharray e animação de stroke-dashoffset. O círculo aparece como se estivesse sendo desenhado ao redor do texto alvo.
Linhas de explosão
Linhas que irradiam de um ponto central. Use animações de escala e opacidade em múltiplos elementos de linha.
Rabisco
Um caminho SVG rabiscado que se desenrola. Use stroke-dasharray e stroke-dashoffset.
Esboço
Uma forma de esboço que aparece com tremor de linha. Combine múltiplos caminhos SVG com diferentes temporizações de offset.
Para qualquer uma dessas animações, coloque-as em uma camada separada (z-index) para que não interfiram com o layout do texto. A estrutura HTML deve ter o wrapper de destaque como um contêiner irmão do texto alvo.
Geração de Texto-para-Fala (TTS)
Use o comando de TTS para gerar narração a partir de texto:
hyperframes tts "texto para falar" --output narracao.mp3 --voice "pt-BR-Wavenet-A"
Os comandos CLI (init, lint, preview, render, transcribe, tts) são cobertos pela skill hyperframes-cli. Os parâmetros de voz e configuração são detalhados lá.
Comandos CLI de Áudio
Transcrever
hyperframes transcribe audio.mp3 --output transcricao.json
Isso gera um arquivo JSON com segmentos de texto com carimbo de data/hora.
TTS
hyperframes tts "texto" --output audio.mp3 --voice "pt-BR-Wavenet-A"
Guardrails (Inegociáveis)
Métricas e Estatísticas
- NUNCA invente métricas que não existem nos dados.
- Citações: NUNCA cite fontes ou dados que você não pode verificar. Se você não tem dados, não cite estatísticas.
- Números: NUNCA crie números que não são fornecidos nos dados de origem.
Apropriado para preenchimento
Não preencha espaços vazios com conteúdo inventado. Se faltar informação, peça ao usuário.
Precauções de tamanho de composição
- Use
data-widthedata-heightque correspondam ao formato de exibição alvo. Não use tamanhos arbitrários. - As dimensões da composição devem ser 1920x1080 (paisagem) ou 1080x1920 (retrato). Não use outros tamanhos.