serenakeyitan/launch-video-skill

launch-video

Genera un vídeo de lanzamiento de producto como código (Remotion → MP4). Este skill es una biblioteca de escenas + un flujo de trabajo, no una plantilla fija. Productos diferentes cuentan historias diferentes — la historia de una herramienta CLI ocurre en una terminal, la de una app SaaS en un navegador, la de una app móvil en un teléfono, la de una biblioteca en un editor. Diseña el arco para ESTE producto primero, luego ensámblalo desde la paleta de escenas. No fuerces un producto dentro de la forma del ejemplo tdoc.

La regla inquebrantable

Diseña el arco narrativo antes de tocar el código. Pregunta: ¿qué hace este producto?, ¿quién es el usuario?, ¿cuál es el único momento "ajá"? Escribe una lista de momentos (5–9 momentos, cada uno con una duración en fotogramas @24fps) y confírmala con el usuario. Solo entonces ensambla las escenas. Un vídeo de lanzamiento cuenta una historia, no es un recorrido de funciones.

Flujo de trabajo

1. Comprende el producto. ¿Qué es? ¿Dónde interactúa el usuario con él (terminal / navegador / teléfono / editor / mixto)? ¿Cuál es el antes→después? ¿Cuál es el momento que hace que alguien lo quiera?
2. Escribe la lista de momentos. Cada momento: nombre, qué aparece en pantalla, duración en fotogramas. Total ≈ 30–45 s (720–1080 fotogramas). Confirma con el usuario mediante AskUserQuestion antes de construir.
3. Elige escenas de la paleta (abajo) por momento. La mayoría de los vídeos usan 1–3 tipos de escena + un outro opcional. No todos los tipos son necesarios.
4. Reúne assets. Capturas de pantalla reales > maquetas. Colócalas en <proyecto>/public/. Recrea la IU como componentes nítidos solo cuando una captura sea de baja resolución o cuando necesites animarla 1:1.
5. Prepara un proyecto dentro del repositorio (copia examples/tdoc como esqueleto inicial — su estructura, no su contenido) o en un directorio hermano. Conecta un único <Composition> cuya duración sea la suma de las duraciones de los momentos, con un <Sequence> por momento.
6. Construye los momentos, luego añade efectos de sonido (scripts/make-sfx.sh <public>), luego renderiza, luego verifica visualmente cada momento cambiado, itera.
7. Entrega el MP4 solo después de que el bucle de verificación pase.

Paleta de escenas (src/)

Importa desde la biblioteca; ensambla solo lo que la historia necesita.

Escena	Úsala para	Props clave
Terminal	Herramientas CLI, agentes, herramientas de desarrollo — historia en un shell	lines (entrada tecleada, llamadas a herramientas, resultados, alerta, url), spinner, title. Un /comando-con-barra inicial en una entrada tecleada se resalta automáticamente en acento negrita.
BrowserWindow	Apps web, documentación, paneles, SaaS	captura/HTML como hijos, `chrome="bar"
MobileFrame	Apps móviles	carcasa de teléfono; captura/IU como hijos
CodeEditor	Bibliotecas, SDKs — "escribe esto → obtén aquello"	líneas code, revelación tecleada
Outro / LogoCard	Despedida (opcional)	titular/subtitular, o logo giratorio + marca de texto
WaveBackground	Fondo tranquilo con marca detrás de cualquier ventana	colores
Cursor	Hacer clic en un artefacto/enlace/botón	coordenadas desde/hasta, clickAt
PixelPet	Una mascota amigable sobre una ventana	filas de píxeles crown/base, color; ojos se mueven arriba/abajo (sin blancos oculares — se lee limpio en pequeño)
Caption	Línea corta bajo una ventana	at, text

Estas son independientes. El lanzamiento de una biblioteca podría ser solo CodeEditor + Terminal + LogoCard. El lanzamiento de un SaaS podría ser BrowserWindow + Outro.

Reglas de ritmo y transiciones (aprendidas por las malas)

• @24fps. Duraciones de momentos en fotogramas. Mantén el total ajustado: acorta las pausas estáticas, no la acción. Si un momento es mayormente un fotograma congelado, acórtalo.
• Transiciones bruscas. Fundidos entre escenas ≤ 5 fotogramas; fundidos de entrada de momento ≈ 4 fotogramas. Una ventana "abriéndose" (escala 0.35→1 durante ~12 fotogramas) se lee mejor que una escala lenta de 30+ fotogramas.
• Un momento continuo cuando sea posible. Fusiona "escribe → clic → resultado" en un solo Sequence para que no haya destello/corte a mitad de la acción.
• El cursor debe viajar y presionar. No teletransportes; anima hacia el objetivo, reduce escala al hacer clic. Cada clic tiene un efecto de sonido en el fotograma de presión.
• Sin cromo doble. Si una captura ya tiene un encabezado, usa chrome="none". No apiles una barra de ventana sobre una ya incrustada.
• Marco con tarjeta de marca. Reutiliza una tarjeta de marca (logo/mascota + nombre del producto + propuesta de valor en una línea) como fotograma TANTO de apertura como de cierre (≈1.5–2.5 s cada uno). Enmarca la historia y es más barato que una tarjeta final animada separada. Conduce todos los desplazamientos de momento con un acumulador at() para que añadir la tarjeta de introducción desplace automáticamente todo (incl. SFX) hacia adelante.

Reglas de audio

• Ejecuta scripts/make-sfx.sh <proyecto>/public para sintetizar sfx-typing.mp3 + sfx-click.mp3. Estos son artefactos generados ignorados por git — siempre (re)genéralos; nunca confíes en que estén presentes después de un clonado nuevo.
• El SFX de tecleo se reproduce solo mientras un humano está escribiendo (una entrada, un comentario). Nunca sobre salida de flujo automático/agente.
• El SFX de clic se dispara en el fotograma de presión de cada clic del cursor (enlace, botón, artefacto). Haz coincidir el <Sequence from> con el fotograma del clic.
• Coloca el audio con <Audio src={staticFile(...)} volume={0.3}> dentro de <Sequence>s cortos limitados a las ventanas de fotogramas exactas.

Bucle de verificación (obligatorio antes de la entrega)

El proxy de imagen que lee PNGs es ruidoso para OCR — confía en mediciones de píxeles (Python/PIL/numpy), no en descripciones de texto, para alineación/color.

1. scripts/verify.sh <entrada> <CompId> <dir-public> <fotograma> ... obtiene fotogramas fijos + imprime ventanas de audio. Pasa el public/ del proyecto como <dir-public> (o - si no tiene ninguno) — misma regla de --public-dir que el render; de lo contrario los fotogramas fijos tendrán assets 404.
2. Lee cada fotograma fijo. Para cada momento cambiado, confirma: contenido correcto, nada recortado por overflow:hidden, transiciones aterrizan, cursor en el objetivo, ventanas de SFX alineadas con los fotogramas visibles de clic/escritura.
3. Arregla → re-renderiza → re-verifica. No informes "listo" desde la intención; verifica los fotogramas reales.

Renderizado

npx remotion render <entrada> <CompId> out/<nombre>.mp4 \
  --public-dir=<proyecto>/public
# fotograma fijo:  npx remotion still <entrada> <CompId> out/x.png --frame=N \
#           --public-dir=<proyecto>/public

<entrada> es el src/index.ts del proyecto (llama a registerRoot). Pasa siempre --public-dir cuando la entrada esté en un subdirectorio — de lo contrario, staticFile() resuelve contra public/ de la raíz del repo y los assets dan 404.

Ejemplo de referencia

examples/tdoc/ es el ejemplo canónico trabajado (≈39 s): una tarjeta de marca de introducción, un ingeniero escribe una entrada /tdoc … a un agente (Terminal, comando con barra resaltado automáticamente), obtiene un enlace, el documento se abre (BrowserWindow), los compañeros comentan, el agente envía v2, luego la misma misma tarjeta de marca lo cierra — con SFX de escritura/clic limitados a escritura real y un PixelPet cuyos ojos se mueven. Léelo para ver la biblioteca en uso; no clonar su historia. Construye el propio arco del nuevo producto.