CLI HyperFrames
Tudo roda através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.
Fluxo de Trabalho
- Estruturar —
npx hyperframes init meu-video - Escrever — crie a composição HTML (veja a habilidade
hyperframes) - Analisar —
npx hyperframes lint - Visualizar —
npx hyperframes preview - Renderizar —
npx hyperframes render
Analise antes de visualizar — detecta data-composition-id ausentes, trilhas sobrepostas, timelines não registradas.
Estruturação
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 --non-interactive # pular perguntas (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 habilidades de programação de IA. Use-o em vez de criar arquivos manualmente.
Análise
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
Analisa index.html e todos os arquivos em compositions/. Reporta erros (devem ser corrigidos), avisos (devem ser corrigidos) e informações (com --verbose).
Visualização
npx hyperframes preview # serve o diretório atual
npx hyperframes preview --port 4567 # porta personalizada (padrão 3002)
Recarrega automaticamente com alterações nos arquivos. Abre o estúdio no navegador automaticamente.
Renderização
npx hyperframes render # MP4 padrão (saída para renders/ automaticamente)
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
| Bandeira | 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ções |
--format | mp4, webm | mp4 | WebM suporta transparência |
--workers | 1-8 ou auto | auto | Cada um inicia uma instância do Chrome |
--docker | bandeira | desligado | Saída reproduzível |
--gpu | bandeira | desligado | Codificação acelerada por GPU |
--strict | bandeira | desligado | Falhar em erros de análise |
--strict-all | bandeira | desligado | Falhar em erros E avisos |
Orientação de qualidade: draft durante iterações, 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 integrado
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.
Armadilhas
O caminho --out deve ser um diretório, não um nome de arquivo
npx hyperframes render --out renders/saida.mp4 → ✗ erro: "Não é um diretório"
npx hyperframes render → ✅ saída para renders/nome_timestamp.mp4 automaticamente
Use --output (não --out) para especificar um caminho de arquivo nomeado.
A timeline raiz de index.html deve corresponder ao data-composition-id da sub-composição
Se index.html contém apenas uma referência data-composition-src (sem conteúdo inline), você ainda precisa de um registro window.__timelines que corresponda a um data-composition-id real. Boa prática: registre window.__timelines['<id-da-sub-comp>'] = gsap.timeline({paused:true}) — mas como as sub-composições registram suas próprias timelines, o bloco de script de index.html é necessário apenas para passar na análise. Use o id da sub-composição (não 'root').
<div> da sub-composição precisa de data-start="0" e data-duration
A <div data-composition-id="..."> dentro de <template> deve ter data-start="0" e data-duration="N", senão a análise emitirá avisos e a reprodução pode não iniciar.
Outros
npx hyperframes compositions # listar composições no projeto
npx hyperframes docs # abrir documentação
npx hyperframes benchmark . # avaliar desempenho de renderização