O que HyperFrames faz?
Visão Geral
HyperFrames é um framework open-source (Apache-2.0) da HeyGen que transforma HTML, CSS, mídia e animações em vídeos MP4 determinísticos — mesma entrada sempre produz a mesma saída. Ele analisa composições HTML anotadas com atributos de tempo data-*, usa Chrome headless para buscar e capturar cada quadro e codifica o resultado com FFmpeg. Não há etapa de build, requisito de React ou taxa por renderização. É projetado para ser amigável a agentes: o CLI é não interativo por padrão, encaixando-se perfeitamente em pipelines automatizados de conteúdo.
Use esta habilidade para estruturar projetos, criar composições HTML, visualizá-las com recarga automática e renderizar vídeo quadro a quadro — incluindo animações com GSAP, CSS, Lottie, Three.js, Anime.js ou a Web Animations API.
Instruções
Pré-requisitos
Confirme o ambiente antes de começar:
- Node.js 22+ (
node --version) - FFmpeg no PATH (
ffmpeg -version) - O Chrome/Chromium headless é baixado pelo mecanismo na primeira execução.
Estruturando um projeto
npx hyperframes init my-video # estrutura um projeto (cria index.html + package.json)
cd my-video
Para configuração gerenciada por agente dentro de um workspace existente de agente de IA, a habilidade pode ser instalada com npx skills add heygen-com/hyperframes.
Criando uma composição
Composições são arquivos index.html simples. Um elemento raiz de palco declara a tela e o ID da composição; elementos filhos declaram quando aparecem e por quanto tempo duram por meio de atributos data-*. Os valores de tempo estão em segundos.
| Atributo | Propósito |
|---|---|
data-composition-id | Nomeia a composição (alvo para render/inspecionar) |
data-start | Quando o elemento entra na linha do tempo (segundos) |
data-duration | Quanto tempo o elemento permanece na linha do tempo (segundos) |
data-width / data-height | Dimensões da tela em pixels (no elemento de palco) |
data-track-index | Ordem da camada/faixa para áudio ou vídeo empilhados |
data-volume | Nível de áudio, 0.0–1.0 |
Visualizando e renderizando
npx hyperframes preview # visualização no navegador com recarga automática durante a criação
npx hyperframes render # busca cada quadro no Chrome headless, codifica para MP4 via FFmpeg
npx hyperframes lint # valida a estrutura da composição antes de renderizar
npx hyperframes inspect # exibe metadados da composição (duração, faixas, dimensões)
A resolução vem de data-width/data-height no palco; taxa de quadros, caminho de saída e codec são parâmetros de renderização (verifique npx hyperframes render --help para as flags exatas em sua versão instalada, pois os nomes das flags evoluem). Como a saída é determinística, re-renderizar a mesma entrada é seguro para cache.
Usando o catálogo de componentes
Blocos pré-construídos (transições, sobreposições, legendas, gráficos animados, mapas, efeitos) são instalados no projeto:
npx hyperframes add flash-through-white # uma transição
npx hyperframes add data-chart # um bloco de gráfico animado
npx hyperframes add instagram-follow # uma sobreposição social
Navegue pelo catálogo completo em hyperframes.heygen.com/catalog e adicione blocos pelo nome.
Animações
Qualquer animação buscável e precisa por quadro funciona porque o mecanismo busca cada posição da linha do tempo deterministicamente, em vez de gravar em tempo real. Adaptadores suportados: GSAP, animações CSS, Lottie, Three.js, Anime.js, WAAPI e adaptadores personalizados. Evite aleatoriedade baseada em tempo ou movimento orientado por Date.now()/relógio de parede — vincule o progresso da animação à linha do tempo da composição para que as buscas sejam reproduzíveis.
Pipelines de agente / CI
O CLI é não interativo, portanto um fluxo automatizado típico é: gerar/modelar o HTML → hyperframes lint → hyperframes render → coletar o MP4. Para escala, o pacote @hyperframes/aws-lambda permite renderização distribuída no Lambda.
Exemplos
Exemplo 1: Renderizar uma composição de lançamento de produto
index.html:
<div id="stage" data-composition-id="launch"
data-start="0" data-width="1920" data-height="1080">
<video data-start="0" data-duration="6" src="intro.mp4"></video>
<h1 id="title" data-start="1" data-duration="4">Dia do lançamento</h1>
<audio data-start="0" data-duration="6" data-volume="0.8" src="music.wav"></audio>
</div>
npx hyperframes inspect # confirma: launch, 6s, 1920x1080
npx hyperframes lint # valida antes de gastar tempo de renderização
npx hyperframes render # produz um MP4 1080p
Exemplo 2: Uma animação de título GSAP buscável
<div id="stage" data-composition-id="title-card"
data-start="0" data-width="1080" data-height="1080">
<h1 id="headline" data-start="0" data-duration="3">Resultados Q3</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// Vincule o progresso à linha do tempo (tween pausado que o mecanismo busca), não ao tempo real.
const tl = gsap.timeline({ paused: true });
tl.from("#headline", { y: 80, opacity: 0, duration: 1 })
.to("#headline", { scale: 1.05, duration: 2 });
window.__seek = (t) => tl.seek(t); // o mecanismo chama isso por quadro
</script>
</div>
npx hyperframes preview # itere ao vivo, depois:
npx hyperframes render
Diretrizes
- Determinismo primeiro. Vincule todo movimento à linha do tempo da composição. Evite
Math.random(),Date.now(), loops em tempo real ou chamadas de rede durante a renderização — eles quebram a reprodutibilidade. - Analise antes de renderizar.
hyperframes lintdetecta erros estruturais/de tempo de forma barata; a renderização é a etapa cara. - Defina a tela no palco.
data-width/data-heightficam no elemento raiz da composição; o tempo dos filhos (data-start/data-duration) fica em cada elemento, em segundos. - Verifique o conjunto de ferramentas. A maioria das falhas se deve à falta de FFmpeg ou Node < 22, ou a um download do Chromium bloqueado por firewall.
- Use
--helppara flags exatas. As opções derender/addvariam por versão; confirme as flags de fps/saída/codec no CLI instalado, em vez de assumir. - Prefira blocos do catálogo.
hyperframes addpuxa componentes mantidos e buscáveis, em vez de criar transições e gráficos manualmente. - Escale com Lambda. Para trabalhos em lote/grandes, renderize via
@hyperframes/aws-lambdaem vez de um longo trabalho local. - Mantenha a mídia local e versionada. Referencie ativos por caminhos estáveis; buscas remotas durante a renderização prejudicam a determinismo e a reprodutibilidade.