Installation du plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'installation du plugin lorsque ce skill se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
Tout d'abord, gardez ce skill à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update music-to-video. C'est une opération rapide (no-op) quand tout est à jour ; sinon, cela rafraîchit ce skill ainsi que les compétences de base du domaine dont il dépend avant que vous ne les utilisiez.
music-to-video — workflow vidéo basé sur la musique et synchronisée au rythme
Utilisez ce skill pour transformer un morceau de musique en une vidéo HyperFrames synchronisée au rythme. Vous analysez le morceau une fois, disposez les cadres, remplissez un plan par cadre, et construisez chaque cadre sous forme de composition. L'entrée est un morceau de musique accompagné éventuellement d'images ou de vidéos 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 asset) ; tout média fourni par l'utilisateur est coupé sur la même grille de beats.
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) — ces deux points sont des portes de contrôle conformément à ../hyperframes/references/brief-contract.md (lisez-le avant l'Étape 0) : en mode autonome, affichez le résumé en guise d'information et continuez au lieu d'attendre. Faites vous-même chaque étape, sauf l'Étape 4, où vous déléguez un sous-agent par cadre. 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 skill. 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 (cadres, groupes TBD) ; Étape 3 planification → STORYBOARD.md complété + 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. Ses données d'énergie/densité/roulements/attaques/silences sont toujours fiables. Sonbpmetbeats_secne sont fiables que lorsque la musique est réellement rythmique ; sur une musique calme, la grille est un métronome imposé par l'analyseur, donc rythmez plutôt par phrases et énergie et ne l'utilisez jamais pour des coupures dures. Décider dans quel cas vous vous trouvez relève de chaquepacingde cadre (Étape 2). - Un cadre = un fichier ; les groupes vivent à l'intérieur. L'Étape 2 découpe le morceau en cadres, et chaque cadre devient un fichier de composition
compositions/frames/NN-<frame_id>.html, construit par un frame-worker. Un cadre peut être subdivisé 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 cadres suit les traitements distincts, pas les beats — 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.
Le brief commence à la couche d'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érive 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 nouvelle demande de création 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 → aspect — ../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 d'édition ignorent tout cela.
La musique est l'épine dorsale — établissez un morceau avant toute autre chose. Ce skill est conçu pour des BGM rapides et à haute énergie : une grille de beats forte guide les coupures (les morceaux calmes fonctionnent, mais rythmez par phrase plutôt que par beat). Si l'utilisateur a fourni un fichier audio — un fichier musical, ou une vidéo pour en extraire l'audio — utilisez-le. Sinon, choisissez l'ambiance à partir de la demande et générez un morceau via /media-use (references/bgm.md). Avant la première action de fournisseur authentifié, 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, remontez 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 § Fournisseurs. Le morceau résultant atterrit dans assets/bgm.mp3. Stagifiez les images ou vidéos fournies pour que les cadres 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 le morceau via /media-use, ou demandez le texte des paroles à l'utilisateur et placez les lignes sur la grille de beats.
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 skills installés par rapport aux dernières versions sur GitHub et met à jour l'ensemble global si certains 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" # extrayez 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 morceau à l'avance — les assets sont juste un ingrédient facultatif, et le genre émerge des choix par cadre.
Gate : hyperframes.json + assets/bgm.mp3 existent ; l'aspect / la durée / les fps et (si présents) l'inventaire des assets 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 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 ne sont fiables que lorsque la musique est réellement rythmique, et juger cela est l'appel que vous faites à 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
Gate : audiomap.json existe ; audio.duration_sec est connu.
Étape 2 : Squelette des cadres (structure uniquement)
Objectif : Lire la musique et disposer les cadres — 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 cadres aux changements musicaux réels (hard_stops, key_moments SURGE/DROP, les bords d'un roulement, une section sans attaques, un grand saut d'énergie), en accrochant chaque limite à un ancrage de l'audiomap. Pour chaque cadre, 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 uniquement ici : laissez chaque ### Groups de cadre comme TBD (Step 3) et le frontmatter style vide — pas de modèles, de texte, de couleurs ou de polices. Attendez-vous à environ 1 à 6 cadres.
Gate : les cadres couvrent le morceau (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 (approuvé par l'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 assets). 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 de../hyperframes-creative/references/design-spec.md(correspondant à 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 cadre. 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 à
pacing. Avant de composer librement un look nommé, cherchez-le dans le catalogue en direct : pour chaque look, effet, traitement ou transition demandé par l'utilisateur — "lignes de balayage CRT", "glitch", "grain de film", "voile scintillant" — exécuteznpx hyperframes catalog --query "<le look, en anglais simple>" --jsonet lisez les meilleurs résultats.template-catalog.mdetmotion-primitive-catalog.mdlistent uniquement les matériaux locaux de ce skill ; la recherche classe tout le registre hébergé (~400 blocs et composants) et ne nécessite rien d'installé — pas de projet, pas deaddpréalable, pas de compte. Composez librement un look uniquement après qu'une recherche pour celui-ci n'ait rien trouvé qui convienne. É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 : décalage de durée, cadres ne couvrant pas le morceau, src manquant) ; les avertissements sont au mieux. Ensuite, présentez le résumé cadre par cadre dans le chat en tant que 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 également sous forme de storyboard.html (../hyperframes-creative/references/storyboard-recipe.md § 3) pour qu'il puisse l'ouvrir. En mode autonome, c'est une porte de contrôle : affichez le résumé en guise d'information et continuez (le passage validate-plan.mjs est une porte qualité et bloque toujours).
Gate : frame.md est une copie textuelle d'un préréglage ; validate-plan.mjs renvoie 0 ; l'utilisateur a approuvé le plan (autonome : le résumé a été affiché en guise d'information).
Étape 4 : Construire les cadres à partir du plan
Objectif : Construire chaque cadre sous forme de 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 cadre, en parallèle si possible (sinon par vagues). Chaque worker reçoit exactement un cadre et ce contexte :
PROJECT_DIR: <chemin abs>
frame_id: <NN-frame_id> # = le nom du fichier du cadre, ex. 02-f2 ; l'id de 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 stagifiés/ (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 duplique les matériaux cités, convertit chaque ancrage en secondes locales du cadre (local_t = track_t − span_sec[0]), cloisonne ses groupes avec des coupures à 0 ms, et écrit un fichier de cadre sûr 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 des fichiers erronés. Le worker se contente d'écrire 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 a atterri sur le disque.
Gate : chaque cadre a son compositions/frames/NN-*.html sur le disque.
Étape 5 : Assembler
Objectif : Relier les cadres construits + 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 de cadre à son data-start cumulatif, monte assets/bgm.mp3 sur la piste 11, et effectue des coupures dures cadre → cadre (les cadres couvrent le morceau sans lacunes, 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 cadre 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 ; 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 cadre ne pouvaient pas l'exécuter). check effectue une analyse structurelle et le runtime du navigateur sans tête, la mise en page, la conformité des composants, l'intégrité audio et la couverture temporelle. render produit une vidéo MP4.
cd "$PROJECT_DIR"
npx hyperframes check # vérification sans tête — signale les erreurs d'exécution, les ressources manquantes
npx hyperframes render # génère renders/video.mp4 ; durée == audio.duration_sec
Si une vérification échoue, lisez la sortie pour localiser le problème — un fichier de cadre manquant ou vide signifie que le worker respectif (Étape 4) doit être redélégé, pas réparé ici. Ensuite, présentez le rendu dans le chat comme proposition (../hyperframes/references/review-loop.md § 2 ; en autonome, le point de contrôle est un avis) et itérez sur les révisions jusqu'à approbation ; ensuite, produisez le fichier vidéo final.
Gate (point de contrôle) : hyperframes check renvoie 0 et l'utilisateur a approuvé le rendu (autonome : l'avis a été affiché).