CLI HyperFrames
Tudo roda através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.
Fluxo de trabalho
- Inicializar —
npx hyperframes init meu-video - Escrever — crie a composição HTML (veja a habilidade
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, trilhas sobrepostas e timelines não registradas. O inspect abre a composição renderizada no Chrome headless, percorre a timeline e relata texto saindo de balões/contêineres ou fora da tela.
Inicialização
npx hyperframes init meu-video # assistente 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 --example blank --tailwind # com Tailwind v4 em runtime de 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ídia, transcreve áudio com Whisper e instala habilidades de codificação de IA. Use-o em vez de criar arquivos manualmente.
Ao usar --tailwind, invoque a habilidade tailwind antes de editar classes ou tokens de tema. O scaffold usa Tailwind v4.2 via runtime de navegador, não a configuração Tailwind v3 do Studio.
Lint
npx hyperframes lint # diretório atual
npx hyperframes lint ./meu-projeto # projeto específico
npx hyperframes lint --verbose # achados em nível de informação
npx hyperframes lint --json # legível por máquina
Analisa 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 ./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 principais
Use isso 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 da tela da composição
- Filhos escapando de contêineres com recorte
Erros devem ser corrigidos antes de renderizar. Avisos são exibidos para revisão do agente; adicione --strict para também falhar 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 passagem de inspeção visual.
Preview
npx hyperframes preview # servir diretório atual
npx hyperframes preview --port 4567 # porta personalizada (padrão 3002)
Recarrega automaticamente em mudanças de arquivo. Abre o estúdio no seu navegador automaticamente.
Ao devolver um projeto ao usuário, use a URL do projeto no Studio, não o caminho do index.html fonte:
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, relate http://localhost:3017/#project/codex-openai-video.
Trate index.html apenas como contexto de código-fonte. Tudo bem linká-lo como um arquivo de implementação, mas não o rotule como 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 # 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 Chrome |
--docker | bandeira | desligado | Saída reproduzível |
--gpu | bandeira | desligado | Codificação acelerada por GPU |
--strict | bandeira | desligado | Falhar em erros de lint |
--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 incorporado
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