Communitygithub.com

Vídeo Explicativo de Produto

Transforme qualquer projeto de software (repositório GitHub, pasta local, scraper, automação, bot, site, CLI, API ou um portfólio completo de ferramentas) em um vídeo explicativo animado e personalizado, com narração por IA, legendas e música. Analisa o código para extrair fatos reais, projeta animações específicas para o que o projeto faz (não um modelo fixo), verifica o layout, narra com voz neural e exporta um MP4 (paisagem ou retrato), legendas SRT e um player HTML incorporável.

O que é Vídeo Explicativo de Produto?

Esta skill cria vídeos explicativos animados e personalizados para projetos de software. Ela analisa o código-fonte (GitHub, pastas locais, sites, etc.) para extrair fatos reais sobre o projeto, como comandos, recursos, linguagens e estatísticas. Com base nessa análise, gera um storyboard único com uma metáfora visual específica para o produto, narração automática (usando a melhor engine de voz disponível), legendas e música de fundo. O resultado é um vídeo MP4 profissional (em paisagem ou retrato), legendas SRT e um player HTML interativo que pode ser incorporado em sites. A skill é útil para demos de produtos, vídeos de lançamento, walkthroughs, clipes para redes sociais (Reels, Shorts, TikTok, LinkedIn, X) e qualquer situação onde um desenvolvedor precise mostrar visualmente o que seu software faz, mesmo que não peça explicitamente um vídeo. Ela suporta projetos únicos ou portfólios completos, verificando rigorosamente a veracidade das informações e a qualidade do layout.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cheransanketh070-afk/claude-explainer-skill/tree/HEAD/product-explainer-video

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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):

  1. A promessa em uma frase.
  2. O que o produto fisicamente faz (coisas se movendo entre lugares) e a metáfora visual única que o mostra.
  3. A cena do momento "ahá!".
  4. Tema, cor de destaque (a cor da marca do usuário, se conhecida), estilo bg, ritmo: combinado com a personalidade do produto.
  5. 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.
  • narration em 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.url para 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.

Habilidades Relacionadas