Communitygithub.com

nastechresearch/nastech-agent

Renderize vídeos MP4/WebM a partir de composições HTML.

O que é nastech-agent?

Esta skill permite criar vídeos MP4/WebM renderizando composições HTML com animações GSAP e atributos `data-*` de temporização. Ela captura a página quadro a quadro usando o Chrome headless e codifica o resultado com FFmpeg, suportando desde gráficos animados até narrações com legendas e tours de produto. Funciona como complemento ao `manim-video`, focado em conteúdo matemático/geométrico. É compatível com plataformas como Claude Code, Cursor e Codex, oferecendo um fluxo completo: scaffolding com `npx hyperframes init`, validação com `lint`/`validate`/`inspect`, preview ao vivo e renderização final com flags de qualidade, FPS e formato. A skill impõe boas práticas como definição de identidade visual via `DESIGN.md`, uso de transições entre cenas, animações determinísticas sem `Math.random()`, e limpeza do servidor de preview para evitar consumo excessivo de CPU em ambientes sem GPU.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nastechresearch/nastech-agent/tree/HEAD/optional-skills/creative/hyperframes

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

HyperFrames

O HTML é a fonte 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 mecanismo HyperFrames captura a página quadro a quadro e codifica para MP4/WebM com FFmpeg.

Complemento ao manim-video: Use manim-video para vídeos explicativos matemáticos/geométricos (equações, estilo 3B1B). Use hyperframes para gráficos animados, cabeça falante com legendas, tours de produto, sobreposições sociais, transições com shader e qualquer coisa impulsionada por mídia de vídeo/áudio real.

Quando Usar

  • Usuário pede um vídeo renderizado a partir de texto, roteiro ou site
  • Cartões de título animados, barras inferiores ou introduções tipográficas
  • Vídeo de narração legendada (TTS + legendas sincronizadas com a forma de onda)
  • Visuais reativos a áudio (batida sincronizada, barras de espectro, brilho pulsante)
  • Transições cena a cena (crossfade, wipe, warp com 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 precise 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 my-video               # criar um projeto
cd my-video
npx hyperframes lint                        # validar antes do preview/render
npx hyperframes preview                     # preview com live-reload (servidor de longa duração, porta 3002)
npx hyperframes render --output final.mp4   # renderizar para MP4
npx hyperframes doctor                      # diagnosticar problemas de ambiente

preview é um servidor Next.js de longa duração que mantém workers do Chrome abertos. Sempre pare-o quando terminar (veja Limpeza) — um preview esquecido mantém workers chrome-headless-shell ociosos que, em hosts sem GPU (WSL, contêineres, CI), consomem um núcleo de CPU cada indefinidamente via WebGL por software (swiftshader).

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 ~/.nastech/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 (imprime instruções de correção se não).
  2. Instala a CLI hyperframes globalmente (npm install -g hyperframes@>=0.4.2).
  3. Pré-armazena em cache chrome-headless-shell via Puppeteer — necessário para renderização de melhor qualidade através do caminho de captura HeadlessExperimental.beginFrame do Chrome.
  4. Executa npx hyperframes doctor e 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 de movimento (explosivo / cinematográfico / fluido / técnico)
  • Quadro herói — para cada cena, o momento em que o maior número de 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:

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

  2. Usuário nomeou um estilo (ex.: "Swiss Pulse", "dark and techy", "luxury brand")? → Gere um DESIGN.md mínimo com ## Style Prompt, ## Colors (3-5 hex com funções), ## Typography (1-2 famílias), ## What NOT to Do (3-5 anti-padrões).

  3. Nada do acima? → 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. Scaffold

npx hyperframes init my-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 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 estiver 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

Toda composição DEVE:

  • Registrar sua timeline: window.__timelines["<composition-id>"] = tl
  • Começar pausada: gsap.timeline({ paused: true }) — o player controla a reprodução
  • Usar valores finitos de repeat (sem repeat: -1 — quebra o mecanismo de captura). Calcule: repeat: Math.ceil(duracao / cicloDuracao) - 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, setTimeout ou Promises em torno da construção da timeline.

Veja references/gsap.md para a API central do GSAP (tweens, eases, stagger, timelines).

5. Transições entre cenas

Composições com múltiplas 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-transicao> para instalar transições com shader (flash-through-white, liquid-wipe, etc.). Lista completa: npx hyperframes add --list.

6. Áudio, legendas, TTS, reativo a áudio, destaque

  • Áudio: sempre um elemento <audio> separado (vídeo é muted playsinline).
  • TTS: npx hyperframes tts "Texto do roteiro" --voice af_nova --output narration.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 --lang apenas para substituir. A fonemização em outros idiomas requer espeak-ng instalado no sistema.
  • Legendas: npx hyperframes transcribe narration.wav → transcrição a nível de palavra. Escolha o estilo a partir do tom da transcrição (hype / corporativo / tutorial / storytelling / social — veja a tabela em references/features.md). Regra de idioma: nunca use modelos .en do whisper a menos que o áudio seja confirmadamente em inglês — .en traduz áudio não-inglês em vez de transcrevê-lo. Cada grupo de legenda DEVE ter um tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) duro de eliminação após seu tween de saída — caso contrário, grupos vazam visíveis para os posteriores.
  • Visuais reativos a áudio: pré-extraia bandas de áudio (grave / médio / agudo) 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 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.
  • 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ável, sem filtros SVG animados.
  • Transições de cena: toda composição com múltiplas cenas DEVE usar transições (sem cortes secos). Escolha entre primitivas CSS (push slide, blur crossfade, zoom through, staggered blocks) ou transições com shader (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 shader na mesma composição.

7. Lint, validate, inspect, preview, render

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 visual de layout — overflow, elementos fora do quadro, texto oculto
npx hyperframes preview           # preview 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 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 múltiplos timestamps e sinaliza problemas que um lint estático não pode ver (uma legenda que passa da á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 captura para vídeo em 7 etapas em references/website-to-video.md: capturar → DESIGN.md → SCRIPT.md → storyboard → composição → render → entregar.

Limpeza

render é único (os workers saem quando termina). preview não é — ele executa um servidor Next.js em segundo plano que mantém workers do Chrome residentes até você pará-lo. Nunca deixe um em execução: em hosts sem GPU, cada processo swiftshader de worker ocioso consome um núcleo de CPU, e um preview deixado aberto por dias acumula vários.

Pare um preview quando o usuário terminar de revisar (ou antes de iniciar um novo):

pkill -f "hyperframes.*preview"     # o servidor Studio (libera a porta 3002)
pkill -f chrome-headless-shell      # seus workers de render; seguro apenas se mais nada os usar

Se não tiver certeza se outras ferramentas usam chrome-headless-shell, verifique primeiro: pgrep -af chrome-headless-shell. Recupere um host travado (vários workers ociosos consumindo CPU) da mesma forma — veja references/troubleshooting.md.

Armadilhas

  • Deixar preview em execução — é um servidor de longa duração que mantém workers do Chrome; no WSL/contêineres/CI esses workers ociosos consomem um núcleo de CPU cada (WebGL por software). Pare-o quando terminar — veja Limpeza.

  • HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ removeu este protocolo. Certifique-se de estar no hyperframes@>=0.4.2 (detecta automaticamente e recai 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. 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 mecanismo de captura. Sempre calcule uma contagem de repetições finita.

  • gsap.set() em elementos de clipe que entram mais tarde — o elemento não existe no carregamento da página. Use tl.set(selector, vars, timePosition) dentro da timeline em vez disso, no momento ou após o data-start do 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> quebra duplamente. Use max-width para deixar o texto quebrar. Exceção: títulos curtos de exibição onde cada palavra está deliberadamente em sua própria linha.

  • Animar visibility ou display — GSAP não pode animar estes. Use autoAlpha (lida com visibilidade e opacidade).

  • Chamar video.play() ou audio.play() — o framework controla a reprodução. Nunca chame estes por conta própria.

  • Construir timelines de forma assíncrona — o mecanismo de captura lê window.__timelines de forma síncrona após o carregamento da página. Nunca envolva a construção da timeline em async, setTimeout ou uma Promise.

  • index.html autônomo envolto em <template> — esconde todo o conteúdo do navegador. Apenas sub-composições carregadas via data-composition-src usam <template>.

  • Usar vídeo para áudio — sempre <video> com mute + <audio> separado.

Verificação

Antes e depois da renderização:

  1. Lint + validate + inspect passam: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint captura problemas estruturais, validate captura contraste, inspect captura problemas visuais de layout/overflow — veja troubleshooting.md se aparecerem avisos).
  2. Coreografia da animação — para novas composições ou mudanças 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 <diretorio-da-composicao> \
      --out <diretorio-da-composicao>/.hyperframes/anim-map
    
    Gera um único animation-map.json com resumos por tween, timeline 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. Pule em pequenas edições.
  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=noprint_wrappers=1:nokey=1 final.mp4 → compara com o valor data-duration.
  5. Playcheck visual (se disponível): abra o vídeo renderizado e assista. Verifique sincronização labial, timing de legendas, curva de transições e movimento geral. Se possível, compartilhe um link do frame.io ou similar para revisão do usuário.

Verificação de qualidade de renderização:

  • Bandas/artefatos: Defina quality=high se o vídeo final mostrar bandas de cor ou artefatos de compressão. O perfil high usa CRF 17 para MP4 (libx264) e CRF 15 + CPU-used 4 para WebM (libvpx-vp9). Se o artefato persistir, adicione --extra-ffmpeg-args "-pix_fmt yuv420p10le" (melhora o subamostragem de croma principalmente para gradações suaves e fundos escuros).
  • Correspondência de taxa de quadros: ffprobe -v error -select_streams v:0 -show_entries stream=r_frame_rate -of default=noprint_wrappers=1:nokey=1 final.mp4.
  • Integridade do arquivo: ffmpeg -v error -i final.mp4 -f null - — sem erros significa que o arquivo está bem.

Esta documentação é para uso interno do agente. Consulte os arquivos de referência vinculados para detalhes de implementação.

Habilidades Relacionadas