ak:hyperframes
Empacota a CLI hyperframes da HeyGen
para geração programática de vídeos baseados em HTML. Esta habilidade é apenas
documentação + wrapper — sem código-fonte HeyGen embutido, sem habilidades de
agente HeyGen copiadas. Todos os comandos abaixo executam o pacote npm publicado
via npx, fixado em uma versão estável conhecida.
Quando usar
- Vídeos curtos verticais/para redes sociais (1080×1920, 9:16) renderizados a partir de HTML/CSS.
- Clipes de lançamento de produto, loops promocionais, gráficos em movimento criados como composição HTML em vez de componentes React ou editores de timeline.
- Qualquer tarefa onde a fonte da composição seja marcação HTML com atributos
data-composition-id/data-start(consulte references/composition-basics.md).
Não é adequado para composições baseadas em React, curvas de interpolação quadro a quadro ou o ecossistema de áudio/legendas do Remotion — consulte também a habilidade remotion instalada para essa alternativa (vídeo programático baseado em React). Não é adequado para tarefas puramente de codificação com FFmpeg/ImageMagick — consulte também a habilidade ak-media-processing.
Pré-requisitos
- Node.js 22+
- FFmpeg no
PATH - Opcional: uma chave de API HeyGen cloud/lambda (
HEYGEN_API_KEY) para renderização remota; a renderização local funciona sem ela.
Execute o verificador incluso antes de iniciar qualquer trabalho de renderização:
node scripts/verify-prereqs.mjs
# ou, para saída legível por máquina:
node scripts/verify-prereqs.mjs --json
Consulte references/env-and-deps.md para instruções de instalação por plataforma e a nota sobre verificação de versão fixada.
Versão fixada da CLI
Toda invocação abaixo fixa [email protected] — a versão mais recente
publicada em 2026-08-07 (npm view hyperframes version). Atualize essa
fixação em um único lugar (este arquivo + references/render-workflow.md)
ao fazer upgrade; não execute npx -y hyperframes ... sem fixação em
scripts ou documentação.
Fluxo de trabalho
O loop padrão é init → edit HTML → preview → lint → render. Invocações
concretas completas para cada etapa estão em
references/render-workflow.md; a forma
resumida:
# 1. Gere a estrutura de um novo projeto de composição.
npx -y [email protected] init my-composition --resolution portrait
# 2. Edite a composição HTML gerada (consulte composition-basics.md para o
# contrato de data-composition-id / data-start / data-width / data-height).
# 3. Visualize em um servidor de desenvolvimento local.
npx -y [email protected] preview my-composition
# 4. Faça lint da composição antes de renderizar (detecta atributos de tempo
# malformados).
npx -y [email protected] lint my-composition
# 5. Renderize para MP4.
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
Sempre execute lint antes de render — uma composição que passa no lint
falha na etapa de renderização com muito menos frequência do que uma que pula
diretamente para a renderização.
Contrato da composição
Composições HyperFrames são arquivos HTML simples anotados com atributos
data-composition-id, data-start, data-width e data-height nos
elementos raiz. Consulte
references/composition-basics.md para a
referência completa dos atributos e um exemplo completo vertical 1080×1920.
Material de referência
- references/heygen-skills.md — as 25
habilidades de agente HeyGen às quais este wrapper delega em vez de
reimplementar; instale-as via
npx -y [email protected] skillsquando for necessário conhecimento mais aprofundado específico do HyperFrames (animação, keyframes, legendas, templates de lançamento de produto, etc.). - references/composition-basics.md — contrato de atributos de composição HTML com um exemplo completo de predefinição vertical.
- references/render-workflow.md — o fluxo
completo
init → edit → preview → lint → rendercom todas as invocações fixadas. - references/env-and-deps.md — configuração de Node/FFmpeg/chave de API por plataforma.
Solução de problemas
| Sintoma | Ação |
|---|---|
command not found: ffmpeg | Execute node scripts/verify-prereqs.mjs para a correção exata para sua plataforma. |
npx hyperframes informa uma flag desconhecida | A versão fixada neste arquivo pode estar desatualizada em relação ao upstream; execute npx -y [email protected] --help para confirmar as flags atuais antes de atualizar a fixação. |
render falha com MP4 em branco/curto | Execute lint primeiro; a maioria das falhas de renderização são atributos data-start/data-composition-id malformados detectados pelo lint. |
| Renderização remota/cloud necessária | Defina HEYGEN_API_KEY conforme references/env-and-deps.md e use hyperframes cloud render (um comando separado de nível superior, não uma flag de render) — consulte references/render-workflow.md. |
Veja também
- A habilidade remotion instalada (
ak-remotion) — geração de vídeo programática baseada em React; use-a quando a composição for naturalmente uma árvore de componentes React em vez de marcação HTML. - A habilidade ak-html-video — um wrapper HTML-para-MP4 separado
(
nexu-io/html-video) com seu próprio fluxo de trabalho de template/Studio; use ak-hyperframes especificamente quando a tarefa for uma composição HeyGen HyperFrames. - A habilidade ak-motion-graphics — roteador entre todas as habilidades de vídeo/movimento no repositório, além de pacotes de habilidades de movimento externos.