syklayou-glitch/video-shotcraft

video-shotcraft : Création de vidéos produit cinématographiques

Une bibliothèque de production autonome : 152 fiches de plans (avec code démo et galerie d'échantillons dynamiques), un template complet de vidéo promotionnelle validé, des composants réutilisables et des ressources audio, le tout organisé en six étapes de travail. L'accent actuel est mis sur les vidéos promotionnelles pour produits web et desktop, mais les fiches de plans sont un vocabulaire d'animation universel – elles peuvent être utilisées individuellement pour n'importe quel plan dans n'importe quelle vidéo.

Déterminer le mode avant d'appeler

Une vidéo promotionnelle complète propose trois modes mutuellement exclusifs. Avant de commencer la collecte de ressources, le storyboard ou l'implémentation, déterminez d'abord si l'utilisateur a déjà fait un choix clair ; si c'est le cas, exécutez directement sans redemander, et ne passez pas à un autre mode.

1. Utilisation directe du template : Suivez le processus de remplacement d'Ink Press. Lisez template/TEMPLATE.md, puis remplacez les captures d'écran, le texte et les informations de marque du produit cible selon la structure de plans existante.
2. Création libre autonome : Lisez references/pipeline.md. L'agent détermine de manière autonome la direction visuelle, le mapping des plans, le storyboard, les ressources et l'audio en fonction des exigences de l'utilisateur et du contenu du projet, et avance en continu jusqu'au rendu final ; ne s'arrête pas pour attendre la confirmation de l'utilisateur lors des phases de brief produit, styleframe, mapping des plans ou storyboard.
3. Création collaborative : Lisez references/guided-free-creation.md. L'agent propose d'abord des jugements et des solutions fondés, que l'utilisateur valide étape par étape pour le brief produit, les décisions sur les besoins, la direction visuelle, le mapping des plans et le storyboard final ; une fois le storyboard approuvé, passez à la phase finale de collecte de ressources et de production dans references/pipeline.md.

Lorsque l'utilisateur fournit un chemin de projet, une URL, une capture d'écran ou une vidéo mais n'a pas encore choisi de mode, effectuez d'abord une inspection minimale et en lecture seule du produit : comprenez le positionnement du produit, ses fonctionnalités principales, son aspect visuel, son état de démonstration et les risques liés aux ressources ; ne modifiez pas le projet métier, ne collectez pas de données sensibles, n'écrivez pas de code vidéo. Après l'inspection, présentez les trois modes en expliquant :

• si Ink Press convient au produit, avec des raisons précises pour et contre ;
• si la création libre autonome et la création collaborative conviennent, en indiquant quels indices visuels du produit seraient conservés ;
• le mode recommandé par l'agent, avec ses justifications et compromis.

Demandez ensuite clairement : « D'après l'inspection du produit ci-dessus, je recommande le mode ××. Faut-il continuer avec ce mode ? » Informez également l'utilisateur qu'il peut consulter les échantillons dynamiques sur https://vincentwei1021.github.io/video-shotcraft/ et choisir les effets de plan à utiliser dans la vidéo.

Lorsque l'utilisateur n'a pas encore fourni de projet ou de page à inspecter, présentez brièvement les trois modes puis demandez ; ne recommandez pas Ink Press par défaut simplement parce que c'est un template prêt à l'emploi.

• L'utilisateur choisit le template : lisez intégralement template/TEMPLATE.md et suivez le processus du template original.
• L'utilisateur choisit la création libre autonome : lisez intégralement references/pipeline.md, l'agent avance de manière autonome sans attendre de confirmation par étapes.
• L'utilisateur choisit la création collaborative : lisez intégralement references/guided-free-creation.md et collaborez selon les points de validation qui y sont définis.
• L'utilisateur n'a pas encore décidé : restez ici en attendant un choix ; ne choisissez pas à sa place et ne commencez pas la production.

Exception 1 : Lorsque l'utilisateur nomme explicitement le template Ink Press, le mode template est considéré comme choisi. Par exemple : « Fais une vidéo promotionnelle pour mon produit avec le template Ink Press. » Dans ce cas, ne demandez plus, lisez directement template/TEMPLATE.md et exécutez selon le parcours du template.

Exception 2 : Lorsque l'utilisateur spécifie clairement qu'il souhaite utiliser ou se référer à certaines fiches de plans, la contrainte des plans est déjà fixée. Par exemple : « Utilise deck-deal-flyin et row-embed pour cette vidéo » ou « Réfère-toi à l'effet de spotlight-hero-card. » Dans ce cas, ne présentez pas le template et ne demandez pas s'il faut l'utiliser ; confirmez les plans spécifiés selon les règles de résolution des noms de la Galerie, lisez chaque fiche en entier, et localisez le code démo exact selon la « Référence d'implémentation » de la fiche. Un plan unique peut être exécuté une fois la ressource cible claire ; pour une vidéo promotionnelle complète, si l'utilisateur n'a pas encore précisé s'il s'agit d'une création libre autonome ou collaborative, demandez uniquement ces deux modes, les plans spécifiés servant de contrainte pour la suite, sans être automatiquement assimilés à la création collaborative.

Quatre cas d'utilisation

1. Vidéo promotionnelle complète (parcours template) : Vous voulez un résultat très similaire à la vidéo template → lisez template/TEMPLATE.md, suivez le « Guide de remplacement pour reproduire le produit » en adaptant les ressources plan par plan.
2. Vidéo promotionnelle complète (création libre autonome) : Vous voulez un nouveau style et autorisez l'agent à décider de manière autonome → lisez references/pipeline.md, avancez de la compréhension du produit à la vérification finale sans vous arrêter pour confirmation à chaque étape.
3. Vidéo promotionnelle complète (création collaborative) : Vous voulez participer aux décisions clés → lisez references/guided-free-creation.md, validez le brief produit, les décisions sur les besoins, la direction visuelle, le mapping des plans et le storyboard final ; après approbation, continuez à partir de la collecte finale des ressources dans le pipeline.
4. Plan unique / effet unique : Sélectionnez une fiche dans references/shots/ (ou laissez l'utilisateur choisir dans la galerie gallery/), lisez la fiche en entier et localisez le code démo exact selon la « Référence d'implémentation », puis adaptez-le à la ressource cible.

Frontière entre création libre autonome et création collaborative

La création libre autonome confie les décisions créatives et techniques à l'agent. L'agent déduit dynamiquement du contenu du projet les points clés du produit, la direction visuelle, le mapping des plans, le storyboard, le traitement des ressources et la conception audio, enregistre les décisions importantes et exécute directement ; sauf en cas d'absence d'entrée nécessaire impossible à déduire en toute sécurité, il ne pose pas de questions, ne s'arrête pas par étapes et ne demande pas de confirmation des livrables intermédiaires. Les exigences explicites de l'utilisateur restent toujours contraignantes et ne peuvent pas être remplacées par les choix par défaut de l'agent.

La création collaborative utilise une validation par étapes. Par défaut, lisez references/guided-free-creation.md, ne posez que 1 à 3 questions par tour pour minimiser les reprises, et arrêtez-vous pour attendre la confirmation de l'utilisateur aux étapes de brief produit, décisions sur les besoins, direction visuelle, mapping des plans et storyboard final. L'utilisateur valide la direction métier et créative ; l'agent réalise de manière autonome la méthode de collecte, les paramètres d'implémentation, le sound design, le projet Remotion, le rendu et l'assurance qualité technique.

En création collaborative, si l'utilisateur dit explicitement « Décide complètement » ou « Passe la confirmation et fais-le », basculez en mode création libre autonome et enregistrez ce choix ; ne prétendez pas avancer de manière autonome tout en continuant à demander une validation par étapes.

Le mapping fonction-vers-plan n'est qu'une « grammaire de mouvement à utiliser », pas un storyboard complet. Après avoir confirmé le mapping en création collaborative, l'agent doit fournir l'ordre des plans, leur durée, le contenu visuel exact, l'état de la page, la source des ressources, les sous-titres, les transitions et les effets sonores ; seule l'approbation du storyboard complet déclenche la collecte finale des ressources. Lorsque l'utilisateur copie un nom de plan depuis la Galerie, il suffit de fournir le nom de la fiche ou « nom de fiche · nom de style » ; l'agent se charge de lire la fiche locale et le code démo.

Principes fondamentaux

1. Pour reproduire une page existante, utilisez de vraies captures d'écran ; l'UI recréée à la main est réservée aux scènes non-reproductives, avec une exigence de qualité et de clarté d'expression impérative. Pour montrer une page réelle du produit, démarrez d'abord un serveur dev local, utilisez un navigateur headless pour capturer une texture 2x de la page entière, découpez les éléments et produisez une table de coordonnées layout.json. Les scènes non-reproductives (ouverture abstraite, segment de marque, composant de démonstration indépendant) permettent une UI recréée à la main, mais si elle n'atteint pas une qualité publiable ou si le spectateur ne comprend pas ce qu'elle exprime, revenez à la capture d'écran. Traitez les données de page selon leur sensibilité : les données de démonstration publiques ne peuvent être conservées qu'après validation explicite dans le brief produit ; les données clients, personnelles, internes, les clés, les données en temps réel ou autres données sensibles doivent être fictives ou anonymisées, et figées avant la collecte.

2. Le langage visuel de toute la vidéo doit émerger du produit lui-même, et non d'une « peau de vidéo promotionnelle » non pertinente. Avant de créer un styleframe, extrayez du système de design du produit/du site, du code source ou des styles calculés, et rédigez une spécification de design : famille de polices et graisses, hiérarchie des tailles, hauteurs de ligne/espacement, grille, espacement, alignement, densité d'information et coins arrondis, ainsi que couleurs d'arrière-plan/surface/texte/accentuation/état, dégradés et matières. Tous les titres, sous-titres, chiffres, cartes de texte, typographie, transitions, particules, effets lumineux et autres animations de la vidéo doivent utiliser ou étendre avec retenue ces tokens, tout en correspondant au ton, au goût et à la texture du produit. Lorsque vous suivez le parcours template ou fiche de plan, héritez uniquement de la structure des plans, de la grammaire de mouvement, du rythme et des paramètres déjà réglés ; la police, la mise en page, les couleurs et les matières doivent être réadaptés au produit cible. Si la narration nécessite de s'écarter du visuel du produit, en création collaborative, expliquez d'abord la raison et faites valider par l'utilisateur ; en création libre autonome, notez la raison et les compromis dans la spécification de design, puis continuez.

3. Le cinématographique provient de la combinaison des mouvements de caméra, de la lumière, du rythme et du son, et non d'animations tape-à-l'œil. Ce qui est régulièrement apprécié : un arc d'action complet pour un protagoniste unique (projection → zoom avant → flottement → retour), une accélération dictée par une métaphore physique (distribution de cartes), un orbit-shot latéral en caméra inclinée pour un gros plan, une structure sonore riser → impact → sparkle. L'entrée en scène d'éléments en masse repose sur le mouvement lui-même, pas sur des éclats individuels – des glints/déclenchements décoratifs en groupe sont bon marché, un effet lumineux ponctuel de haute qualité est acceptable.

4. Chaque plan raconte un seul effet ; après le dépôt des informations clés, il faut respirer. Un procédé d'animation (entrée volante/empilement/retournement) n'est le protagoniste qu'une seule fois dans toute la vidéo ; les plans et taglines répétés sont supprimés sans exception. La préférence rythmique est unidirectionnelle : tous les retours historiques indiquent « ralentir/rester », jamais une seule fois « trop lent » – le logo de marque doit tenir ≥1s après son dépôt, la fin d'un effet de masse doit laisser 0,5s d'immobilité, le mouvement d'ouverture doit durer au moins 3s. Prévoyez un budget d'images pour les hold/rest lors de la planification de la timeline.

5. Pour une vidéo avec une musique rythmée forte, toutes les transitions et animations doivent être calées sur le beat. L'utilisateur a déjà choisi la musique → avant de commencer, effectuez une analyse rythmique (ajustement de grille avec librosa pour obtenir le BPM/phase réels + détection des coups de kick/snare/hihat en trois catégories), validez la grille par couverture transitoire avant le storyboard ; la timeline utilise la notation beatF(n) pour les temps, les accents clés sont verrouillés sur les transitoires réelles plutôt que sur des points de grille interpolés. Après rendu, extrayez la piste audio de la vidéo finale et vérifiez que l'erreur de coupe ≤3f. La synchronisation concerne le timing, pas l'amplitude – un impact rythmique agissant sur un calque entier/caméra est considéré comme un grand slam, limité à ≤3 occurrences dans toute la vidéo (règle esthétique R4) ; les autres effets sur le beat n'affectent que les calques d'éléments. Méthodologie dans references/music-beat-sync.md. Les vidéos avec BGM sont livrées en deux versions : avec BGM + sans BGM (en conservant les SFX), rendues à partir de la même timeline grâce à la prop input bgm, pour permettre à l'utilisateur d'ajouter sa propre musique en post-production.

6. Pour utiliser un effet de fiche de plan, il faut d'abord analyser l'index de la Galerie et lire le code d'implémentation de la démo précise. Utilisez d'abord gallery/api/library.json pour valider le nom de la fiche et la style-key, puis localisez le TSX spécifique selon la « Référence d'implémentation » de la fiche. La fiche donne la sémantique et les paramètres ; le code source de la démo précise est la vérité réelle des paramètres réglés (easing, rapport de durée, timing des masques, contournement des bugs connus). Des adaptations sont autorisées, mais les paramètres marqués comme « pièges connus / points faibles » sur la fiche ne doivent pas être dégradés – la qualité ne fait que monter, jamais descendre. Réécrire de zéro en se basant uniquement sur le nom de la fiche et la compréhension, c'est abandonner tout l'accumulation de réglages.

7. La création collaborative place les validations bon marché en amont ; la création libre autonome conserve les mêmes décisions sous forme d'enregistrements d'exécution. L'ordre brief produit → tableau des décisions besoins-à-exécution → direction textuelle → styleframe → mapping des plans → storyboard reste le même ; en création collaborative, il est soumis étape par étape à l'utilisateur ; en création libre autonome, l'agent le sélectionne et avance en continu. Aucun des deux modes ne doit entrer dans l'implémentation plan par plan sans direction définie.

8. Validation tout au long du processus + révision indépendante avant livraison. À partir de l'étape 5, chaque plan est vérifié avec npx remotion still pour une image fixe d'auto-vérification ; après chaque série de modifications, effectuez un rendu complet + extraction d'images avec ffmpeg pour révision. Avant livraison, envoyez un sous-agent propre avec un contexte vierge pour une révision finale indépendante. Les entrées de la révision incluent la vidéo finale, les images clés, le brief produit, le tableau des décisions besoins-à-exécution, la direction visuelle/styleframe confirmée ou enregistrée pour le mode actuel, le mapping fonction-vers-plan, les noms/variantes des fiches de la Galerie, le TSX démo précis, les échantillons/images clés de la Galerie de référence, le storyboard final, les fiches de plans sélectionnées et les règles esthétiques ; suivez references/final-review.md pour vérifier simultanément la cohérence du plan, l'intégralité fonctionnelle, la fidélité des plans, la qualité technique visuelle/audio et la sécurité des données, en produisant un rapport avec des preuves par numéro d'image. Le créateur a un biais de confirmation sur sa propre production ; la première inspection ne doit jamais être confiée à l'utilisateur.

9. Rendu déterministe : Date.now()/Math.random() interdits, toute pseudo-aléatoire utilise une graine fixe (mulberry32/hash, seed dérivé de l'index), reproductible image par image.

Flux de travail

En création libre autonome, suivez references/pipeline.md de l'étape 0 en continu, sans attendre la confirmation de l'utilisateur par étape. En création collaborative, suivez d'abord references/guided-free-creation.md pour les étapes 0–3 (compréhension du produit, direction visuelle, mapping des plans et validation du storyboard), puis continuez à partir de l'étape 4 du pipeline (collecte finale des ressources), sans répéter les questions ni reconcevoir. Aux étapes 2–3, parcourez le frontmatter de chaque fiche dans references/shots/ et sélectionnez les plans selon la courbe d'énergie. Aux étapes 5–7, vérifiez en continu contre references/aesthetic-rules.md. À l'étape 6, lisez references/sound-design.md. Pour les vidéos synchronisées, suivez references/music-beat-sync.md tout du long.

Après la livraison de la vidéo finale dans tous les modes, demandez une fois par défaut à l'utilisateur s'il a également besoin d'exporter un projet CapCut (pour modifier le contenu/la taille/la couleur des sous-titres, changer la vitesse/réorganiser les plans, ajuster ou remplacer l'audio dans CapCut). Si l'utilisateur en a besoin ou demande explicitement l'export, lisez references/jianying-export.md et exécutez.

Quand lire quel fichier

Moment	Lire
Démarrage du projet et mode non défini	Inspection minimale en lecture seule, puis proposer les trois modes complets et recommander
Création libre autonome	pipeline.md (l'agent réalise les étapes 0–7 de manière autonome, sans attendre de confirmation par étape)
Création collaborative	guided-free-creation.md (validation des étapes 0–3), puis continuer à partir de l'étape 4 dans pipeline.md
L'utilisateur a déjà choisi la BGM	music-beat-sync.md (analyser d'abord, puis storyboard)
Parcours template	template/TEMPLATE.md intégralement
Conception du storyboard	sequences/ modèles de séquence (remplir d'abord le squelette de la vidéo) ; shots/ tout le frontmatter ; fiches sélectionnées lues en entier
Implémentation plan par plan	Fiche du plan en entier + code source démo précis selon la « Référence d'implémentation » + composants correspondants dans assets/lib/
Conception sonore	sound-design.md + assets/audio/
Validation	final-review.md + aesthetic-rules.md intégralement avec checklist (exécuté par un sous-agent indépendant)
Après livraison de la vidéo (export projet CapCut)	jianying-export.md + modules de plateforme dans jianying-export/

Utilisation des ressources

• Composants assets/lib/ : copiez-les dans le nouveau projet et modifiez-les librement (n'importez pas depuis cette bibliothèque). Liste : PageCam (caméra 2.5D pour page – base de tous les plans de « page réelle »), ClipCard (emballe une source vidéo externe mp4 comme un « personnage de carte » piloté par le squelette de mouvement de la fiche de plan, avec boucle de fondu croisé OffthreadVideo – lecture continue si la source est plus courte que le plan), DigitRoll, FlashCut, Caption, FlatPanel, VerticalTicker (mur de défilement 3D infini), helpers(rand/shake/camera/motion). FlatPanel et helpers/camera nécessitent three + @react-three/fiber + @remotion/three ; les autres nécessitent uniquement Remotion.
• assets/scripts/capture-template.mjs : copiez et modifiez le CONFIG en haut (BASE/routes/sélecteurs).
• assets/audio/ : effets sonores à copier et utiliser directement (licence commerciale gratuite, voir audio/ATTRIBUTION.md) : audio/bgm/ contient des BGM rythmées en option ; audio/sfx/<catégorie>/ contient 149 effets sonores répartis en 16 catégories par scène (transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter) – cherchez d'abord par catégorie, la liste complète est dans sound-design.md. Le vocabulaire sparkle est dans le dossier light/ (pas de dossier sparkle/). S1 interdit le timbre mais pas l'action – si l'image montre un clic/un interrupteur, il faut l'accompagner d'un bruitage, mais la moitié des sons dans ui/ sont des retours synthétiques (tone/bleep/notification) – ils doivent être écoutés un par un, ne pas approuver un dossier entier (liste dans sound-design 3.3) ; les échantillons longs et les fichiers audio légers ont chacun une liste à traiter spécialement (sound-design 4.1).
• demos/ : code source d'implémentation de chaque fiche – la plupart sont des démos en niveaux de gris autonomes (certaines importent demos/_fixtures/Fixtures.tsx pour des scènes UI factices, quelques-unes importent demos/_textures/ pour des textures de page réelle) ; copiez-les dans un projet Remotion et elles s'exécutent. Certaines démos utilisent @remotion/motion-blur (CameraMotionBlur) et nécessitent npm i @remotion/motion-blur ; la liste est dans demos/README.md.
• template/ : projet Remotion complet et rendable : npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4.
• jianying-export/ : module d'export de projet CapCut : mac_draft.py (testé avec succès sur CapCut Mac 11.2), windows_draft.py (implémenté selon le chemin de support en amont, non testé sur machine réelle), smoke_test.py (test de fumée minimal à exécuter dans un nouvel environnement). Le processus, l'extraction de la timeline et la construction des pistes sont décrits dans references/jianying-export.md ; nécessite venv + pip install pyJianYingDraft.
• gallery/ : galerie statique – privilégiez la version en ligne directement pour l'utilisateur : https://vincentwei1021.github.io/video-shotcraft/library.html ; pour une exécution locale, exécutez d'abord gallery/fetch-media.sh pour télécharger les échantillons (mp4 non versionnés dans git), puis cd gallery && python3 -m http.server 4178. 152 fiches, 209 échantillons dynamiques visibles/recherchables/sélectionnables par copie multiple du nom – idéal pour que l'utilisateur choisisse les plans en regardant les échantillons.