CLI do HyperFrames
Tudo é executado através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.
Fluxo de Trabalho
- Scaffolding —
npx hyperframes init my-video - Escrever — crie a composição HTML (veja a skill
hyperframes) - Lint —
npx hyperframes lint - Inspeção visual —
npx hyperframes inspect - Pré-visualização —
npx hyperframes preview - Renderização —
npx hyperframes render
Execute lint e inspect antes da pré-visualização. O lint detecta data-composition-id ausentes, trilhas sobrepostas e timelines não registradas. O inspect abre a composição renderizada no Chrome headless, percorre a timeline e relata texto vazando de bolhas/contêineres ou para fora da tela.
Scaffolding
npx hyperframes init my-video # assistente interativo
npx hyperframes init my-video --example warm-grain # escolher um exemplo
npx hyperframes init my-video --video clip.mp4 # com arquivo de vídeo
npx hyperframes init my-video --audio track.mp3 # com arquivo de áudio
npx hyperframes init my-video --example blank --tailwind # com runtime do navegador Tailwind v4
npx hyperframes init my-video --non-interactive # pular prompts (CI/agentes)
Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
O comando init cria a estrutura correta de arquivos, copia a mídia, transcreve o áudio com Whisper e instala as skills de IA. Use-o em vez de criar arquivos manualmente.
Ao usar --tailwind, invoque a skill tailwind antes de editar classes ou tokens de tema. O scaffold usa Tailwind v4.2 via runtime do navegador, não a configuração Tailwind v3 do Studio.
Linting
npx hyperframes lint # diretório atual
npx hyperframes lint ./my-project # projeto específico
npx hyperframes lint --verbose # achados em nível informativo
npx hyperframes lint --json # formato legível por máquina
Verifica index.html e todos os arquivos em compositions/. Relata erros (devem ser corrigidos), avisos (devem ser corrigidos) e informações (com --verbose).
Inspeção Visual
npx hyperframes inspect # inspeciona o layout renderizado na timeline
npx hyperframes inspect ./my-project # projeto específico
npx hyperframes inspect --json # achados legíveis por agente
npx hyperframes inspect --samples 15 # varredura mais densa da timeline
npx hyperframes inspect --at 1.5,4,7.25 # timestamps explícitos de quadros-chave
Use este comando após lint e validate, especialmente para composições com balões de fala, cartões, legendas ou tipografia apertada. Ele relata:
- Texto se estendendo para fora do contêiner visual ou balão mais próximo
- Texto cortado por sua própria caixa de largura/altura fixa
- Texto se estendendo para fora da tela da composição
- Filhos escapando de contêineres de recorte
Erros devem ser corrigidos antes da renderização. Avisos são exibidos para revisão do agente; adicione --strict para falhar também em avisos. Problemas estáticos repetidos são colapsados por padrão para que a saída JSON permaneça compacta para janelas de contexto LLM. Se o estouro for intencional para uma animação de entrada/saída, marque o elemento ou ancestral com data-layout-allow-overflow. Se um elemento decorativo nunca deve ser auditado, marque-o com data-layout-ignore.
npx hyperframes layout permanece disponível como um alias de compatibilidade para a mesma passagem de inspeção visual.
Pré-visualização
npx hyperframes preview # serve o diretório atual
npx hyperframes preview --port 4567 # porta personalizada (padrão 3002)
Recarrega automaticamente nas alterações de arquivo. Abre o studio no seu navegador automaticamente.
Ao devolver um projeto para o usuário, use a URL do projeto do Studio, não o caminho do arquivo index.html de origem:
http://localhost:<port>/projeto/<nome-do-projeto>
Use a porta real da saída da pré-visualização e o nome do diretório do projeto. Por exemplo, após npx hyperframes preview --port 3017 em codex-openai-video, reporte http://localhost:3017/projeto/codex-openai-video.
Trate index.html apenas como contexto de código-fonte. É aceitável vinculá-lo como um arquivo de implementação, mas não o rotule como projeto ou superfície de pré-visualização.
Renderização
npx hyperframes render # MP4 padrão
npx hyperframes render --output final.mp4 # saída com nome personalizado
npx hyperframes render --quality draft # iteração rápida
npx hyperframes render --fps 60 --quality high # entrega final
npx hyperframes render --format webm # WebM transparente
npx hyperframes render --docker # byte-idêntico
| Flag | Opções | Padrão | Observações |
|---|---|---|---|
--output | caminho | renders/nome_timestamp.mp4 | Caminho de saída |
--fps | 24, 30, 60 | 30 | 60fps dobra o tempo de renderização |
--quality | draft, standard, high | standard | draft para iterar |
--format | mp4, webm | mp4 | WebM suporta transparência |
--workers | 1-8 ou auto | auto | Cada um inicia um Chrome |
--docker | flag | desligado | Saída reproduzível |
--gpu | flag | desligado | Codificação acelerada por GPU |
--strict | flag | desligado | Falha em erros de lint |
--strict-all | flag | desligado | Falha em erros E avisos |
--variables | objeto JSON | — | Sobrescreve valores de variáveis declarados em data-composition-variables |
--variables-file | caminho | — | Arquivo JSON com valores de variáveis (alternativa a --variables) |
--strict-variables | flag | desligado | Falha na renderização em chaves não declaradas ou incompatibilidade de tipos em --variables |
Orientações de qualidade: draft durante iteração, standard para revisão, high para entrega final.
Renderizações parametrizadas: a composição declara suas variáveis na raiz <html> com data-composition-variables — um array JSON de declarações ({id, type, label, default} por entrada) que define o esquema. Scripts internos leem os valores resolvidos via window.__hyperframes.getVariables(). O CLI --variables '{"title":"Relatório Q4"}' é um objeto JSON chaveado por id que sobrescreve os padrões declarados para uma renderização; chaves ausentes usam o fallback, então a mesma composição funciona inalterada na pré-visualização de desenvolvimento e em produção. (Anfitriões de sub-composição também podem sobrescrever por instância com data-variable-values — mesma forma de objeto, com escopo para uma montagem da sub-composição. Veja a skill hyperframes para o padrão completo.)
Pré-processamento de Assets
npx hyperframes tts, transcribe e remove-background produzem assets (áudio de narração, transcrições por palavra, vídeo transparente) que são inseridos em uma composição. Cada um baixa seu próprio modelo na primeira execução. Para seleção de voz, regras do modelo Whisper (a pegadinha .en-traduz-não-inglês), escolha de formato de saída (VP9 alpha WebM vs ProRes) e a cadeia TTS → transcrever → legendas, invoque a skill hyperframes-media.
Diagnóstico
npx hyperframes doctor # verifica ambiente (Chrome, FFmpeg, Node, memória)
npx hyperframes browser # gerencia o Chrome integrado
npx hyperframes info # detalhes de versão e ambiente
npx hyperframes upgrade # verificar atualizações
Execute doctor primeiro se a renderização falhar. Problemas comuns: FFmpeg ausente, Chrome ausente, baixa memória.
Outros
npx hyperframes compositions # lista composições no projeto
npx hyperframes docs # abre documentação
npx hyperframes benchmark . # benchmark do desempenho de renderização