Habilidad de Video Explicativo (Hellboy)
Conviertes un tema técnico en un MP4 terminado de 2 a 3 minutos a 1080×1920 que una persona no técnica entiende a la primera. El estilo visual, el ritmo y la estructura del guion están clonados de un canal de referencia (analizado en docs/01-style-bible.md). Dos cosas son deliberadamente nuestras: el personaje (Hellboy) y la voz.
Solo escribes archivos de texto (un guion y un storyboard.json). El motor en engine/ se encarga de la voz, los subtítulos, la animación, el personaje, la música y la renderización.
Cuando el usuario solo da un tema
Haz todo el trabajo sin hacer más preguntas:
- Crea un slug a partir del tema (
como-funciona-dns) y ejecutapython engine/make_video.py new videos/<slug>. - Escribe
videos/<slug>/script.md(docs/02), luegovideos/<slug>/storyboard.json(docs/03 + docs/04). Copia patrones deexamples/upi-explained/. - Ejecuta
python engine/validate_storyboard.py videos/<slug>. Corrige cada ERROR y repite hasta que imprima0 error(s). - Ejecuta
python engine/make_video.py preview videos/<slug>. Si puedes ver imágenes, revisabuild/preview.pngcontra docs/06 sección B y corrige. - Ejecuta
python engine/make_video.py render videos/<slug>. Responde con la rutaoutput/<slug>.mp4, la duración y un resumen de 2 líneas.
Los puntos no negociables
- Hellboy nunca se redibuja. Proviene únicamente de
character/hellboy/hellboy.js. Solo puedes establecershow,arm(down/point/explain) yexpression, nada más. Leecharacter/hellboy/CHARACTER_BIBLE.mduna vez. - La voz es fija en
engine/config.json. No la cambies por video. - Duración: 360–470 palabras de narración, 2:00–2:50. Oraciones ≤ 20 palabras.
- Cada oración cambia algo en pantalla. Los elementos aparecen en su palabra clave hablada (
"at"). - Correcto supera a simple. Simplifica omitiendo cosas, nunca diciendo algo falso.
- El validador debe pasar (
0 errores) antes de renderizar.
Flujo de trabajo (hazlos en orden)
| # | Paso | Lee | Salida |
|---|---|---|---|
| 1 | Andamio | – | python engine/make_video.py new videos/<slug> |
| 2 | Planifica + escribe el guion | docs/02-script-writing.md | videos/<slug>/script.md (360–470 palabras, 7 latidos) |
| 3 | Planifica los visuales | docs/03-visual-planning.md | lista de escenas: narración → tipo, titular, personaje |
| 4 | Escribe el storyboard | docs/04-storyboard-reference.md | videos/<slug>/storyboard.json (o meta.json + scenes.jsonl → assemble) |
| 5 | Valida | – | python engine/validate_storyboard.py videos/<slug> → corrige hasta 0 errores |
| 6 | Vista previa + QA | docs/06-qa-checklist.md | make_video.py preview videos/<slug> → inspecciona build/preview.png, corrige |
| 7 | Renderiza | docs/05-production.md | make_video.py render videos/<slug> → output/<slug>.mp4 |
| 8 | QA final | docs/06-qa-checklist.md | puntuación ≥ 85, todos los elementos OBLIGATORIOS pasan |
¿Modelo pequeño/local? Sigue docs/07-small-model-playbook.md en lugar de los pasos 2–5. Divide el trabajo en instrucciones de una escena a la vez.
El guion de 7 latidos (memoriza)
Enganche (≤ 22 palabras: "X explicado." / "¿Cómo funciona realmente X?" / afirmación sorprendente / acción relatable) → Tensión (el misterio) → Hoja de ruta ("Sigamos…") → Cuerpo (3–6 capítulos: concepto → significado simple → ejemplo cotidiano → consecuencia; UN ejemplo continuo con una persona nombrada) → Giro ("Pero aquí está la parte interesante…") → Resumen ("Así que recuérdalo así." una línea por capítulo) → Remate (fragmentos que repiten el enganche: "Un escaneo. Cuatro jugadores. Dos segundos.").
Receta de escena (memoriza)
- 1 escena = 1–3 oraciones (8–28 palabras, 3–8 s); 20–32 escenas por video.
- Elige
visual.typede la tabla de decisión endocs/03-visual-planning.md. Usa 7–12 tipos diferentes por video. - Muestra a Hellboy en el 40–70 % de las escenas (siempre: primera escena, giro, resumen, última escena). Ocúltalo para
sequence,hub,diagram,compare. - Construye diagramas grandes en 2–4 escenas con elementos
"continue": true+"shown": truey el mismo titular. - Titulares de 2–6 palabras con una palabra de acento. Etiquetas en pantalla de 1–4 palabras.
Comandos (desde la raíz del repositorio)
# activa primero: source .venv/bin/activate | Windows: .\.venv\Scripts\Activate.ps1
python engine/make_video.py new videos/<slug> # plantillas
python engine/make_video.py assemble videos/<slug> # meta.json + scenes.jsonl -> storyboard.json
python engine/validate_storyboard.py videos/<slug> # debe ser 0 errores
python engine/make_video.py preview videos/<slug> # build/preview.png (1 fotograma por escena)
python engine/make_video.py render videos/<slug> [--fast]
Primera vez en una máquina: ./setup.sh (Linux/macOS) o setup.ps1 (Windows). Los videos terminados se guardan en output/<slug>.mp4.
Material de referencia
examples/upi-explained/(papel cálido) yexamples/load-balancer-explained/(plano) — ejemplos completos ya resueltos. Copia sus patrones.templates/—script.template.md,storyboard.template.json.docs/01-style-bible.md— lo que hace la referencia, medido (por qué existen las reglas).engine/icon_names.txt— todos los 2359 nombres de iconos permitidos (Lucide).