Installation du plugin : Avant l'installation ou les commandes de mise à jour, suivez les règles d'installation du plugin lorsque cette compétence se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
D'abord, gardez cette compétence à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update music-to-video. Une opération rapide sans effet si tout est à jour ; sinon, cette commande met à jour cette compétence ainsi que les compétences du domaine central dont elle dépend avant que vous ne vous y appuyiez.
music-to-video — un workflow de vidéo synchronisé à la musique
Utilisez cette compétence pour transformer un morceau de musique en une vidéo HyperFrames synchronisée au 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 morceau de musique plus des images ou vidéos optionnelles de l'utilisateur — il n'y a ni narration ni capture de site web. La typographie et les templates constituent le socle (une vidéo complète n'a besoin d'aucun actif) ; tout média fourni par l'utilisateur est découpé sur la même grille de beats.
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) — ce sont des portes de checkpoint conformément à ../hyperframes/references/brief-contract.md (lisez-le avant l'Étape 0) : en mode autonome, publiez le résumé de l'Étape 3 comme information et continuez ; l'approbation du rendu de l'Étape 6 est toujours demandée, comme seule question conservée. Faites chaque étape vous-même sauf l'Étape 4, où vous déléguez un sous-agent par plan. Ne mettez pas les règles de design et de mouvement dans ce fichier — elles se trouvent dans references/ et le sous-agent frame-worker.
SKILL_DIR = ce dossier 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 planification → 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 analyseur unique, 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. Ses données d'énergie / densité / rolls / onsets / silences sont toujours fiables. Sesbpmetbeats_secsont fiables uniquement lorsque la musique est vraiment rhythmique ; sur une musique calme, la grille est un métronome imposé par le tracker, donc rythmez par phrases et par énergie et ne coupez jamais brutalement. 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-<frame_id>.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 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.
Le brief commence au niveau de l'intention. Règle d'ouverture, dans l'ordre : (1) BRIEF.md existe → lisez-le et ne demandez rien à quoi il répond — son flow/storyboard en dérivent le mode (brief contract § 1). (2) Pas de BRIEF.md mais le projet existe → reprenez à partir de ce qui est sur le disque ; ne réinterrogez jamais. (3) Une demande de création neuve arrivée directement ici → lisez /hyperframes et exécutez sa couche d'intention (references/intent-interview.md) : elle confirme les incontournables de cette route (la source musicale, la destination → l'aspect — ../hyperframes/references/routes/music-to-video.md) et annonce ce qui reste différé — la marque et le genre sont choisis à l'Étape 3 par conception. Écrivez BRIEF.md immédiatement après l'initialisation (jamais avant — init refuse un dossier non vide) et enregistrez les réponses basées sur les préférences (brief-format.md). Les demandes de modification ignorent tout ceci.
La musique est l'épine dorsale — établissez une piste avant toute chose. Cette compétence est conçue pour une BGM rapide et à haute énergie : une grille de beats forte conduit les coupes (les pistes calmes fonctionnent, mais rythmez par phrase plutôt que par beat). Si l'utilisateur a fourni un audio — un fichier musical, ou une vidéo dont extraire l'audio — utilisez-le. Sinon, choisissez l'ambiance à partir de la demande et générez une piste via /media-use (audio/references/bgm.md). Avant la première action authentifiée d'un fournisseur, exécutez npx hyperframes auth status et relayez sa sortie textuellement. Si déconnecté, appliquez une branche :
- Collaboratif : attendez la connexion ou un choix explicite de continuer hors ligne avec le fournisseur local.
- Autonome : indiquez le statut et continuez avec le fournisseur local disponible.
Si aucun fournisseur hors ligne ne peut satisfaire la capacité musicale requise, signalez le blocage. N'écrivez jamais de clés dans un .env par dépôt. La propriété de l'authentification et les solutions de repli hors ligne se trouvent dans /media-use references/setup-providers.md § Providers. La piste résultante atterrit dans assets/bgm.mp3. Placez les images ou vidéos fournies pour que les plans puissent les utiliser sur la grille de beats ; sinon, la typographie porte la vidéo.
Vidéos lyriques : pour des paroles synchronisées avec la voix, obtenez le timing des mots/lignes en transcrivant la piste via /media-use, ou demandez à l'utilisateur le texte des paroles et placez les lignes sur la grille de beats.
Initialisez uniquement si hyperframes.json est manquant. Nommez <projet> à partir du 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 --skill=music-to-video
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 ; l'aspect / la durée / les fps et (le cas échéant) l'inventaire des actifs sont notés.
Étape 1 : Analyser la musique
Objectif : Produire l'analyse temporelle canonique unique 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), onsets + 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 toute musique ; bpm et beats_sec sont fiables uniquement lorsque la musique est vraiment rhythmique, 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 onsets, 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 à la 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 associe à un template). Classez et disposez uniquement ici : laissez chaque ### Groups du plan en TBD (Étape 3) et le style du frontmatter vide — pas de templates, de copie, 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é 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 modifiant le même fichier sur place, faites deux choses :
- Choisissez la marque. Choisissez un préréglage parmi
../hyperframes-creative/frame-presets/en utilisant le tableau dans../hyperframes-creative/references/design-spec.md(associez à l'ambiance du morceau ; 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 échantillons) à partir de celui-ci. - Remplissez chaque plan. Décidez de ses groupes et donnez à chacun un traitement : un template correspondant du catalogue (avec des paramètres liés et des ancrages réels d'audiomap), une composition libre à partir du catalogue de primitives, ou un traitement d'actif qui obéit à
pacing. Avant de composer librement un aspect nommé, recherchez-le dans le catalogue en direct : pour chaque aspect, effet, traitement ou transition demandé par l'utilisateur — "lignes de balayage CRT", "glitch", "grain de film", "balayage chatoyant" — exécuteznpx hyperframes catalog --query "<l'aspect, en anglais simple>" --jsonet lisez les premiers résultats.template-catalog.mdetmotion-primitive-catalog.mdlistent uniquement les matériaux locaux de cette compétence ; la recherche classe l'ensemble du registre hébergé (~400 blocs et composants) et ne nécessite rien d'installé — aucun projet, aucunaddpréalable, aucun compte. Composez librement un aspect uniquement après qu'une recherche pour celui-ci n'a rien donné de convenable. Écrivez la copie. 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. Présentez ensuite le résumé plan par plan dans le chat comme une proposition (../hyperframes/references/review-loop.md § 1) et itérez sur les réponses de l'utilisateur jusqu'à approbation ; pour storyboard: yes, écrivez-le aussi comme storyboard.html (../hyperframes-creative/references/storyboard-recipe.md § 3) pour qu'il puisse l'ouvrir. En mode autonome, c'est une porte de checkpoint : publiez le résumé comme information et continuez (le passage de validate-plan.mjs est une porte qualité et bloque toujours).
Porte : frame.md est une copie textuelle d'un préréglage ; validate-plan.mjs se termine avec le code 0 ; l'utilisateur a approuvé le plan (autonome : le résumé a été publié comme information).
É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/references/subagent-dispatch.md. Déléguez 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-frame_id> # = le nom du fichier du plan, p. ex. 02-f2 ; l'ID de composition
Votre bloc : le bloc `## Plan N — <frame_id>` 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 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/<frame_id>.html
Le worker bifurque les matériaux cités, convertit chaque ancrage en secondes locales au plan (local_t = track_t − span_sec[0]), barre ses groupes avec des coupes de 0 ms, et écrit un fichier de plan sécurisé pour la recherche. Le worker n'exécute jamais la 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 arrivé sur le disque.
Porte : chaque plan a son compositions/frames/NN-*.html sur le disque.
Étape 5 : Assembler
Objectif : Relier 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 coupe directement plan → plan (les plans couvrent la piste sans lacunes, donc il n'y a aucun 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 ce worker a écrit un fichier partiel ; redéléguez-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 la CLI sur le projet assemblé — c'est l'unité correcte (les workers par plan ne pouvaient pas l'exécuter). check exécute des contrôles d'intégrité, preview ouvre un aperçu local, et render produit le fichier final. Présentez un résumé à l'utilisateur et demandez l'approbation du rendu (porte checkpoint).