product-motion

Product Motion

Vídeos cortos que muestran cómo funciona una funcionalidad: la interfaz del producto en pantalla, el cursor hace clic, el texto se escribe, las etiquetas se colocan bajo los fragmentos de entrada, las tarjetas aparecen en cascada, la cámara sigue la mirada, y una voz narra lo que sucede. El enfoque ha sido probado en vídeos para varios productos; aquí está separado de una marca concreta.

Principios

1. El fotograma es función del tiempo. El vídeo es una página HTML donde render(t) calcula el estado del fotograma en función del tiempo, y scripts/render.py captura los fotogramas uno a uno y los pasa a ffmpeg. Sin animaciones CSS, temporizadores ni grabación de pantalla: no hay saltos ni desincronización; cualquier momento se puede verificar con un fotograma individual. El motor es templates/engine.js (references/engine.md).
2. Mostramos solo lo que existe en el producto. Las pantallas, anotaciones y estados provienen del código, prototipo, docs/ o capturas de pantalla del proyecto actual. No hay funcionalidades inexistentes en el vídeo. Los datos son nombres cortos ficticios. Cualquier elemento inventado para la escena (respuestas, textos de estado) se muestra al usuario para su verificación.
3. El estilo es del producto, no del skill. Los colores, acentos, fuentes y logotipos provienen del perfil de marca del proyecto (motion/brand/), recopilado de su código (references/brand.md). El perfil neutro del skill es solo para el borrador.
4. No sintetizamos la voz nosotros mismos. Los TTS locales suenan robóticos. El usuario recibe el texto y el prompt para Gemini TTS por separado (o graba su propia voz) y envía el archivo; align_vo.py lo desglosa por palabras. Hasta entonces, el vídeo vive con subtítulos y música.
5. Primero con los ojos, luego el renderizado. Las hojas de contactos de los momentos clave en los formatos seleccionados y verify_scene.py se ejecutan antes del renderizado completo. Es más barato detectar errores de composición en los fotogramas.
6. No adivinamos las decisiones del usuario. El idioma, los formatos, la velocidad, la música y la publicación se determinan a partir del brief o de una pregunta. Los valores predeterminados a continuación son solo cuando el usuario no ha indicado lo contrario.

Proceso

0. Entorno (una vez por máquina)

python3 <skill>/scripts/check_env.py

Se necesita Python 3.9+, ffmpeg/ffprobe, pip install playwright numpy scipy pillow (+ faster-whisper para la locución), python -m playwright install chromium; para la versión acelerada, ffmpeg con rubberband. Es mejor hacerlo en el venv del proyecto o cerca; no instales las dependencias sin el consentimiento del usuario; solo sugiere los comandos.

1. Brief

Funcionalidad; duración (si no se indica: 30–35 s para una funcionalidad, 60–75 s para una sección); audiencia y propósito (tutorial, promocional, inversor, landing); idioma; formatos (si no se indica: 16:9, ofrecer vertical 9:16). No más de dos preguntas a la vez; el resto son valores predeterminados razonables, mencionados en la respuesta. Más detalles en references/brief.md.

2. Datos sobre la funcionalidad — del proyecto actual

Lee el código y el prototipo de la funcionalidad, docs/, capturas de pantalla: pantallas, anotaciones exactas, marcadores de posición, botones, estados, qué hay y qué no. Si no está claro qué ve el usuario después de la acción principal, pregunta.

3. Perfil de marca — una vez por proyecto

Si el proyecto no tiene motion/brand/, recopílalo según references/brand.md: brand.css (tokens de variables CSS, temas, configuración de Tailwind), fuentes locales con derechos verificados, logotipos. Muestra al usuario un fotograma de muestra antes del primer vídeo. Los vídeos siguientes usarán el perfil ya preparado.

4. Guion gráfico

Tabla «código de tiempo · qué hay en el fotograma · cámara/animación · réplica» (references/storyboard.md: esqueletos por duración, densidad de texto 1.3–1.6 palabras por segundo, arquetipos de escenas). Si el vídeo dura más de 30 s o el brief está incompleto, muestra la tabla y espera el «ok»; si es corto y el brief es claro, se puede proceder directamente y mostrar la tabla junto con los primeros fotogramas.

5. Proyecto del vídeo

Si el proyecto ya tiene un lugar para vídeos (promo/, design/motion/, etc.), colócalo allí; de lo contrario, motion/<slug>/.

python3 <skill>/scripts/new_project.py motion/<slug> --brand motion/brand --lang <idioma> --title "Funcionalidad · Producto"

Dentro: video.html, plan.js, cues.js, tmap.js, engine.js, processing.js, base.css, brand/, build/, out/, README.md. build/ y los out/*.mp4 pesados se añaden a .gitignore del proyecto, a menos que el usuario decida lo contrario. Si el proyecto tiene docs/, añade un enlace corto al vídeo y su README.

6. plan.js y escenas

plan.js es la fuente única: duration, fps, canvas, language, product, audience, hold, réplicas vo[] (id, at, text, tts, subs), pronounce, emphasis, music. JSON estricto después de window.PLAN =.

En video.html, reemplaza el contenido de demostración de la plantilla con las pantallas de la funcionalidad: build (elementos repetidos), setup (medidas E.measureAt + E.rect, claves de cámara para ambos formatos, cursor, clics), scene(t). Los eventos en pantalla se sincronizan con las palabras de las réplicas (E.sync('p3:palabra', respaldo)). Las pantallas oscuras y los modales se hacen con E.dim() y en #app2. Recetas de escenas en references/scenes.md, reglas de movimiento y cámara en references/motion.md. Vista previa con control deslizante: video.html?preview=1 mediante python3 -m http.server desde la carpeta del vídeo.

7. Verificación con fotogramas

python3 <skill>/scripts/verify_scene.py video.html --fmt both
python3 <skill>/scripts/render.py video.html stills --fmt both --times 1,6,9,12,15,19,23,27,31,34 --sheet

Abre build/stills/sheet_h.jpg y sheet_v.jpg: la cámara apunta a la acción; las etiquetas están bajo sus fragmentos; el texto no se divide ni se corta; el énfasis está solo en sus lugares; en la transición «procesamiento → resultado» no hay destello blanco; en 9:16 el texto es grande, los subtítulos están sobre el panel inferior. Corrige hasta que los fotogramas clave estén limpios. Antes del primer renderizado, revisa references/pitfalls.md.

8. Locución

python3 <skill>/scripts/vo_pack.py plan.js            # --model 3.8 para Gemini 3.8 Flash TTS, --voice female

Proporciona out/voiceover/tts_text.txt y tts_prompt.txt en dos bloques de código separados (el texto en el campo de texto, el prompt en el campo de estilo), la voz (para ruso masculino, Schedar primero), la solicitud de grabar una sola toma completa y la tabla de timing.md. También vale la propia grabación del usuario con el mismo texto. Reglas en references/voiceover.md.

9. Llegó la locución → alineación

python3 <skill>/scripts/align_vo.py plan.js voice.wav        # build/vo_aligned.wav, cues.js, out/subtitles.srt, informe

Lee build/align_report.md: las palabras «verificar auditivamente» se muestran al usuario con el código de tiempo; las réplicas desplazadas es mejor corregirlas en plan.js. El script se detendrá si el habla se extiende hasta el fotograma final (hold).

Aceleración: solo una sugerencia. Si el vídeo «se alarga», ofrece retime.py (lectura +4.5 %, pausas más cortas, una línea de tiempo para vídeo, voz, música y subtítulos). Haz solo la principal si se acepta.

10. Música, mezcla, renderizado, ensamblaje

python3 <skill>/scripts/music.py plan.js --out build/music.wav                         # síntesis de borrador según la sección music
python3 <skill>/scripts/prepare_music.py plan.js track.mp3 --end-align --out build/music.wav   # o pista del usuario
python3 <skill>/scripts/mix.py build/music.wav build/vo_aligned.wav --out build/mix.wav
python3 <skill>/scripts/render.py video.html video --fmt h --out build/h_subs.mp4
python3 <skill>/scripts/render.py video.html video --fmt h --qs subs=0 --out build/h.mp4
python3 <skill>/scripts/assemble.py --video build/h.mp4 --audio build/mix.wav --out out/<slug>_16x9.mp4
python3 <skill>/scripts/assemble.py --video build/h_subs.mp4 --audio build/mix.wav --out out/<slug>_16x9_subs.mp4
#   … y lo mismo para --fmt v (_9x16, _9x16_subs), si el brief incluye vertical
python3 <skill>/scripts/verify_media.py plan.js out/*.mp4 --sheet

El renderizado dura aproximadamente 2–5 minutos por minuto de vídeo y formato; ejecútalo en segundo plano o por partes (--start/--end, unión con assemble.py --video part1 part2 …). La música sintetizada es provisional; para un vídeo público, sugiere una pista con licencia. Detalles en references/audio.md. Si se solicita, export_web.py (MP4 limpio, WebVTT, póster, fotograma final) para un reproductor en el sitio web; no publiques sin una decisión explícita del usuario.

Qué entregar al usuario

• Archivos en los formatos seleccionados: <slug>_16x9.mp4, <slug>_16x9_subs.mp4 (+ _9x16), SRT, paquete de locución (antes de grabar la voz), hoja de contactos. Rutas de archivos; si hay una herramienta de envío de archivos, envíalos.
• Resumen: duración, qué hay en cada escena; qué es inventado y requiere verificación con el producto; qué música es provisional; qué no se ha comprobado (por ejemplo, no se ha escuchado auditivamente).
• Actualiza el README de la carpeta del vídeo: estado, decisiones del brief, cómo reensamblar.
• Sin repetir el proceso ni hacer publicidad de «IA revolucionaria».

Archivos del skill

templates/engine.js	motor de fotogramas: cámara, cursor, clics, oscurecimiento y capa superior #app2, subtítulos (subs=0), mapa de tiempo tmap.js, vista previa preview=1, medidas, markup/grad/plural
templates/base.css	componentes sobre tokens de marca: encabezado, campo con degradado, etiquetas, sugerencias, procesamiento oscuro, resultados, popovers, chat, valoración, final
templates/brand/	perfil de marca neutro: brand.css, Manrope (OFL), logotipo provisional
templates/processing.js	animación de procesamiento neutra (anillos, destello de acento, tarjetas que entran volando)
templates/starter.html, plan.js	demo funcional de ≈36 segundos «Búsqueda inteligente» en el producto ficticio Demo: gancho → entrada con etiquetas → sugerencias → procesamiento → resultados con «por qué» → guardado → valoración → final
scripts/	check_env, new_project, verify_scene, render, vo_pack, align_vo, retime, music, prepare_music, mix, assemble, verify_media, export_web
references/	brief.md · brand.md · storyboard.md · scenes.md · motion.md · engine.md · voiceover.md · audio.md · pitfalls.md