pranav7/video-explainers

Criador de Vídeos Explicativos

Crie um vídeo explicativo narrado, no estilo 3Blue1Brown, sobre qualquer tópico. Os visuais são feitos com Manim (Community Edition). A narração usa Kokoro-82M, um modelo local de texto-para-fala. Tudo roda na sua máquina, sem necessidade de chave de API. Cada linha de narração define o tempo da animação que a acompanha.

O trabalho tem duas partes:

1. Você escreve o script.md: cada linha de narração e o que aparece na tela enquanto ela é reproduzida. Você tem o contexto, então escreve o roteiro.
2. Um subagente constrói o vídeo a partir do script.md. Ele escreve as cenas, renderiza, verifica o layout e faz a renderização final.

A construção faz aproximadamente 20 chamadas de ferramenta, e cada chamada envia o contexto completo novamente. Um novo subagente tem um contexto pequeno, então a construção é mais barata e rápida lá. O subagente também roda em segundo plano, para que o usuário possa continuar trabalhando com você.

O comando explainer faz o resto do trabalho. Ele deve estar no PATH. Para configuração, veja https://github.com/pranav7/video-explainers. Execute explainer -h para ver os comandos.

0. Configuração (uma vez por máquina)

Execute explainer doctor. Ele instala pacotes Homebrew, fontes, TinyTeX, um ambiente Python e os ícones, depois testa Kokoro e LaTeX. É seguro executar novamente. Execute-o se um comando falhar por falta de dependência.

1. Planejamento

• Onde. Se a conversa for sobre um projeto que tem sua própria pasta para documentos, coloque o vídeo em uma pasta videos/<slug>/ lá. Caso contrário, use ~/Movies/explainers/<slug>/.
• Público e duração. Pergunte apenas se a solicitação não os tornar claros. Padrão: um adulto curioso sem conhecimento prévio no tópico, de 2 a 4 minutos.
• Tamanho do roteiro. Kokoro fala aproximadamente 170 palavras por minuto, então um vídeo de 3 minutos tem aproximadamente 500 palavras de narração. Escreva um capítulo para cada 30 a 45 segundos.

Escolha a estrutura que se encaixa no tópico.

Para um conceito (um algoritmo, uma ideia em matemática ou ciência):

1. Comece com uma pergunta ou problema concreto, não uma definição.
2. Construa intuição com um exemplo específico que o espectador possa ver.
3. Generalize, e só então mostre a fórmula. A fórmula nomeia o que eles já viram.
4. Termine com a ideia chave em uma imagem.

Para uma situação (uma execução que falhou, um incidente, um design, uma atualização de trabalho):

1. Comece com o que aconteceu, com os números reais.
2. Mostre o mecanismo que causou isso, um passo de cada vez.
3. Mostre o que muda: a correção, a decisão ou o próximo passo.
4. Termine com uma imagem de todo o sistema com a mudança implementada.

2. Escreva script.md

Escreva script.md no diretório do vídeo, neste formato:

# Por que a página de pedidos está lenta

Para engenheiros da equipe. Cerca de 3 minutos.

## Paleta

| Conceito | Cor |
| --- | --- |
| O servidor da API | SKY |
| O banco de dados | VIOLET |
| Trabalho lento e desperdiçado | CORAL |
| A correção | MINT |

## 1. Gancho: Cinquenta pedidos, cinquenta consultas

- "A página de pedidos leva quatro segundos para carregar cinquenta pedidos."
  - Um card de navegador com "4,1 s" em coral e uma lista de 50 tags de pedidos.
- "O servidor pergunta ao banco de dados uma vez para cada pedido."
  - Um card do servidor API e um card do banco de dados. Pacotes viajam entre eles, um por pedido.

Cada cabeçalho de capítulo é ## <número>. <NomeDaCena>: <título do capítulo>. O construtor cria uma classe de cena para cada capítulo. Os títulos dos capítulos se tornam marcadores de capítulo no vídeo.

O construtor não pode ver esta conversa. Coloque todos os nomes, números, rótulos e valores que aparecem na tela no roteiro.

A narração é lida em voz alta exatamente como escrita:

• Escreva a forma falada: "x ao quadrado", "dois pi r", "número P O", "v dois". Não coloque LaTeX, símbolos ou código na narração.
• Escreva uma frase para cada linha, no máximo duas. Cada linha é uma mudança visual.
• Se Kokoro pronunciar uma palavra incorretamente, dê seus fonemas inline: [Kokoro](/kˈOkəɹO/).
• A voz padrão é af_heart. Se o usuário se importar com a voz, execute explainer voices e deixe-o ouvir (afplay voice-samples/<nome>.wav).

Abaixo de cada linha, descreva a imagem, não um slide. Nomeie os objetos, o que eles mostram e o que se move. Dê a cada conceito uma cor da paleta.

Pegue as cores da paleta dos acentos do kit: SKY, MINT, AMBER, CORAL, VIOLET, AQUA, ROSE, PEACH, LIME. O kit também tem neutros para coisas que não são um conceito: SUBTLE, FAINT, INK. O kit tem cards, tags, tabelas, janelas de código, pipelines, diagramas de sequência, linhas do tempo, árvores, destaques, gráficos, números grandes e ícones Lucide. Descreva imagens que os usam.

Mostre cada número como ele é. Não peça um número que conte de zero para cima.

3. Passe a construção para o construtor

Inicie o construtor como um subagente. Se suas instruções nomearem um tipo de agente ou um modelo para trabalho de construção, use-os. Dê a ele este prompt:

Construa o vídeo explicativo para <diretório>/script.md. Execute `explainer guide` e siga-o. Informe o caminho do vídeo, sua duração e cada aviso de layout que você deixou no lugar, com o motivo.

Se o usuário pediu legendas, adicione "Renderize com --captions." ao prompt.

Diga ao usuário que o vídeo está em andamento e continue com outros trabalhos. Se você não puder iniciar um subagente, execute explainer guide e faça seus passos você mesmo.

4. Entrega

Quando o construtor relatar, abra <diretório>/video.mp4 (no macOS, open). Diga ao usuário:

• O caminho do arquivo e a duração.
• O vídeo tem marcadores de capítulo.
• Qualquer problema que o construtor deixou em aberto.

Pergunte o que mudar. Para fazer uma alteração, envie-a para o mesmo construtor se suas ferramentas puderem enviar uma mensagem para ele, porque o construtor mantém seu contexto. Caso contrário, inicie um novo construtor com a alteração. Se a alteração afetar a narração, edite script.md primeiro.