patryk-penczek/ship-video

¿Qué hace ship-video?

Diriges y construyes un video de 10 a 45 segundos del producto del usuario. Todo lo que aparece en pantalla es código: una página HTML, una línea de tiempo de GSAP pausada en segundos absolutos, las pantallas reales de la aplicación capturadas desde su DOM y animadas, renderizadas cuadro a cuadro a MP4.

Cómo se moldea el trabajo. Un video se decide o se arruina por las elecciones hechas antes de cualquier código: qué espectador, qué cambio hace el producto, qué historia, cuánto dura. Esas elecciones van a un guion de una página que el usuario aprueba; cuesta minutos cambiarlo en papel y horas una vez construido. Después de eso, construye bien, revisa tu propio trabajo a fondo, renderiza y muestra el video: el usuario lo mira y te dice qué cambiar. No te detengas para aprobaciones más allá del guion.

Los scripts están en scripts/ junto a este archivo. En Claude Code esa carpeta es ${CLAUDE_SKILL_DIR}/scripts; en otro lugar, resuélvela contra el directorio de este archivo y llámala por ruta absoluta. A continuación, $S es esa carpeta y <film> la carpeta del video. Ejecuta los scripts, no leas su código fuente; cada uno acepta --help.

Preguntar. Pregunta solo decisiones reales (lugar, música, duración, las palabras propias del usuario); decide el resto, dilo en una línea, deja que él lo cambie en la puerta. Pregunta solo en tres momentos: la apertura (paso 1), la puerta del guion gráfico, después del render; nunca te detengas a mitad del trabajo. Una forma sirve para cualquier anfitrión: como máximo 3 preguntas por ronda, 2–3 opciones cada una, recomendación primero, una etiqueta de 1 a 5 palabras, una frase sobre lo que significa para ellos, sin "Otro" (el anfitrión añade texto libre). Usa la herramienta de preguntas del anfitrión (Claude Code: AskUserQuestion; Codex: request_user_input, solo modo Plan), si no, una lista numerada con opciones con letras ("1a 2b") que termina en "o dime algo más". Más de 3 opciones son dos preguntas, la decisiva primero; cuando una respuesta anterior resuelve una pregunta, incorpórala a las opciones.

Límites

Dilo de inmediato si la solicitud choca con uno: solo 16:9 (nada de 9:16); interfaz web (una app nativa solo se puede reconstruir a partir de capturas de pantalla, con menos precisión); 10–45 s; macOS, Linux o Windows; salida MP4 y WebP animado, nada de GIF. La configuración descarga Chromium y paquetes de Python en ~/.ship-video: un anfitrión en un entorno aislado (Codex) necesita acceso a la red y permisos de escritura allí; si un comando es bloqueado, dile al usuario qué permiso necesita en lugar de reintentar.

Iniciar o reanudar

Revisa la carpeta del video (pregunta cuál si no está claro) y comienza en la primera pieza faltante:

existe en <film>	empezar en
nada	0 Configuración
index.html, sin PRODUCT.md	2 Descubrimiento
PRODUCT.md, sin MUSIC.md	3 Música
MUSIC.md, sin SCENARIO.md aprobado (línea Approved:)	4 Guion
SCENARIO.md aprobado, sin screens.js (o estados aún no comparados)	5 Réplicas
screens.js y review/compare/ con cada estado coincidiendo, film.js inicial	6 Construcción
film.js con cada acto construido, sin out/film-*.mp4	7 Revisión
out/film-crisp.mp4 o out/film-motionblur.mp4	pregunta qué cambiar (render.md, Cambios después del render)

El usuario puede saltarse pasos ("Tengo un guion", "sin música", "solo constrúyelo"): saltarlos y decirlo en una línea. Saltarse la puerta del guion gráfico necesita sus palabras explícitas.

Muestra esta lista de verificación en la primera respuesta y cuando entregues:

- [ ] 0 Configuración   - [ ] 1 Briefing   - [ ] 2 Descubrimiento   - [ ] 3 Música
- [ ] 4 Guion (aprobado)   - [ ] 5 Réplicas   - [ ] 6 Construcción
- [ ] 7 Revisión   - [ ] 8 Renderizado y entrega

0. Configuración

node $S/lib/check.mjs: instantáneo una vez que la configuración se haya ejecutado. Solo si informa que falta algo: node $S/setup.mjs (instala en ~/.ship-video, omite lo que ya está).

1. Briefing

Mira primero: README, package.json, rutas, componentes, el sitio, capturas de pantalla y logotipos existentes (los activos reales se usan sin preguntar). Luego pregunta lo que aún falta en dos rondas consecutivas (la duración depende de la música):

1. Dónde se reproduce: los tres lugares más probables para este producto (un feed social, el sitio web, un README o documentación, un centro de ayuda), el que se muestra primero. Esto determina qué sabe el espectador, si el sonido está activado, la apertura (direction.md, La prueba del espectador) y el tamaño mínimo del texto.
2. Música: sí o no; recomienda no donde ese lugar se reproduce silenciado, y en sí di que la música solo llega al MP4 (el WebP de un README es silencioso).
3. Segunda ronda · Fuente de música (la pregunta del paso 3, ahora, para que una pista de Suno se genere mientras trabajas) y duración: la más corta que muestre el único cambio del producto (10–15 s suele ser lo mejor), una más larga, y con música Ajustar a la música (la pista la determina, corta en compases según lo que aguante el material; recomendado entonces).

El tipo de video (lanzamiento, teaser de una función, tutorial, página de inicio) generalmente se deduce de la solicitud y el lugar: indícalo. Cualquier cosa que ya hayan dicho responde a su pregunta.

Un video cuya sensación quieran: divídelo en una hoja de contactos (ffmpeg -i ref.mp4 -vf "fps=2,scale=480:-1,tile=6x5" <film>/review/reference.png), enumera sus técnicas, tómalas prestadas, nunca su contenido.

Crea la carpeta: node $S/new-film.mjs <film> (fuera del repositorio del producto a menos que quieran que esté dentro; --theme light|dark si se conoce; --silent para un video sin música).

2. Descubrimiento

Un video hecho a partir del README muestra características; uno hecho a partir de todo el producto muestra un beneficio. Conoce primero el producto. Para cualquier cosa más allá de una aplicación pequeña, divide esto en tres subagentes paralelos si puedes (subagents.md).

1. Inventario de cada ruta y vista del enrutador, con los estados que importan (diálogos, paletas, notificaciones toast, estados vacíos, temas) y todo lo que está en vivo (gráficos, mapas, lienzos).
2. Ve cada una: con la aplicación en ejecución (reutiliza su servidor, render.md, Compartiendo la máquina) node $S/capture.mjs <url> <film> --discover escribe una captura de pantalla por ruta en <film>/review/discovery/; léelas. Inicios de sesión, teléfonos, páginas de inicio: replicas.md, Opciones. Si no se ejecuta: usa sus capturas de pantalla y documentos, y dímelo.
3. Encuentra lo nuevo y lo especial: el registro de cambios, notas de la versión, gh pr list --state merged --limit 30 si está disponible; los 3 a 5 momentos que un usuario le mostraría a un amigo; el único cambio que es el producto.
4. Escribe <film>/PRODUCT.md: la promesa en las propias palabras del producto, el espectador, las vistas (principales / secundarias / omitir, con rutas de captura de pantalla), momentos sorprendentes, el caso concreto que podría sustentar el video, lo que no se puede mostrar. Muéstralo en unas pocas líneas y continúa; las correcciones pueden llegar en cualquier momento, a más tardar en la puerta.

3. Música

Lee music.md. Sin música: una cuadrícula de BPM; lee direction.md, Videos silenciosos. La pregunta sobre la fuente (hecha en la apertura) muestra las tres opciones, una línea cada una sobre lo que le cuestan al usuario (un archivo nuevo en ~/Downloads va en la línea de archivo propio):

• Ritmo generado: gratuito, libre de licencia, listo en segundos, una partitura funcional más que una canción. Escribe beat.json a partir de los actos planeados y ejecuta music.mjs synth.
• Suno: una canción real moldeada a los compases del video; necesita una cuenta de Suno, unos 10 minutos de su tiempo, un plan de pago para cualquier cosa pública, así que para un lugar público etiquétalo como Suno (plan de pago) (music.md, Derechos). Guíalos a través del proceso (suno-prompt.md, Guiando al usuario). No esperes inactivo: escribe MUSIC.md a partir de un GRID DRAFT y redacta el guion mientras ellos generan.
• Archivo propio: cópialo a <film>/track.<ext>.

Analiza la pista, lee la trama, confirma el drop tú mismo y escribe <film>/MUSIC.md con el papel narrativo de cada sección.

4. Guion gráfico

Lee direction.md y escribe <film>/SCENARIO.md a partir de scenario-template.md: el espectador, la historia (problema → héroe → acción → recompensa en el drop), cada toma con sus segundos, qué se mueve y dónde aterriza la cámara, el texto final palabra por palabra. Ejecuta la autocomprobación de la plantilla y corrige los "no" primero. Dile al usuario si la duración no se ajusta al material y ofrécele la mejor.

Luego pregunta, en una ronda: variantes solo donde las palabras sean suyas, y "¿Aprobar el guion?" (Aprobar / Cambiar tiempos / Cambiar escenas) con la historia en tres líneas y la tabla de tomas.

5. Réplicas

Lee replicas.md. Con la aplicación en ejecución, su propio DOM y CSS son la réplica: escribe <film>/states.json con cada estado que el guion necesite (ambos lados de cada interacción), ejecuta capture.mjs … --css, luego compare.mjs, y lee los PNG de comparación hasta que cada estado coincida. Sin una aplicación en ejecución, construye a partir de los componentes y dilo en el informe.

6. Construcción

Lee film-api.md y shots.md. Establece track, duration, hits (music.md) y fonts/images a partir de la salida de la captura, luego escribe las escenas en el orden del guion en los segundos del guion. Anima los elementos reales dentro de las pantallas capturadas (direction.md). Cuando te alejes del guion, añade una línea a Cambios vs guion.

Verifica mientras avanzas: node $S/render.mjs <film>/index.html <film>/review/test.mp4 --preset draft --from 0 --to 1 detecta una página rota en segundos; el usuario puede abrir <film>/index.html para previsualizar (la barra espaciadora reproduce, las flechas avanzan, ?t=12.5).

7. Revisión

Mira el video como un director antes que nadie:

node $S/sheet.mjs <film>/index.html <from> <to> <step> <film>/review/sheet-<act>.png
node $S/shots.mjs <film>/index.html <film>/review/stills <t1> <t2> … --label

Una hoja de contactos por acto (pasos de 0.25 s para el tipo, 0.5 s para la interfaz), fotogramas a resolución completa de cada corte + 0.01 s, la recompensa y la tarjeta final. Lee cada imagen y ejecuta la autocomprobación de scenario-template.md en los fotogramas; haz zoom en cada interacción en pasos de 0.1 s, ya que la mayoría de las sensaciones "inacabadas" viven en esos medios segundos. Luego obtén una opinión crítica nueva (subagents.md) y corrige lo que retrase. Termina con node $S/audit.mjs <film>/index.html hasta que esté limpio (render.md, Auditoría).

8. Renderizado y entrega

Lee render.md: renderiza nítido en segundo plano, verifícalo (hits.mjs, motion.mjs), corrige y vuelve a renderizar si es necesario, luego entrega (Entrega: la carpeta se abre, un primer corte, una pregunta).

Referencias

archivo	leer en
references/direction.md	4, y de nuevo en 6 y 7: la prueba del espectador, historia, estructura, ritmo, encuadre, tipos de video
references/scenario-template.md	4 (plantilla y autocomprobación), 7 (autocomprobación en los fotogramas)
references/music.md	3: análisis, MUSIC.md, cuadrícula silenciosa, ritmo generado, derechos
references/suno-prompt.md	3, cuando la música proviene de Suno
references/replicas.md	2 (opciones de captura) y 5
references/film-api.md	6, antes de escribir film.js
references/shots.md	6: recetas con código
references/subagents.md	2 y 7, si tu anfitrión puede ejecutar subagentes
references/render.md	7 (auditoría) y 8; Compartiendo la máquina antes de iniciar servidores o renders