CLI do HyperFrames
Tudo é executado através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.
Fluxo de Trabalho
- Scaffold —
npx hyperframes init meu-video - Escreva — autorize 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 inspeção antes da pré-visualização. O lint detecta data-composition-id ausente, trilhas sobrepostas e timelines não registradas. O inspect abre a composição renderizada no Chrome headless, percorre a timeline e relata texto vazando para fora de balões/contêineres 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)
Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
O init cria a estrutura de arquivos correta, copia mídias, transcreve áudio com Whisper e instala skills de codificação 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 o 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 # descobertas em nível informativo
npx hyperframes lint --json # 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 ./meu-projeto # projeto específico
npx hyperframes inspect --json # descobertas 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 hero-frame
Use após o 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 pela própria caixa de largura/altura fixa
- Texto se estendendo para fora do canvas da composição
- Elementos 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 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 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 em alterações de arquivo. Abre o Studio no navegador automaticamente.
Ao entregar um projeto de volta ao usuário, use a URL do projeto no Studio, não o
caminho da fonte index.html:
http://localhost:<porta>/#project/<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,
relate http://localhost:3017/#project/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 o projeto ou a 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 # saída 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 uma instância do 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 | — | 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 | Falha na renderização em chaves não declaradas ou incompatibilidade de tipos em --variables |
Orientação 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(). A CLI **`--variables '{