Plextrang/story-shorts

Story Shorts: cualquier idea entra, un cortometraje animado terminado sale

Este skill es un motor cinematográfico más un flujo de trabajo. El motor (engine/) renderiza three.js cuadro a cuadro en Chrome sin interfaz: personajes tipo marioneta en un lienzo 2D sobre un mundo 3D con sombreado cartoon y contornos de tinta, movimientos de cámara y fundidos, una superposición 2D para gráficos explicativos, subtítulos incrustados y una mezcla de sonido basada en eventos temporizados. Cada película escribe solo su capa narrativa: quién aparece, dónde ocurre, los planos, los gráficos y el plan de sonido. Una película nueva parte del proyecto base en blanco (starter/: dos personajes de relleno, dos lugares, cuatro planos). examples/floating-scale/ es una película terminada, solo como referencia. No reutilices nunca sus personajes ni su historia.

Léelos según los necesites:

• reference/rules.md: las reglas de la historia y la imagen. Léelo primero.
• reference/story-templates.md: seis formas narrativas. Elige una por película.
• reference/engine-api.md: cómo escribir una película sobre el motor (personajes, poses, mundos, atrezo, planos, gráficos, indicaciones).
• reference/transitions.md: regla 11 en la práctica (movimientos de cámara, puesta en escena para continuidad, cortes mantenidos).
• reference/sound.md: voz, música y efectos, con Epidemic Sound o las herramientas gratuitas.
• reference/lessons.md: errores ya cometidos y sus correcciones. Consúltalo antes de depurar cualquier cosa.

Antes de empezar: haz dos preguntas

1. La idea. Una frase basta: "un farero que tiene miedo a la oscuridad", "la maratón olímpica de 1904", "qué pasaría si la gravedad se redujera a la mitad durante un día". Pregúntala si el usuario no la ha dado. Pregunta sobre la duración solo si le importa (por defecto unos 60 s).
2. Herramientas de sonido. Pregunta: "¿Tienes Epidemic Sound (con su conector Claude), o uso las herramientas gratuitas?"
   • Epidemic Sound (recomendado): locución para el narrador y los personajes, una pista musical de Epidemic cortada para la historia, efectos y ambiente de Epidemic. Necesita el conector MCP de Epidemic Sound en Claude Code.
   • Gratuito: Kokoro TTS para las voces (scripts/kokoro_voice.py), una banda sonora y efectos sintetizados en código.
   • No mezcles los dos en una misma película sin decirlo en el README de la película.

Luego ejecuta python scripts/check_setup.py y corrige cualquier elemento marcado como FALTANTE antes de escribir código de película.

El flujo de trabajo (sin necesidad de aprobaciones a menos que el usuario las pida)

1. Nuevo proyecto. python scripts/new_film.py <carpeta> "Título" copia el motor y el proyecto base en blanco, escribe una línea de tiempo provisional e instala film/node_modules desde cero. Trabaja solo dentro de esa carpeta.
2. Historia (docs/STORY.md, script/lines.json).
   • Elige la plantilla narrativa que encaje con la idea (reference/story-templates.md), y di cuál has elegido y por qué.
   • Escribe el guion: una entrada por línea hablada (id, hablante, inicio, texto). Narración más unas pocas líneas de personajes; unas 150 palabras por minuto de película.
   • Escribe la lista de planos con una lectura en silencio por plano: qué entiende un espectador con el sonido apagado solo con la imagen.
   • Nombra los lugares. Un cambio de lugar es la única razón para un fundido; dentro de un lugar la cámara se mueve.
   • Los hechos deben ser verídicos, con números reales. Personajes, historia y mundo son originales.
3. Reparto (film/src/story/cast.js).
   • Una clave por personaje (la misma que su id de hablante). Empieza cada uno desde un ajuste predefinido y sobrescribe colores, proporciones y rasgos hasta que sean propios de esta película (reference/engine-api.md, "Characters"). Añade un nuevo aspecto en character.js detrás de una nueva bandera feat cuando la historia lo necesite.
   • Renderiza node film/tools/charsheet.mjs y revisa cada hoja antes de construir cualquier plano.
4. Mundo y atrezo (story/world.js, story/set.js, opcional story/props.js).
   • Construye cada lugar a partir de worldkit.js más sus propios puntos de referencia. Pon cada marca en SET. Da a los objetos principales los estados que la historia necesita.
5. Bloqueo de la imagen (story/shots.js, story/overlay.js).
   • Sustituye los cuatro planos del proyecto base por los planos de la película. Marca los tiempos a partir de la línea de tiempo (K.wordAt, K.lineAt), nunca en segundos fijos. Hasta que exista la voz, python tools/build_timeline.py --placeholder.
   • Escenifica para continuidad desde el principio (regla 11): una interpretación por personaje por lugar, atrezo en sus marcas.
   • Explica con diagramas 2D (regla 4). Enumera cada acción visible en CUES.
6. Voz.
   • Genera cada línea como su propio clip en audio/vo/raw/<id>.mp3|wav (Epidemic, o scripts/kokoro_voice.py).
   • python <repo>/scripts/prepare_voice.py (añade --atempo-off para Kokoro) recorta los extremos silenciosos y ajusta el ritmo.
   • python tools/build_timeline.py, python tools/captions.py, luego cd film && node tools/cues.mjs.
   • Nunca cortes un clip en tiempos de palabras susurradas. Vuelve a comprobar el encuadre: los tiempos cambiaron con la voz real.
7. Revisa la imagen antes de cualquier renderizado completo:
   • node framecheck.mjs --step 4 debe imprimir "encuadre OK".
   • node tools/poptest.mjs --out ../render/pop comprueba todos los bordes en busca de saltos; bash tools/movesheet.sh comprueba movimientos.
   • bash tools/sheet.sh <nombre> "<tiempos>" genera hojas de contactos. Míralas y verifica cada plano contra su lectura en silencio. Haz al menos dos rondas completas.
8. Sonido (audio/sound_plan.json, reference/sound.md).
   • Epidemic: descarga la pista y los efectos en audio/epidemic/, completa music, effects y ambience, luego cd audio/epidemic_mix && python mix_film.py && python autolevel.py && python qc.py && python sync_check.py.
   • Gratuito: completa synth, luego cd audio/synth && python music.py && python build_fx.py && python mix.py && python cue_presence.py.
   • Objetivos: −14 LUFS, pico verdadero ≤ −1.3 dBTP, voz al menos 6 dB clara en cada línea, sin silencios, cada efecto dentro de un fotograma.
9. Renderiza, ensambla, entrega.
   • cd film && node render.mjs --from 0 --to <fotogramas-1> --scale 1.5 --workers 2 --jpg --out ../render/frames.
   • bash tools/assemble.sh escribe out/<Título>.mp4 y out/contact_sheet.jpg, y mide el resultado. Se niega a ejecutarse si un worker bloqueado dejó un fotograma vacío.
   • Si earshot está instalado: bash audio/tools/es.sh critique out/<Título>.mp4, con el objetivo de "calidad de publicación".
   • Escribe el README.md de la película: logline, mediciones, cada corte mantenido y por qué, los sonidos utilizados y los puntos débiles sinceros. Nunca afirmes que la película es buena: no puedes verla ni oírla a velocidad completa. Enumera lo que el usuario debe comprobar visual y auditivamente, luego detente y espera su revisión.

Puntos no negociables (detalles en reference/rules.md)

• Se entiende con el sonido apagado. Muestra el problema antes de la solución. Muestra cada línea en pantalla mientras se dice.
• Sin metáforas literales; explica con un diagrama 2D claro.
• El atrezo se entiende de un vistazo. Usa planos medios y generales con figuras completas, mantén limpia la banda de subtítulos (62–78 % de la altura) y que nadie quede cortado al final.
• Mismo lugar implica movimiento de cámara, lugar nuevo implica fundido, y un corte solo se mantiene con una razón declarada.
• Cada acción visible tiene un sonido audible, y la narración se mantiene clara durante todo el metraje.
• Solo personajes, historias y mundos originales. Nunca copies los personajes o el aspecto de una serie existente, y nunca reutilices los de la película de ejemplo.
• Trabaja solo dentro de la carpeta de la película. Instala todo desde cero allí; nunca enlaces a otro proyecto.