g1304458637-afk/cinematic-music-video-studio

Directeur de Vidéoclip Cinématographique

Un skill de production pour réaliser un court métrage regardable dont l'épine dorsale est une chanson — pas un modèle de paroles, pas un diaporama, pas un tas de clips génératifs sans rapport. Chaque image est dessinée par du code et est reproductible à partir d'un numéro d'image entier.

Le skill est délibérément centré sur la musique et les preuves :

1. mesurer la chanson avant d'imaginer des images ;
2. écrire une thèse et un score de réalisateur avant d'écrire un seul plan ;
3. verrouiller un montage image par image avant de rendre ;
4. prouver le look et le mouvement dans un pilote de 10 à 20 s ;
5. rendre par unités de plans avec reprise ;
6. vérifier le fichier que vous avez réellement livré.

Règle absolue : n'inventez jamais un timestamp, un BPM, une ligne de paroles, un résultat de rendu ou un passage QC. Si une preuve manque, marquez l'élément non vérifié et mentionnez-le dans les notes de livraison.

---

Quand l'utiliser

À utiliser lorsque l'utilisateur demande un clip vidéo, un court métrage animé monté sur de la musique, une séquence de générique ou une tâche « transforme ma chanson en film », et que le rendu par code local est acceptable. La sortie par défaut est 9:16, 1080×1920, 24 ips, H.264 + AAC, avec un fichier de sous-titres optionnel.

N'utilisez pas ce skill pour télécharger de l'audio sous droit d'auteur, cloner l'apparence d'un artiste vivant, ou reproduire un clip existant plan pour plan. Demandez à l'utilisateur un fichier audio qu'il a le droit d'utiliser.

Prérequis (vérifiez, ne présumez pas)

• Node 20+, ffmpeg/ffprobe, Google Chrome ou Chromium.
• Python 3.10–3.13 avec numpy scipy soundfile librosa (matplotlib optionnel, Pillow pour les planches).
• puppeteer-core, p5, p5.brush dans le node_modules du projet.
• Assez d'espace disque pour les images : 1080×1920 JPEG q94 ≈ 0,2–0,5 Mo/image ; un film de 4 minutes ≈ 1–3 Go.
• Pour les paroles en chinois, un fichier LRC/SRT fourni par l'utilisateur, ou un modèle Whisper local ; ne grattez jamais et ne présentez jamais le timing d'un site de paroles aléatoire comme vérifié.

Exécutez scripts/doctor.sh (ou les commandes équivalentes dans references/render-recovery.md) et enregistrez le résultat. Si un prérequis manque, corrigez-le ou signalez le blocage.

---

Le cycle de production

0. Réception et droits

Collectez : chemin audio, texte des paroles et tout fichier de timing, format/ratio/résolution/images par seconde, deadline, langue et contexte d'utilisation. Copiez l'audio en lecture seule dans assets/ ; ne remplacez jamais l'original. Indiquez l'hypothèse de droits dans README.md (par exemple « audio fourni par l'utilisateur, usage privé uniquement »).

1. Analyse musicale (passerelle M)

python scripts/analyze_music.py assets/song.m4a \
  --out analysis --lrc assets/song.lrc --sections analysis/sections.json \
  --asr analysis/asr/whisper.json --fps 24

Produit analysis/audiomap.json, lyrics.json, lyrics.srt, analysis.md, analysis.png. La carte contient la durée, une grille de tempo ajustée par phase, les temps forts/contretemps, les courbes d'énergie/spectrales, les fenêtres candidates de climax, les plages de sections et le timing ligne par ligne des paroles avec provenance.

Acceptation :

• la durée et le taux d'échantillonnage correspondent au fichier fourni ;
• la cohérence du tempo est rapportée ; si < 0,6, inspectez à l'oreille/au spectrogramme et envisagez une carte de tempo ;
• chaque ligne de paroles a une source de timing (lrc_line, srt_line, cross_checked, untimed) ;
• la loudness n'est pas traitée comme un climax émotionnel sans une vérification structurelle croisée.

Si l'utilisateur ne fournit pas de timing de paroles, exécutez scripts/align_lyrics.py avec une transcription ASR locale et vérifiez-la. Gardez le temps de phrase (repère de mesure/phrase, utilisé pour les coupes) séparé du début vocal (utilisé pour les sous-titres). Ne décalez jamais silencieusement toute la chanson pour rendre une coupe plus nette.

2. Trois concepts, puis un (passerelle D1)

Écrivez storyboard/concepts.md avec trois films réellement différents. Notez chacun sur l'adéquation paroles/musique, la complétude de l'histoire, l'impact émotionnel, l'originalité visuelle, la faisabilité technique et la qualité de visionnage long. Sélectionnez-en un et expliquez pourquoi. Ne commencez pas le code des plans avant que cela n'existe.

Écrivez ensuite storyboard/director_score.json : thèse, antithèse, courbe émotionnelle, chapitres visuels (monde/palette/espace/caméra/grammaire), carte de contrastes, motifs et retours, désirs/besoins/arcs des personnages, rôles des plans et transitions, carte son–visuel.

Un plan qui ne peut pas énoncer son rôle, sa transition d'entrée et sa transition de sortie n'est pas prêt.

3. Langage visuel et tests (passerelle D2)

Écrivez style-guide.md et une bible des personnages/artistique avant d'animer. Définissez : palette avec valeurs hexadécimales et un script de couleurs ; grammaire d'objectif/composition pour le 9:16 ; règles de ligne et de texture ; proportions des personnages, silhouettes, continuité des vêtements et gamme d'expressions ; éclairage ; vocabulaire de transitions ; les choses exactes que le film ne fera pas (par exemple « pas de particules flottantes sans raison narrative »).

Rendez 1 à 3 images de style et une planche de personnages. Jugez-les en pleine résolution, pas en vignettes. Si le look est faible, changez le langage maintenant — pas après 40 plans.

4. Montage image par image (passerelle E)

Écrivez storyboard/timeline.json avec fps, total_frames, shots[] et, pour chaque plan : id, start_frame, end_frame, section, lyric_refs, size, composition, environment, action, expression, camera, transition_in/out, emotion, function, implementation, complexity. Les plans doivent être contigus et couvrir toute la durée audio.

python scripts/validate_timeline.py \
  --timeline storyboard/timeline.json --audiomap analysis/audiomap.json \
  --out analysis/timeline_validation.md

Le validateur est une passerelle stricte : pas de trous, pas de chevauchements, dernière image ≥ ceil(durée×fps), chaque ligne de paroles prise en compte, aucune coupe absurdement éloignée d'un temps fort/parole/section sans raison écrite.

5. Pilote (passerelle P)

Rendez 10–20 s contenant au moins : un plan large d'établissement, un plan moyen de personnage, un gros plan, une action rapide ou un impact, et une transition. Construisez une planche contact et un clip regardable avec l'audio réel. Vérifiez :

• Le style tient-il à 100 % ?
• Les proportions, le costume et l'éclairage des personnages sont-ils continus ?
• Le mouvement de caméra est-il motivé, ou dérive-t-il sans raison ?
• Les coupes tombent-elles sur des événements musicaux ?
• Le moteur de rendu survit-il à 300+ images sans exception ?
• Quel est le temps mesuré en ms/image et le coût disque ?

Corrigez le pilote avant le passage complet. Enregistrez les performances mesurées dans LESSONS.md.

6. Rendu complet (passerelle R)

Utilisez un contrat de page déterministe : window.renderAt(t) -> dataURL, pas de Math.random, bruit seedé, indices d'image entiers. Rendez plan par plan ou image par image avec écritures atomiques ; conservez un manifeste des unités terminées et des hachages pour qu'un plan modifié ne s'invalide que lui-même.

node scripts/render.mjs --project . --start 0 --end 232.6 --out renders/frames

Préférez des unités par plan et un chemin --force/--shot plutôt que « tout supprimer et recommencer ». Ne rendez pas deux fois le même plan approuvé. Ne laissez jamais une image échouée passer pour complète : une image doit exister, être non nulle et pouvoir être décodée.

7. Assemblage (passerelle A)

ffmpeg -y -framerate 24 -i renders/frames/f_%06d.jpg -i assets/song.m4a \
  -c:v libx264 -preset slow -crf 16 -pix_fmt yuv420p -profile:v high -level 4.2 \
  -c:a aac -b:a 256k -ar 44100 -shortest -movflags +faststart output/final.mp4

L'audio maître est immuable. Ne fondez pas, ne retimerez pas et ne ré-encodez pas la chanson pour l'adapter à l'image. Le dernier plan doit couvrir la queue audio ; pas de queue noire, pas d'accord final tronqué.

8. Contrôle qualité (passerelle Q)

Exécutez les deux, et joignez les preuves :

python scripts/qc_video.py output/final.mp4 --audio assets/song.m4a \
  --expected-frames 5583 --timeline storyboard/timeline.json --out analysis/qc

Technique : décodage, durée vs audio (tolérance ≤ 0,12 s), nombre de flux, résolution, fps, pix_fmt, nombre d'images, blackdetect, freezedetect, couverture, images manquantes/placeholders. Visuel : planches contact en pleine résolution, images clés par scène, bandes d'images consécutives aux coupes, vérifications ponctuelles de synchronisation A/V, inspection de la continuité des personnages, sécurité des titres/légendes.

Le QC visuel n'est pas automatisé. Indiquez exactement quels plans vous avez regardés, à quelle résolution, et ce que vous avez trouvé. Un ffprobe propre n'est pas un passage visuel.

9. Livraison

Livrez : MP4 maître, aperçu basse résolution, storyboard.md, timeline.json, style-guide.md, qc-report.md, README.md, SRT optionnel, et la source reproductible. Gardez l'audio et les paroles en local sauf si l'utilisateur a les droits de les publier. Ajoutez une entrée datée dans LESSONS.md.

---

Contrat de fichiers

projet/
  assets/            # song.m4a, lyrics.lrc/srt, références fournies par l'utilisateur (ne pas écraser)
  analysis/          # audiomap.json, lyrics.json, sections.json, validation, QC
  storyboard/        # concepts.md, director_score.json, timeline.json, storyboard.md
  characters/        # bible artistique, modèles de personnages
  src/               # code de dessin déterministe : lib/, custom_shots.js, shots.js
  studio.html        # contrat window.renderAt(t)
  renders/           # frames/ (séquence globale), pilot/, manifests
  previews/          # pilot.mp4, planches contact, tableau de révision
  output/            # MP4 final, aperçu, SRT, storyboard.md, timeline.json, style-guide.md, QC

Règles de métier non négociables

• La chanson est la timeline maître. L'image est coupée sur la musique ; la musique n'est jamais coupée sur l'image.
• Un film, pas une playlist de looks. Les motifs reviennent et changent.
• Un refrain répété peut rimer visuellement ; il ne peut pas réutiliser la même composition inchangée.
• Les personnages ont besoin d'un désir, d'un obstacle, d'un choix, d'une conséquence. Les visages et les mains doivent agir.
• Les mouvements de caméra ont besoin d'une motivation (révélation, pression, relâchement), pas d'un Ken Burns par défaut.
• Chaque plan doit contenir au moins un élément en mouvement qui appartient au monde de l'histoire.
• Ne cachez pas une histoire manquante derrière des particules, des rampes de vitesse ou un bloom gratuit.
• Si le résultat honnête est stylisé et limité, dites-le dans le rapport QC ; ne l'appelez pas photoréaliste.

Échec et reprise

Le moteur de rendu est conçu pour échouer bruyamment et reprendre à moindre coût :

• écritures atomiques d'images (*.tmp → renommage), jamais une demi-JPEG comptée comme faite ;
• un manifeste par plan avec hachage source, image de début/fin et statut ;
• --shot / --start/--end ne re-rend que la plage affectée ;
• conservez le dernier encodage connu comme bon ; ne remplacez jamais le maître tant que le QC n'est pas passé.

Si le navigateur ou le GPU meurt, réessayez l'unité deux fois avec une nouvelle page/profil. Si une image échoue trois fois, arrêtez-vous, isolez le plan et signalez le numéro d'image et l'erreur. Ne remplissez pas avec une image dupliquée ou une image fixe.

Index de référence

• references/directing.md — sélection de concepts, score de réalisateur, durée, rythme, fins.
• references/visual-language.md — composition 9:16, caméras, couleur, personnage, texture.
• references/audio-lyrics.md — mesure, tempo ajusté par phase, sections, alignement honnête.
• references/render-recovery.md — contrat déterministe, manifests, encodage, reprise.
• references/qc.md — passerelles dures/molles, planches contact, ce que l'automatisation ne voit pas.
• templates/ — score de réalisateur, timeline, fiche de plan, guide de style, configuration de projet.
• tests/ — tests d'analyseur, de couverture et de validateur ; exécutez bash tests/run_tests.sh.
• LESSONS.md — ce qui a cassé dans les productions réelles et ce qui l'a réparé.

Crédits et licences

Les motifs du moteur sont inspirés par ClaudeAnimationBase (John Heibel) sous licence MIT et claude-music-video-skill (Sage Arbor). Les concepts de workflow ont été étudiés à partir de musical-mv-storyboard, qui n'a pas de licence ; aucun code ou texte n'en est copié. Voir THIRD_PARTY_LICENSES.md. p5 est LGPL-2.1, p5.brush MIT, puppeteer-core Apache-2.0, librosa ISC, ffmpeg GPL. La chanson et les paroles utilisées dans un projet ne font pas partie de ce skill.