jpoz/make-video

¿Qué hace make-video?

Crea una película narrada a partir de un prompt. Cada fotograma es una función pura del tiempo t, dibujada en un lienzo (@napi-rs/canvas) y codificada con ffmpeg. La voz se genera localmente con Kokoro. La música se sintetiza en Python. Cada imagen se sincroniza con la palabra de la voz que la nombra.

El flujo es fijo: prompt → storyboard (voz real, música real, un fotograma real por escena) → el usuario itera sobre el storyboard → render completo. No renderices la película completa antes de que el usuario apruebe el storyboard. Muestra fotogramas reales en cada paso y corrige lo que veas antes de mostrarlo.

<skill> indica la carpeta que contiene este SKILL.md.

Requisitos

node 20+, ffmpeg, uv (ejecuta los scripts de Python e instala sus dependencias) y python3. ./make.sh setup los verifica. El modelo Kokoro (~115 MB) se descarga una vez, en la primera ejecución de voz, en ~/.cache/make-video/models. Las fuentes no se incluyen: consulta references/fonts.md.

1. Comprender la película (a partir del prompt)

Lee de qué trata la película antes de escribir una línea: el PR, el repositorio, la documentación, la aplicación, el anuncio. Encuentra las cosas reales que la película puede mostrar: pantallas reales, código real, resultados reales. Decide estas y pregunta al usuario solo sobre lo que no puedas averiguar por ti mismo:

• Tipo y duración. Intro o anuncio de funcionalidad: 30–75 s, 6–10 escenas, pantallas reales de la app. Explicativo: 2–6 min, capítulos con portadas, diagramas y código. Regla general: 2.5 palabras de voz por segundo.
• Audiencia y la única cosa que deben saber o hacer al final.
• Estilo visual. La paleta ink (negro casi total, acento rojo) o navy (azul intenso, cielo y ámbar) en theme.mjs, o los colores y fuentes del propio producto.
• Estilo musical. pop (brillante, alegre) o chip (chiptune tranquilo), o none.

2. Crear el proyecto

<skill>/scripts/new-project.sh ~/Developer/<tema>-video <tema>-video

Esto copia <skill>/template (una película de muestra funcional de 30 s) y ejecuta npm install. Consigue las fuentes (references/fonts.md). El proyecto es autocontenido. Edita estos archivos:

Archivo	Qué es
video.json	El guion: escenas, líneas de voz, señales, tiempos, música, el resumen para el storyboard
scenes/*.mjs	Una función de dibujo por id de escena
theme.mjs	Paleta, fuentes, fondo
music.py	La partitura (acordes, ganchos, instrumentos), cuando los valores por defecto no encajan
shots/plan.mjs	Capturas de pantalla reales de la app, cuando la película muestra una aplicación

No edites timeline.json. timeline.py lo genera.

3. Escribir el guion (video.json)

Lee primero references/script.md. En resumen: una idea por escena, oraciones cortas y claras, comienza con un gancho y termina con qué hacer a continuación. Una línea es una cadena, o {"text", "say"} cuando el subtítulo y la forma hablada difieren ("video.json" se dice "video dot jason"). Una señal nombra la palabra sobre la que aterriza una imagen: {"label": "badge", "at": "badge", "sound": "chime"}. Pon una señal en cada llegada importante. Completa brief (entradilla, enfoque, preguntas abiertas); el storyboard lo mostrará.

4. Dibujar las escenas (scenes/*.mjs)

Lee references/drawing.md (la API de la escena, ayudantes, reglas de diseño y movimiento). Cada escena recibe (ctx, t, S). Coloca cada llegada en S.cue(label) o S.w('palabra'), y haz que cada elemento salga mediante S.tout. Usa material real:

• Pantallas de app: captura la IU real con shots/capture.mjs y muéstrala con screens.mjs (cámara, cursor, anillos). Consulta references/screens.md.
• Código: code.mjs lee el archivo real por número de línea, así una cita no puede ser errónea.
• Salida de programa: ejecuta el programa real y dibuja su salida real. No dibujes una salida que no hayas visto.

Muestra mientras dibujas. Después de cada escena, ejecuta ./make.sh scene <id> y mira out/sheet.jpg antes de pasar a la siguiente escena. Para cada movimiento o transición complicada, ejecuta ./make.sh clip A B y mira out/clip.mp4. references/review.md tiene la lista de verificación.

5. El storyboard: el usuario itera aquí

./make.sh storyboard

Esto ejecuta voz → línea temporal → música → mezcla de audio → un fotograma por escena → storyboard.html: una página autocontenida con la mezcla real de voz y música, un fotograma de cada escena, el guion con cada palabra de señal marcada, los códigos de tiempo y el resumen. Al reproducirlo, resalta la escena y la línea actual.

Antes de mostrarlo, mira cada fotograma en out/board/ y corrige lo que esté mal. Luego entrega la página al usuario. Si tu andamiaje puede publicar una página HTML o un artefacto, publica storyboard.html y comparte el enlace. Si no, da la ruta del archivo para abrir en un navegador.

Luego itera con el usuario. Cada cambio es pequeño y rápido: edita una línea en video.json (solo las líneas cambiadas se vuelven a vocalizar), mueve una señal, cambia la energía de una escena, rediseña el estilo, redibuja una escena. Luego ejecuta ./make.sh storyboard de nuevo. Mantén actualizadas las preguntas abiertas del resumen. Permanece en este bucle hasta que el usuario apruebe el storyboard.

6. El render completo

Solo después de que el usuario haya aprobado:

./make.sh film            # o: ./make.sh film --blur 4   (desenfoque de movimiento, ~4x más lento)

Esto escribe out/<nombre>.mp4 (1920×1080, 60 fps, AAC, sonoridad −16 LUFS), out/<nombre>.srt y out/<nombre>.vtt. Luego verifica la salida real, no el código (consulta references/review.md, "Verificación final"): extrae fotogramas del MP4 codificado, confirma la duración y los flujos, y escucha la mezcla en los puntos que cambiaron. Ejecuta python3 storyboard.py --final para hacer que la página del storyboard contenga la película terminada. Entrega el MP4, los subtítulos y el storyboard. Si la película es un anuncio, ofrece un mensaje corto para acompañarlo, escrito a partir del mismo guion.

Comandos

Comando	Hace
./make.sh storyboard	Voz, línea temporal, música, mezcla, fotogramas del storyboard, storyboard.html
./make.sh scene ID [0.3,0.6,0.9]	Fotogramas fijos en fracciones de una escena, más out/sheet.jpg
./make.sh samples [24]	Fotogramas fijos distribuidos en toda la película, más out/sheet.jpg
./make.sh stills 3,20.5	Fotogramas fijos en segundos exactos, más out/sheet.jpg
./make.sh clip A B	out/clip.mp4: segundos de A a B de la película real, con sonido
./make.sh voice / music / timeline	Solo un paso
./make.sh film [--blur N]	El render y la mezcla completos
uv run tts.py --voices	Lista las voces de Kokoro

Referencias

• references/script.md: cómo escribir la voz en off, y todo sobre video.json
• references/drawing.md: la API de la escena, los ayudantes de lib.mjs, diseño, movimiento, patrones de escena
• references/screens.md: capturar pantallas reales de la app y mover una cámara sobre ellas
• references/audio.md: voces, estilos musicales, sonidos de señales, mezcla, audio adicional
• references/review.md: cómo muestrear, la lista de verificación de pulido, la verificación final
• references/fonts.md: dónde conseguir fuentes