Communitygithub.com

ngocsangyem/reporeaper

Empacota a CLI HeyGen HyperFrames para geração programática de vídeos baseados em HTML. Ideal para vídeos curtos verticais/para redes sociais, clipes de lançamento de produto e gráficos em movimento renderizados a partir de composições HTML. Veja também a habilidade remotion instalada para uma alternativa baseada em React.

O que é reporeaper?

Esta habilidade, ngocsangyem/reporeaper, atua como um wrapper em torno da CLI oficial HyperFrames da HeyGen, permitindo que desenvolvedores gerem vídeos programaticamente usando HTML e CSS como fonte única de verdade para composição. Ela é particularmente útil para criação de vídeos verticais curtos (1080×1920, 9:16), clipes de lançamento de produto e animações gráficas, oferecendo um fluxo de trabalho de `init → edit HTML → preview → lint → render` sem depender de editores de timeline ou componentes React. A habilidade é suportada em ambientes com Node.js 22+, FFmpeg e, opcionalmente, uma chave de API HeyGen para renderização em nuvem. Ela se baseia em uma versão fixa da CLI (`[email protected]`) para garantir consistência, e inclui verificações de pré-requisitos e scripts de lint para evitar erros comuns de renderização. Em vez de reimplementar recursos avançados, ela redireciona para as habilidades especializadas da HeyGen (instaláveis via a própria CLI) para animações, keyframes, legendas e templates de lançamento. É a escolha ideal quando a composição é puramente HTML com atributos de tempo, enquanto para composições baseadas em React recomenda-se a habilidade Remotion.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ngocsangyem/reporeaper/tree/HEAD/.claude/skills/ak-hyperframes

Perguntar na sua IA favorita

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

Documentação

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] skills quando 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 → render com todas as invocações fixadas.
  • references/env-and-deps.md — configuração de Node/FFmpeg/chave de API por plataforma.

Solução de problemas

SintomaAção
command not found: ffmpegExecute node scripts/verify-prereqs.mjs para a correção exata para sua plataforma.
npx hyperframes informa uma flag desconhecidaA 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/curtoExecute 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áriaDefina 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.

Habilidades Relacionadas