wbr664393425-lgtm/rui-ui-promo-video

Flujo de trabajo para video promocional con componentes reales

Estilo predeterminado = «Una Línea»: un motivo de marca del producto recorre todo el video, combinado con espacios en blanco y tres clímax activados por interacciones reales. Como contraste, se incluyen tomas de estilo instructivo y tomas tipo lanzamiento con efectos apilados; consulte el manual creativo.

templates/ = cascarón de grabación (generalizado, con correcciones de errores) + scripts de composición, estilo, música y exportación (versión v3 finalizada). Copie a videos/<nombre>/ y modifique las secciones marcadas con 【OBLIGATORIO】.

Lea según sea necesario:

• references/creative-playbook.md: motivo, tres clímax, reglas de espacios en blanco, texto, tabla de tiempos. Lectura obligatoria antes de definir el storyboard.
• references/compose-recipes.md: coordenadas, mapeo temporal, contenedores de tomas, paneles de luz, líneas trazadas, enfoque, inversión de mundo, ensamblaje de logotipos, transiciones, escritura de líneas de tiempo. Leer antes de escribir la composición.
• references/pitfalls.md: tabla de fenómenos → causas raíz → soluciones y comandos de verificación para grabación, renderizado, audio y entrega. Consultar primero ante anomalías.

Stack tecnológico

Fase	Tecnología	Puntos clave
Composición/Renderizado	HyperFrames (fijo [email protected], npx --yes, no instalar en dependencias del proyecto)	check para validar, snapshot para extraer fotogramas, render para producir el video
Animación	GSAP (copiar la versión ya instalada en el proyecto de negocio a assets/vendor/gsap.min.js)	Registrar una línea de tiempo paused única en window.__timelines[id]
Construcción de capturas	Vite + @vitejs/plugin-vue (createRequire para resolver dependencias desde el frontend)	Raíz independiente; envDir/publicDir apuntando al frontend; vendor como chunk separado
Reloj determinista	Plugin Vite transform	Todas las llamadas desnudas y con prefijo window. de setTimeout/rAF/Date.now/performance.now se redirigen a window.__shoot
Aislamiento de datos	fixtureFetch en memoria (incluye simulación de operaciones de escritura) + lista blanca de red + semilla fija + época fija + ubicación fija	Datos ficticios, solicitudes de negocio redirigidas a fixtures, reloj de grabación fijo
Script de interacción	performActions(t) + once/byText/rowButton/typeInto	Conducir clics reales, entradas de teclado, arrastres en segundos especificados
Materiales	Horizontal PROMO_RESOLUTION=4k a 2x píxeles; móvil 430×932 con viewport separado	La composición puede acercarse significativamente manteniendo nitidez
Música	Python3 + NumPy (96 BPM, reverberación FFT, semilla fija)	Silencios en los tiempos de caída, acentos en los clímax, tonos de campana al iluminar nodos
Sonoridad/Exportación	FFmpeg con normalización de dos pasos loudnorm (−14 LUFS / TP −3), encapsulado musical original normalizado, versión comprimida, portada	Video principal + -share.mp4 (~11 MB) + portada PNG

Estructura de directorios

videos/<nombre>/
  promo.config.mjs   appDir/srcDir/entry/motionFile/id/duration/coverAt/hyperframes — única configuración relacionada con el proyecto
  capture/           index.html (cascarón de grabación) bootstrap.ts (reloj/aislamiento/interacción) fixtures.ts (datos ficticios, deben ser reescritos) vite.config.mjs
  scripts/           render-footage.mjs compose-film.mjs compose-audio.py normalize-audio.mjs render-film.mjs remux.mjs
  assets/            footage/ footage-4k/ audio/score-final.wav vendor/gsap.min.js
  index.html (generado por compose) film.css package.json README.md

Scripts npm: capture / compose / audio / check / snap -- <segundo,segundo> / render / remux / dev.

Flujo

1. Definir dirección: Leer PRODUCT.md/DESIGN.md/identidad de marca; según el creative-playbook, buscar el motivo y diseñar tres clímax. Confirmar solo dos cosas con el usuario: línea creativa (ofrecer 2–3 opciones, recomendar «un motivo») y tono del texto (mantener el actual o cambiarlo).
2. Storyboard: Cada escena = página real + título en Songti + segundos clave de interacción + forma del motivo en esa escena; la referencia de ritmo para 45 segundos está en el playbook. Escribir en la tabla de storyboard del README.
3. Cascarón de grabación: En bootstrap.ts, instalar window.__shoot, lista blanca de red, ubicación fija, limpiar almacenamiento (incluyendo borradores de IndexedDB), preestablecer tema/vista/token sin conexión; replaceState a la ruta y luego import la entrada del producto; para páginas de carga lenta, usar waitFor/settle para vaciar rAF; inyectar estilos para cursor oculto, barra de desplazamiento y caret ocultos. fixtures.ts debe mantener los campos de las interfaces reales; las operaciones de escritura solo modifican la memoria. Primero previsualizar la interacción en el navegador con ?shot=<escena>&live.
4. Captura: Ejecutar npm run capture (un solo worker); para tomas horizontales con mucho zoom, ejecutar luego PROMO_RESOLUTION=4k npm run capture.
5. Medir coordenadas: Desde los fotogramas extraídos del material (coordenadas 1920, recorte local 4K para valores precisos), medir las posiciones de las polilíneas, botones, ventanas emergentes, nodos de paso.
6. Composición: Modificar la tabla de fragmentos, coordenadas, texto y puntos temporales en compose-film.mjs, reutilizando sus funciones auxiliares; las reglas están en compose-recipes. En cada ronda, ejecutar npm run compose && npm run check, luego npm run snap -- <segundos clave> para ver la hoja de contactos (entrada/salida de clímax, transiciones, alineación de anotaciones).
7. Música: Modificar los puntos temporales en compose-audio.py (acentos de clímax, segmentos de silencio, clics, tonos de campana en nodos) y ejecutar npm run audio.
8. Renderizado y verificación: Ejecutar npm run render en segundo plano; al finalizar, usar ffprobe para verificar duración/fotogramas/resolución/fps, ebur128 para verificar sonoridad y pico verdadero, blackdetect para verificar si los negros son intencionales (requiere justificación), y extraer ~18 fotogramas en un collage para inspección visual. Para cambiar solo la portada, ejecutar npm run remux.

Restricciones

• No modificar el código fuente ni las dependencias del producto; la reescritura del reloj solo ocurre en la construcción de captura.
• Usar solo datos ficticios; no conectar con backends ni bases de datos de negocio; no leer credenciales reales. Los recursos en línea de terceros (como mapas) deben pasar por la lista blanca; las claves solo deben ir en directorios de construcción ignorados. El README debe describir claramente el método de aislamiento, la semilla y la fecha fija.
• Las anotaciones deben usar solo números que realmente aparezcan en la interfaz; las imágenes y el texto no deben contener las palabras «demostración», «ejemplo» o «simulación».
• El diseño visual debe seguir el DESIGN.md del proyecto y los colores de la marca; declarar las fuentes localmente (Songti SC / PingFang SC / Georgia).
• Los artefactos intermedios (.capture-build/ .shots/ .quality/ renders/ logs) deben incluirse en .gitignore; las versiones antiguas del proyecto deben conservarse tal cual, y las nuevas versiones deben crearse en un directorio separado.
• No realizar commits ni publicar en plataformas externas a menos que el usuario lo solicite explícitamente.
• Antes de escribir o modificar una composición, verificar las API actuales de hyperframes-core, hyperframes-animation y hyperframes-cli según sea necesario.

Lista de entrega

• Video principal MP4 (45.000 s / 2700 fotogramas / 1920×1080 / 60 fps / H.264 yuv420p / AAC 320k 48 kHz / −14 LUFS / pico verdadero ≤ −1 dBTP).
• Versión comprimida -share.mp4 y portada PNG, entregados a través del medio compatible con la plataforma actual.
• index.html + film.css editables, junto con materiales y scripts.
• README: descripción visual, tabla de storyboard, descripción musical, comandos de reproducción, aislamiento de captura y verificación de entrega.