chensiyuan040-hash/skill

HyperFrames 中文视频实战

Em HTML se escreve o vídeo, a engine renderiza quadro a quadro para MP4. Este skill é o acúmulo prático de uma produção completa de vídeo educativo chinês de 6,5 minutos (com dados reais, dublagem e capturas de tela) em outubro de 2026, com foco nas armadilhas que a documentação oficial não menciona e que só se descobrem na prática.

Fluxo Completo (Cinco Etapas)

1. Inicialização: npx hyperframes init <dir> → Node22+, FFmpeg como pré-requisitos; na máquina local, defina HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome (a engine baixa automaticamente o chrome-headless-shell, que pode falhar devido à rede, veja pitfalls#1)
2. Estrutura e Conteúdo: O index.html principal conecta as sub-composições das cenas; o conteúdo (dados reais/capturas de tela) deve ser arquivado primeiro em scripts/sources.md antes de ser inserido nas cenas — a densidade de informação é a vida de um vídeo explicativo
3. Animação: Cada cena usa uma timeline GSAP pausada; sistema de legendas sincronizadas por frase com destaque de ritmo (receita em references/scene-recipe.md)
4. Verificação: npx hyperframes check deve passar completamente em verde como pré-condição para renderização; correções comuns em references/pitfalls.md (90% dos erros têm solução pronta no manual)
5. Dublagem (opcional): edge-tts gera áudio → ajuste de velocidade conforme a duração medida → o áudio deve ser montado dentro do root do index.html principal (não funciona dentro das sub-composições, veja pitfalls#6) → re-renderize
6. Controle de Qualidade e Entrega: Após renderizar, use npx hyperframes snapshot para extrair quadros-chave e revisar um a um (ciclo de auto-inspeção visual: renderizar → ver quadros → melhorar → re-renderizar); a imagem de capa é extraída diretamente do snapshot, sem precisar de outra ferramenta

Comando-chave: preview use --background (com hot reload); renderizar 365s@1080p leva cerca de 9-10 minutos (modo de captura com 5 workers, sem GPU na máquina local).

Quando Ler Cada Referência

• Qualquer erro/anomalia de renderização → primeiro consulte references/pitfalls.md (consulte por sintoma, incluindo a conclusão sobre o bug não resolvido da engine na cadeia de transformação da câmera)
• Escrever nova cena → references/scene-recipe.md (inclui template JS de legendas sincronizadas por frase e padrão de animação com destaque)
• Adicionar dublagem → references/voice-pipeline.md
• Analisar vídeos de referência (Douyin, etc.) → seção final de pitfalls.md "Análise Quantitativa de Vídeos de Referência"
• Procurar blocos de efeitos prontos, skills do mesmo nicho, upgrades de dublagem, integração com Jianying e outras ferramentas externas → references/ecosystem.md (lista do ecossistema open source, incluindo reprodução 1:1 com capture --video oficial)

Scripts Inclusos

• scripts/inject_subtitles.py — Injeção em lote de legendas sincronizadas por frase (HTML/CSS/JS de uma vez, evitando erros manuais)
• scripts/gen_voice.py — Geração em lote com edge-tts + ajuste automático de velocidade para a duração da cena (execute com uv run)
• scripts/frame_audit.py — Auditoria de centroide dos quadros renderizados (detecção automática de deslocamento/quadro em branco, essencial para solucionar problemas de enquadramento)

Três Regras de Ouro

1. Antes de modificar qualquer arquivo de cena, use grep: O Studio insere data-hf-id nos elementos; substituições de string falham silenciosamente (pitfalls#2)
2. Não mexa na câmera da tela grande: O pipeline de renderização da engine causa desalinhamento com cadeias contínuas de transformação; já foi verificado com múltiplas abordagens e não tem solução (pitfalls#8); anime apenas elementos individuais
3. Linha do tempo narrativa primeiro: O tempo das legendas + a duração da dublagem determinam todo o ritmo da animação; defina a linha do tempo primeiro e depois anime — o retrabalho é mínimo