Toon Explainer

Contrato de Activación

Cargar cuando el usuario quiera un clip explicativo 3D estilo cartoon / cel-shaded (colores planos, contornos negros, objetos que aparecen, cámara en movimiento, subtítulos grandes), quiera reproducir un video estilo "Stupy Doo", o pida animar un diagrama en Blender a partir de texto.

Reglas Estrictas

• Nunca generar los visuales con un modelo de IA de imagen/video. El aspecto es geometría 3D + contornos Freestyle renderizados por Blender.
• Binario de Blender: ~/.local/bin/blender (5.1.x, instalación de usuario). Ejecutar siempre sin interfaz gráfica con -b -P.
• El storyboard es la única fuente de verdad: storyboard.json (esquema en references/storyboard-schema.md). Editar JSON, re-renderizar. Nunca editar manualmente el .blend.
• Siempre revisar antes de renderizar el video completo: renderizar --stills en 3–5 tomas, construir una hoja de contactos, leerla, corregir solapamientos/objetos fuera de cámara.
• Los subtítulos y el audio son post-procesamiento (mix.py, captions.py), nunca objetos de texto de Blender.
• Los efectos de sonido se sincronizan con los tiempos de acción mediante referencias action: en la sección audio, nunca escribiendo segundos manuales si existe una acción.
• La narración en español se mantiene neutra; el texto de la interfaz/subtítulos sigue el idioma del usuario.
• Mantener los clips cortos: 8–30 s por storyboard. Encadenar clips con ffmpeg concat para videos más largos.

Puertas de Decisión

Necesidad	Hacer
Video narrado	Narración primero, subtítulos sincronizados con ella, luego animar. Voz mediante voice-video (tts.py) en audio.narration.
SFX / música	Sección audio: narración, música, sfx con referencias action:. Marcadores de posición en assets/sfx/, fuentes CC0 en su README.
Música proporcionada	beats.py snap storyboard.json --music track.mp3 --write antes de los fotogramas.
Verificación rápida	--preview --stills t1,t2,t3 (media resolución, 8 muestras).
Render final	Sin --preview; 1080x1920 por defecto, 30 fps.
Objeto no en prefabs	Prefabs: box, plane, cylinder, sphere, panel, panel_row, cable, device, car, charger, transformer, cloud, tree, pole. Si no, primitivas o model (glb/obj).
El fotograma se ve mal	Un sujeto por toma, cámara a 8–13 m, adornos de árbol/poste/nube, cables draw luego flow. Ver references/style-notes.md.
Ajuste manual deseado	Añadir --blend, abrir out/scene.blend en la interfaz de Blender.

Pasos de Ejecución

1. Leer references/storyboard-schema.md y references/style-notes.md.
2. Escribir un pequeño gen.py que genere <workdir>/storyboard.json: objetos sobre un plano base en z=0, tomas (un sujeto cada una), acciones, subtítulos, post, audio.
3. Fotogramas: ~/.local/bin/blender -b -P ~/.claude/skills/toon-explainer/assets/build.py -- storyboard.json out --preview --stills 1,3,5. Construir una hoja de contactos con Pillow y leerla.
4. Corregir encuadre y tiempos en JSON. Repetir paso 3 hasta que cada toma se lea claramente.
5. Video de vista previa: el mismo comando solo con --preview. Verificar out/raw.mp4 con ffprobe (duración, fps).
6. Audio (si audio está presente): python3 ~/.claude/skills/toon-explainer/assets/mix.py storyboard.json out/mix.wav. Leer la tabla de pistas.
7. Subtítulos + multiplexado: python3 ~/.claude/skills/toon-explainer/assets/captions.py storyboard.json out/raw.mp4 out/final.mp4 --audio out/mix.wav (o --audio narration.wav sin audio).
8. Final: quitar --preview, re-ejecutar pasos 5–7. Abrir out/final.mp4 con xdg-open.

Contrato de Salida

Devolver: ruta de storyboard.json, ruta de out/final.mp4, duración, resolución, y una línea por toma describiendo qué hay en pantalla. Reportar tiempo de renderización. Listar cualquier cosa aún no implementada (sincronización de labios, concatenación de múltiples clips).

Referencias

• references/storyboard-schema.md — Esquema JSON, prefabs, acciones, convenciones de cámara.
• references/style-notes.md — Aspecto de referencia, problemas con Blender 5, cómo arreglar el corte económico, diseño de sonido.
• references/external/ — Copias MIT: EL4CTEO blender-stylized-npr, arjun988 camera-cinematography.
• assets/toonlib.py — Biblioteca bpy (materiales, prefabs, cámara, animaciones).
• assets/build.py — Storyboard → render Blender.
• assets/mix.py — Sección audio a un WAV (música con reducción de volumen, pistas SFX).
• assets/beats.py — Detección de ritmo + ajuste de tiempos de acción.
• assets/sfx/ — Efectos de sonido marcadores de posición, fuentes CC0.
• assets/captions.py — Subtítulos ffmpeg + multiplexado de audio.
• assets/storyboard.example.json — Ejemplo de panel solar en tejado, 9 s.