HyperFrames CLI
Tudo é executado através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.
Fluxo de Trabalho
- Criar —
npx hyperframes init my-video - Escrever — crie a composição HTML (veja a skill
hyperframes) - Lintar —
npx hyperframes lint - Inspecionar visualmente —
npx hyperframes inspect - Pré-visualizar —
npx hyperframes preview - Renderizar —
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 vazando para fora de bolhas/contêineres ou do canvas.
Criação (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 --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 correta de arquivos, copia mídia, transcreve áudio com Whisper e instala skills de codificação de IA. Use-o em vez de criar arquivos manualmente.
Linting
npx hyperframes lint # diretório atual
npx hyperframes lint ./my-project # projeto específico
npx hyperframes lint --verbose # descobertas em nível informativo
npx hyperframes lint --json # legível por máquina
Linta 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 # inspecionar layout renderizado ao longo da timeline
npx hyperframes inspect ./my-project # 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 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 do canvas da composição
- Elementos filhos escapando de contêineres de corte
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 de 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 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 em alterações de arquivos. Abre o estúdio no navegador automaticamente.
Ao entregar um projeto de volta ao usuário, use a URL do projeto no Studio, não o caminho do index.html de origem:
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. Não há problema em 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 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 | Observações |
|---|---|---|---|
--output | caminho | renders/nome_timestamp.mp4 | Caminho de saída |
--fps | 24, 30, 60 | 30 | 60fps dobra o tempo de render |
--quality | draft, standard, high | standard | draft para iteração |
--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 | Falhar em erros de lint |
--strict-all | flag | desligado | Falhar em erros E avisos |
Orientação de qualidade: draft durante a iteração, standard para revisão, high para entrega final.
Transcrição
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # importar existente
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Texto-para-Fala
npx hyperframes tts "Texto aqui" --voice af_nova --output narracao.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # mostrar todas as vozes
Solução de Problemas
npx hyperframes doctor # verificar ambiente (Chrome, FFmpeg, Node, memória)
npx hyperframes browser # gerenciar Chrome incluído
npx hyperframes info # versão e detalhes do ambiente
npx hyperframes upgrade # verificar atualizações
Execute doctor primeiro se a renderização falhar. Problemas comuns: FFmpeg ausente, Chrome ausente, pouca memória.
Outros
npx hyperframes compositions # listar composições no projeto
npx hyperframes docs # abrir documentação
npx hyperframes benchmark . # benchmark de desempenho de renderização