Premièrement, gardez cette compétence à jour — exécutez silencieusement, sans demander :
npx hyperframes skills update music-to-video. Une opération rapide sans effet si tout est à jour ; sinon, elle actualise cette compétence ainsi que les compétences de base dont elle dépend avant que vous ne les utilisiez.
music-to-video — un workflow vidéo unique, synchronisé sur la musique
Utilisez cette compétence pour transformer un morceau de musique en une vidéo HyperFrames synchronisée sur le rythme. Vous analysez la piste une fois, disposez les trames, remplissez un plan par trame, et construisez chaque trame comme une composition. L'entrée est un morceau de musique 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 sont le socle (une vidéo terminée n'a besoin d'aucun asset) ; tous les médias fournis par l'utilisateur sont découpés sur la même grille rythmique.
Vous êtes l'orchestrateur. Travaillez dans videos/<project>/. Exécutez les étapes dans l'ordre et passez chaque Gate avant de continuer. Deux étapes nécessitent l'utilisateur : Étape 3 (approbation du plan) et Étape 6 (approbation du rendu) — ce sont des points de contrôle conformément à ../hyperframes-core/references/brief-contract.md (lisez-le avant l'Étape 0) : en mode autonome, publiez le résumé comme notification et poursuivez au lieu d'attendre. Faites chaque étape vous-même sauf l'Étape 4, où vous déléguez un sous-agent par trame. 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-projet>/.
Workflow : Étape 0 configuration → hyperframes.json + assets/bgm.mp3 ; Étape 1 analyse → audiomap.json ; Étape 2 squelette → STORYBOARD.md (trames, 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 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 vraiment rythmique ; sur une musique calme, la grille est un métronome imposé par le suivi, donc rythmez par phrases et énergie à la place et ne coupez jamais dessus. Décider dans quel cas vous vous trouvez est lepacingde chaque trame (Étape 2). - Une trame = un fichier ; les groupes vivent à l'intérieur. L'Étape 2 découpe la piste en trames, et chaque trame devient un fichier de composition
compositions/frames/NN-<frame_id>.html, construit par un frame-worker. Une trame peut se subdiviser en groupes (chacun un modèle ou une combinaison de primitives de mouvement). La densité supplémentaire va à l'intérieur d'un groupe, donc le nombre de trames suit les traitements distincts, pas les battements — 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 tous les médias fournis 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 qu'il répond — son flow/storyboard déduisent 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 fraîche qui est arrivée ici directement → lisez /hyperframes et exécutez sa couche d'intention (references/intent-interview.md) : elle confirme les indispensables de cette route (la source musicale, destination → format — ../hyperframes/references/routes/music-to-video.md) et annonce ce qui est 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 répertoire non vide) et enregistrez les réponses basées sur les préférences (brief-format.md). Les demandes de modification sautent tout cela.
La musique est l'épine dorsale — établissez une piste avant tout. Cette compétence est conçue pour une BGM rapide et énergique : une grille de rythme forte pilote les coupures (les pistes calmes fonctionnent, mais rythmez par phrase plutôt que par battement). Si l'utilisateur a fourni un fichier audio, ou une vidéo pour en extraire l'audio, utilisez-le. Sinon, choisissez l'ambiance à partir de la demande et générez une piste via /media-use (references/bgm.md). Avant toute action authentifiée auprès du 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 l'état et continuez via 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 alternatives hors ligne se trouvent dans /media-use references/setup-providers.md § Fournisseurs. La piste résultante atterrit dans assets/bgm.mp3. Mettez en scène les images ou vidéos fournies pour que les trames puissent les utiliser sur la grille rythmique ; sinon, la typographie porte la vidéo.
Lyric videos : pour les paroles synchronisées avec la voix, obtenez le timing mot/ligne en transcrivant la piste via /media-use, ou demandez le texte des paroles à l'utilisateur et placez les lignes sur la grille rythmique.
Initialisez uniquement si hyperframes.json est manquant. Nommez <project> à 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/<project>" --non-interactive --example=blank --skill=music-to-video
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3" # extraire d'une vidéo d'abord si nécessaire
# seulement si l'utilisateur vous a donné des images/vidéos :
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --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 assets sont juste un ingrédient optionnel, et le genre émerge des choix par trame.
Gate : hyperframes.json + assets/bgm.mp3 existent ; le format / la durée / les fps et (le cas échéant) l'inventaire des assets sont notés.
Étape 1 : Analyser la musique
Objectif : Produire l'analyse de timing canonique unique sur laquelle toute la vidéo est construite.
analyze-beatgrid.py est le seul analyseur de rythme — ne mesurez jamais les battements 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, 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 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'importation é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
Gate : audiomap.json existe ; audio.duration_sec est connu.
Étape 2 : Squelette des trames (structure uniquement)
Objectif : Lire la musique et disposer les trames — le squelette de STORYBOARD.md.
Lisez references/frame-skeleton.md. Transformez vous-même audiomap.json en le squelette de STORYBOARD.md — il n'y a pas de JSON intermédiaire. Découpez la piste en trames aux changements musicaux réels (hard_stops, key_moments SURGE / DROP, les bords d'un roulement, un segment sans attaques, un grand saut d'énergie), en accrochant chaque limite à un ancrage de l'audiomap. Pour chaque trame, définissez span_sec, pacing (le verdict de l'appel de confiance de l'Étape 1 — beat_cut lorsque la grille est réelle, phrase_flow lorsque c'est un métronome imposé sur une musique calme), mood, et une feel d'une ligne (la situation musicale simple à laquelle l'Étape 3 fait correspondre un modèle). Classez et disposez uniquement ici : laissez chaque ### Groups de la trame comme TBD (Step 3) et le style du frontmatter vide — pas de modèles, de copie, de couleur ou de polices. Attendez-vous à environ 1 à 6 trames.
Gate : les trames tuilent la piste (première à 0, dernière à duration_s) ; chacune porte span_sec + pacing + mood + feel ; chaque ### Groups est TBD ; aucun contenu nulle part.
Étape 3 : Remplir le plan (contrôlé 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 assets). En modifiant le même fichier sur place, faites deux choses :
- Choisissez la marque. Choisissez un préréglage de
../hyperframes-creative/frame-presets/en utilisant le tableau dans../hyperframes-creative/references/design-spec.md(faites correspondre l'ambiance de la piste ; seules ses polices et couleurs comptent — les modèles possèdent la composition). Copiez-le dansframe.mdsans modification et remplissez lestyledu frontmatter (police + une palette ≤4–6 échantillons) à partir de celui-ci. - Remplissez chaque trame. Décidez de ses groupes et donnez à chacun un traitement : un modèle correspondant du catalogue (avec des paramètres liés et des ancrages réels de l'audiomap), une composition libre à partir du catalogue de primitives, ou un traitement d'asset qui obéit au
pacing. Écrivez 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, trames ne tuilant pas la piste, un src manquant) ; les avertissements sont au mieux. Puis montrez à l'utilisateur un résumé trame par trame et itérez jusqu'à ce qu'il approuve. En mode autonome, c'est un point de contrôle : publiez le résumé comme notification et continuez (le passage de validate-plan.mjs est un contrôle de qualité et bloque toujours).
Gate : frame.md est une copie textuelle du préréglage ; validate-plan.mjs sort 0 ; l'utilisateur a approuvé le plan (autonome : le résumé a été publié comme notification).
Étape 4 : Construire les trames à partir du plan
Objectif : Construire chaque trame 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 trame, en parallèle si possible (sinon par vagues). Chaque worker reçoit exactement une trame et ce contexte :
PROJECT_DIR : <chemin absolu>
frame_id : <NN-frame_id> # = le nom du fichier de trame, ex. 02-f2 ; l'id de la composition
Votre bloc : le bloc `## Frame 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 (modèles) et
<SKILL_DIR>/references/motion-primitives/<id>/ (libre) ; assets mis en scène/ (groupes d'assets)
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 à la trame (local_t = track_t − span_sec[0]), déclenche ses groupes avec des coupures de 0 ms, et écrit un fichier de trame sûr 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 dans 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 a atterri sur le disque.
Gate : chaque trame a son fichier compositions/frames/NN-*.html sur le disque.
Étape 5 : Assembler
Objectif : Relier les trames construites + 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 trame à son data-start cumulatif, monte assets/bgm.mp3 sur la piste 11, et coupe durement trame → trame (les trames tuilent 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 trame manquant ou vide signifie que ce worker a écrit un fichier partiel ; redéléguez-le (Étape 4) et réassemblez.
Gate : 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 workers par trame ne pouvaient pas l'exécuter). check exécute le lint structurel et l'exécution du navigateur sans tête, la disposition, le mouvement et le contrôle de contraste en un seul passage ; --snapshots émet également les trames de révision.
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
Inspectez à t=0, chaque début de trame, le DROP / SURGE le plus fort, chaque hard_stops[].t, et la trame finale. En cas d'échec, faites vous-même la correction la moins coûteuse et la plus sûre : modifiez le 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 gates passées, faites une pause pour la révision de l'utilisateur, puis ne rendez qu'après approbation (mode autonome : posez l'unique question retenue — « prévisualiser d'abord, ou rendre directement ? » — puis délivrez le MP4 avec la fiche contact) :
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
Gate : check a réussi et les instantanés ont été inspectés ; l'utilisateur a approuvé (autonome : les vérifications ont réussi et la livraison inclut la fiche contact) ; renders/video.mp4 existe avec audio, durée == audiomap.audio.duration_sec. La réponse finale indique le chemin du MP4 et la durée.
Tableau de reprise
| Vous avez | Continuez de |
|---|---|
BRIEF.md préexistant | Étape 0 |
hyperframes.json + assets/bgm.mp3 | Étape 1 |
audiomap.json | Étape 2 |
STORYBOARD.md (squelette) | Étape 3 |
STORYBOARD.md (complet) + frame.md | Étape 4 |
tous les fichiers compositions/frames/ | Étape 5 |
index.html | Étape 6 |