HyperFrames
O HTML é a fonte da verdade para o vídeo. Uma composição é um arquivo HTML com
atributos data-* para temporização, uma linha do tempo 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 linha do tempo.
API de atributos, estrutura de composição/modelo, variáveis e regras de mídia: references/authoring.md. Leia antes de escrever sua primeira composição HTML em uma sessão.
Abordagem
Descoberta (apenas para solicitações exploratórias)
Para solicitações abertas ("faça um vídeo de lançamento de produto") onde o usuário não se comprometeu com uma direção, entenda a intenção antes de escolher cores: público, plataforma, prioridade (qualidade do movimento vs. precisão vs. velocidade) e se ele deseja variações. Se houver variações, ofereça 2-3 que difiram em ritmo ou estrutura - uma segura, uma ambiciosa - não apenas trocas de cores.
Para solicitações específicas ("adicione uma cartela de título", "corrija o tempo da cena 3"), pule a descoberta.
Etapa 1: Sistema de design
Se design.md ou DESIGN.md existir, leia primeiro (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. Se nomear fontes sem
arquivos .woff2 em fonts/ e sem correspondência integrada, avise o usuário antes
de escrever HTML.
Se não existir design.md, ofereça uma escolha:
- O usuário nomeou um estilo ou clima? Leia visual-styles.md (8 predefinições nomeadas), escolha a mais próxima.
- Navegar visualmente? Execute o seletor de design - references/design-picker.md.
- Ir rápido? Pergunte o clima, claro/escuro, cores/fontes da marca; escolha uma paleta de house-style.md.
design.md define a marca, não as regras de composição de vídeo. Essas vêm de references/video-composition.md e house-style.md. Cores da marca em escala de vídeo, não opacidade de interface web.
Etapa 2: Expansão do prompt
Execute em todas as composições, exceto em peças de cena única e edições triviais - funda a intenção contra design.md/house-style.md em um intermediário consistente. Processo e formato: references/prompt-expansion.md.
Etapa 3: Planejar
- O quê - arco narrativo, momentos-chave, batidas emocionais.
- Estrutura - quantas composições, subcomposições vs. inline, quais trilhas carregam o quê.
- Ritmo - declare o ritmo da cena antes de implementar (rápido-rápido-LENTO-rápido-SHADER-pausa). Modelos: references/beat-direction.md.
- Tempo - quais clipes determinam a duração, onde as transições aterrissam.
- Layout - construa o estado final primeiro (próxima seção).
- Animar - depois adicione movimento.
Construa o que foi solicitado. "Uma cartela de título" não é "uma cartela de título + 3 cenas de apoio + música + legendas." Proponha extras; não os adicione.
Para edições pequenas, vá direto para as regras.
Layout Antes da Animação
Posicione cada elemento onde ele deve estar em seu momento mais visível - completamente entrado, colocado corretamente, ainda não saindo. Escreva isso como HTML+CSS estático primeiro. Sem GSAP ainda.
Por quê: se você posicionar os elementos em seu estado inicial animado (fora da tela, opacidade 0) e animar em direção a onde você acha que eles pousam, você está adivinhando o layout final, e sobreposições permanecem invisíveis até a renderização. Construa o estado final primeiro e os bugs de layout são visíveis antes do movimento existir.
- Identifique o quadro herói por cena - o momento em que a maioria dos elementos está simultaneamente visível. Construa esse layout.
- Escreva CSS estático para ele.
.scene-contentDEVE preencher a cena:width: 100%; height: 100%; padding: Npx;comdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. O padding empurra o conteúdo para dentro - NUNCA useposition: absolute; top: Npxem um contêiner de conteúdo (ele transborda quando o conteúdo cresce). Reserve o posicionamento absoluto para elementos decorativos. - Entradas com
gsap.from()- anime DE fora da tela PARA a posição CSS. O CSS é a verdade fundamental; a animação é a jornada. (Subcomposições carregadas viadata-composition-src: prefiragsap.fromTo()- veja references/motion-principles.md.) - Apenas na cena final: saídas com
gsap.to(). Todas as outras cenas terminam totalmente visíveis - a transição É a saída (regra de transição 3 abaixo).
Se o elemento A sair antes do elemento B entrar na mesma área, dê a ambos as posições CSS corretas para seus próprios quadros heróis - a linha do tempo os impede de coexistir, e a etapa de layout captura a sobreposição acidental de erros de cronometragem. Sobreposição intencional (brilho atrás do texto, pilhas de cartões) é aceitável; a etapa existe para capturar sobreposição não intencional - dois títulos colidindo, uma estatística cobrindo um rótulo, conteúdo fora do quadro.
Contrato da Linha do Tempo
- Todas as linhas do tempo começam
{ paused: true }- o player controla a reprodução - Registre cada linha do tempo:
window.__timelines["<composition-id>"] = tl - O framework aninha automaticamente as sublinhas do tempo - NÃO as adicione manualmente
- A duração vem de
data-duration, não do comprimento da linha do tempo GSAP - Nunca crie animações vazias para definir a duração
Regras (Inegociáveis)
Determinístico: sem Math.random(), Date.now() ou lógica baseada em tempo.
PRNG com semente (ex.: mulberry32) para pseudoaleatório.
GSAP: anime apenas propriedades visuais (opacity, x, y, scale,
rotation, color, backgroundColor, borderRadius, transformações). Nunca
anime visibility ou display; nunca chame video.play()/audio.play().
Conflitos de animação: nunca anime a mesma propriedade no mesmo elemento de várias linhas do tempo simultaneamente.
Sem repeat: -1: repetições infinitas quebram o motor de captura. Calcule
repeat: Math.ceil(duration / cycleDuration) - 1.
Construção síncrona da linha do tempo: nunca construa linhas do tempo dentro de
async/await, setTimeout ou Promises - o motor de captura lê
window.__timelines de forma síncrona após o carregamento. As fontes são incorporadas pelo
compilador; sem espera por carregamento de fonte.
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 uma div com tempo - use um wrapper sem tempo
- Use
data-layer(usedata-track-index) oudata-end(usedata-duration) - Anime dimensões do elemento de vídeo - anime uma div wrapper
- Chame play/pause/seek na mídia - o framework controla a reprodução
- Crie um contêiner de nível superior sem
data-composition-id - Use
repeat: -1em qualquer linha do tempo ou animação - Construa linhas do tempo de forma assíncrona
- 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)em ou após odata-startdo clipe. - Use
<br>no texto do conteúdo - ele empilha com a quebra natural de linha e causa sobreposição; usemax-width. Exceção: títulos de exibição curtos deliberadamente uma palavra por linha.
Transições de Cena (Inegociáveis)
Toda composição com várias cenas DEVE seguir todas as quatro. Violar qualquer uma é uma composição quebrada.
- SEMPRE use transições entre cenas. Sem cortes secos.
- SEMPRE anime CADA elemento ENTRANDO via
gsap.from(). Nada aparece totalmente formado. Cinco elementos significam cinco animações de entrada. - NUNCA use animações de saída exceto na cena final. Sem
gsap.to()desbotando a opacidade, movendo para fora da tela ou escalando para 0 antes de uma transição - a transição É a saída, e a cena de saída deve estar totalmente visível quando ela disparar. Uma animação de saída antes de uma transição entrega uma transição com um quadro vazio. - Apenas na cena final pode desbotar elementos.
Seleção e implementação de transição: references/transitions.md.
Diretrizes de Animação
- Desloque a primeira animação em 0,1-0,3s (não t=0)
- Varie as atenuações - pelo menos 3 atenuações diferentes por cena, sem padrão de entrada repetido dentro de uma cena
- Evite gradientes lineares em tela cheia em fundos escuros (bandeamento H.264) - gradientes radiais ou sólidos + brilho localizado
- Títulos de 60px+, corpo de 20px+, rótulos de dados de 16px+
font-variant-numeric: tabular-numsem colunas de números
Editando Composições Existentes
- Leia os arquivos reais, não adivinhe. A composição É a especificação - extraia códigos hex, fontes e padrões de atenuação exatos da fonte, não da memória.
- Altere apenas o que foi solicitado; preserve o tempo dos clipes não relacionados.
Lista de Verificação de Saída
Rápido (execute imediatamente, bloqueie nos resultados):
-
npx hyperframes lintenpx hyperframes validatepassam - Aderência ao design verificada se design.md existir
Lento (execute em paralelo enquanto apresenta a pré-visualização):
-
npx hyperframes inspectpassa, ou cada estouro reportado está intencionalmente marcado - Avisos de contraste resolvidos
- Coreografia de animação verificada (script animation-map)
Como executar e corrigir cada verificação: references/quality-checks.md.
Índice de Referência
Sempre leia para qualquer nova composição:
| Arquivo | Abrange |
|---|---|
| references/authoring.md | Atributos data, estrutura de modelo, variáveis, vídeo/áudio, fontes/assets |
| references/video-composition.md | Regras de meio de vídeo - essas substituem instintos da web |
| references/typography.md | Pares de fontes, OpenType, ajustes de fundo escuro |
| references/motion-principles.md | Design de movimento, movimento de imagem, regras GSAP de suporte de carga |
Também leia sempre para composições com várias cenas:
| Arquivo | Abrange |
|---|---|
| references/beat-direction.md | Modelos de ritmo, verbos de coreografia, camadas de profundidade |
| references/transitions.md | Seleção de transição; catálogo roteia para implementações; transições de shader vivem no pacote npm @hyperframes/shader-transitions (leia sua fonte em node_modules) |
Leia quando a tarefa exigir:
| Arquivo | Leia quando |
|---|---|
| references/quality-checks.md | Executando verificações inspect/contrast/design/animation-map |
| references/cli.md | Qualquer comando CLI; solução de problemas de build/render |
| references/captions.md | Qualquer texto sincronizado com o tempo do áudio |
| references/transcript-guide.md | Manipulação de transcrição do lado da legenda (a invocação da CLI vive em media.md) |
| references/dynamic-techniques.md | Animação de legenda dinâmica (karaokê, slam, dispersão) |
| references/audio-reactive.md | Visuais respondendo à música/voz |
| references/css-patterns.md | Destaque de marcador (destaque, círculo, explosão, rabisco) |
| references/techniques.md | Técnicas de planejamento por batida (11 padrões com código) |
| references/narration.md | Narração/TTS: ritmo e estrutura do roteiro |
| references/media.md | TTS (Kokoro), transcrição (Whisper), remoção de fundo |
| references/prompt-expansion.md | Etapa 2 da abordagem |
| references/design-picker.md | Criando um design.md visualmente |
| references/from-website.md | Transformando um site em um vídeo |
| references/registry.md | Instalando/contribuindo blocos de registro (hyperframes add) |
| visual-styles.md | Usuário nomeia um estilo; gerando design.md |
| house-style.md | Padrões estéticos quando não há design.md |
| patterns.md | PiP, cartelas de título, apresentações de slides |
| data-in-motion.md | Dados, estatísticas, infográficos |
Adaptadores de runtime (leia quando a composição usa esse runtime em vez de GSAP): waapi, lottie, three, animejs, css-animations, typegpu.