Installations de plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution des plugins lorsque cette compétence se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
Tout 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 lorsque tout est à jour ; sinon, cela met à jour cette compétence ainsi que les compétences du domaine central dont elle dépend avant de les utiliser.
music-to-video — un flux de travail unique de vidéo synchronisée 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 le morceau 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 la base (une vidéo complète n'a besoin d'aucun média) ; tout média fourni par l'utilisateur est intégré sur la même grille de battements.
Vous êtes l'orchestrateur. Travaillez dans videos/<projet>/. Exécutez les étapes dans l'ordre et passez chaque Porte avant de passer à la suivante. Deux étapes nécessitent l'utilisateur : Étape 3 (approbation du plan) et Étape 6 (approbation du rendu) — ce sont des portes de point de contrôle 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 notification et continuez ; l'approbation du rendu de l'Étape 6 est toujours demandée, comme la seule question conservée. Effectuez 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-du-projet>/.
Flux de travail : Étape 0 configuration → hyperframes.json + assets/bgm.mp3 ; Étape 1 analyser → audiomap.json ; Étape 2 squelette → STORYBOARD.md (trames, groupes TBD) ; Étape 3 plan → STORYBOARD.md complet + frame.md ; Étape 4 construire → compositions/frames/NN-*.html ; Étape 5 assembler → 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 battements — 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 tracker, donc rythmez par phrases et énergie à la place et ne coupez jamais en fonction d'elle. Déterminer 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 le morceau en trames, et chaque trame devient un fichier de composition
compositions/frames/NN-<id_frame>.html, construit par un frame-worker. Une trame peut être subdivisée 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 correspond aux traitements distincts, pas aux battements — un morceau rapide ne multiplie 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 brève 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 dérivent le mode (contrat de brève § 1). (2) Pas de BRIEF.md mais le projet existe → reprenez depuis ce qui est sur le disque ; ne ré-interrogez jamais. (3) Une demande de création fraîche 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 est reporté — 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 un morceau avant toute autre chose. Cette compétence est conçue pour un BGM rapide et énergique : une grille de battements forte guide les coupes (les morceaux calmes fonctionnent, mais rythmez par phrase plutôt que par battement). Si l'utilisateur a fourni de l'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 un morceau via /media-use (audio/references/bgm.md). Avant la première action d'un fournisseur authentifié, exécutez npx hyperframes auth status et retransmettez 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 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 replis hors ligne se trouvent dans /media-use references/setup-providers.md § Fournisseurs. Le morceau résultant atterrit à assets/bgm.mp3. Mettez en scène les images ou vidéos fournies pour que les trames puissent les utiliser sur la grille de battements ; sinon, la typographie porte la vidéo.
Vidéos lyriques : pour les paroles synchronisées avec les voix, obtenez le timing des mots/lignes en transcrivant le morceau via /media-use, ou demandez à l'utilisateur le texte des paroles et placez les lignes sur la grille de battements.
Initialisez uniquement si hyperframes.json est manquant. Nommez <projet> à partir de la brève 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
# 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 morceau à l'avance — les médias sont juste un ingrédient optionnel, et le genre émerge des choix par trame.
Porte : hyperframes.json + assets/bgm.mp3 existent ; l'aspect / longueur / fps et (le cas échéant) l'inventaire des médias 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 battements — 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 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
Porte : 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 audiomap.json en squelette de STORYBOARD.md vous-même — il n'y a pas de JSON intermédiaire. Découpez le morceau en trames aux changements musicaux réels (hard_stops, SURGE / DROP key_moments, les bords d'un roulement, une section sans attaques, un grand saut d'énergie), en accrochant chaque limite à un point d'ancrage de l'audiomap. Pour chaque trame, définissez span_sec (plage temporelle), pacing (le verdict de l'appel de confiance de l'Étape 1 — beat_cut lorsque la grille est réelle, phrase_flow lorsqu'il s'agit d'un métronome imposé sur une musique calme), mood (ambiance) et un feel (sensation) d'une ligne (la situation musicale simple à laquelle l'Étape 3 associe un modèle). Ne faites que classifier et disposer ici : laissez chaque ### Groups de trame comme TBD (Étape 3) et le frontmatter style vide — pas de modèles, de contenu, de couleur ou de polices. Attendez-vous à ~1–6 trames.
Porte : les trames couvrent le morceau (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 (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 médias). En éditant le même fichier sur place, faites deux choses :
- Choisissez la marque. Choisissez un préréglage depuis
../hyperframes-creative/frame-presets/en utilisant le tableau dans../hyperframes-creative/references/design-spec.md(associez-le à 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 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 points d'ancrage réels de l'audiomap), une composition libre à partir du catalogue de primitives, ou un traitement de média qui obéit au
pacing. Avant de composer librement un aspect nommé, cherchez-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 meilleurs résultats.template-catalog.mdetmotion-primitive-catalog.mdlistent seulement 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é — pas de projet, pas d'addpréalable, pas de compte. Composez librement un aspect seulement après qu'une recherche n'a rien trouvé qui convient. Écrivez le contenu. Vous possédez le QUOI (modèle / primitives + contenu + points d'ancrage) ; le frame-worker possède le 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, trames ne couvrant pas le morceau, src manquant) ; les avertissements sont optionnels. Ensuite, présentez le résumé trame par trame dans le chat comme une proposition (../hyperframes/references/review-loop.md § 1) et itérez sur les réponses de l'utilisateur jusqu'à ce qu'il approuve ; 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 point de contrôle : publiez le résumé comme notification et continuez (la passe validate-plan.mjs est une porte de qualité et bloque toujours).
Porte : frame.md est une copie textuelle du préréglage ; validate-plan.mjs sort avec 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/references/subagent-dispatch.md. Déléguez un frame-worker par trame, en parallèle si possible (sinon par vagues). Chaque travailleur reçoit exactement une trame et ce contexte :
PROJECT_DIR : <chemin absolu>
frame_id : <NN-id_frame> # = le nom de base du fichier de trame, ex. 02-f2 ; l'id de composition
Votre bloc : le bloc `## Frame N — <id_frame>` 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) ; médias mis en scène/ (groupes de médias)
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_frame>.html
Le travailleur duplique les matériaux cités, convertit chaque point d'ancrage en secondes locales à la trame (local_t = track_t − span_sec[0]), verrouille ses groupes avec des coupes à 0ms, et écrit un fichier de trame sûr pour la recherche. Le travailleur 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 travailleur écrit juste selon le contrat et s'arrête ; vous vérifiez après l'assemblage (Étape 6). Au retour de chaque travailleur, vous pouvez confirmer que son fichier a atterri sur le disque.
Porte : chaque trame a son compositions/frames/NN-*.html sur le disque.
Étape 5 : Assembler
Objectif : Connecter les trames construites + le BGM dans index.html lisible.
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 directement trame → trame (les trames couvrent le morceau 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 trame manquant ou vide signifie que le travailleur a écrit un fichier partiel ; redé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 travailleurs par trame ne pouvaient pas l'exécuter). check exécute...