CLI HyperFrames
Tudo é executado através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.
Fluxo de trabalho
- Scaffolding —
npx hyperframes init meu-video - Escrever — criar composição HTML (consulte a skill
hyperframes) - Lint —
npx hyperframes lint - Inspeção visual —
npx hyperframes inspect - Preview —
npx hyperframes preview - Renderizar —
npx hyperframes render
Execute lint e inspect antes do preview. O lint detecta data-composition-id ausentes, faixas sobrepostas e timelines não registradas. O inspect abre a composição renderizada no Chrome headless, navega pela timeline e relata texto saindo de balões/contêineres ou da tela.
Scaffolding
npx hyperframes init meu-video # wizard interativo
npx hyperframes init meu-video --example warm-grain # escolher 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 --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 a mídia, transcreve o á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 ./meu-projeto # projeto específico
npx hyperframes lint --verbose # achados em nível informativo
npx hyperframes lint --json # legível por máquina
Faz lint de index.html e de 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 layout renderizado na 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 quadros-chave
Use após lint e validate, especialmente em composições com balões de fala, cartões, legendas ou tipografia ajustada. Relata:
- Texto que se estende para fora do contêiner visual ou balão mais próximo
- Texto cortado por sua própria caixa de largura/altura fixa
- Texto que se estende 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 pelo agente; adicione --strict para falhar também em avisos. Problemas estáticos repetidos são colapsados por padrão, mantendo a saída JSON 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 passagem de inspeção visual.
Preview
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 estúdio no navegador automaticamente.
Ao devolver um projeto ao usuário, use a URL do projeto no Estúdio, não o caminho do arquivo index.html de origem:
http://localhost:<porta>/#project/<nome-do-projeto>
Use a porta real da saída do preview e o nome do diretório do projeto. Por exemplo, após npx hyperframes preview --port 3017 em codex-openai-video, informe http://localhost:3017/#project/codex-openai-video.
Trate index.html apenas como contexto do código-fonte. É aceitável vinculá-lo como um arquivo de implementação, mas não o rotule como o projeto ou superfície de preview.
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 # byte-idêntico
| 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 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 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 |
Orientação de qualidade: draft durante 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 (TTS)
npx hyperframes tts "Texto aqui" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # mostrar todas as vozes
Diagnóstico de Problemas
npx hyperframes doctor # verificar ambiente (Chrome, FFmpeg, Node, memória)
npx hyperframes browser # gerenciar Chrome empacotado
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