music-to-video — un workflow vidéo synchronisé au rythme musical
Utilisez cette compétence pour transformer une piste musicale en une vidéo HyperFrames synchronisée au rythme. Vous analysez la piste une fois, disposez les plans, remplissez un plan par plan, et construisez chaque plan comme une composition. L'entrée est une piste musicale plus des images ou vidéos utilisateur optionnelles — il n'y a pas de narration ni de capture web. La typographie et les templates sont 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 passez chaque Porte avant de continuer. Deux étapes nécessitent l'utilisateur : Étape 3 (approbation du plan) et Étape 6 (approbation du rendu). Faites chaque étape vous-même sauf Étape 4, où vous envoyez un sous-agent par plan. Gardez les règles de conception et de mouvement hors de ce fichier — elles se trouvent 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 TBD) ; É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 beats — ne remesurez jamais les beats avec un autre outil ou à l'oreille. Son énergie / densité / rolls / attaques / silences sont toujours fiables. Sonbpmetbeats_secsont fiables uniquement quand la musique est vraiment rythmique ; sur une musique calme, la grille est un métronome imposé par le tracker, donc rythmez plutôt par phrases et énergie et ne coupez jamais brutalement 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 la piste 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 un template ou une combinaison de primitives de mouvement). La densité supplémentaire va à l'intérieur d'un groupe, donc le nombre de plans suit les traitements distincts, pas les beats — une piste rapide ne fait pas exploser 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 une piste avant toute autre chose. Cette compétence est optimisée pour une BGM rapide et énergique : une grille de beats forte guide les coupes (les morceaux calmes fonctionnent, mais rythmez par phrase plutôt que par beat). Si l'utilisateur vous a donné un fichier audio — ou une vidéo dont extraire l'audio — utilisez-le. Sinon, générez-en un : choisissez l'ambiance dans la description de l'utilisateur (par exemple "synthwave entraînante", "beat trap", "corporate dynamique") et produisez une piste via /hyperframes-media (references/bgm.md — HeyGen si les identifiants sont disponibles, sinon local Lyria / MusicGen ; 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 pas et ne réécrivez pas) — elle indique si la BGM vient 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 la piste ; 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 instructions canoniques. Quoi qu'il arrive, la piste arrive dans assets/bgm.mp3. Stagiairez 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> à partir du brief en kebab-case, comme 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 vous a donné 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 piste à 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 ; le format / la longueur / les 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 toute la vidéo est construite.
analyze-beatgrid.py est le seul analyseur de beats — ne remesurez jamais les beats avec un autre outil ou à l'oreille. Il lit la piste une fois et écrit audiomap.json : phases d'énergie (niveau / densité / sensation), attaques + onset_rate, rolls, 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 n'importe quelle musique ; bpm et beats_sec sont fiables uniquement quand la musique est vraiment 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 la piste en plans aux changements musicaux réels (hard_stops, SURGE / DROP key_moments, les bords d'un roll, un tronçon sans attaques, un grand saut d'énergie), en accrochant chaque limite à un ancrage de l'audiomap. 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 un feel d'une ligne (la situation musicale simple que l'Étape 3 associe à un template). Classez et disposez uniquement ici : laissez chaque ### Groups du plan comme TBD (Step 3) et le style du frontmatter vide — pas de templates, de texte, de couleurs ou de polices. Attendez-vous à ~1 à 6 plans.
Porte : les plans couvrent la piste (premier à 0, dernier à duration_s) ; chacun porte span_sec + pacing + mood + feel ; chaque ### Groups est TBD ; aucun contenu nulle part.
Étape 3 : Remplir le plan (validée par l'utilisateur)
Objectif : Transformer le squelette en un STORYBOARD.md approuvé et complet.
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 preset dans
../hyperframes-creative/frame-presets/en utilisant le tableau dans../hyperframes-creative/references/design-spec.md(correspondant à l'ambiance de la piste ; seules ses polices et couleurs comptent — les templates possèdent la composition). Copiez-le dansframe.mdsans modification et remplissez lestyledu frontmatter (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 template apparié du catalogue (avec paramètres liés et ancrages réels de l'audiomap), une composition libre à partir du catalogue de primitives, ou un traitement d'actif qui obéit à
pacing. Écrivez le texte. Vous possédez QUOI (template / 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 : décalage de durée, plans ne couvrant pas la piste, src manquant) ; les avertissements sont au mieux. Ensuite, montrez à l'utilisateur un résumé plan par plan et itérez jusqu'à ce qu'il approuve.
Porte : frame.md est une copie textuelle du preset ; validate-plan.mjs se termine 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. Envoyez un frame-worker par plan, en parallèle si possible (sinon par vagues). Chaque worker reçoit exactement un plan et ce contexte :
PROJECT_DIR : <chemin absolu>
frame_id : <NN-id_plan> # = le nom du fichier du plan, ex. 02-f2 ; l'id de la composition
Votre bloc : le bloc `## Frame 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 (templates) et
<SKILL_DIR>/references/motion-primitives/<id>/ (libre) ; actifs stagé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
Le worker fork 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 à 0ms et écrit un fichier de plan sécurisé pour la recherche. Le worker n'exécute jamais le CLI hyperframes — ces commandes opèrent sur le projet assemblé, qui n'existe pas encore, donc elles signaleraient les mauvais fichiers. Le worker écrit simplement selon le contrat et s'arrête ; vous vérifiez après l'assemblage (Étape 6). Au retour de chaque worker, 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 : Assembler
Objectif : Câbler les plans construits + la BGM dans le index.html jouable.
assemble-index.mjs est déterministe — pas de sous-agent, pas de jugement. Il référence chaque fichier de plan à son data-start cumulatif, monte assets/bgm.mp3 sur la piste 11 et fait des coupes franches plan → plan (les plans couvrent la piste 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 de plan manquant ou vide signifie que le worker a écrit un fichier partiel ; renvoyez-le (Étape 4) et ré-assemblez.
Porte : index.html existe ; la 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 le CLI sur le projet assemblé — c'est l'unité correcte (les workers 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 prend des instantanés des plans.
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
Inspectez à t=0, chaque début de plan, le plus fort DROP / SURGE, chaque hard_stops[].t, et le dernier plan. En cas d'échec, faites vous-même la correction la moins risquée : modifiez le fichier compositions/frames/NN-*.html incriminé. Ne changez jamais la durée ou le timing audio pour masquer un problème de synchronisation. Une fois les portes passées, faites une pause pour la revue utilisateur, puis rendez uniquement après approbation :
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
Porte : lint / validate / inspect passés ; l'utilisateur a approuvé ; renders/video.mp4 existe avec audio, durée == audiomap.audio.duration_sec. La réponse finale donne le chemin et la durée du MP4.
Tableau de reprise
| Vous avez | Continuez depuis |
|---|---|
assets/bgm.mp3 uniquement | Étape 1 |
audiomap.json | Étape 2 |
STORYBOARD.md (squelette) | Étape 3 |
STORYBOARD.md (complet) | Étape 4 |
| tous les fichiers de 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 (staging des médias utilisateur), lib/storyboard.mjs (analyseur intégré). Tout le reste est le CLI hyperframes.
| Lisez | 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, écrire le plan |
references/template-catalog.md | Étape 3 : choisir un template par groupe |
references/motion-primitive-catalog.md | Étape 3 : choisir des primitives de mouvement par groupe (si pas de template) |
references/montage.md | Étape 3 : si l'utilisateur a fourni des actifs |
[../hyperframes-creative/references/design-spec.md](.. /hyperframes-creative/references/design-spec.md) | Étape 3 : tableau des presets de frame |
sub-agents/frame-worker.md | Étape 4 : construire chaque plan |
[../hyperframes-core/references/subagent-dispatch.md](.. /hyperframes-core/references/subagent-dispatch.md) | Étape 4 : envoyer les sous-agents frame-worker |
[../hyperframes-core/references/sub-compositions.md](.. /hyperframes-core/references/sub-compositions.md) | Étape 4 : contrats de sous-composition |
[../hyperframes-core/references/determinism-rules.md](.. /hyperframes-core/references/determinism-rules.md) | Étape 4 : règles de déterminisme |
Rappel : Le format d'entrée est un fichier audio. Si c'est une vidéo, extrayez la piste audio d'abord. La sortie est une vidéo MP4 synchronisée au rythme avec typographie et templates, les actifs utilisateur étant intégrés sur la même grille rythmique. La marque (police + palette) est choisie à l'Étape 3. Le genre émerge des choix de plan.