O que HyperFrames CLI faz?
Tudo roda através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.
Fluxo de Trabalho
- Scaffold —
npx hyperframes init meu-video - Escreva — crie a composição HTML (veja a skill
hyperframes) - Linte —
npx hyperframes lint - Inspecione visualmente —
npx hyperframes inspect - Pré-visualize —
npx hyperframes preview - Renderize —
npx hyperframes render
Linte e inspecione antes de pré-visualizar. lint detecta data-composition-id ausentes, trilhas sobrepostas e timelines não registradas. inspect abre a composição renderizada no Chrome headless, percorre a timeline e relata texto que transborda de balões/containers ou do canvas.
Scaffolding
npx hyperframes init meu-video # assistente interativo
npx hyperframes init meu-video --example warm-grain # escolha um exemplo
npx hyperframes init meu-video --video clip.mp4 # com arquivo de vídeo
npx hyperframes init meu-video --audio track.mp3 # com arquivo de áudio
npx hyperframes init meu-video --example blank --tailwind # com runtime do Tailwind v4 no navegador
npx hyperframes init meu-video --non-interactive # pular prompts (CI/agentes)
Modelos: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
init cria a estrutura de arquivos correta, copia mídia, transcreve áudio com Whisper e instala skills de codificação de IA. Use 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 ./meu-projeto # projeto específico
npx hyperframes lint --verbose # achados de nível informativo
npx hyperframes lint --json # legível por máquina
Linte 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 # inspecione layout renderizado ao longo da timeline
npx hyperframes inspect ./meu-projeto # 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 frames principais
Use após lint e validate, especialmente para composições com balões de fala, cartões, legendas ou tipografia apertada. Relata:
- Texto que se estende além do container visual ou balão mais próximo
- Texto cortado por sua própria caixa de largura/altura fixa
- Texto que se estende além do canvas da composição
- Filhos escapando de containers de recorte
Erros devem ser corrigidos antes da renderização. Avisos são expostos 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 contextos de janela do LLM. Se o transbordamento 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 # servir diretório atual
npx hyperframes preview --port 4567 # porta personalizada (padrão 3002)
Recarrega automaticamente com alterações de arquivo. Abre o studio no seu navegador automaticamente.
Ao devolver um projeto ao usuário, use a URL do projeto Studio, não o caminho da fonte index.html:
http://localhost:<porta>/#project/<nome-do-projeto>
Use a porta real da saída de 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/#project/codex-openai-video.
Trate index.html apenas como contexto de código-fonte. É aceitável vinculá-lo como 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 nomeada
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 # reprodução byte-idêntica
| Flag | Opções | Padrão | Notas |
|---|---|---|---|
--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 o Chrome |
--docker | flag | desligado | Saída reproduzível |
--gpu | flag | desligado | Codificação acelerada por GPU |
--strict | flag | desligado | Falhar em erros de lint |
--strict-all | flag | desligado | Falhar em erros E avisos |
--variables | objeto JSON | — | Substitui valores de variáveis declaradas em data-composition-variables |
--variables-file | caminho | — | Arquivo JSON com valores de variáveis (alternativa a --variables) |
--strict-variables | flag | desligado | Falhar renderização em chaves não declaradas ou incompatibilidades de tipo em --variables |
Orientações de qualidade: draft enquanto itera, 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 dentro leem os valores resolvidos via window.__hyperframes.getVariables(). O CLI --variables '{"title":"Relatório Q4"}' é um objeto JSON indexado por id que substitui aqueles padrões declarados para uma renderização; chaves ausentes continuam com os padrões, para que a mesma composição funcione inalterada na pré-visualização de desenvolvimento e na produção. (Hosts de sub-composições também podem substituir 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 Ativos
npx hyperframes tts, transcribe e remove-background produzem ativos (áudio de narração, transcrições no nível da palavra, vídeo transparente) que são colocados 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 de que .en traduz não-inglês), escolha de formato de saída (VP9 alpha WebM vs ProRes) e a cadeia TTS → transcribe → captions, invoque a skill hyperframes-media.
Solução de Problemas
npx hyperframes doctor # verifique ambiente (Chrome, FFmpeg, Node, memória)
npx hyperframes browser # gerencie Chrome empacotado
npx hyperframes info # detalhes da versão e ambiente
npx hyperframes upgrade # verifique atualizações
Execute doctor primeiro se a renderização falhar. Problemas comuns: FFmpeg ausente, Chrome ausente, pouca memória.
Outros
npx hyperframes compositions # liste composições no projeto
npx hyperframes docs # abra documentação
npx hyperframes benchmark . # avalie desempenho de renderização