HyperFrames
O HTML é a fonte da verdade para o vídeo. Uma composição é um arquivo HTML com atributos data-* para timing, 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 narração e legendas, tours de produtos, sobreposições sociais, transições com shaders e qualquer coisa orientada por mídia de vídeo/áudio real.
Quando Usar
- O usuário pede um vídeo renderizado a partir de texto, um script ou um site
- Cards de título animados, barras inferiores de informação ou intros tipográficas
- Vídeo de narração legendada (TTS + legendas sincronizadas com a forma de onda)
- Visuais reativos a áudio (sincronia de batida, barras de espectro, brilho pulsante)
- Transições de cena para cena (crossfade, wipe, warp de shader, flash-through-white)
- Sobreposições 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 para um arquivo de vídeo
Não use esta 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 da pré-visualização/renderização
npx hyperframes preview # pré-visualização ao vivo no navegador (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 (uma vez)
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 (exibe instruções de correção se não estiverem).
- Instala a CLI
hyperframesglobalmente (npm install -g hyperframes@>=0.4.2). - Pré-armazena em cache
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ácter de movimento (explosivo / cinematográfico / fluido / técnico)
- Quadro herói — para cada cena, o momento em que a maioria dos elementos está simultaneamente visível. 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 sinais de que esta etapa foi pulada). Verifique nesta ordem:
-
DESIGN.mdna raiz do projeto? → Use suas cores exatas, fontes, regras de movimento e restrições de "O que NÃO Fazer". -
O usuário nomeou um estilo (ex.: "Swiss Pulse", "dark and techy", "marca de luxo")? → Gere um
DESIGN.mdmínimo com## Style Prompt,## Colors(3-5 hexadecimais com funções),## Typography(1-2 famílias),## What NOT to Do(3-5 anti-padrões). -
Nenhum dos acima? → Faça 3 perguntas antes de escrever qualquer HTML:
- Humor? (explosivo / cinematográfico / fluido / técnico / caótico / caloroso)
- Tela clara ou escura?
- Alguma cor de marca, fonte ou referência visual?
Em seguida, gere um
DESIGN.mda partir das respostas. Cada composição deve rastrear 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 herói 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 use 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 herói 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. Animar com GSAP
Cada composição deve:
- Registrar sua timeline:
window.__timelines["<composition-id>"] = tl - Iniciar pausada:
gsap.timeline({ paused: true })— o player controla a reprodução - Usar valores
repeatfinitos (semrepeat: -1— quebra o motor de captura). Calcular:repeat: Math.ceil(duracao / duracaoCiclo) - 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 pseudo-aleatoriedade. - Construir de forma síncrona — sem
async/await,setTimeoutou Promises em torno da construção da timeline.
Veja references/gsap.md para a API central GSAP (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-transicao> para instalar transições com shader (flash-through-white, liquid-wipe, etc.). Lista completa: npx hyperframes add --list.
6. Áudio, legendas, TTS, áudio-reativo, destaque
- Áudio: sempre um elemento
<audio>separado (o vídeo émuted playsinline). - TTS:
npx hyperframes tts "Texto do script" --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 a nível de 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.endo whisper a menos que o áudio seja confirmado como inglês —.entraduz áudio não inglês em vez de transcrevê-lo. Cada grupo de legenda DEVE ter umtl.set(el, { opacity: 0, visibility: "hidden" }, group.end)rígido como morte após seu tween de saída — caso contrário, os grupos vazam visíveis para os posteriores. - Visuais reativos a áudio: pré-extraia faixas de áudio (graves / médios / agudos) 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 graves →scale(pulso), agudos →textShadow/boxShadow(brilho), amplitude geral →opacity/y/backgroundColor. Evite clichês de equalizador — deixe o conteúdo guiar o visual, o áudio guiar seu comportamento. - Destaque estilo marcador: efeitos de destaque, círculo, explosão, rabisco, contorno 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: cada composição com várias cenas DEVE usar transições (sem cortes secos). Escolha entre primitivas CSS (push slide, blur crossfade, zoom through, blocks escalonados) ou transições com shader (
flash-through-white,liquid-wipe,cross-warp-morph,chromatic-split, etc.) vianpx hyperframes add. Tabelas de humor 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 # captura 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 rascunho.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 avisa sobre taxas de contraste abaixo de 4.5:1 (ou 3:1 para texto grande). hyperframes inspect é o companheiro de layout — executa a página em vários timestamps e sinaliza problemas que um lint estático não pode ver (uma legenda que passa da área segura apenas em 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 recai para o modo de captura de tela). Escape hatch: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 então 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 de repetição finita.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 sabem a largura da fonte renderizada, então a quebra natural +<br>causam 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 destes. UseautoAlpha(lida com visibilidade e opacidade). - Chamar
video.play()ouaudio.play()— o framework possui a reprodução. Nunca chame isso você mesmo. - Construindo timelines de forma assíncrona — 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.htmlindependente envolto em<template>— esconde todo o conteúdo do navegador. Apenas sub-composiçõ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 + validar + inspecionar passam:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(lint captura problemas estruturais, validar captura contraste, inspecionar captura layout visual / overflow — veja troubleshooting.md se avisos aparecerem). - Coreografia de animação — para novas composições ou mudanças significativas de animação, execute o mapa de animação.
npx hyperframes initcopia os scripts de skill para o projeto, então o caminho é local ao projeto:
Gera um úniconode skills/hyperframes/scripts/animation-map.mjs <diretorio-da-composicao> \ --out <diretorio-da-composicao>/.hyperframes/anim-mapanimation-map.jsoncom resumos por tween, timeline Gantt ASCII, 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). Digitalize resumos e flags — corrija ou justifique cada um. Pule em pequenas edições. - Arquivo existe + não vazio:
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 de timeline, regras inegociáveis, regras de tipografia/assets
- 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, áudio-reativo, destaque de 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 OpenClaw, variáveis de ambiente, erros comuns de renderização