coleam00/hyperframes-ai-video-generation

HyperFrames CLI

Tudo é executado através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.

Fluxo de Trabalho

1. Scaffold — npx hyperframes init meu-video
2. Escrever — autorizar composição HTML (consulte a skill hyperframes)
3. Lint — npx hyperframes lint
4. Inspeção visual — npx hyperframes inspect
5. Pré-visualização — npx hyperframes preview
6. Renderizar — npx hyperframes render

Execute lint e inspect antes da pré-visualização. lint captura data-composition-id ausente, trilhas sobrepostas e timelines não registradas. inspect abre a composição renderizada em headless Chrome, percorre a timeline e relata texto vazando para fora de balões/contêineres ou do canvas.

Scaffold

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 --non-interactive       # pular prompts (CI/agentes)

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init cria a estrutura de arquivos correta, copia mídia, transcreve áudio com Whisper e instala skills de codificação de IA. Use em vez de criar arquivos manualmente.

Lint

npx hyperframes lint                  # diretório atual
npx hyperframes lint ./meu-projeto    # projeto específico
npx hyperframes lint --verbose        # achados informativos
npx hyperframes lint --json           # legível por máquina

Aplica lint em 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 hero-frame

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 do canvas da composição
• 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 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 alias de compatibilidade para a mesma passagem de 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 arquivo. Abre o estúdio no navegador automaticamente.

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 tempo de render
--quality	draft, standard, high	standard	draft para iterar
--format	mp4, webm	mp4	WebM suporta transparência
--workers	1-8 ou auto	auto	Cada um gera um Chrome
--docker	flag	off	Saída reproduzível
--gpu	flag	off	Codificação acelerada por GPU
--strict	flag	off	Falha em erros de lint
--strict-all	flag	off	Falha em erros E avisos

Orientações 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

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 embutido
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 .    # benchmarking de desempenho de render