CLI do HyperFrames
Tudo é executado através de npx hyperframes, a menos que as instruções do projeto especifiquem um wrapper local. Obedeça exatamente ao wrapper local. Requer Node.js >= 22 e FFmpeg.
Fluxo de Trabalho
- Estrutura Inicial —
npx hyperframes init meu-video(oucapturea partir de uma URL).inittambém verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada. A flag--skip-skillsestá atualmente neutralizada (temporariamente, enquanto o registro skills.sh se atualiza), então todoinitexecuta essa verificação e baixa nossas skills mais recentes independentemente. - Escrever — crie a composição HTML (veja a skill
hyperframes-core) - Lint —
npx hyperframes lint - Validar —
npx hyperframes validate(erros de runtime + contraste) - Inspeção visual —
npx hyperframes inspect - Preview —
npx hyperframes previewabre o Studio, o editor de timeline onde o usuário pode editar manualmente qualquer coisa (não apenas assistir). Revise lá e pergunte antes de renderizar. - Renderizar — escolha a variante:
- Iterar:
npx hyperframes render --quality draft - Entregar:
npx hyperframes render --quality high --output out.mp4 - CI / reprodutibilidade entre máquinas:
npx hyperframes render --docker --strict --output out.mp4 - Nuvem (longo / grande):
npx hyperframes lambda render ./meu-projeto --width 1920 --height 1080 --wait(veja Lambda abaixo)
- Iterar:
Execute lint, validate e inspect antes do preview. lint captura data-composition-id ausente, trilhas sobrepostas e timelines não registradas. validate carrega a composição no Chrome headless e reporta erros de console em tempo de execução, além de problemas de contraste WCAG. inspect percorre a timeline e reporta texto transbordando de balões/contêineres ou saindo da tela — e, quando um arquivo *.motion.json adjacente está presente, verifica a intenção de movimento (entradas acionadas durante a busca, ordem de escalonamento, dentro do quadro, vivacidade) contra essa mesma timeline percorrida.
Para trabalhos com muitos movimentos, prefira iteração baseada em snapshots e um arquivo *.motion.json adjacente — consulte references/lint-validate-inspect.md para a disciplina e especificação de verificação de movimento.
Convenções para Agentes
Regras transversais que valem para todos os comandos:
--jsonestá disponível em todos os comandos, excetorender,previeweplay. Use-o para qualquer invocação de agente / CI dos comandos suportados; a saída inclui um envelope_meta(versão da CLI, versão mais recente disponível, sugestão de atualização).renderinforma o status via stdout + código de saída apenas — verifique o sucesso com a verificação pós-renderização abaixo;preview/playsão servidores, sem JSON.doctor --jsonsempre sai com código 0, mesmo quando o ambiente está quebrado. Condicione a verificação no campookdo payload:npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Isso isola os pipelines de mudanças na versão da CLI.- Modo não-TTY é detectado automaticamente. Quando
stdoutnão é um TTY (CI, agentes, saída pipeada) a CLI muda automaticamente para modo não-interativo;initentão requer--example. Passe--non-interactivepara forçar este modo mesmo em um TTY. - Gating de CI na renderização:
--strictfalha em erros de lint,--strict-allfalha também em avisos,--strict-variablesfalha em chaves--variablesnão declaradas. - Caminhos em
--jsonsão censurados —$HOMEse torna o literal$HOMEpara que a saída seja segura para colar em relatórios de bugs e contextos de agente. - Renderização é controlada pelo usuário. Nunca renderize automaticamente quando as verificações passarem. Pare no
preview, informe ao usuário que o vídeo é editável no Studio, e renderize apenas após aprovação. - Verificação pós-renderização. Após
renderretornar código 0, confirme se o arquivo de saída existe e tem um tamanho plausível antes de relatar sucesso:[ -s "$OUTPUT" ] || echo "renderização não produziu saída". A CLI imprime◇ <caminho>em caso de sucesso; para renderizações longas, verifique também a duração comffprobe -i "$OUTPUT" -show_format -v error.
Roteamento
| Se você deseja… | Leia |
|---|---|
Estruturar um projeto (init, capture, skills) | references/init-and-scaffold.md |
Verificar correção (lint, validate, inspect, snapshot) | references/lint-validate-inspect.md |
Visualizar ou renderizar (preview, play, render, publish) | references/preview-render.md |
Diagnosticar o ambiente (doctor, browser) | references/doctor-browser.md |
Renderizar em nuvem no AWS Lambda (lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
Todo o resto (info, upgrade, compositions, docs, benchmark, telemetry, pré-processamento de assets) | references/upgrade-info-misc.md |
Transferências Entre Skills
- Projetos Tailwind (
init --tailwind) → usehyperframes-core(referência Tailwind) antes de editar classes ou tokens de tema. - Blocos/componentes do Registry (
hyperframes add,hyperframes catalog) → usehyperframes-registrypara caminhos de instalação, conexão de sub-composições e mesclagem de snippets. - Pré-processamento de assets (
tts,transcribe,remove-background) → usehyperframes-mediapara seleção de voz, regras do modelo Whisper, legendas e cadeia TTS-para-legendas. - Renderizações parametrizadas (
--variables) → declaradas viadata-composition-variablesno<html>; vejahyperframes-corepara o esquema completo.
Lambda (Renderização em Nuvem)
hyperframes lambda implanta renderização distribuída no AWS Lambda e executa renderizações a partir do seu laptop ou CI. O processo ponta a ponta consiste em três comandos:
npx hyperframes lambda deploy # provisionar pilha SAM (Lambda + Step Functions + S3)
npx hyperframes lambda render ./meu-projeto --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # desmontar (o bucket S3 é mantido)
Use Lambda quando uma renderização for muito longa / muito grande para uma única máquina (vídeos com vários minutos, 4K, lotes paralelos grandes) e você tiver credenciais AWS configuradas. Para iteração no ciclo de desenvolvimento, mantenha-se na renderização local.
Consulte references/lambda.md para pré-requisitos, todos os 6 subcomandos (deploy, sites create, render, progress, destroy, policies), validação de política IAM, arquivos de estado e regras de custo/limpeza.
Gate de Conclusão Mínimo
Gates estáticos
npx hyperframes lint
npx hyperframes validate
Adicione inspect para trabalhos sensíveis a layout e render --strict em CI para falhar em erros de lint.
Teste visual de fumaça — obrigatório quando o projeto usa sub-composições
lint / validate / inspect avaliam cada composição isoladamente. Eles nunca carregam index.html e montam sub-composições via data-composition-src, portanto não conseguem capturar falhas de montagem entre arquivos (veja hyperframes-core → references/sub-compositions.md, "Armadilhas comuns"). O único gate que as captura é aquele que realmente carrega index.html e percorre a timeline.
Use hyperframes snapshot — ele carrega o projeto da mesma forma que render (portanto exercita o mesmo caminho de montagem), mas captura apenas os timestamps solicitados, levando segundos em vez de uma renderização completa:
# Capture um quadro no ponto médio de cada sub-composição.
# Pontos médios = data-start + data-duration/2 para cada slot hospedeiro em index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
# Ou, se não precisar de segmentação por cena, uma amostra uniformemente espaçada:
npx hyperframes snapshot --frames 9
A saída vai para snapshots/frame-NN-at-Xs.png. Examine cada quadro visualmente em relação ao plano da cena.
Sinais de alerta por quadro (cada um mapeia para um modo de falha específico que os gates estáticos não detectam):
| O que você vê | Causa raiz |
|---|---|
| Texto aparece minúsculo + sem estilo no canto superior esquerdo | Bloco <style> deixado em <head> fora de <template> (Armadilha 1) — nenhum CSS alcançou o DOM ativo |
| Elementos SVG/ícone ampliados ao tamanho da tela | Mesma da anterior — sem restrições de largura/altura aplicadas |
| Elemento principal da cena está completamente ausente; apenas fundo + marca d'água visível | ID do host ≠ ID do template (Armadilha 2) — a timeline nunca foi executada, quadro capturado no estado inicial |
O comando de snapshot registra Timelines de sub-composição não registradas após 45000ms | Armadilha 2 — confirmação direta |
snapshots/ pode ser excluído após a inspeção visual; a renderização final voltada ao usuário é uma etapa separada com npx hyperframes render.