music-to-video — un workflow de vidéo synchronisée sur le rythme musical
Utilisez cette compétence pour transformer un fichier musical en une vidéo HyperFrames synchronisée sur le rythme. Vous analysez le morceau une fois, disposez les plans, remplissez un plan par plan, et construisez chaque plan sous forme de composition. L'entrée est un fichier musical plus des images ou vidéos optionnelles fournies par l'utilisateur — il n'y a ni narration ni capture de site web. La typographie et les modèles constituent la base (une vidéo complète n'a besoin d'aucun actif) ; tout média fourni par l'utilisateur est intégré sur la même grille rythmique.
Vous êtes l'orchestrateur. Travaillez dans videos/<projet>/. Exécutez les étapes dans l'ordre et franchissez chaque Porte avant de passer à la suivante. Deux étapes nécessitent l'utilisateur : Étape 3 (approbation du plan) et Étape 6 (approbation du rendu). Effectuez vous-même chaque étape sauf Étape 4, où vous déléguez un sous-agent par plan. Gardez les règles de conception et d'animation hors de ce fichier — elles résident dans references/ et le sous-agent frame-worker.
SKILL_DIR = ce répertoire de compétence. PROJECT_DIR = videos/<nom-du-projet>/.
Workflow : Étape 0 configuration → hyperframes.json + assets/bgm.mp3 ; Étape 1 analyse → audiomap.json ; Étape 2 squelette → STORYBOARD.md (plans, groupes À DÉFINIR) ; Étape 3 plan → STORYBOARD.md complet + frame.md ; Étape 4 construction → compositions/frames/NN-*.html ; Étape 5 assemblage → index.html ; Étape 6 rendu → renders/video.mp4.
Deux idées qui façonnent tout
- Un seul analyseur, et vous lui faites confiance.
analyze-beatgrid.pyest le seul analyseur de rythme — ne mesurez jamais les battements avec un autre outil ou à l'oreille. Son énergie / densité / roulements / attaques / silences sont toujours fiables. Sonbpmetbeats_secsont fiables uniquement lorsque la musique est véritablement rythmique ; sur une musique calme, la grille est un métronome imposé par le tracker, donc rythmez par phrases et énergie et ne faites jamais de coupes franches dessus. Décider dans quel cas vous vous trouvez est lepacingde chaque plan (Étape 2). - Un plan = un fichier ; les groupes vivent à l'intérieur. L'Étape 2 découpe le morceau en plans, et chaque plan devient un fichier de composition
compositions/frames/NN-<id_plan>.html, construit par un frame-worker. Un plan peut se subdiviser en groupes (chacun étant un modèle ou une combinaison de primitives d'animation). La densité supplémentaire va à l'intérieur d'un groupe, donc le nombre de plans suit les traitements distincts, pas les battements — un morceau rapide n'augmente pas le nombre de sous-agents.
Étape 0 : Configuration, BGM et entrées
Objectif : Établir la source musicale, créer le projet HyperFrames et noter tout média fourni par l'utilisateur.
La musique est l'épine dorsale — établissez un seul morceau avant toute autre chose. Cette compétence est optimisée pour une BGM rapide et énergique : une grille rythmique solide pilote les coupes (les morceaux calmes fonctionnent aussi, mais rythmez par phrase plutôt que par battement). Si l'utilisateur vous a donné un fichier audio — un fichier musical, ou une vidéo dont extraire l'audio — utilisez-le. Sinon, générez-en un : choisissez l'ambiance d'après la description de l'utilisateur (par ex. « synthwave entraînante », « beat trap », « corporate dynamique ») et produisez un morceau via /hyperframes-media (references/bgm.md — récupération HeyGen lorsque les identifiants sont disponibles, sinon Lyria / MusicGen local ; ElevenLabs ou un autre générateur fonctionne aussi). Avant de générer, exécutez npx hyperframes auth status et retransmettez sa sortie textuellement (ne paraphrasez ni ne réécrivez) — elle indique si la BGM provient de HeyGen ou de MusicGen local et, si vous n'êtes pas connecté, comment vous connecter. Si vous n'êtes pas connecté, ARRÊTEZ-VOUS et attendez que l'utilisateur choisisse — se connecter ou continuer hors ligne avec MusicGen local — avant de générer le morceau ; n'écrivez pas de clés dans un .env par dépôt. (En mode autonome, notez l'état et continuez hors ligne.) Voir /hyperframes-media → Preflight pour les conseils canoniques. Dans tous les cas, le morceau atterrit dans assets/bgm.mp3. Placez toutes les images ou vidéos fournies par l'utilisateur pour que les plans puissent les intégrer sur la grille rythmique ; sinon, la typographie porte toute la vidéo.
Initialisez uniquement si hyperframes.json est manquant. Nommez <projet> d'après le brief en kebab-case, par exemple midnight-drive-loop — jamais un horodatage. init vérifie les compétences installées par rapport aux dernières sur GitHub et met à jour l'ensemble global si certaines sont obsolètes.
npx hyperframes init "videos/<projet>" --non-interactive --example=blank
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<musique-utilisateur>" "$PROJECT_DIR/assets/bgm.mp3" # extraire d'une vidéo d'abord si nécessaire
# uniquement si l'utilisateur a fourni des images/vidéos :
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dossier> --hyperframes "$PROJECT_DIR" --into public
La marque (police + palette) est choisie à l'Étape 3, pas ici. Ne choisissez pas un genre ou un type de morceau à l'avance — les actifs sont juste un ingrédient optionnel, et le genre émerge des choix par plan.
Porte : hyperframes.json + assets/bgm.mp3 existent ; les aspect / durée / fps et (le cas échéant) l'inventaire des actifs sont notés.
Étape 1 : Analyser la musique
Objectif : Produire l'unique analyse temporelle canonique sur laquelle repose toute la vidéo.
analyze-beatgrid.py est le seul analyseur de rythme — ne mesurez jamais les battements avec un autre outil ou à l'oreille. Il lit le morceau une fois et écrit audiomap.json : phases d'énergie (niveau / densité / sensation), attaques + onset_rate, roulements, silences, hard_stops, key_moments, phrases, tempo / grille, et audio.duration_sec. Il est déterministe — le même fichier donne toujours la même carte. La plupart des champs sont fiables sur toute musique ; bpm et beats_sec sont fiables uniquement lorsque la musique est véritablement rythmique, et juger cela est la décision que vous prenez à l'Étape 2.
Prérequis : Python 3 avec librosa, numpy et soundfile disponibles. Si l'import échoue, installez-les dans l'environnement Python actif avant d'exécuter l'analyseur :
python3 -m pip install librosa numpy soundfile
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-o "$PROJECT_DIR/audiomap.json" --print
Porte : audiomap.json existe ; audio.duration_sec est connu.
Étape 2 : Squelette des plans (structure uniquement)
Objectif : Lire la musique et disposer les plans — le squelette de STORYBOARD.md.
Lisez references/frame-skeleton.md. Transformez audiomap.json en le squelette de STORYBOARD.md vous-même — il n'y a pas de JSON intermédiaire. Découpez le morceau en plans aux changements musicaux réels (hard_stops, SURGE / DROP key_moments, les bords d'un roulement, une étendue sans attaque, un grand saut d'énergie), en alignant chaque limite sur un ancrage de la carte audio. Pour chaque plan, définissez span_sec, pacing (le verdict de l'appel de confiance de l'Étape 1 — beat_cut quand la grille est réelle, phrase_flow quand c'est un métronome imposé sur une musique calme), mood et une ligne feel (la situation musicale simple que l'Étape 3 fait correspondre à un modèle). Classez et disposez ici uniquement : laissez chaque ### Groups du plan comme À DÉFINIR (Étape 3) et le frontmatter style vide — pas de modèles, de texte, de couleurs ou de polices. Attendez-vous à ~1–6 plans.
Porte : les plans couvrent le morceau (premier à 0, dernier à duration_s) ; chacun porte span_sec + pacing + mood + feel ; chaque ### Groups est À DÉFINIR ; aucun contenu nulle part.
Étape 3 : Remplir le plan (avec validation utilisateur)
Objectif : Transformer le squelette en un STORYBOARD.md complet et approuvé.
Lisez references/planning.md, storyboard-format.md, template-catalog.md, motion-primitive-catalog.md et montage.md (uniquement si l'utilisateur a fourni des actifs). En éditant le même fichier sur place, faites deux choses :
- Choisissez la marque. Choisissez un préréglage dans
../hyperframes-creative/frame-presets/en utilisant le tableau dans../hyperframes-creative/references/design-spec.md(faites correspondre l'ambiance du morceau ; seules ses polices et couleurs comptent — les modèles possèdent la composition). Copiez-le dansframe.mdsans modification et remplissez le frontmatterstyle(police + une palette de ≤4–6 nuances) à partir de celui-ci. - Remplissez chaque plan. Décidez de ses groupes et donnez à chacun un traitement : un modèle correspondant du catalogue (avec paramètres liés et ancrages réels de la carte audio), une composition libre du catalogue de primitives, ou un traitement d'actif qui obéit au
pacing. Rédigez le texte. Vous possédez QUOI (modèle / primitives + contenu + ancrages) ; le frame-worker possède COMMENT — n'écrivez jamais de tweens en millisecondes dans le storyboard.
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
Corrigez chaque ✗ (erreurs dures : non-correspondance de durée, plans ne couvrant pas le morceau, un src manquant) ; les avertissements sont au mieux. Montrez ensuite à l'utilisateur un résumé plan par plan et itérez jusqu'à ce qu'il approuve.
Porte : frame.md est une copie textuelle du préréglage ; validate-plan.mjs sort avec 0 ; l'utilisateur a approuvé le plan.
Étape 4 : Construire les plans à partir du plan
Objectif : Construire chaque plan comme un fichier de composition autonome.
Créez compositions/frames/. Lisez sub-agents/frame-worker.md et ../hyperframes-core/references/subagent-dispatch.md. Déléguez un frame-worker par plan, en parallèle si possible (sinon par vagues). Chaque ouvrier reçoit exactement un plan et ce contexte :
PROJECT_DIR : <chemin absolu>
frame_id : <NN-id_plan> # = le nom du fichier plan, ex. 02-f2 ; l'id de composition
Votre bloc : le bloc `## Plan N — <id_plan>` dans PROJECT_DIR/STORYBOARD.md
audiomap : PROJECT_DIR/audiomap.json
frame.md : PROJECT_DIR/frame.md
Matériaux : pour chaque groupe, <SKILL_DIR>/references/templates/<id>/index.html (modèles) et
<SKILL_DIR>/references/motion-primitives/<id>/ (libre) ; assets/ placés (groupes d'actifs)
Contrats : ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas : <l>×<h> Pacing : <beat_cut|phrase_flow>
Écrire dans : PROJECT_DIR/compositions/frames/<id_plan>.html
L'ouvrier duplique les matériaux cités, convertit chaque ancrage en secondes locales au plan (local_t = track_t − span_sec[0]), verrouille ses groupes avec des coupes à 0 ms, et écrit un fichier plan sûr pour la recherche. L'ouvrier n'exécute jamais l'interface CLI hyperframes — ces commandes opèrent sur le projet assemblé, qui n'existe pas encore, donc elles signaleraient les mauvais fichiers. L'ouvrier écrit juste selon le contrat et s'arrête ; vous vérifiez après l'assemblage (Étape 6). À mesure que chaque ouvrier revient, vous pouvez confirmer que son fichier est bien sur le disque.
Porte : chaque plan a son compositions/frames/NN-*.html sur le disque.
Étape 5 : Assemblage
Objectif : Relier les plans construits + la BGM dans le index.html lisible.
assemble-index.mjs est déterministe — pas de sous-agent, pas de jugement. Il référence chaque fichier plan à son data-start cumulatif, monte assets/bgm.mp3 sur la piste 11, et fait des coupes franches plan → plan (les plans couvrent le morceau sans espace, donc il n'y a pas d'injecteur de transition).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
Corrigez tout ✗ qu'il signale — un fichier plan manquant ou vide signifie que cet ouvrier a écrit un fichier partiel ; ré-déléguez-le (Étape 4) et ré-assemblez.
Porte : index.html existe ; durée totale == audiomap.audio.duration_sec.
Étape 6 : Vérifier et rendre
Objectif : Vérifier la vidéo assemblée, obtenir l'approbation de l'utilisateur et rendre le MP4 final.
Exécutez la CLI sur le projet assemblé — c'est l'unité correcte (les ouvriers par plan ne pouvaient pas l'exécuter). lint vérifie la structure, validate exécute Chrome sans tête (attrapant les erreurs JS et les actifs manquants), inspect capture des plans.
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
Inspectez à t=0, au début de chaque plan, au DROP / SURGE le plus fort, à chaque hard_stops[].t, et à la dernière image. En cas d'échec, faites vous-même la correction la moins risquée : éditez le fichier compositions/frames/NN-*.html concerné. Ne changez jamais la durée ou le timing audio pour cacher un problème de synchronisation. Une fois les portes passées, faites une pause pour la revue utilisateur, puis rendez uniquement sur approbation :
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
Porte : lint / validate / inspect réussis ; l'utilisateur a approuvé ; renders/video.mp4 existe avec audio, durée == audiomap.audio.duration_sec. La réponse finale indique le chemin du MP4 et sa durée.
Tableau de reprise
| Vous avez | Reprendre depuis |
|---|---|
assets/bgm.mp3 seulement | Étape 1 |
audiomap.json | Étape 2 |
STORYBOARD.md (squelette) | Étape 3 |
STORYBOARD.md (complet) | Étape 4 |
| tous les fichiers plans | Étape 5 |
index.html | Étape 6 |
Référence rapide
Formats : paysage 1920x1080 par défaut ; portrait 1080x1920 ; carré 1080x1080. Définissez le canvas une fois dans le frontmatter du storyboard (canvas : { w, h, fps }).
Scripts sous scripts/ : analyze-beatgrid.py (l'unique analyseur), validate-plan.mjs (vérification du plan), assemble-index.mjs (assemblage de l'index), stage-assets.mjs (placement des médias utilisateur), lib/storyboard.mjs (analyseur fourni). Tout le reste est la CLI hyperframes.
| Lire | Quand |
|---|---|
references/frame-skeleton.md | Étape 2 : lire la musique, disposer les plans, définir le pacing |
references/planning.md · storyboard-format.md | Étape 3 : choisir la marque, remplir chaque plan, rédiger le plan |
references/template-catalog.md | Étape 3 : choisir un modèle par groupe |
references/motion-primitive-catalog.md | Étape 3 : composer librement si aucun modèle ne correspond |
references/montage.md | Étape 3 : traiter les actifs utilisateur en groupes montés |
sub-agents/frame-worker.md | Étape 4 : contrat de l'ouvrier, échelle temporelle locale |
../hyperframes-core/references/subagent-dispatch.md | Étape 4 : comment déléguer |
../hyperframes-core/references/sub-compositions.md | Étape 4 : contrat de sortie de composition |
../hyperframes-core/references/determinism-rules.md | Étape 4 : règles pour un rendu reproductible |