jdrurka/explainer-skill

Explainer

Un video explicativo sin presentador es una voz en off sobre un mundo animado continuo, construido en código (un corte transversal, un mecanismo aumentado, una mano sosteniendo un objeto), con subtítulos en la parte superior y sin música. El resultado es un mp4 de 1080×1920.

Léelos antes de escribir:

• script-craft.md: cómo se da forma al guion (gancho, giro, imagina, mecanismo, remate, CTA) y su ritmo.
• craft-rules.md: qué hace que los visuales se sientan vivos y con profundidad. Un primer borrador competente rompe la mayoría de estas reglas.

La parte difícil es la metáfora visual para cada momento. La segunda más difícil es mantener cada fotograma en movimiento e iluminado con profundidad. El código es la parte fácil.

Modos

• Directo (predeterminado): ir del concepto al video final sin parar. Tú mismo tomas las decisiones y las reportas al final.
• Revisión: si el usuario pide revisar o aprobar, detente dos veces: después del guion y después del storyboard. Revisa según sus notas y continúa.

Verificación inicial (una vez)

ffmpeg en el PATH, remotion/node_modules presente (si no, ejecuta npm install en remotion/), y FISH_API_KEY en .env (copia .env.example). Sin clave, construye todo con voice --placeholder e informa al usuario de que el paso final es re-ejecutar voice y renderizar.

Estructura

projects/<concepto>/ (el concepto es un slug, como como-funcionan-las-neveras):

• script.txt, storyboard.md
• composition.tsx (pila de capas), timeline.ts (TL), captions.ts, words.ts (generado), scenes/S01.tsx …
• public/vo.wav, vo/ (toma original y alineación), out/ (renderizados, fotogramas)

La biblioteca central es remotion/src/core (las escenas la importan como ../../../remotion/src/core):

• makeTimeline → TL.at("frase"), TL.end("frase")
• Captions, Drift, Bokeh, Vignette, handheld, Backdrop, Dust, Footnote
• Camera (WorldSvg, camAt, toScreen), Label, Sparks, Snow / Rain
• easing, ramp, keys, rand, fuentes SANS / MONO

Herramientas: python3 bin/explainer.py … (ejecuta -h)

Comando	Hace
new <c>	Crea el proyecto
voice <c> [--voice-id ID] [--speed 1.0]	Toma de Fish Audio con marcas de tiempo de palabras → words.ts, además de public/vo.wav a −14 LUFS. Imprime el wpm
voice <c> --placeholder [--wpm 200]	Audio silencioso y tiempos sintéticos, sin llamada a la API
stills <c> <seg>…	Fotogramas en esos segundos → una hoja de contactos en out/. Revísala
studio <c>	Vista previa en vivo en Remotion Studio (para el usuario)
render <c> [--blur]	mp4 a 60 fps en out/. --blur renderiza a 240 fps y promedia a 60 para desenfoque de movimiento (~4× más lento)
qa <c>	Control de calidad: fotogramas congelados < 10 %, sin parón congelado ≥ 0,3 s. Termina con 1 si FALLA y nombra cada tramo congelado

Flujo de trabajo

1. Guion. Ejecuta new <c>.

   • Si el usuario dio un guion, úsalo palabra por palabra (corrige solo números y símbolos a palabras).
   • De lo contrario, escribe script.txt siguiendo script-craft.md: formato de objeto cotidiano por defecto (270–320 palabras), formato de sistema para productos y redes. Ejecuta su lista de verificación.
   • Modo de revisión: detente para aprobación.

2. Voz. Ejecuta voice <c>, luego verifica el wpm impreso (apunta a 190–215; re-ejecuta con el --speed sugerido si se desvía).

   • La voz es --voice-id, si no FISH_VOICE_ID, si no la predeterminada de Fish. El ID de una voz clonada funciona igual.
   • El modelo es --model, si no FISH_MODEL, si no s2.1-pro.
   • Base tu trabajo en words.ts, no en script.txt. La voz deletrea números, y TL.at() y las frases de los subtítulos deben coincidir con las palabras habladas.

3. Storyboard (storyboard.md). Completa primero la sección Mundo, luego una fila por momento. Para inventar la metáfora de un momento, pregúntate qué vería el espectador si pudiera:

   • Aumentar: una vista en corte o explotada.
   • Rayos X: dentro del objeto.
   • Cámara lenta: una onda viajando, una pieza cambiando de estado.
   • Medir: un indicador subiendo o bajando.

   El escenario "imagina" se convierte en el mundo de excursión, y cada momento de mecanismo regresa al diagrama principal. Ejecuta las verificaciones del storyboard.

   • Modo de revisión: detente para aprobación.

4. Construcción. Escribe un archivo de escena por toma del storyboard en scenes/ y añade cada uno a composition.tsx.

   • Cada escena es una función pura de t que devuelve null fuera de su ventana.
   • Tiempo: cada evento está sincronizado con TL.at("palabras exactas"). Nunca escribas segundos fijos.
   • Continuidad: los momentos que comparten un diagrama viven en UNA escena con UNA trayectoria de cámara (A4).
   • Movimientos: cada escena entra moviéndose, solapándose con la salida de la escena anterior (A2).
   • Prefija los IDs SVG por escena.

5. Iteración. Ejecuta stills en las palabras clave de cada toma y revísalos contra las reglas de diseño A y B. Luego ejecuta render y qa. Corrige cada tramo CONGELADO en su propia toma dándole un portador de movimiento (A1b). Escribe las frases de captions.ts a mano: un sustantivo clave resaltado (ámbar, aparece cuando se pronuncia) por frase.

6. Entrega. El render final debe pasar qa (usa --blur si el usuario quiere el máximo pulido). Entrega al usuario:

   • la ruta del mp4
   • el guion
   • un resumen de una línea por momento del storyboard
   • cualquier voz placeholder que aún necesite una toma real

Banderas rojas: detente y corrige

Pensamiento	Regla
"Un nuevo escenario para este momento lo mantiene fresco"	C1: un diagrama principal más 1–2 mundos de excursión. Cuéntalos
"Quédate completamente quieto en el remate para crear suspense"	A1c: detén el sujeto, mantén la cámara y el ambiente en movimiento
"Añade una pista musical, grano o un drop en el remate"	D, B8: solo voz, sin grano; la profundidad viene de la iluminación
"Fundido de entrada" / "encadenado a la siguiente escena"	A2: entra, sal y transiciona moviéndote
"El movimiento global lo mantendrá vivo"	A1b: cada toma necesita un motor de tamaño medio a 10–60 px/s
"Acercar la cámara para este momento" (mismo diagrama)	A4: un mundo, una cámara; pasa los fotogramas clave
"Iluminación uniforme está bien, es un diagrama"	B1: degradado hacia la oscuridad, luz de borde, viñeta
"Teñir todo cuando se activa"	B4: propaga desde la causa, con frente y flujo
"Un rectángulo está bien para el objeto"	B2: un pase de anatomía; construye lo que revelará un alejamiento
"Se ve bien, sáltate qa"	E: qa debe PASAR; el ojo no detecta congelados