wbr664393425-lgtm/rui-ui-promo-video

Workflow de vidéo promotionnelle avec composants réels

Style par défaut = « Une ligne » : Un motif de marque issu du produit traverse toute la vidéo, accompagné de blancs et de trois points forts déclenchés par de vraies interactions. Les plans de type « manuel d'instructions » et les plans de type « keynote avec effets superposés » sont présentés en contraste dans le manuel créatif.

templates/ = Shell de capture (généralisé, avec corrections des pièges déjà appliquées) + scripts de composition, de style, de musique et d'exportation de la version v3 finale. Copier dans videos/<name>/ puis modifier les emplacements marqués 【À MODIFIER OBLIGATOIREMENT】.

Lire selon les besoins :

• references/creative-playbook.md : Motif, trois points forts, règles de blanc, texte, tableau de rythme. À lire avant de définir le storyboard.
• references/compose-recipes.md : Mesures des coordonnées, mapping temporel, conteneurs de plans, panneaux lumineux, tracés, projecteurs, retournement du monde, assemblage de logo, transitions, écriture de timeline. À lire avant d'écrire la composition.
• references/pitfalls.md : Problèmes de capture, rendu, audio, livraison → causes profondes → tableaux de traitement et commandes de validation. Consulter en cas d'anomalie.

Stack technique

Étape	Technologie	Points clés
Composition/Rendu	HyperFrames ([email protected] fixé, npx --yes, pas dans les dépendances du projet)	check pour valider, snapshot pour extraire des images, render pour produire la vidéo
Animation	GSAP (copier la version installée dans le projet métier vers assets/vendor/gsap.min.js)	Une seule timeline paused enregistrée dans window.__timelines[id]
Build de capture	Vite + @vitejs/plugin-vue (createRequire pour résoudre les dépendances depuis le frontend)	Root indépendant ; envDir/publicDir pointant vers le frontend ; vendor dans un bloc séparé
Horloge déterministe	Plugin Vite transform	Tous les setTimeout/rAF/Date.now/performance.now (appel nus ou avec préfixe window.) sont redirigés vers window.__shoot
Isolation des données	fixtureFetch en mémoire (incluant les simulations d'écriture) + liste blanche réseau + seed fixé + epoch fixé + localisation fixée	Données fictives, requêtes métier détournées vers les fixtures, horloge de capture fixe
Scripts d'interaction	performActions(t) + once/byText/rowButton/typeInto	Déclenche des clics réels, saisies, glissements à des secondes précises
Média	Paysage PROMO_RESOLUTION=4k en 2x pixels ; mobile 430×932 dans une fenêtre séparée	La composition peut zoomer fortement sans perte de netteté
Musique	Python3 + NumPy (96 BPM, réverbération FFT, seed fixé)	Silences et accents sur les points forts, clochettes pour l'activation des nœuds
Loudness/Export	FFmpeg loudnorm en deux passes (−14 LUFS / TP −3), encapsulation de la musique originale normalisée, version compressée, vignette	Vidéo principale + -share.mp4 (environ 11 Mo) + PNG de couverture

Structure des répertoires

videos/<name>/
  promo.config.mjs   appDir/srcDir/entry/motionFile/id/duration/coverAt/hyperframes — seule configuration liée au projet
  capture/           index.html (shell de capture) bootstrap.ts (horloge/isolation/interaction) fixtures.ts (données fictives, à écrire) 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 (généré par compose) film.css package.json README.md

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

Processus

1. Définir la direction : Lire PRODUCT.md/DESIGN.md/identité de marque, trouver le motif et concevoir trois points forts selon le creative-playbook. Ne demander la confirmation à l'utilisateur que sur deux choses : la ligne créative (proposer 2–3 directions, recommander « un seul motif ») et le ton du texte (conserver ou changer).
2. Storyboard : Chaque scène = page réelle + titre en Songti + seconde clé de l'interaction + forme du motif dans cette scène ; rythme de référence pour 45 secondes dans playbook. Écrire dans le tableau de storyboard du README.
3. Shell de capture : bootstrap.ts installe window.__shoot, la liste blanche réseau, la localisation fixée, efface le stockage (y compris les brouillons IndexedDB), préconfigure le thème/vue/token hors ligne, appelle replaceState vers la route puis import le point d'entrée du produit ; pour les pages lentes, utiliser waitFor/settle pour vider les rAF ; injecter les styles pour masquer le curseur, les barres de défilement et le caret. Les fixtures dans fixtures.ts reprennent les champs des vrais endpoints, les écritures ne modifient que la mémoire. Prévisualiser d'abord dans le navigateur avec ?shot=<scene>&live.
4. Capture : npm run capture (un seul worker). Pour les plans paysage avec un fort zoom, relancer PROMO_RESOLUTION=4k npm run capture.
5. Mesurer les coordonnées : Extraire des images des rushes (coordonnées 1920, recadrage local 4K pour des valeurs précises) pour mesurer les trajectoires, boutons, popups, positions des nœuds.
6. Composition : Modifier le tableau des segments, les coordonnées, le texte et les points temporels dans compose-film.mjs, en réutilisant ses fonctions utilitaires ; règles dans compose-recipes. À chaque tour : npm run compose && npm run check, puis npm run snap -- <seconde-clé> pour voir la planche contact (entrées/sorties des points forts, transitions, alignement des annotations).
7. Musique : Modifier les points temporels dans compose-audio.py (accents sur les points forts, silences, clics, clochettes de nœuds), npm run audio.
8. Rendu et validation : Lancer npm run render en arrière-plan ; après la fin, vérifier la durée/le nombre d'images/la résolution/le framerate avec ffprobe, le volume et le vrai pic avec ebur128, détecter les noirs (les noirs intentionnels doivent être documentés), et extraire environ 18 images en mosaïque pour inspection visuelle. Pour ne modifier que la vignette, exécuter npm run remux.

Contraintes

• Ne pas modifier le code source ni les dépendances du produit ; la réécriture de l'horloge ne se produit que dans le build de capture.
• Utiliser uniquement des données fictives, ne pas se connecter aux backends/DB métier, ne pas lire de véritables identifiants ; les ressources tierces en ligne (ex: cartes) passent par la liste blanche, les clés ne vont que dans le répertoire de build ignoré par git. Le README doit décrire la méthode d'isolation, le seed et la date fixe.
• N'utiliser que des chiffres réellement présents dans l'interface ; le texte et les visuels ne doivent pas contenir les mots « démo/échantillon/simulation ».
• Respecter le DESIGN.md du projet et les couleurs de la marque ; les polices doivent être déclarées localement (Songti SC / PingFang SC / Georgia).
• Les artefacts intermédiaires (.capture-build/ .shots/ .quality/ renders/ logs) vont dans .gitignore ; les anciennes versions du projet sont conservées telles quelles, les nouvelles versions créent un nouveau répertoire.
• Ne pas commiter ni publier sur des plateformes externes, sauf demande explicite de l'utilisateur.
• Avant d'écrire ou de modifier une composition, appeler hyperframes-core, hyperframes-animation, hyperframes-cli pour vérifier l'API actuelle si nécessaire.

Liste de livraison

• Vidéo principale MP4 (45.000 s / 2700 images / 1920×1080 / 60 fps / H.264 yuv420p / AAC 320k 48 kHz / −14 LUFS / pic réel ≤ −1 dBTP).
• Version compressée -share.mp4 et vignette PNG, livrées via le mode de transfert de fichiers supporté par la plateforme actuelle.
• index.html + film.css modifiables, ainsi que les rushes et scripts.
• README : description visuelle, storyboard, description de la musique, commandes de reproduction, isolation de la capture, validation de la livraison.