product-video

product-video — Creación de vídeos promocionales de productos con código

Reconstruye la interfaz del producto en HTML, escribe los movimientos de forma que "solo dependan del tiempo" y captura cada fotograma con un navegador headless para obtener un vídeo. La música y los efectos de sonido también se sintetizan dentro del navegador. Solo necesitas Node.js, ffmpeg y Chromium.

Este skill incluye una plantilla funcional (assets/template/) con herramientas de captura, audio e inspección, junto con un vídeo de muestra de 30 segundos. No es necesario construir el mecanismo desde cero: solo hay que duplicar la plantilla y reemplazar el contenido.

Premisa importante: no puedes ver ni escuchar

No es posible reproducir el vídeo para comprobarlo. Por eso, la calidad de este trabajo depende de la cantidad de veces que generes imágenes fijas y las examines con tus ojos, así como de la inspección numérica. Si avanzas simplemente después de escribir el código, quedarán errores como texto cortado, superposiciones o parpadeos momentáneos. Cada vez que escribas una escena, debes revisarla visualmente, corregirla y luego pasar a la siguiente. Como no puedes escuchar el audio, debes mostrar los valores medidos y pedir a una persona que confirme la percepción auditiva.

Reglas a seguir (con sus razones)

1. La apariencia solo depende del tiempo. Los movimientos se programan con tl.* para "a qué segundo" o se calculan directamente desde t en onFrame((t) => …). No uses animaciones CSS, transiciones, setTimeout, Math.random() ni la hora actual. Como la escena es la misma sin importar a qué tiempo se salte, se puede renderizar en paralelo y solo se necesita re-renderizar una parte.
2. Escribe y revisa. Cada vez que escribas una escena, usa --sheet para generar una cuadrícula, abre la imagen y revísala. Para las transiciones entre escenas, revisa cada 0.1–0.2 segundos. No avances a la siguiente escena sin haber revisado.
3. No muevas lentamente componentes de texto. El navegador alinea la posición del texto a píxeles enteros, por lo que si se mueve lentamente durante varios segundos, el texto vibrará. Mueve los contenedores y títulos en aproximadamente 1 segundo y, una vez detenidos, mueve el contenido dentro de ellos. Solo los fondos de luz pueden moverse lentamente.
4. Usa tl.in para la aparición y tl.out / tl.hide para la desaparición. tl.fromTo mantiene el valor original antes del tiempo de inicio, por lo que si lo usas para la aparición, el elemento se verá brevemente antes de comenzar.
5. Escribe el CSS de la interfaz del producto bajo la clase raíz de la escena (por ejemplo, .ui-chat .row). Usar nombres cortos como .row o .title sin contexto puede causar conflictos con componentes de la plantilla o de otras escenas, generando errores difíciles de detectar.
6. Asegura un tamaño legible. El vídeo se verá también en móviles. Los títulos deben tener al menos 68 px, y el texto dentro de los contenedores debe tener al menos 18 px en pantalla (tamaño de fuente × escala). Para pantallas pequeñas, coloca el contenedor más grande o acerca la vista a lo que quieras mostrar.
7. No tergiverses los hechos. No incluyas nada que no puedas verificar con fuentes. No muestres algo que no se puede hacer como si fuera posible. No incluyas cifras no verificadas, comparaciones con otras empresas ni testimonios. No dibujes logotipos de otras empresas; escribe sus nombres en texto. En la tarjeta final, incluye en pequeño que la escena es una recreación (brand.fine).
8. Coloca los límites de escena y los movimientos grandes al comienzo de un compás. El momento en que un logotipo encaja, el cambio de escena o la tarjeta final deben coincidir con el golpe de la música (hit: true). Esto solo da una sensación de conjunto más sólida.
9. No cambies el volumen ni el timbre. Los valores en kit/audio.js están medidos para mantener el equilibrio. Alterarlos sin poder escuchar causará desajustes. Solo modifica las secciones de la música (plan.js) y las señales de efectos de sonido.
10. No escribas que "has confirmado" algo que no has medido. En el informe, debes indicar explícitamente que no has escuchado el audio.

Flujo de trabajo

Cada etapa tiene una verificación. No avances sin haber completado la verificación (cuanto más tarde corrijas, más costoso será).

El trabajo puede ser largo. Si en el camino pierdes contexto y olvidas detalles, vuelve a leer este archivo y los references/ de la etapa actual. Guarda la estructura decidida (tabla de escenas) como comentario al inicio de src/js/plan.js; así, si te interrumpen, podrás retomarlo desde donde lo dejaste.

0. Preparación

node "${CLAUDE_SKILL_DIR}/scripts/new.mjs" video     # Duplica la plantilla en video/ (ajusta la ruta según la solicitud)
cd video && npm install --ignore-scripts
node render.mjs --sheet 0:29:2                       # Si se genera out/sheet.png con la vista previa, la preparación está lista

${CLAUDE_SKILL_DIR} es la carpeta donde se encuentra este archivo SKILL.md. Si ves el texto literal, reemplázalo con la ruta absoluta de esta carpeta.

Si te dice que no hay navegador, ejecuta npx playwright install chromium. Si no es posible, usa Chrome o Edge ya instalados (añade la variable de entorno CHROME_CHANNEL=chrome o CHROME_CHANNEL=msedge). Si falta ffmpeg, pide que lo instalen.

Primero, mira el archivo de ejemplo src/js/scenes.js y la imagen generada out/sheet.png. Para aprender a usar los componentes, el ejemplo es más rápido que las explicaciones.

1. Investigación

Todos los hechos que aparezcan en el vídeo deben tener una fuente. Lee el README, la documentación, las reglas de diseño (colores, tipografía, márgenes) y el texto real de la interfaz. Luego, escribe lo siguiente:

• ¿De quién es el producto, qué problema resuelve y cómo? (en una frase)
• Las funciones que quieres mostrar y la evidencia de por qué son importantes (¿en qué parte de qué documento?)
• El texto real que aparece en la interfaz (nombres de botones, estados, notificaciones). El texto inventado será detectado al instante por alguien que conozca el producto real.
• La apariencia de la interfaz real. Si tienes capturas de pantalla o maquetas, ábrelas y copia la disposición, colores, márgenes y tamaños de texto. Si no, extráelos del código de la UI (componentes, estilos, tokens de diseño).
• Entorno compatible, restricciones y suposiciones (para no exagerar).

Si la solicitud no lo especifica, decide lo siguiente por tu cuenta y continúa, pero anótalo en el informe: duración (60–90 segundos; 30 segundos para solicitudes cortas), idioma (el de la interfaz y la documentación del producto), cuándo usar escenas claras y cuándo oscuras. Solo pregunta al solicitante si no puedes encontrar los colores, logotipo o tipografía de la marca en los documentos.

2. Definir la estructura

Crea una tabla de escenas antes de empezar a construir. Las guías sobre tipos de estructura, redacción de títulos y asignación de tiempos están en references/direction.md. Léelo obligatoriamente.

• Cada escena comunica una sola idea. El título de cada escena también es uno solo. No hagas una lista de funciones.
• El inicio no debe ser el producto, sino el "problema".
• Los límites de las escenas deben coincidir con el inicio de un compás (a 120 BPM, cada 2 segundos).
• Escribe en src/js/plan.js los valores de T (tiempo de inicio de cada escena) y music (secciones de la música) según esta tabla.

Muestra la estructura decidida brevemente al solicitante. No es necesario esperar su respuesta para empezar a construir (si la dirección es incorrecta, te darás cuenta antes).

3. Preparar la marca y la interfaz

• src/js/brand.js: nombre, eslogan, colores, tipografía, logotipo. Los valores deben tomarse del producto real.
• src/css/app.css y el HTML de scenes.js: recreación de la interfaz del producto. Ajusta colores, dimensiones y texto para que coincidan con el original.
• Antes de animar, usa --shot en estado estático y compáralo con el original. Si no se parecen en estático, no se parecerán en movimiento.

No pegues capturas de pantalla; recrea la interfaz con HTML. Así puedes animar componentes por separado, ampliarlos sin pérdida de calidad y cambiar los colores según la escena.

4. Crear las escenas una por una

Escribe una función por escena en scenes.js. Los componentes y las reglas de escritura están en references/kit.md. Léelo antes de empezar a escribir.

Para cada escena, repite lo siguiente:

node render.mjs --sheet 14:26:1        # Genera una cuadrícula de la escena cada 1 segundo → abre out/sheet.png y revísala
node render.mjs --shot 16.6,22.5       # Mira momentos específicos a tamaño real → out/shots/
node render.mjs --sheet 13.4:14.6:0.1 --cols 7 --w 420   # Revisa las transiciones cada 0.1–0.2 segundos
node render.mjs --lint                 # Detecta automáticamente texto cortado, superposiciones o texto demasiado pequeño

Puntos a revisar: ¿el texto está cortado? ¿Hay superposiciones? ¿El tamaño es legible? ¿Los márgenes están desequilibrados? ¿Queda claro de un vistazo qué hay que mirar? ¿Quedan componentes de la escena anterior?

Como regla general, cada escena debe revisarse al menos tres veces: justo después de escribirla, después de corregirla, y en las transiciones con las escenas adyacentes. Si algo no se ve bien en la cuadrícula pequeña, usa --shot para verlo a tamaño real.

5. Añadir el audio

La música se compone automáticamente a partir de la secuencia de secciones en plan.js. Los efectos de sonido se activan con cue("tipo", tiempo) al construir la escena. Más detalles en references/audio.md.

node render.mjs --audio                # Genera out/audio-master.wav. Muestra el volumen y los picos.

6. Vista previa completa e inspección de calidad

node render.mjs                        # Renderiza todo el vídeo a tamaño real (unos minutos para 30 segundos). Genera out/video.mp4
node tools/qa.mjs                      # Verifica formato, volumen, parpadeos, fotogramas perdidos, negro y silencio.
node render.mjs --sheet 0:90:1.5 --cols 6     # Revisa todo el vídeo (ajusta los segundos a la duración real).

Corrige todas las marcas ✗. Las guías para interpretar los resultados de QA y solucionar problemas comunes están en references/qa.md.

Aquí comienza el pulido. La primera versión que pasa suele ser "correcta, pero sosa". Revisa la cuadrícula completa y escribe al menos 5 cosas que quieras mejorar. Busca:

• Tramos de más de 2 segundos donde no pase nada.
• Espacios en blanco grandes, composición desequilibrada, vacío dentro de los contenedores (por ejemplo, la mitad inferior de un móvil en blanco).
• Momentos donde no quede claro qué desencadena qué (acción → reacción).
• Texto, colores o disposición que no coincidan con el original.

Si no encuentras 5 cosas, es que estás revisando con demasiada separación. Vuelve a revisar cada 1 segundo, y cada 0.25 segundos en las escenas que te preocupen.

7. Exportación final

node render.mjs --scale 2 --keep-frames     # Renderiza al doble de tamaño y luego reduce (3–4 veces más lento). Ejecútalo en segundo plano.
node tools/qa.mjs
node tools/extras.mjs web                   # Versión ligera (<10 MB) para compartir en chat o GitHub.
node tools/extras.mjs poster 15.9           # Imagen fija para la portada (en el momento que mejor resuma el contenido).

Renderizar al doble de tamaño suaviza los contornos y reduce la vibración del texto a la mitad. Si se interrumpe, usa --resume --reuse-audio para continuar. Si solo corriges una parte, elimina los fotogramas correspondientes de out/frames/ y vuelve a ejecutar con --resume; solo se re-renderizará esa parte.

8. Informe

Escribe lo siguiente de forma breve y honesta (la plantilla está al final de references/qa.md):

• Lo que se ha creado (ubicación del archivo, duración, resolución) y un resumen de la estructura.
• Lo que se ha verificado (resultados de QA) y lo que no se ha podido verificar. Como no has escuchado el audio, debes indicar: "Los valores numéricos están dentro del rango esperado. Por favor, confirma la percepción auditiva".
• Las decisiones que tomaste por tu cuenta (duración, idioma, tratamiento del color, etc.) y lo que no pudiste incluir por falta de fuentes.
• Que la escena es una recreación. Cómo pedir correcciones.

Cuando te pidan una modificación

Para modificar un vídeo creado con esta plantilla, no sigas el proceso desde el principio.

1. Lee references/kit.md y el código de la parte a modificar. Los títulos y el texto de la interfaz están en scenes.js, la tarjeta final en brand.js, la duración y la música en plan.js, y la apariencia visual en app.css.
2. Haz la modificación.
3. Revisa la escena modificada y las transiciones con --shot / --sheet. También ejecuta --lint.
4. Si cambias la duración o las secciones de la música, ejecuta node render.mjs --audio para asegurarte de que no aparezcan advertencias.
5. Si te pidieron el archivo de vídeo final, expórtalo siguiendo los pasos 6–7. Si no, informa lo que has verificado y pregunta si deseas exportarlo.

Ejecutar node render.mjs sin opciones inicia la exportación completa (varios minutos o más). Si solo quieres comprobar, usa siempre --shot, --sheet o --lint. Consulta node render.mjs --help para más información.

Estándar de calidad

Antes de entregar, compruébalo tú mismo.

• La historia se entiende solo con los títulos, incluso sin audio.
• En los primeros 3 segundos aparece un problema que el espectador sienta como propio.
• En cada escena, el punto focal está claro (no hay dos lugares en movimiento al mismo tiempo).
• Una persona que conozca el producto no encontrará anomalías en la interfaz ni en el texto.
• No hay marcas ✗ en --lint ni en tools/qa.mjs.
• Has revisado todas las transiciones entre escenas cada 0.1–0.2 segundos.

Material de referencia

Archivo	Contenido	Cuándo leerlo
references/direction.md	Tipos de estructura, asignación de tiempos, redacción de títulos, colocación y movimiento de escenas	Antes de definir la estructura (obligatorio)
references/kit.md	Roles de los archivos de la plantilla y uso del motor y componentes	Antes de escribir las escenas (obligatorio)
references/audio.md	Secciones de la música, lista de señales de efectos de sonido, cómo medir	Al añadir el audio
references/qa.md	Interpretación de resultados de QA, problemas comunes y soluciones, plantilla de informe	Durante la vista previa y la exportación final
assets/template/src/js/scenes.js	Vídeo de ejemplo con ejemplos de uso de componentes	Al inicio