csm-kr/reference-motion-video

Vidéo animée par référence

Le film est du HTML, et sa liste de cues est la partition. Chaque événement visible enregistre un cue à côté de la constante qui anime l'image ; chaque segment du film est une section nommée selon son rôle. Une palette transforme ces cues en musique qui colle à chaque frame et raconte l'histoire : pas de rythme quand le problème est posé, un groove quand le produit fonctionne, un souffle avant la révélation, les drums qui s'arrêtent quand le produit s'arrête délibérément, un silence brutal sur le logo.

Exemples prêts à l'emploi : examples/claude-code/ (films de lancement, explicatifs et démos exécutables sur une scène commune, chacun avec une palette différente), examples/moments-v2.html (spot publicitaire continu de 36 s), examples/ads/ (publicités Moments : drums, orchestre, violon). Les compositions Moments nécessitent des assets produit et des ajustements de chemins ; ce sont des références, pas des démos prêtes à être rendues.

Règles qui ont déterminé les films passés

1. L'adéquation d'abord. La musique doit correspondre à l'ambiance du produit et épouser le flux de l'image. Dans un test A/B en aveugle (KIBO v4.5, 30 s, même image, même volume), le propriétaire a choisi la partition composée sur mesure plutôt qu'un morceau electropop libre de droits, pourtant calé sur le rythme et meilleur sur tous les métriques machines : "la deuxième ne convient pas". La composition sur mesure est la règle ; une piste de bibliothèque uniquement si l'utilisateur la choisit explicitement (references/music.md).
2. Un son sur chaque cue, à sa frame. Les cuts tombent sur le temps fort, les mots claquent sur le contretemps, la plus grande révélation reçoit le plus grand impact sonore.
3. Images réelles et rendu réaliste uniquement. Les animations de motion design encadrent et expliquent ; elles ne simulent jamais une fonctionnalité. Étiquetez les accélérations et les cuts d'attente à l'écran ("App en direct · 1×", "⋯ cut d'attente", "▶▶ accéléré"), signalez les voix synthétiques, citez une source sous chaque donnée chiffrée.
4. La voix d'abord. Quand il y a une narration ou un dialogue, le lit sonore s'efface devant elle (references/music.md, "Mix").
5. Les vérifications machines sont nécessaires, pas suffisantes. La synchro, le volume et la reconnaissance vocale peuvent tous passer sur une musique qui ne convient pas. C'est la personne qui décide, par une écoute en aveugle.
6. Demandez, puis décidez. Ne demandez que ce que la requête et le dépôt ne peuvent pas fournir, avec une réponse recommandée en premier ; décidez le reste et dites-le.

Workflow

0. Vérification de l'environnement (avant toute chose)

Rapportez chaque ligne comme ok ou manquante, avec la correction ; n'affichez jamais la valeur d'une clé.

• Google Chrome (le moteur de rendu pilote le Chrome installé : le Chromium intégré ne peut pas décoder le H.264), ffmpeg (avec rubberband), Node ≥ 20 avec npm ci --prefix engine --ignore-scripts depuis le répertoire du skill.
• Python 3.12 avec numpy, scipy, soundfile, pytest (uv venv --python 3.12 .venv, puis uv pip install --python .venv/bin/python -r requirements.txt depuis le répertoire du skill).
• Échantillons : exécutez bash engine/fetch_samples.sh core (VSCO-2-CE CC0 percussion, cuivres, mallets ; SFX sous licence Pixabay), puis bash engine/fetch_samples.sh piano pour soft_pulse (Salamander Grand Piano, CC-BY 3.0 ; créditez-le si utilisé). Les palettes se rabattent sur la synthèse quand un échantillon manque, mais le recours au piano peut échouer à la vérification d'équilibre des sections ; utilisez les deux jeux pour la suite complète des tests.
• Un fournisseur de narration et ses identifiants uniquement si une narration est demandée (references/voice.md). Aucune clé API n'est nécessaire pour les trois exemples exécutables. Les clients de narration, de transcription et de capture d'applications ne sont pas inclus ; utilisez les outils disponibles et vérifiez la documentation actuelle du fournisseur choisi si nécessaire.
• Espace disque : les rendus pipe les frames (pas de dump PNG), mais les bibliothèques d'échantillons et les prises nécessitent quelques Go.

1. Entretien d'analyse → brief d'une page (approuvé avant la planification)

Ne demandez que le contexte que la requête et le dépôt ne fournissent pas. Utilisez l'outil de questions de l'environnement, ou une simple discussion si aucun n'est disponible ; regroupez les questions liées, placez l'option recommandée en premier et réutilisez les réponses déjà données :

1. Objectif : quel type de film (lancement, concept explicatif, démonstration pas à pas, vignette d'usage, manifeste), qui le regarde, où il va (YouTube, un concours, les réseaux sociaux), ce qu'ils doivent faire après, la date limite et les éventuels critères de jugement.
2. Message et preuves : la phrase à retenir, trois preuves avec leurs sources, ce qui ne doit pas être dit.
3. Format et son : durée et formats (16:9, 9:16, versions réduites), langues pour l'écran, les sous-titres et la voix ; liens de référence musicale ou une ambiance (proposez les palettes du tableau ci-dessous qui correspondent à l'objectif, plus "J'ai des liens de référence") ; narration ou non, et quelle voix.
4. Sources et règles : l'application réelle peut-elle être enregistrée (URL, identifiant, données de démonstration, deux appareils), des personnes apparaîtront-elles, assets de marque, règles du concours, IP tierce. Relisez le brief et obtenez un accord. Écrivez-le dans video/BRIEF.md.

2. Genre et références

Choisissez le template de rythme du genre et les cibles mesurées dans references/genres.md (16 références officielles pour cinq genres, avec longueurs de plans, mots par carte, rythme de voix off, moment d'apparition du produit et du logo). Regardez les références choisies avec /watch ; mesurez leur musique avec engine/ref-analyze.py. Pour une publicité en plan-séquence, lisez references/transitions.md et references/youtube-analysis.md.

3. Plan → video/PLAN.md (approuvé avant la construction)

Un storyboard sur la grille du BPM (100 BPM = 0,6 s par temps, 18 frames à 30 ips ; placez le drop sur un temps fort) : time | bars | scène | texte à l'écran | images | type de section | cues | voix. Nommez l'objet héros (un élément du produit qui traverse le film et atterrit dans le logo), le cadre persistant, et chaque affirmation avec son fichier de preuve.

4. Capturer des écrans réels

references/capture.md : lorsque le produit le nécessite, prises en direct sur deux appareils à partir de l'application réelle (frames de screencast CDP avec horodatage mur, une voix client synthétique jouée dans le micro du téléphone, la réponse de l'IA tapée depuis la page), converties en MP4 à fréquence d'images constante sur une seule horloge, puis jouées dans le film via une carte temporelle ([[t film, t prise], ...] : des pas égaux sont 1×, une course plate est un arrêt, deux points distants de 1 ms sont un cut). Utilisez l'outil navigateur disponible dans l'environnement ; references/aside-capture.md donne une implémentation spécifique à Aside. Sortie de terminal ou d'outil : recomposez la sortie réelle (les exemples Claude Code), ne l'inventez jamais.

5. Narration (optionnelle)

references/voice.md : utilisez le fournisseur TTS choisi ou les enregistrements fournis, écoutez les prises, choisissez par exactitude des mots et rythme (155-170 mots/min est un point de départ pour une démo en anglais), et ajustez le texte ou les pauses avant d'étirer la voix. Nettoyez à la source et écrivez chaque ligne selon un budget de mots pour son créneau.

6. Construire la composition

• Une seule #stage fixe en 1920×1080 ; tout mouvement à partir d'UNE timeline GSAP en pause ; la frappe, les compteurs, le point héros et les vidéos de prise sont évalués à partir du temps seul dans __seek(t). Jamais d'animations CSS, setTimeout ou requestAnimationFrame pour le mouvement. fromTo nécessite immediateRender: false.
• Contrat pour le moteur : window.__duration, __seek(t), __ready, __cues, __sections, __bpm, __T. Partez de examples/claude-code/stage.js (cues, sections, pops de mots, frappe, compteurs, cartes de terminal, le point héros) ou examples/moments-v2.html (caméra virtuelle sur écrans réels).
• Enregistrez un cue à côté de chaque constante qui rend quelque chose visible ; marquez chaque segment avec une section selon son rôle (tableau ci-dessous).
• Sous-titres : réservez un emplacement lisible pour les lignes parlées et gardez les autres contenus hors de cet espace ; identifiez les locuteurs synthétiques et leur fournisseur, ajoutez des traductions si le brief le demande, et générez le fichier .srt à partir de la même liste de sous-titres.
• Vérifiez les images fixes avant tout rendu complet : node engine/stills.mjs index.html out/stills 1.7 3.6 ....

7. Musique : composer pour l'image

node engine/cues.mjs > cues.json                      # duration, bpm, T, cues, sections
python engine/compose.py cues.json score.wav --palette bright_demo [--narr narr.js --narr-root .]

compose.py écrit la partition, mixe les voix en priorité, masterise à -14 LUFS (crête réelle sous -1 dBTP) et exécute lui-même la vérification de synchronisation : un cue sans début audible dans les 33 ms reçoit le son d'accentuation de la palette et le mix est refait (deux fois au maximum) ; le rapport liste ce qui a été ajouté. Écoutez avant de choisir : rendez le même segment de 15 à 30 s avec deux ou trois palettes adaptées et laissez la personne choisir en aveugle. Détails, règles de mixage et chemin de piste de bibliothèque : references/music.md.

8. Rendu

node engine/render.mjs index.html out/film.mp4 --fps 30 --audio score.wav (frames JPEG q95 pipées vers x264 : environ 10× plus rapide que le PNG ; flags YouTube : High profile, GOP de la moitié de la fréquence d'images, balises BT.709, AAC 48 kHz 384 kbps). Plages courtes pour les brouillons : --from 10 --to 16. Chrome charge environ 18 vidéos distinctes dans une page ; utilisez des images fixes pour les prises qui ne bougent pas.

9. Vérifications (toutes sur les fichiers finaux)

references/qa.md. Vérifiez la synchronisation sur le MP4 final (python engine/synccheck.py out/film.mp4 cues.json : chaque cue dans les 33 ms, lu avec sa ligne de base de probabilité), le volume, la crête réelle, les images fixes, les transitions et le jugement d'écoute de la personne. Appliquez les vérifications de voix, de sous-titres, de QR et de révision uniquement lorsque ces fonctionnalités existent, en utilisant les outils disponibles dans l'environnement ; ne rapportez pas de vérifications non exécutées comme réussies. Un test de compréhension en cloud est optionnel et nécessite le choix de l'utilisateur d'envoyer le film à ce service.

10. Livraison

Livrez la durée et le format demandés, normalement H.264 MP4, un fichier .srt d'accompagnement si des sous-titres sont présents, et une miniature ou des versions réduites si demandées. La scène et le moteur de rendu intégrés sont en 1920×1080 ; un autre rapport d'aspect nécessite une adaptation explicite, pas un drapeau du moteur de rendu. Rapportez les vérifications effectivement exécutées et leurs preuves. La publication est une action distincte, sauf si l'utilisateur l'a déjà demandée.

Sections, par rôle

type	utilisez-le là où l'image...	la musique
intro	expose le problème, avant que le produit n'agisse	pas de rythme : un pad, seulement les sons de cues
tease	réveille le produit, la première demande	un groove sparse (pas de backbeat, de percussion supérieure ou de mélodie)
build	est sur le point d'atteindre un résultat ; le remplissage avant une ré-entrée	un crescendo jusqu'à la fin de la section
groove	montre le produit au travail (e 0.5-1.2)	le groove complet à l'énergie e
light	porte une ligne dense ou une carte pleine de texte	le groove sans sa figure mélodique
muffled	énonce un fait sérieux, une statistique, un problème	le groove en passe-bas, s'ouvrant sur la section suivante
breath	tient sur un temps avant la révélation	presque silence ; seul le son de l'objet héros résonne
stop	montre le produit qui n'agit délibérément pas (un arrêt de sécurité, une limite)	drums coupés, un pad tenu
end	est la carte de fin	silence
riser (superposition)	s'élève vers un atterrissage	un riser qui se termine à la fin de la section

Types de cues que chaque palette sait traiter : drop (la révélation), reentry, final (le logo, puis un silence brutal), break (un arrêt commence), cut (big pour un chapitre), tap, tapTouch, pop, word, chip, node, num, count, fill, bar, key (frappe), dot (le son propre de l'objet héros).

Palettes (engine/palettes/)

palette	convient à	son	origine
bright_demo	démonstrations pas à pas, applications grand public/SaaS conviviales, guidées par la voix	Pop en Fa majeur à 100 BPM : kick percutant, clap et snap, shaker et tambourin, marimba (échantillons VSCO ou synthétisé), basse pincée, pad aérien, son d'objet héros de goutte d'eau	KIBO v4.5 (A2-bright), choix du propriétaire ; a gagné le test A/B en aveugle
drums_launch	films de lancement et publicités, révélations de produit, guidés par la musique	Kit live en Ré mineur à 100 BPM : kick, caisse claire et ghosts, hats, congas, cowbell, basse syncopée, skank de guitare en sourdine, stabs de trompette et cor	Publicité Moments de 50 s avec drums (d'après le film MacBook Air M5 d'Apple), style préféré du propriétaire
soft_pulse	explainers de concepts, diagrammes, films avec beaucoup de narration	Do majeur à 96 BPM : piano échantillonné, sons de cue de marimba accordé, un kit doux, basse et pad ; les couches entrent avec l'énergie et les notes de cue montent à mesure que le diagramme se construit	pour examples/claude-code/explainer

Encore sous forme de scripts autonomes, à porter vers l'interface de palette : piano et cloches (engine/score.py, Moments v2), groupe (engine/score_band.py, une promo B2B), orchestre et violon solo (examples/ads/orch, examples/ads/violin). Pour ajouter une palette, suivez engine/palettes/__init__.py et ajoutez son nom à tests/test_compose.py : les tests prouvent qu'elle suit la grammaire des sections (pas de kick dans l'intro, un souffle silencieux et une carte de fin, drums coupés dans le stop, chaque cue entendu, -14 LUFS).

Fichiers

• engine/ : render.mjs, cues.mjs, stills.mjs, compose.py + palettes/, audio.py (buses, sampler, room), synccheck.py, beatmap.py et bedmix.py (le chemin de piste de bibliothèque), ref-analyze.py, music-analyze.py, fetch_samples.sh.
• references/ : genres.md, music.md, voice.md, capture.md, qa.md, transitions.md, youtube-analysis.md, aside-capture.md, ads/.
• tests/ : python -m pytest -q tests/ (carte des temps fort, mix de bibliothèque, vérification de synchro, grammaire des sections sur chaque palette).

Contraintes du brief et de la soumission

• Utilisez la durée, les langues, le rapport d'aspect et la destination demandés. Pour un concours, lisez son règlement effectif et vérifiez la durée avec ffprobe ; n'héritez pas des limites d'un concours passé.
• Montrez des images réelles du produit ou une sortie réelle pour les affirmations de fonctionnalité, et respectez les autorisations de marque et d'assets de l'utilisateur. Identifiez les échantillons non officiels concernant un autre produit, comme le font les exemples Claude Code.
• Préparez d'abord les livrables locaux. Ne téléversez que lorsque l'utilisateur a autorisé la destination et la visibilité.