makerjackie/short-film

Cortometraje programático (short-film)

Convierte un tema en un cortometraje: de aproximadamente 30 segundos (se puede ajustar entre 15 y 90 segundos), vertical a 1080×1920, 24 fps; alterna tomas de fondo de papel (paper plate) con estilo de tinta dibujada a mano y tomas de fondo de plano azul (blueprint plate); cada evento cae en una rejilla de compás (bpm → pulso → fotograma); cada píxel y cada muestra de audio se calcula con JavaScript puro en el navegador. El entregable es dist/<slug>.html (reproductor autónomo), exports/<slug>.mp4 (con sus versiones para móvil y previsualización), y un paquete de publicación: portada para TikTok (captura de HTML), título y descripción recomendados.

Este skill encapsula un pipeline ya verificado. Incluye tres componentes:

• foundation/ — Motores y herramientas que se copian al nuevo proyecto: src/core.js, src/lib.js, src/player.js, src/music.js (motor + banda sonora de ejemplo), y tools/ (construcción, verificación, captura, renderizado, stubgen, análisis de audio, paquete de publicación, fixtures). Todo está impulsado por src/timeline.js, por lo que cada cortometraje no necesita modificar el código de las herramientas.
• templates/ — Cuatro documentos de planificación inicial para cada cortometraje.
• reference/ — Se consulta según sea necesario: tipos de toma, anatomía de la escena, música, presets de plataforma; primero mira las tres imágenes de referencia.

Primero mira reference/: contact-sheet.jpg es la hoja de contacto completa del cortometraje de ejemplo (examples/llm-evolution, un estilo personalizado "ATLAS") — esa densidad de detalle y calidad es el estándar; paper-frame.jpg y blueprint-frame.jpg son un fotograma completo de cada uno de los estilos predeterminados (renderizados por tools/fixtures), los cortometrajes que usan el estilo predeterminado los toman como objetivo visual.

El ejemplo completo está en examples/llm-evolution/: un cortometraje de 24 tomas que va desde las neuronas hasta los grandes modelos de IA, incluye documentos de planificación, código fuente, dist/ y paquete de publicación. Observa que es un producto de estilo personalizado (se desvía del estilo papel × plano azul mediante un análisis de referencia), lo que demuestra la capacidad completa de este skill. Cuando una plantilla te haga dudar de cómo se ve un documento completo, ve allí y lee su contraparte.

El control (The gate)

node tools/check.cjs es el control: seis verificaciones (escaneo de medios, determinismo, escaneo de código fuente, línea de tiempo, dibujo, tiempo por fotograma), pasa si el código de salida es 0. Desde la fase de stubs, si el control está en rojo, ningún paso se considera completo. En escenarios reales tarda menos de un minuto — déjalo terminar.

Pipeline

0. Briefing (Brief)

Solo una ronda de preguntas: cuál es el tema, qué debe incluir el cortometraje sobre él, duración (por defecto 30 segundos), y en qué plataforma se publicará (determina la relación de aspecto y las zonas seguras, ver reference/platform-presets.md). El resto se inventa, indicando qué se ha inventado.

Criterio de finalización: el tema está redactado como una frase que el usuario ya ha visto, y la duración y plataforma están definidas.

1. Inicialización (Setup)

Crear una carpeta de proyecto con el slug del cortometraje y copiar foundation/ dentro. En tools/, ejecutar npm install (Playwright; si falta el navegador, añadir npx playwright install chromium), confirmar que ffmpeg está en PATH o establecer la variable FFMPEG con la ruta al binario. Copiar las plantillas a docs/, escribir el tema en el Goal de docs/CONTRACT.md.

Criterio de finalización: node tools/smoke.cjs pasa, node tools/check.cjs --fixtures está en verde, y node tools/render.cjs --fixtures --scale 0.5 produce exports/fixtures.mp4 con sonido. Este mini cortometraje fixtures demuestra que la cadena de herramientas funciona antes de invertir esfuerzo en la planificación.

2. Investigación (Research)

Listar las etapas de la historia del tema, hacer una búsqueda web por cada pregunta abierta, y guardar de dos a cuatro fuentes completas y autoritativas en .tmp/research/. La investigación solo llega a dos lugares posteriores: las referencias temáticas en la biblia de arte y la sección Subject de cada toma.

Criterio de finalización: cada etapa de la historia se puede rastrear hasta una fuente ya descargada.

3. Biblia de arte (Art bible)

Rellenar docs/art-bible.md según la plantilla. Las secciones 1–9 son el estilo predeterminado — ya están definidas; la sección 2.2 (paleta del tema, cada color es un hex con nombre y se refleja en el bloque anotado de src/lib.js), el tono identitario 2.3 y la sección 10 (referencias del tema) se reescriben para cada cortometraje. La sección 10 termina con "Errores a evitar", cada uno acompañado de la forma correcta de dibujar.

Si el usuario quiere un aspecto diferente al estilo predeterminado, primero haz un análisis de referencia según el método de templates/reference-analysis.md, y luego actualiza las secciones 1–9 en consecuencia.

Criterio de finalización: cada elemento que se dibujará en el storyboard tiene reglas de dibujo y un nombre de paleta; src/lib.js coincide con la sección 2.2; existe una lista de errores; y se ha ejecutado node tools/snap.cjs --fixtures --shot palette --samples 5 --sheet.

4. Storyboard (Storyboard)

Leer reference/shot-types.md, rellenar docs/storyboard.md según la plantilla: logline; números (primero elegir bpm, pulso = 60/bpm segundos, duración que caiga en un número entero de compases); tabla resumen; actos asignados a compases; una tabla de geometría compartida para las formas que sobreviven a través de cada corte coincidente; luego una entrada por cada toma — de 1 a 3 segundos, límites en la rejilla de compases, alternando los dos fondos — incluyendo los ocho subapartados, con pistas de sonido marcadas con marcas de tiempo en la rejilla.

Criterio de finalización: las tomas cubren exactamente [0, duration] sin espacios; cada toma tiene los ocho subapartados; cada forma de corte coincidente tiene su tabla de geometría compartida; el documento puede pasar una autoinspección con ojo crítico (los números en el texto coinciden con las tablas, el contenido obligatorio está dentro de las zonas seguras — el contenido aritmético también cuenta). Los errores del storyboard se multiplican en cada escena, es el momento más barato para detectarlos.

5. Línea de tiempo (Timeline)

Escribir src/timeline.js según el storyboard (la forma está en la plantilla del storyboard): título, bpm, duración, array de shots (id, file, start, end, mode, title, transitionIn, brief), y las cues planas recogidas de las secciones Sound. La fase de stubs es la prueba de este paso — un formato incorrecto de la línea de tiempo fallará estrepitosamente.

6. Fase de stubs (Stub pass)

node tools/stubgen.cjs genera escenas placeholder para cada toma, ejecuta el control, luego node tools/render.cjs --scale 0.5 --out exports/draft-stubs.mp4 y visualiza el borrador de principio a fin. Es una bala trazadora: antes de dibujar cualquier escena real, demuestra que la línea de tiempo, las escenas, el control, el renderizado y el audio funcionan todos juntos.

Criterio de finalización: el control está en verde, y el MP4 del borrador muestra cada toma en orden, cada transición cae en la rejilla.

7. Escenas (Scenes)

Un agente por archivo de escena — la propiedad del archivo es la ley (docs/CONTRACT.md). Cada agente de escena lee reference/scene-anatomy.md, su entrada del storyboard, la biblia de arte y la geometría compartida, luego escribe src/scenes/NN-<id>.js, toma una hoja de contacto (node tools/snap.cjs --shot <id> --samples 6 --sheet) y revisa cada fotograma, iterando hasta que cumpla con el briefing. snap --only puede renderizar una sola toma mientras los archivos hermanos están a medio escribir, así que los agentes de escena pueden paralelizarse libremente.

Las tomas también pueden compartir un módulo de dibujo (diseño centralizado, ver docs/CONTRACT.md «Dos diseños para el código de escena») — en ese caso, cada src/scenes/NN-*.js es solo un envoltorio de registro de unas pocas líneas, y el dibujo se centraliza en FILM.art. El ejemplo examples/llm-evolution usa este sistema; es más eficiente cuando las tomas comparten la misma geometría y solo varían en parámetros.

Criterio de finalización: la hoja de contacto de cada toma ha sido inspeccionada visualmente y se ha determinado que cumple con el briefing, y el control está en verde.

8. Música (Music)

Según reference/music.md, escribir src/music.js: mantener el motor, reemplazar la tabla de acordes CH, la automatización MIX.ride y toda la función score(), implementar cada cue en los tiempos exactos de FILM.TIMELINE.cues, asegurando que los acentos caigan en las transiciones.

Criterio de finalización: después de node tools/audio/render-audio.cjs, node tools/audio/analyze.cjs .tmp/audio/score.wav --cues muestra que los inicios y las pistas coinciden dentro de 10 ms, node tools/audio/peaks.cjs .tmp/audio/score.wav muestra que el margen está por debajo del límite del limitador, y el control está en verde.

9. Olas de crítica (Critic waves)

Primero pon todo el cortometraje en una sola tabla: node tools/snap.cjs --samples 24 --sheet --scale 0.25. Las tomas que no se puedan leer a ese tamaño son P1 — arréglalas cambiando la composición, no añadiendo detalles.

Luego revisa cada toma basándote en fotogramas renderizados: vuelve a tomar la hoja de contacto, usa un subagente crítico para puntuar composición, fidelidad al storyboard, movimiento y densidad. El crítico debe medir las proporciones geométricas clave a nivel de píxel (puntuación de bandas, regla de tercios, aritmética de zonas seguras, posición de geometría compartida), no solo fiarse del ojo; y para cada corte coincidente, captura ambos lados y compáralos.

Corrige por olas — prioridad P1, cada corrección referenciando fotogramas de evidencia, manteniendo la propiedad del archivo (restaurando el agente que posee el archivo), y volviendo a capturar después de cada corrección. El director revisa aleatoriamente cada corrección P1 en los nuevos fotogramas. Verifica el determinismo capturando el mismo fotograma en dos órdenes diferentes y comparando los hashes de los archivos.

Criterio de finalización: cada corrección P1 y P2 se ha verificado en los nuevos fotogramas, y el control está en verde.

10. Entrega (Deliver)

node tools/render.cjs escribe el master (crf 16). Luego transcodifica:

ffmpeg -i exports/<slug>.mp4 -vf scale=720:1280 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k exports/<slug>-phone.mp4
ffmpeg -i exports/<slug>.mp4 -c:v libx264 -crf 23 -preset medium -c:a copy exports/<slug>-preview.mp4

node tools/build.cjs escribe dist/<slug>.html. Luego visualiza el master de principio a fin con sonido, y abre el reproductor HTML una vez (clic o espacio para reproducir, flechas para avanzar fotograma a fotograma, ?shot=<id> para bucle de una sola toma).

Escribe exports/<slug>-shots.md: una línea por cada toma, explicando qué muestra.

Criterio de finalización: el master, la transcodificación para móvil, el archivo HTML y exports/<slug>-shots.md existen, el control está en verde, y la visualización final no encuentra nada que arreglar.

11. Paquete de publicación (Publish pack)

Usa tools/publish.cjs para generar una portada adecuada para publicar y un andamio de texto:

node tools/publish.cjs                          # Toma por defecto el fotograma gancho de la primera toma
node tools/publish.cjs --at 2.5 --title "De una neurona, a una máquina de lenguaje" --platform tiktok

Hace dos cosas:

1. Portada (captura de HTML, por defecto 1080×1920): renderiza un fotograma del cortometraje en el momento --at como imagen principal, superpone título/subtítulo/marca de esquina, y genera exports/<slug>-cover.png. La página de portada puede usar fuentes del sistema e imágenes, ya que no entra en el HTML entregado, no viola la regla "sin medios".
2. Andamio de texto exports/<slug>-publish.md: candidatos a título, descripción, hashtags, lista de tomas, duración/relación de aspecto/plataforma, etc. El título y la descripción son un punto de partida, que tú debes refinar hasta convertirlos en la recomendación final siguiendo las reglas de reference/publish.md.

Criterio de finalización: exports/<slug>-cover.png se ha generado y visto en persona (el título está dentro de las zonas seguras, es legible, tiene gancho); el título y la descripción en exports/<slug>-publish.md han sido refinados por ti hasta convertirlos en la recomendación final; la plataforma y la relación de aspecto coinciden con el briefing del paso 0.