O que Vídeo Explicativo de Produto faz?
O usuário aponta para algo que construiu; você entrega um explicador animado e polido com narração que um estranho entende em menos de um minuto. O vídeo deve ser projetado para este projeto: sua própria metáfora visual, suas próprias animações personalizadas. Nunca produza um vídeo genérico com os nomes trocados.
analisar (fatos) → brief de design → storyboard.json (cenas integradas + personalizadas) → validar → contato-QA → corrigir → renderizar (+voz, +música) → entregar
Os scripts estão em scripts/ ao lado deste arquivo. $SK = a pasta desta skill (onde este SKILL.md está).
0. Verificação de configuração (10 segundos)
python3 -c "import playwright, PIL, numpy" && which ffmpeg && python3 $SK/scripts/voiceover.py --list
Peças faltando: pip install playwright pillow numpy edge-tts --break-system-packages && playwright install chromium. Sem ffmpeg → avise o usuário (necessário para MP4; --html-only ainda fornece o player HTML). A --list do voiceover mostra quais mecanismos de fala funcionam agora.
1. Entender o que explicar
Inferir primeiro, perguntar raramente: assunto (um produto ou um portfólio), público/propósito (desenvolvedores no GitHub, clientes, redes sociais), fonte (caminho local, zip enviado, URL do GitHub, site ativo ou apenas uma descrição). Padrões: 16:9, 45–75 s, desenvolvedores mais espectadores não técnicos curiosos, narração ativada. Faça uma pergunta curta apenas se for verdadeiramente ambíguo (ex.: 15 repositórios, sem dica de qual). Caso contrário, declare a suposição em uma linha e vá em frente. Não entreviste o usuário.
2. Coletar fatos (nunca pule: isso mantém o vídeo honesto)
python3 $SK/scripts/analyze_project.py /caminho/ou/git-url [mais...] -o facts.json
python3 $SK/scripts/capture_site.py https://site-deles.com -o site-capture # sites ativos: capturas de tela + fatos da página
O analisador imprime descrição, linguagens, capacidades, comandos reais do README, flags da CLI, rotas, domínios contatados, saídas, variáveis de ambiente, CI/cron e ESTATÍSTICAS REAIS seguras para mostrar. Leia, depois leia o README e 1–3 arquivos de código-fonte chave você mesmo quando os fatos forem escassos (qual é o loop principal? o que o usuário realmente executa? como é a saída?). Falha no clone ou rede desligada → peça um zip ou o README. Captura de site bloqueada → peça capturas de tela ou desenhe uma interface com cenas personalizadas.
3. Brief de design, depois o storyboard
Leia references/narrative-playbook.md (arco, regras de veracidade), references/storyboard-schema.md (todos os tipos/campos de cena) e references/custom-scenes.md (como escrever cenas personalizadas). Storyboards de referência em assets/examples/ mostram como é um bom trabalho; são inspiração, não modelos: não reutilize o conteúdo, estrutura ou redação deles.
Primeiro decida (anote brevemente):
- A promessa em uma frase.
- O que o produto fisicamente faz (coisas se movendo entre lugares) e a metáfora visual única que o mostra.
- A cena do momento "ahá!".
- Tema, cor de destaque (a cor da marca do usuário, se conhecida), estilo
bg, ritmo: combinado com a personalidade do produto. - Quais 2–4 cenas serão personalizadas (desenhadas para este produto) e quais batidas genéricas usam componentes integrados (título, problema, passos, cta...).
Depois escreva storyboard.json:
- Arco: gancho → problema → como funciona → prova de que é simples → resultado tangível → por que é bom → CTA; 7–10 cenas, 45–75 s.
- Padrão de qualidade: pelo menos uma cena é personalizada, a menos que o produto seja verdadeiramente uma CLI simples; a cena do momento "ahá" é sempre personalizada ou um componente integrado cuidadosamente escolhido. Um bot mostra uma conversa; um scraper mostra uma página se transformando em linhas; uma API mostra uma requisição e resposta; um dashboard mostra números ao vivo.
narrationem cada cena: estilo falado, 15–35 palavras. Torna-se a narração, legendas e SRT.- Apenas a verdade: comandos, flags, recursos, rotas e números vêm dos fatos ou do usuário. A saída do terminal e linhas de tabela podem ser ilustrativas, mas genéricas; nunca invente benchmarks, contagens de clientes ou capacidades. Cenas de estatísticas usam apenas números de
ESTATÍSTICAS REAIS/README/usuário. - Defina
meta.urlpara o repositório/site e termine com um CTA claro.
4. Validar, depois verificar antes de renderizar
python3 $SK/scripts/storyboard.py explainer/storyboard.json
python3 $SK/scripts/render_video.py explainer/storyboard.json --contact-sheet
A folha de contato (~20 s) executa a auditoria de layout (texto fora do palco, cortado, truncado, colidindo com legendas e erros de JS em cenas personalizadas) e escreve explainer-output/contact-sheet.png. Veja-a e verifique: nada apertado ou cortado, texto legível, cenas visivelmente diferentes umas das outras, cenas personalizadas parecem intencionais. Uma folha de contato mostra um quadro tardio por cena, portanto, para cada cena personalizada, inspecione também um quadro inicial e um intermediário: --still 3.2,6.5. Corrija e repita até que esteja limpo.
5. Renderizar com narração
cd explainer
setsid nohup python3 $SK/scripts/render_video.py storyboard.json --quality final --gif \
> render.log 2>&1 < /dev/null &
sleep 100; tail -c 300 render.log
Continue perguntando (sleep 100; tail -c 300 render.log) até CONCLUÍDO. Em ambientes isolados (claude.ai), o trabalho em segundo plano avança apenas enquanto uma chamada de ferramenta está em execução, portanto, a consulta com sono impulsiona a renderização; não termine sua vez enquanto ela estiver em execução. Predefinições: draft (960×540, 15 fps), standard (1280×720, 30 fps, padrão), final (1920×1080, 30 fps). Mais núcleos de CPU → mais rápido (--workers N). Vertical: meta.aspect: "9:16" ou --vertical. Máquina lenta: --fps 24.
A narração é automática (--voice auto, padrão). O renderizador gera um arquivo de áudio por cena, estica as cenas para que a narração nunca seja cortada, abaixa a música sob a voz e armazena em cache o áudio para que re-renderizações sejam gratuitas. Prioridade do mecanismo: ElevenLabs (ELEVENLABS_API_KEY) → OpenAI TTS (OPENAI_API_KEY) → Vozes neurais da Edge (pip install edge-tts, gratuito, sem chave, precisa de internet) → Piper (neural offline) → say do macOS → espeak-ng. Opções: --voice-name en-US-AndrewNeural (nome de voz de qualquer mecanismo), --voice-rate +8% (Edge), --voice none apenas para música, --voice-dir pasta/ para usar os próprios arquivos scene-01.mp3… do usuário, meta.voice para armazenar a escolha no storyboard.
Se a renderização imprimir AVISO voiceover: nenhum mecanismo de fala disponível, o vídeo ainda foi renderizado (apenas música) e voiceover.txt tem o script. Informe o usuário claramente, com a correção de uma linha: ative a internet e pip install edge-tts (gratuito), ou defina uma chave de API, ou instale o espeak-ng; em seguida, execute novamente o mesmo comando (apenas voz e codificação são refeitas; o player e o storyboard permanecem inalterados). No claude.ai, o ambiente isolado geralmente não tem internet, então espere isso: diga isso, entregue o vídeo silencioso com música e o script, e explique que eles podem adicionar voz executando o pipeline localmente no Claude Code ou com uma chave de API. Nunca afirme que o vídeo tem narração a menos que o log diga voiceover: usando '<engine>'.
Música: gerada livre de royalties (--mood calm|upbeat|tech ou meta.music_mood); --music none ou --music file.mp3.
6. Entregar
Saídas em explainer-output/: <nome>.mp4, <nome>-poster.png, player.html (player interativo autossuficiente; incorpore com <iframe src="player.html?embed">; ele tem movimento e legendas, mas sem áudio), captions.srt, voiceover.txt, storyboard.resolved.json, voice/, .gif opcional.
Verifique: ffprobe -v error -show_entries stream=codec_type -of csv=p=0 <nome>.mp4 mostra um fluxo de áudio; duração corresponde; veja o poster. Copie os entregáveis para /mnt/user-data/outputs/ e present_files com o MP4 primeiro, depois poster, legendas, player.html e storyboard.json (para que possam editar e re-renderizar). Mantenha a mensagem curta: uma linha por cena, o que foi assumido, qual mecanismo de voz foi usado, como ajustar. Ofereça variantes apenas quando útil: um corte social 9:16 (~30 s), uma voz ou cor de marca diferente, um vídeo para outro repositório.
Edição e re-renderização
Edite storyboard.json (texto, ordem, cores, código de cena personalizada), execute novamente a folha de contato, depois renderize. Mudanças na narração ressintetizam apenas as cenas alteradas. Defina a duration de uma cena para alongá-la; ela nunca é encurtada abaixo do que a animação e a narração precisam.
Portfólio / "todas as minhas ferramentas"
Analise cada repositório em uma chamada, escolha 3–4 carros-chefe que mostrem variedade, dê a cada um uma cena personalizada ou de melhor ajuste com sua própria metáfora visual, feche com uma grade features do restante e um CTA para o perfil. Ofereça vídeos de mergulho profundo por produto depois.
Solução de problemas
Playwright is not installed→ comando do passo 0.- Quadros pretos/brancos ou linhas de
scene error→ o JS de uma cena personalizada lançou uma exceção; a auditoria imprime a exceção. Corrija o código. - Texto cortado/truncado → encurte, remova itens ou crie um layout personalizado.
- Voz robótica → é o espeak; use Edge/OpenAI/ElevenLabs/Piper.
- Voz não corresponde ao tempo da cena → o tempo é automático (as cenas se estendem para o áudio); se as legendas parecerem adiantadas, encurte a narração.
- Log não se move / renderização morta → foi executado anexado ou nada consultou; reinicie desanexado e consulte.
- Saída muito longa → remova as cenas mais fracas; o validador avisa acima de ~90 s.
Limites honestos
Gráficos em movimento (diagramas, terminais, código, maquetes de interface, animação personalizada), não gravações de tela ou filmagens fotorrealistas. Para interface real, passe capturas de tela ou desenhe a interface. A qualidade da voz depende do mecanismo disponível.