NoRoboto/toon-explainer

Contrato de Ativação

Carregue quando o usuário quiser um clipe explicativo 3D cartoon / cel-shaded (cores chapadas, contornos pretos, objetos aparecendo, câmera em movimento, legendas grandes), quiser reproduzir um vídeo no estilo "Stupy Doo", ou pedir para animar um diagrama no Blender a partir de texto.

Regras Rígidas

• Nunca gere os visuais com um modelo de IA de imagem/vídeo. O visual é geometria 3D + contornos Freestyle renderizados pelo Blender.
• Binário do Blender: ~/.local/bin/blender (5.1.x, instalação do usuário). Sempre execute headless com -b -P.
• O storyboard é a fonte única da verdade: storyboard.json (esquema em references/storyboard-schema.md). Edite o JSON, re-renderize. Nunca edite manualmente o arquivo .blend.
• Sempre verifique antes de renderizar o vídeo completo: renderize --stills em 3–5 pontos, monte uma folha de contato, leia-a, corrija sobreposições / objetos fora da câmera.
• Legendas e áudio são pós-processamento (mix.py, captions.py), nunca objetos de texto do Blender.
• Efeitos sonoros são posicionados nos tempos das ações via referências action: na seção audio, nunca segundos digitados manualmente quando uma ação existe.
• Narração em espanhol permanece neutra; o texto da interface/legendas segue o idioma do usuário.
• Mantenha os clipes curtos: 8–30 s por storyboard. Encadeie clipes com concat do ffmpeg para vídeos mais longos.

Portões de Decisão

Necessidade	Faça
Vídeo narrado	Narração primeiro, legendas sincronizadas com ela, depois animação. Voz via voice-video (tts.py) em audio.narration.
Efeitos sonoros / música	Seção audio: narração, música, efeitos com referências action:. Placeholders em assets/sfx/, fontes CC0 no README.
Música fornecida	beats.py snap storyboard.json --music track.mp3 --write antes dos stills.
Verificação rápida	--preview --stills t1,t2,t3 (meia resolução, 8 amostras).
Renderização final	Sem --preview; padrão 1080x1920, 30 fps.
Objeto não está nos prefabs	Prefabs: box, plane, cylinder, sphere, panel, panel_row, cable, device, car, charger, transformer, cloud, tree, pole. Caso contrário, primitivas ou model (glb/obj).
O quadro parece barato	Um assunto por tomada, câmera a 8–13 m, ambientação com tree/pole/cloud, cabos com draw depois flow. Veja references/style-notes.md.
Ajuste manual desejado	Adicione --blend, abra out/scene.blend na interface do Blender.

Etapas de Execução

1. Leia references/storyboard-schema.md e references/style-notes.md.
2. Escreva um pequeno gen.py que emita <workdir>/storyboard.json: objetos em um plano de chão em z=0, tomadas (um assunto cada), ações, legendas, post, audio.
3. Stills: ~/.local/bin/blender -b -P ~/.claude/skills/toon-explainer/assets/build.py -- storyboard.json out --preview --stills 1,3,5. Monte uma folha de contato com Pillow e leia-a.
4. Corrija enquadramento e temporização no JSON. Repita o passo 3 até que cada tomada seja legível.
5. Vídeo de pré-visualização: mesmo comando com --preview apenas. Verifique out/raw.mp4 com ffprobe (duração, fps).
6. Áudio (se audio presente): python3 ~/.claude/skills/toon-explainer/assets/mix.py storyboard.json out/mix.wav. Leia a tabela de cues.
7. Legendas + multiplexação: python3 ~/.claude/skills/toon-explainer/assets/captions.py storyboard.json out/raw.mp4 out/final.mp4 --audio out/mix.wav (ou --audio narration.wav sem audio).
8. Final: remova --preview, repita os passos 5–7. Abra out/final.mp4 com xdg-open.

Contrato de Saída

Retorne: caminho de storyboard.json, caminho de out/final.mp4, duração, resolução e uma linha por tomada descrevendo o que está na tela. Relate o tempo de renderização. Liste tudo que ainda não foi implementado (sincronia labial, concatenação de múltiplos clipes).

Referências

• references/storyboard-schema.md — esquema JSON, prefabs, ações, convenções de câmera.
• references/style-notes.md — aparência de referência, pegadinhas do Blender 5, o que consertou o corte barato, design de som.
• references/external/ — cópias MIT: EL4CTEO blender-stylized-npr, arjun988 camera-cinematography.
• assets/toonlib.py — biblioteca bpy (materiais, prefabs, câmera, animações).
• assets/build.py — storyboard → renderização Blender.
• assets/mix.py — seção audio para um WAV (música com duck, cues de efeitos).
• assets/beats.py — detecção de batida + ajuste de tempos de ação.
• assets/sfx/ — efeitos sonoros placeholders, fontes CC0.
• assets/captions.py — legendas com ffmpeg + multiplexação de áudio.
• assets/storyboard.example.json — exemplo de telhado solar, 9 s.