HyperFrames
O HTML é a fonte da verdade para o 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 motor HyperFrames captura a página quadro a quadro e codifica para MP4/WebM com FFmpeg.
Complemento ao manim-video: Use manim-video para explicadores matemáticos/geométricos (equações, estilo 3B1B). Use hyperframes para motion graphics, vídeos com narrador e legendas, tours de produto, sobreposições para redes sociais, transições com shaders e qualquer coisa orientada por mídia de vídeo/áudio real.
Quando Usar
- O usuário solicita um vídeo renderizado a partir de texto, um roteiro ou um site
- Cartões de título animados, terços inferiores ou introduções tipográficas
- Vídeo com narração legendada (TTS + legendas sincronizadas com a forma de onda)
- Visuais reativos a áudio (sincronia com batida, barras de espectro, brilho pulsante)
- Transições entre cenas (crossfade, wipe, shader warp, flash-through-white)
- Sobreposições para redes sociais (estilo Instagram/TikTok/YouTube)
- Pipeline de site para vídeo (capturar uma URL, produzir um promo)
- Qualquer animação HTML/CSS/JS que deva ser renderizada deterministicamente em um arquivo de vídeo
Não use este skill para:
- Animação pura de matemática/equações (→
manim-video) - Geração de imagens ou memes (→
meme-generation, modelos de imagem) - Videoconferência ou streaming ao vivo
Referência Rápida
npx hyperframes init meu-video # criar um projeto
cd meu-video
npx hyperframes lint # validar antes de pré-visualizar/renderizar
npx hyperframes preview # pré-visualização no navegador com live reload (porta 3002)
npx hyperframes render --output final.mp4 # renderizar para MP4
npx hyperframes doctor # diagnosticar problemas de ambiente
Flags de renderização: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproduzível) · --strict.
Referência completa da CLI: references/cli.md.
Configuração (única)
bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
O script:
- Verifica se Node.js >= 22 e FFmpeg estão instalados (imprime instruções de correção se não).
- Instala a CLI
hyperframesglobalmente (npm install -g hyperframes@>=0.4.2). - Pré-armazena em cache o
chrome-headless-shellvia Puppeteer — necessário para renderização de melhor qualidade através do caminho de capturaHeadlessExperimental.beginFramedo Chrome. - Executa
npx hyperframes doctore relata o resultado.
Veja references/troubleshooting.md se a configuração falhar.
Procedimento
1. Planejar antes de escrever HTML
Antes de tocar no código, articule em alto nível:
- O quê — arco narrativo, momentos-chave, batidas emocionais
- Estrutura — composições, trilhas (vídeo/áudio/sobreposições), durações
- Identidade visual — cores, fontes, caráter do movimento (explosivo / cinematográfico / fluido / técnico)
- Quadro hero — para cada cena, o momento em que o maior número de elementos está visível simultaneamente. Este é o layout estático que você construirá primeiro.
Portão de Identidade Visual (HARD-GATE). Antes de escrever QUALQUER HTML de composição, uma identidade visual deve ser definida. NÃO escreva composições com cores padrão ou genéricas (#333, #3b82f6, Roboto são indícios de que esta etapa foi pulada). Verifique em ordem:
-
DESIGN.mdna raiz do projeto? → Use suas cores exatas, fontes, regras de movimento e restrições "O que NÃO Fazer". -
Usuário nomeou um estilo (ex.: "Pulso Suíço", "sombrio e tecnológico", "marca de luxo")? → Gere um
DESIGN.mdmínimo com## Style Prompt,## Colors(3-5 hex com funções),## Typography(1-2 famílias),## What NOT to Do(3-5 antipadrões). -
Nenhum dos acima? → Faça 3 perguntas antes de escrever qualquer HTML:
- Clima? (explosivo / cinematográfico / fluido / técnico / caótico / acolhedor)
- Fundo claro ou escuro?
- Alguma cor de marca, fonte ou referência visual?
Em seguida, gere um
DESIGN.mda partir das respostas. Toda composição deve traçar sua paleta e tipografia de volta aoDESIGN.mdou à direção explícita do usuário.
2. Scaffold
npx hyperframes init meu-video --non-interactive
Modelos: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Passe --example <nome> para escolher um, --video clip.mp4 ou --audio track.mp3 para semear com mídia.
3. Layout antes da animação
Escreva o HTML+CSS estático para o quadro hero primeiro — sem GSAP ainda. O contêiner .scene-content deve preencher a cena (width:100%; height:100%; padding:Npx) com display:flex + gap. Use padding para empurrar o conteúdo para dentro — nunca position: absolute; top: Npx em um contêiner de conteúdo (o conteúdo transborda quando é mais alto que o espaço restante).
Somente depois que o quadro hero parecer correto, adicione entradas gsap.from() (anime para a posição CSS) e saídas gsap.to() (anime a partir dela).
Veja references/composition.md para o esquema completo de atributos data e regras de composição.
4. Anime com GSAP
Toda composição deve:
- Registrar sua timeline:
window.__timelines["<id-da-composição>"] = tl - Iniciar pausada:
gsap.timeline({ paused: true })— o jogador controla a reprodução - Usar valores de
repeatfinitos (semrepeat: -1— quebra o motor de captura). Calcular:repeat: Math.ceil(duration / cycleDuration) - 1. - Ser determinística — sem
Math.random(),Date.now()ou lógica de relógio de parede. Use um PRNG com semente se precisar de pseudoaleatoriedade. - Construir sincronamente — sem
async/await,setTimeoutou Promises em torno da construção da timeline.
Veja references/gsap.md para a API GSAP central (tweens, eases, stagger, timelines).
5. Transições entre cenas
Composições com várias cenas exigem transições. Regras:
- Sempre use uma transição entre cenas — sem cortes secos.
- Sempre use animações de entrada em cada elemento da cena (
gsap.from(...)). - Nunca use animações de saída exceto na cena final — a transição É a saída.
- A cena final pode desaparecer (fade out).
Use npx hyperframes add <nome-da-transição> para instalar transições com shaders (flash-through-white, liquid-wipe, etc.). Lista completa: npx hyperframes add --list.
6. Áudio, legendas, TTS, visuais reativos a áudio, destaque
- Áudio: sempre um elemento
<audio>separado (o vídeo émuted playsinline). - TTS:
npx hyperframes tts "Texto do roteiro" --voice af_nova --output narracao.wav. Liste vozes com--list. A primeira letra do ID da voz codifica o idioma (a/b=Inglês,e=Espanhol,f=Francês,j=Japonês,z=Mandarim, etc.) — a CLI infere automaticamente a localidade do fonemizador; passe--langapenas para substituir. A fonemização em idiomas não ingleses requerespeak-nginstalado no sistema. - Legendas:
npx hyperframes transcribe narracao.wav→ transcrição no nível da palavra. Escolha o estilo a partir do tom da transcrição (hype / corporativo / tutorial / narrativa / social — veja a tabela emreferences/features.md). Regra de idioma: nunca use modelos whisper.ena menos que o áudio seja confirmadamente inglês —.entraduz áudio não inglês em vez de transcrevê-lo. Cada grupo de legendas DEVE ter um kill duro comtl.set(el, { opacity: 0, visibility: "hidden" }, group.end)após seu tween de saída — caso contrário, grupos vazam para os posteriores. - Visuais reativos a áudio: extraia previamente as bandas de áudio (grave / médio / agudo) e amostre por quadro dentro da timeline com um loop
fordetl.call(draw, [], f / fps)— um único tween longo NÃO reage ao áudio. Mapeie grave →scale(pulso), agudo →textShadow/boxShadow(brilho), amplitude geral →opacity/y/backgroundColor. Evite clichês de equalizador — deixe o conteúdo guiar o visual, o áudio impulsionar seu comportamento. - Destaques estilo marcador: efeitos de destaque, círculo, explosão, rabisco, esboço para ênfase de texto são CSS+GSAP determinísticos — veja
references/features.md#marker-highlighting. Totalmente buscáveis, sem filtros SVG animados. - Transições de cena: toda composição com várias cenas DEVE usar transições (sem cortes secos). Escolha entre primitivas CSS (push slide, blur crossfade, zoom through, staggered blocks) ou transições com shaders (
flash-through-white,liquid-wipe,cross-warp-morph,chromatic-split, etc.) vianpx hyperframes add. Tabelas de clima e energia estão emreferences/features.md#transitions. Não misture transições CSS e shader na mesma composição.
7. Lint, validar, inspecionar, pré-visualizar, renderizar
npx hyperframes lint # detecta data-composition-id ausente, trilhas sobrepostas, timelines não registradas
npx hyperframes validate # auditoria de contraste WCAG em 5 timestamps
npx hyperframes inspect # auditoria de layout visual — overflow, elementos fora do quadro, texto ocluído
npx hyperframes preview # pré-visualização ao vivo no navegador
npx hyperframes render --quality draft --output draft.mp4 # iteração rápida
npx hyperframes render --quality high --output final.mp4 # entrega final
hyperframes validate amostra pixels de fundo atrás de cada elemento de texto e alerta sobre taxas de contraste abaixo de 4.5:1 (ou 3:1 para texto grande). hyperframes inspect é o complemento de layout — executa a página em múltiplos timestamps e sinaliza problemas que um lint estático não pode ver (uma legenda que ultrapassa a área segura apenas aos 4.5s, um cartão que transborda quando seu título é a variante mais longa, um elemento que acaba atrás de um shader de transição). Execute inspect especialmente em composições com balões de fala, cartões, legendas ou tipografia apertada.
8. Site para vídeo (se o usuário fornecer uma URL)
Use o fluxo de trabalho de 7 etapas de captura para vídeo em references/website-to-video.md: capturar → DESIGN.md → SCRIPT.md → storyboard → composição → renderizar → entregar.
Armadilhas
HeadlessExperimental.beginFrame' wasn't found— Chromium 147+ removeu este protocolo. Certifique-se de estar nohyperframes@>=0.4.2(detecta automaticamente e volta para o modo de captura de tela). Válvula de escape:export PRODUCER_FORCE_SCREENSHOT=true. Veja hyperframes#294 e references/troubleshooting.md.- Chrome do sistema (não
chrome-headless-shell) — as renderizações travam por 120s e depois expiram. Executenpx puppeteer browsers install chrome-headless-shell(setup.sh faz isso).hyperframes doctorrelata qual binário será usado. repeat: -1em qualquer lugar — quebra o motor de captura. Sempre calcule uma contagem finita de repetições.gsap.set()em elementos de clipe que entram mais tarde — o elemento não existe no carregamento da página. Usetl.set(selector, vars, timePosition)dentro da timeline, no ou após odata-startdo clipe.<br>dentro de texto de conteúdo — quebras forçadas não conhecem a largura da fonte renderizada, então a quebra natural +<br>causa quebra dupla. Usemax-widthpara deixar o texto quebrar. Exceção: títulos de exibição curtos onde cada palavra está deliberadamente em sua própria linha.- Animando
visibilityoudisplay— GSAP não pode fazer tween desses. UseautoAlpha(lida com visibilidade e opacidade). - Chamando
video.play()ouaudio.play()— o framework controla a reprodução. Nunca chame esses métodos você mesmo. - Construindo timelines assincronamente — o motor de captura lê
window.__timelinessincronamente após o carregamento da página. Nunca envolva a construção da timeline emasync,setTimeoutou uma Promise. index.htmlautônomo envolvido em<template>— esconde todo o conteúdo do navegador. Apenas subcomposições carregadas viadata-composition-srcusam<template>.- Usando vídeo para áudio — sempre
<video>mudo +<audio>separado.
Verificação
Antes e depois da renderização:
- Lint + validate + inspect passam:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(lint detecta problemas estruturais, validate detecta contraste, inspect detecta layout visual / overflow — veja troubleshooting.md se avisos aparecerem). - Coreografia da animação — para novas composições ou mudanças significativas de animação, execute o mapa de animação.
npx hyperframes initcopia os scripts do skill para o projeto, então o caminho é local ao projeto:
Gera um úniconode skills/hyperframes/scripts/animation-map.mjs <diretoria-da-composição> \ --out <diretoria-da-composição>/.hyperframes/anim-mapanimation-map.jsoncom resumos por tween, linha do tempo ASCII Gantt, detecção de stagger, zonas mortas (>1s sem animação), ciclos de vida de elementos e flags (offscreen,collision,invisible,paced-fast<0.2s,paced-slow>2s). Examine resumos e flags — corrija ou justifique cada um. Pule em pequenas edições. - Arquivo existe + não zero:
ls -lh final.mp4. - Duração corresponde a
data-duration:ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4. - Verificação visual: extraia um quadro do meio da composição:
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png. - Áudio presente se esperado:
ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.
Se hyperframes render falhar, execute npx hyperframes doctor e anexe sua saída ao relatar.
Referências
- composition.md — atributos data, contrato da timeline, regras inegociáveis, regras de tipografia/ativos
- cli.md — todos os comandos CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
- gsap.md — API central GSAP para HyperFrames (tweens, eases, stagger, timelines, matchMedia)
- features.md — legendas, TTS, reativo a áudio, destaque marcador, transições (carregar sob demanda)
- website-to-video.md — fluxo de trabalho de 7 etapas de captura para vídeo
- troubleshooting.md — correção do OpenClaw, variáveis de ambiente, erros comuns de renderização