ZardLi1115/zedclaw

HyperFrames

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 para manim-video: Use manim-video para explanadores matemáticos/geométricos (equações, estilo 3B1B). Use hyperframes para motion graphics, vídeos com narração e legendas, tours de produto, sobreposições sociais, transições com shaders e qualquer coisa impulsionada 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
• Cartões de título animados, terços inferiores ou introduções 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 entre cenas (crossfade, wipe, warp de shader, flash através de branco)
• 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 em 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 estrutura de um projeto
cd meu-video
npx hyperframes lint                          # validar antes de pré-visualizar/renderizar
npx hyperframes preview                       # pré-visualização 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 ~/.zedclaw/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

O script:

1. Verifica se Node.js >= 22 e FFmpeg estão instalados (exibe instruções de correção se não estiverem).
2. Instala a CLI hyperframes globalmente (npm install -g hyperframes@>=0.4.2).
3. Pré-armazena em cache o chrome-headless-shell via Puppeteer — necessário para renderização da melhor qualidade através do caminho de captura HeadlessExperimental.beginFrame do Chrome.
4. Executa npx hyperframes doctor e relata o resultado.

Consulte references/troubleshooting.md se a configuração falhar.

Procedimento

1. Planeje 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 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 indícios de que esta etapa foi pulada). Verifique na ordem:

1. DESIGN.md na raiz do projeto? → Use suas cores, fontes, regras de movimento e restrições "O que NÃO Fazer".

2. O usuário nomeou um estilo (ex.: "Pulso Suíço", "dark e técnico", "marca de luxo")? → Gere um DESIGN.md mínimo com ## Style Prompt, ## Cores (3-5 hex com funções), ## Tipografia (1-2 famílias), ## O que NÃO Fazer (3-5 antipadrões).

3. Nada disso? → Faça 3 perguntas antes de escrever qualquer HTML:

   • Clima? (explosivo / cinematográfico / fluido / técnico / caótico / acolhedor)
   • Tela clara ou escura?
   • Alguma cor de marca, fonte ou referência visual?

   Em seguida, gere um DESIGN.md a partir das respostas. Toda composição deve traçar sua paleta e tipografia de volta ao DESIGN.md ou à direção explícita do usuário.

2. Criar Estrutura

npx hyperframes init meu-video --non-interactive

Modelos: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Use --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 container .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 container 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).

Consulte references/composition.md para o esquema completo de atributos de dados 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 player controla a reprodução
• Usar valores finitos de repeat (sem repeat: -1 — quebra o motor de captura). Calcule: repeat: Math.ceil(duração / duraçãoDoCiclo) - 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 sincronamente — sem async/await, setTimeout ou Promises em torno da construção da timeline.

Consulte 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:

1. Sempre use uma transição entre cenas — sem cortes secos.
2. Sempre use animações de entrada em cada elemento da cena (gsap.from(...)).
3. Nunca use animações de saída exceto na cena final — a transição É a saída.
4. 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, reatividade a áudio, destaque

• Áudio: sempre um elemento <audio> separado (o vídeo é muted playsinline).
• TTS: npx hyperframes tts "Texto do script" --voice af_nova --output narração.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; use --lang apenas para sobrescrever. A fonemização não-inglesa requer espeak-ng instalado no sistema.
• Legendas: npx hyperframes transcribe narração.wav → transcrição nível de palavra. Escolha o estilo a partir do tom da transcrição (hype / corporativo / tutorial / narrativa / social — veja a tabela em references/features.md). Regra de idioma: nunca use modelos whisper .en a menos que o áudio seja confirmado como inglês — .en traduz áudio não-inglês em vez de transcrevê-lo. Todo grupo de legenda DEVE ter um tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) duro após seu tween de saída — caso contrário, grupos vazam visíveis para os posteriores.
• Visuais reativos a áudio: extraia previamente as bandas de áudio (graves / médios / agudos) e amostre por quadro dentro da timeline com um loop for de tl.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 impulsionar seu comportamento.
• Destaque em 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ável, 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.) via npx hyperframes add. Tabelas de clima e energia estão em references/features.md#transitions. Não misture transições CSS e de shader na mesma composição.

7. Lint, validar, inspecionar, pré-visualizar, renderizar

npx hyperframes lint              # detecta falta de data-composition-id, trilhas sobrepostas, timelines não registradas
npx hyperframes validate          # auditoria de contraste WCAG em 5 timestamps
npx hyperframes inspect           # auditoria visual de layout — 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 companheiro do lado do 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 em 4.5s, um cartão que transborda quando seu título é a variante mais longa, um elemento que termina 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 não foi encontrado — Chromium 147+ removeu este protocolo. Certifique-se de estar no hyperframes@>=0.4.2 (detecta automaticamente e recai para o modo de screenshot). Chave 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 então expiram. Execute npx puppeteer browsers install chrome-headless-shell (o setup.sh faz isso). hyperframes doctor relata qual binário será usado.
• repeat: -1 em qualquer lugar — quebra o motor de captura. Sempre calcule uma contagem de repetição finita.
• gsap.set() em elementos de clipe que entram depois — o elemento não existe no carregamento da página. Use tl.set(seletor, vars, timePosition) dentro da timeline, no ou após o data-start do clipe.
• <br> dentro do texto de conteúdo — quebras forçadas não conhecem a largura da fonte renderizada, então quebra natural + <br> causa quebras duplas. Use max-width para deixar o texto quebrar naturalmente. Exceção: títulos curtos onde cada palavra está deliberadamente em sua própria linha.
• Animando visibility ou display — GSAP não pode animar estas. Use autoAlpha (lida com visibilidade e opacidade).
• Chamando video.play() ou audio.play() — o framework controla a reprodução. Nunca chame estes você mesmo.
• Construindo timelines assincronamente — o motor de captura lê window.__timelines sincronamente após o carregamento da página. Nunca envolva a construção da timeline em async, setTimeout ou uma Promise.
• index.html independente envolvido em <template> — esconde todo o conteúdo do navegador. Apenas sub-composições carregadas via data-composition-src usam <template>.
• Usando vídeo para áudio — sempre <video> silenciado + <audio> separado.

Verificação

Antes e depois da renderização:

1. Lint + validar + inspecionar passam: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint detecta problemas estruturais, valida detecta contraste, inspeciona detecta problemas de layout visual / overflow — veja troubleshooting.md se avisos aparecerem).
2. Coreografia da animação — para novas composições ou alterações significativas de animação, execute o mapa de animação. npx hyperframes init copia os scripts da skill para o projeto, então o caminho é local ao projeto:

   node skills/hyperframes/scripts/animation-map.mjs <diretório-da-composição> \
     --out <diretório-da-composição>/.hyperframes/anim-map
   

   Gera um único animation-map.json com 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). Escaneie resumos e flags — corrija ou justifique cada um. Pule em edições pequenas.
3. Arquivo existe + não-zero: ls -lh final.mp4.
4. Duração corresponde a data-duration: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
5. Verificação visual: extraia um quadro do meio da composição: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
6. Á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 de dados, contrato de 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, reatividade 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