tzezhang1-crypto/claude-motion-explainer-video

Motion Explainer (Versão Aprimorada com Vídeo) — Animação Explica Conceitos, Fotos Servem como Evidência, Vídeos AI Trazem Emoção

Este skill integra todo o fluxo: "pesquisar na web → escrever roteiro → narração em chinês → animar quadro a quadro → legendas → paleta de cores → buscar fotos licenciadas e gerar imagens ilustrativas → gerar vídeos AI → auto-revisão → exportar MP4". Comparado à versão básica motion-explainer, ele adiciona a seção 7.5 (camada de imagens), seção 7.6 (camada de vídeos AI) e a seção 4 (correção de pronúncia); os demais passos são idênticos. Os materiais de vídeo são gerados por AI sempre que possível: notícias, comerciais e vídeos de banco de imagens geralmente têm direitos autorais e não devem ser usados em vídeos educacionais. Ele se apoia em três pilares:

• HyperFrames (código aberto da HeyGen, HTML + GSAP para MP4) e seus skills oficiais, especialmente a entrada /hyperframes e o fluxo de trabalho /faceless-explainer. Sempre siga a documentação oficial.
• Os skills motion-design (regras de bom gosto: easing, ritmo, pausas, tipografia chinesa) e review-loop (auto-revisão com contact sheets) deste repositório. A qualidade visual segue esses dois skills.
• As ferramentas na pasta scripts/: complementam o fluxo oficial para tratar narração, legendas, consistência de fontes e tema de três cores em chinês.

references/lessons.md contém lições aprendidas em projetos reais. Leia antes de começar — cada item já aconteceu em algum vídeo.

0. Verificação do Ambiente (Primeiro Uso)

• Execute python scripts/hw_check.py --project <projeto>: detecta CPU, memória, GPU e disco, e recomenda qual motor TTS usar, quantos --workers definir e se sub-agentes devem ser despachados em lotes. Explique as recomendações ao usuário conforme references/hardware.md; são estimativas, não benchmarks.
• Node.js 22+, ffmpeg/ffprobe, Python 3 + Pillow + fonttools (pip install fonttools; com brotli instalado, fontes são exportadas como woff2; sem brotli, como ttf).
• CLI HyperFrames: npm install -g hyperframes, depois hyperframes doctor (Docker, Whisper, Kokoro, MusicGen são opcionais).
• Skills oficiais: hyperframes skills update; para este tipo de vídeo, execute também hyperframes skills update faceless-explainer.
• Estatísticas de uso anônimo são ativadas por padrão. Pergunte ao usuário se deseja desabilitar com hyperframes telemetry disable.
• TTS (escolha um, pergunte ao usuário):
  • edge-tts (padrão): pip install edge-tts, não precisa de GPU, requer internet para gerar. Vozes taiwanesas: zh-TW-HsiaoChenNeural (feminina), zh-TW-HsiaoYuNeural (feminina), zh-TW-YunJheNeural (masculina).
  • Breeze TTS 2 (avançado): requer GPU NVIDIA local (~7,7 GB VRAM, recomendado 12 GB+; arquivos do modelo ~7 GB). Permite descrever a voz com texto e fazer clonagem vocal, com controle fino de sotaque e emoção.
  • Outros motores também funcionam: desde que gerem assets/voice/raw/NN.wav para cada frase. Para vídeos em inglês, use Kokoro/HeyGen integrados ao HyperFrames.

1. Pesquisa (Com Busca na Web)

• Pesquise as informações mais recentes sobre o tema, usando pelo menos duas fontes independentes. Anote discrepâncias numéricas e adote o valor consistente entre as fontes.
• Classifique cada número em três categorias para exibição na tela: Oficial / Medido ou Reportado / Estimativa Própria.
• Faça estimativas físicas ou matemáticas simples para que o espectador possa "calcular" — essa é a parte mais valiosa de um vídeo explicativo. Sempre compare a estimativa com a realidade (ex.: "carros normais no máximo 1,2 g" foi refutado por um carro comercial que acelera de 0 a 100 em 1,8 s, então use 1,5 g).
• Não use fotos de marcas ou logotipos; use ilustrações próprias e marque como "Ilustração".
• Enquanto pesquisa, anote pistas de imagens: existem "precedentes", "veteranos" ou "fotos de experimentos" que possam servir como evidência (ex.: fotos históricas da NASA, produtos similares já existentes)? Essas serão as fotos reais a serem buscadas na seção 7.5.

2. Levantamento de Requisitos (Conforme a Camada de Intenção do /hyperframes, Pergunte Tudo de Uma Vez)

Confirme: plataforma de exibição (determina a proporção: aula/YouTube → 16:9), duração (recomendado 60–90 segundos; o comprimento da narração determina a duração real), se deseja narração (recomendado), se deseja revisar o storyboard primeiro, automatizado ou ajuste manual.

Pergunte também sobre as três cores (novo neste skill), como em um template de apresentação:

• Cor de fundo, cor principal (texto e traços), cor de destaque (apenas para respostas, conclusões, números-chave e cartões de seção).
• Se não houver preferência, recomende: fundo preto #121212, texto branco #F2F0EA, destaque laranja #FF7A1A.
• Fonte: use a mesma fonte em todo o vídeo. O padrão é GenSeki Gothic Bold (licença OFL, para chinês, inglês, números e legendas). Se o usuário especificar outra fonte, verifique se ela pode ser usada livremente.
• Escreva as cores e a fonte em theme.json do projeto (formato conforme templates/theme.example.json, com bg/fg/accent/font).

Compile um resumo de requisitos com duas seções: "Respostas do Usuário" e "O que Inferi". Só comece após o usuário confirmar.

3. Criar Projeto e Storyboard

1. hyperframes init videos/<kebab-name> --non-interactive --example=blank --skill=faceless-explainer, depois escreva o BRIEF.md e siga os Passos 0–2 do /faceless-explainer (capture/extracted/, escolha um frame preset para gerar frame.md).
2. Ao escolher o preset, priorize os com traços nítidos (ex.: cobalt-grid). Ele é apenas a "paleta de origem" — depois será substituída pelas três cores do usuário via theme.py.
3. Em frame.md, adicione sobrescritas para chinês tradicional (fonte, peso, espaçamento, altura da linha, tamanho mínimo para projetor), conforme seção 5 do skill motion-design.
4. Execute bash scripts/fetch_fonts.sh <projeto> para baixar GenSeki Gothic Bold (do realease oficial no GitHub), fontes Latinas usadas pelos workers e Noto TC, colocando tudo em assets/fonts/. Não dependa de carregamento online do Google Fonts.
5. Escreva STORYBOARD.md e SCRIPT.md (formato conforme storyboard-format / script-format oficiais). A narração deve ser dividida por orações; cada vírgula é um ponto de revelação na tela. Escreva números por extenso ("zero vírgula oitenta e um segundos") para o TTS não errar a pronúncia.

4. Narração

1. Gere assets/voice/raw/NN.wav (um arquivo por frase, NN é o número do quadro no storyboard):
   • edge-tts: python scripts/edge_tts_voice.py --project <p> --voice zh-TW-HsiaoChenNeural [--rate -5%]. Use a mesma voz em todo o vídeo para consistência; --list zh-TW lista todas as vozes.
   • Breeze TTS 2: python scripts/breeze_voice.py --project <p> --breeze-repo … --model … --voice "<descrição da voz>" --only-ref — primeiro crie uma voz de referência para o usuário ouvir; após confirmação, remova --only-ref para gerar todas as frases (cada uma copia a voz de referência). Se houver um runner em lote, use scripts/tts_jobs.py para gerar a lista de tarefas.
   • Se o usuário ainda não instalou ou não sabe qual escolher: siga as recomendações em references/tts-setup.md, passo a passo, sem instalar nada por conta própria.
2. Deixe o usuário ouvir as primeiras uma ou duas frases; o sotaque e a emoção são julgados pelo ouvido, não por métricas. Se não agradar, troque de voz ou ajuste a velocidade, apague os WAVs antigos e regere.
   • Se, após o vídeo pronto, uma palavra for pronunciada errada (ex.: nome de marca em inglês, homógrafo): não regrave a frase inteira — isso alteraria a duração do quadro e dessincronizaria a animação. Em vez disso, gere 4–6 candidatos da mesma frase com a mesma voz, variando seed ou grafia (ex.: Road-ster ou caractere homófono); mantenha a legenda original. Coloque em assets/voice/fix/cand/NN_X.wav. Execute python scripts/fix_voice.py --project . audition --line N --clauses <oração onde está a palavra> para concatenar os trechos-chave em um arquivo de audição para o usuário escolher. Após a escolha, execute apply --line N --take NN_X: ele estica/encolhe a nova frase inteira para a duração original, ajusta o volume para igualar a frase original e recalcula os tempos de legenda — a duração de cada quadro permanece inalterada. Em seguida, reconstrua as legendas → patch_captions.py → apague .hyperframes/pre-theme/compositions/captions.html (senão theme.py usará as legendas antigas) → theme.py → place_media.py → re-exporte. Não divida a frase regravada em orações e tente alinhar os cortes: as pausas na regravação estarão em posições diferentes, e os cortes cairão no meio das palavras, causando omissões ou repetições (já ocorreu em testes). Use ASR apenas para filtrar erros óbvios; ASR não detecta tom (exemplo real: "輪胎" foi considerado correto pelo ASR, mas o usuário percebeu o erro).
3. python scripts/voice_meta.py --project <p>: remove silêncio inicial e final, mede a duração de cada oração e escreve audio_meta.json.
4. node <faceless-explainer>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
5. Loudness: o vídeo final deve ter aproximadamente −14 LUFS, true peak ≤ −1 dBFS. Se a narração estiver muito baixa, aplique o mesmo ganho com um limitador, preservando os volumes relativos entre as frases.

5. Design de Cena (Passo 4)

• Em shots.json (veja templates/shots.example.json), para cada quadro, escreva "qual oração → o que aparece na tela". Execute python scripts/apply_shots.py --project <p> para converter para segundos reais e atualizar STORYBOARD.md.
• O campo blueprint só pode ser <id> (Adapt), <id> (Reproduce) ou compose; explicações adicionais vão em note.
• Primeiro, use hyperframes catalog --query para encontrar componentes existentes; só crie do zero se não houver.
• Elementos que aparecem em vários quadros (carro, pessoa, instrumento) devem ser desenhados como um SVG compartilhado, com coordenadas fixas para cada parte. Todos os workers devem copiá-lo fielmente. Caso contrário, o elemento aparecerá diferente em cada quadro.

6. Processamento Paralelo de Cada Quadro

1. node <faceless-explainer>/scripts/frame-packets.mjs --project <p> --storyboard <p>/STORYBOARD.md
2. Copie templates/dispatch_context.md para .hyperframes/frame-packets/_dispatch_context.md e preencha os valores do projeto: direção do vídeo, materiais compartilhados, regras de tempo, fonte.
3. Atribua um sub-agente para cada quadro, todos em paralelo. O prompt lê, em ordem: _role.md → _dispatch_context.md → packet do quadro → frame.md → materiais compartilhados.
4. Quando quadros adjacentes continuam a mesma cena (ex.: mesma régua graduada), o quadro que terminar primeiro deve repassar a geometria exata para o quadro ainda em andamento.
5. Após todos retornarem: python scripts/unify_frames.py --project <p> para unificar fontes e posições de fios.

7. Montagem, Legendas e Paleta de Cores

node <fe>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
node <fe>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json
python scripts/patch_captions.py --project .     # Ajusta fonte e peso das legendas em chinês (padrão Bold 700)
python scripts/theme.py --project .              # Aplica as três cores e fonte do theme.json (índice, cada quadro, legendas)
node <fe>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
node <fe>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
hyperframes lint && hyperframes check

(<fe> = diretório do skill faceless-explainer instalado.) Toda vez que as legendas forem reconstruídas, execute novamente patch_captions.py e theme.py. O theme.json define accents para indicar quais elementos em cada quadro usam a cor de destaque (block/fill/text); font substitui todas as fontes (quadros e legendas) pela mesma fonte e peso, sobrescrevendo as configurações originais dos workers. Após trocar a fonte, os caracteres podem ficar mais largos; execute hyperframes check para verificar se há overflow ou sobreposição.

Por último, reduza o tamanho das fontes: python scripts/subset_fonts.py --project .. Ele mantém apenas os caracteres chineses usados no vídeo (reduzindo fontes CJK de 12–17 MB para algumas centenas de KB) e atualiza os @font-face de cada quadro para apontar para o arquivo reduzido. Qualquer alteração de texto, legenda ou cor deve ser seguida por: theme.py (aplica do zero sobre os arquivos originais pré-cor, que apontam para a fonte completa; caracteres novos que não estejam na fonte reduzida cairão para a fonte do sistema).

7.5 Camada de Imagens (Novo Neste Skill)

Regras completas em references/images.md. Pontos principais:

1. Planejamento: 3–5 imagens por vídeo. Fotos reais como cartões de evidência ("alguém realmente fez isso"), imagens geradas por Codex como fundo de abertura e encerramento. A animação é o foco principal; as imagens não podem roubar a cena do conceito explicado.
2. Buscar fotos: python scripts/find_images.py search "<palavra-chave>" → get "File:…" --name <nome_curto> --project .. Aceite apenas domínio público, CC0, CC BY, CC BY-SA; a fonte é automaticamente registrada em assets/images/web/CREDITS.md. Após o download, revise visualmente: remova transeuntes, logotipos de outras marcas e marcas d'água.
3. Gerar ilustrações: escreva os prompts em gen_prompts.json (veja templates/gen_prompts.example.json) e execute python scripts/codex_images.py --project .. Requer o Codex CLI logado localmente, que usa image_gen integrado — não precisa de chave de API. Após a geração, revise visualmente para verificar se há texto ou logotipos indesejados. Se não houver Codex, informe ao usuário que pode usar outra ferramenta de geração de imagens e colocar os PNGs em assets/images/gen/.
4. Aplicar cor: em media.json, defina o corte, tamanho e modo de cada imagem (fotos: duotone, imagens geradas: keep). Execute python scripts/treat_images.py --project ..
5. Posicionamento: após a contact sheet de cada quadro estar finalizada, identifique áreas realmente vazias. Em media.json, em placements, escreva: frame, mode (card/background), box, at, label, credit. Para substituir um traço existente pela foto, use hide. Em seguida, após theme.py, execute python scripts/place_media.py --project ..
6. Indicação na tela: fotos mostram "Foto: Autor · Licença · Fonte"; imagens geradas mostram "Ilustração gerada por AI".
7. Execute hyperframes check (contraste de texto sobre fotos, sobreposições). Por último, execute subset_fonts.py, pois as legendas das imagens e créditos também contêm texto.

7.6 Camada de Vídeos AI (Novo Neste Skill)

Regras completas em references/ai-video.md. Pontos principais:

1. Planejamento: 2–4 segmentos por vídeo. Use na abertura (gancho), para uma ação impossível de filmar mas que combina com a narração (ex.: "só pode pular uma vez" → carro caindo) e no encerramento (emoção). Cenas que exigem números precisos ou direção de forças ainda devem ser feitas com traços.
2. Primeiro quadro com imagem estática do Codex: primeiro, gere uma imagem no tema de cores do vídeo conforme seção 7.5; o H3 animará a partir dessa imagem, garantindo consistência de estilo.
3. Escrever especificação: assets/videos/gen/specs/<nome>.json (exemplo em templates/video-specs/). Cada segmento: 4–15 segundos, sujeito "sem marcas, sem texto", ação descrita como um evento claro, mais movimento de câmera e descrição de som.
4. Gerar: python scripts/ai_video.py prompt --project . (formato oficial de seis parágrafos) → run (requer um runner configurado em video_config.json, veja templates/video_config.example.json). Se não houver runner, forneça ao usuário o prompt.txt e o primeiro quadro, peça para ele gerar usando o template MiniMax H3 R2V oficial do ComfyUI e salvar como assets/videos/gen/<nome>/clip.mp4.
5. Verificar: python scripts/ai_video.py check --project .. Cada check-1.png deve ser inspecionado visualmente: há distorção, peças extras, texto ou logotipos? O tempo da ação corresponde à narração? Se reprovado, troque a seed e regere.
6. Posicionamento: em media.json, em placements, use "video": "assets/videos/gen/<nome>/clip.mp4", adicione duration e, se necessário, out (desvanecer o cartão antes do fim do vídeo). Após theme.py, execute place_media.py, depois hyperframes lint (vídeos precisam de id e não podem estar dentro de elementos temporizados) e hyperframes check.
7. Indicação na tela: "Vídeo gerado por AI (H3)"; todos os vídeos são silenciados — o áudio é apenas a narração.

8. Revisão (review-loop)

• Primeiro execute hyperframes check; depois renderize o vídeo completo em qualidade draft (hyperframes render --quality draft --workers <valor recomendado por hw_check>; sempre use draft durante a revisão). Capture um quadro 0,15 segundos antes do final de cada oração (para obter o estado finalizado) e use review-loop/scripts/sheet.py --video … --at … para montar uma contact sheet. Inspecione cada quadro visualmente.
• Verifique item por item da lista em references/lessons.md. Após correções, re-renderize e revise novamente até que não haja problemas em uma rodada completa.
• Só então renderize a versão final: hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4 e meça a loudness novamente.

9. Entrega

Entregue o caminho do MP4, duração, uma contact sheet geral e uma lista com: quais fontes foram usadas, quais números são declarações oficiais, quais são estimativas, quais pontos diferem dos requisitos (ex.: duração excedida) e o que não foi feito (ex.: sem trilha sonora).