Habilidade de Vídeo Explicativo (Hellboy)
Você transforma um tópico técnico em um MP4 1080×1920 de 2 a 3 minutos que uma pessoa não técnica entende na primeira visualização. O estilo visual, o ritmo e a estrutura do roteiro são clonados de um canal de referência (analisado em docs/01-style-bible.md). Duas coisas são deliberadamente nossas: o personagem (Hellboy) e a voz.
Você só escreve arquivos de texto (um roteiro e um storyboard.json). O mecanismo em engine/ cuida da voz, legendas, animação, personagem, música e renderização.
Quando o usuário fornece apenas um tópico
Faça todo o trabalho sem fazer mais perguntas:
- Crie um slug a partir do tópico (
como-dns-funciona) e executepython engine/make_video.py new videos/<slug>. - Escreva
videos/<slug>/script.md(docs/02) e depoisvideos/<slug>/storyboard.json(docs/03 + docs/04). Copie padrões deexamples/upi-explained/. - Execute
python engine/validate_storyboard.py videos/<slug>. Corrija cada ERRO e repita até que imprima0 error(s). - Execute
python engine/make_video.py preview videos/<slug>. Se você conseguir ver imagens, verifiquebuild/preview.pngcom base na seção B do docs/06 e corrija. - Execute
python engine/make_video.py render videos/<slug>. Responda com o caminhooutput/<slug>.mp4, a duração e um resumo de 2 linhas.
Os itens não negociáveis
- Hellboy nunca é redesenhado. Ele vem apenas de
character/hellboy/hellboy.js. Você pode definirshow,arm(down/point/explain) eexpression, nada mais. Leiacharacter/hellboy/CHARACTER_BIBLE.mduma vez. - A voz é fixa em
engine/config.json. Não a altere por vídeo. - Duração: 360–470 palavras de narração, 2:00–2:50. Frases com ≤ 20 palavras.
- Cada frase muda algo na tela. Os itens aparecem na palavra-chave falada (
"at"). - Correto supera simples. Simplifique omitindo coisas, nunca dizendo algo falso.
- O validador deve passar (
0 erros) antes da renderização.
Fluxo de trabalho (faça nesta ordem)
| # | Etapa | Leia | Saída |
|---|---|---|---|
| 1 | Scaffold | – | python engine/make_video.py new videos/<slug> |
| 2 | Planejar + escrever o roteiro | docs/02-script-writing.md | videos/<slug>/script.md (360–470 palavras, 7 batidas) |
| 3 | Planejar os visuais | docs/03-visual-planning.md | lista de cenas: narração → tipo, título, personagem |
| 4 | Escrever o storyboard | docs/04-storyboard-reference.md | videos/<slug>/storyboard.json (ou meta.json + scenes.jsonl → assemble) |
| 5 | Validar | – | python engine/validate_storyboard.py videos/<slug> → corrigir até 0 erros |
| 6 | Pré-visualizar + QA | docs/06-qa-checklist.md | make_video.py preview videos/<slug> → inspecionar build/preview.png, corrigir |
| 7 | Renderizar | docs/05-production.md | make_video.py render videos/<slug> → output/<slug>.mp4 |
| 8 | QA final | docs/06-qa-checklist.md | pontuação ≥ 85, todos os itens OBRIGATÓRIOS aprovados |
Modelo pequeno/local? Siga docs/07-small-model-playbook.md em vez das etapas 2–5. Ele divide o trabalho em prompts de uma cena por vez.
O roteiro de 7 batidas (memorize)
Gancho (≤ 22 palavras: "X explicado." / "Como o X realmente funciona?" / afirmação surpreendente / ação relacionável) → Tensão (o mistério) → Roteiro ("Vamos seguir…") → Corpo (3–6 capítulos: conceito → significado simples → exemplo cotidiano → consequência; UM exemplo contínuo com uma pessoa nomeada) → Reviravolta ("Mas aqui está a parte interessante…") → Recap ("Então lembre-se assim." uma linha por capítulo) → Frase de efeito (fragmentos que ecoam o gancho: "Uma varredura. Quatro jogadores. Dois segundos.").
Receita de cena (memorize)
- 1 cena = 1–3 frases (8–28 palavras, 3–8 s); 20–32 cenas por vídeo.
- Escolha
visual.typeda tabela de decisão emdocs/03-visual-planning.md. Use 7–12 tipos diferentes por vídeo. - Mostre Hellboy em 40–70% das cenas (sempre: primeira cena, reviravolta, recap, última cena). Esconda-o para
sequence,hub,diagram,compare. - Construa diagramas grandes ao longo de 2–4 cenas com
"continue": true+ itens"shown": truee o mesmo título. - Títulos com 2–6 palavras e uma palavra com acento. Rótulos na tela com 1–4 palavras.
Comandos (a partir da raiz do repositório)
# ative primeiro: source .venv/bin/activate | Windows: .\.venv\Scripts\Activate.ps1
python engine/make_video.py new videos/<slug> # modelos
python engine/make_video.py assemble videos/<slug> # meta.json + scenes.jsonl -> storyboard.json
python engine/validate_storyboard.py videos/<slug> # deve ter 0 erros
python engine/make_video.py preview videos/<slug> # build/preview.png (1 quadro por cena)
python engine/make_video.py render videos/<slug> [--fast]
Primeira vez em uma máquina: ./setup.sh (Linux/macOS) ou setup.ps1 (Windows). Os vídeos finalizados vão para output/<slug>.mp4.
Material de referência
examples/upi-explained/(papel-quente) eexamples/load-balancer-explained/(blueprint) — exemplos completos. Copie seus padrões.templates/—script.template.md,storyboard.template.json.docs/01-style-bible.md— o que a referência faz, medido (por que as regras existem).engine/icon_names.txt— todos os 2.359 nomes de ícones permitidos (Lucide).