Avant tout, gardez cette compétence à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update music-to-video. C'est une opération rapide et sans effet si tout est à jour ; sinon, cela actualise cette compétence ainsi que les compétences de domaine central dont elle dépend avant de vous y fier.
music-to-video — un workflow unique de vidéo synchronisée sur la musique et le beat
Utilisez cette compétence pour transformer un morceau de musique en une vidéo HyperFrames synchronisée sur le beat. Vous analysez le morceau une fois, disposez les images, remplissez un plan par image, et construisez chaque image 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 templates sont le socle (une vidéo complète ne nécessite aucun actif) ; tout média fourni par l'utilisateur est coupé sur la même grille rythmique.
Vous êtes l'orchestrateur. Travaillez dans videos/<project>/. 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 contrôle conformément à ../hyperframes/references/brief-contract.md (lisez-le avant l'Étape 0) : en mode autonome, publiez le résumé comme notification et continuez sans attendre. Faites chaque étape vous-même, sauf Étape 4 où vous dépêchez un sous-agent par image. Gardez les règles de conception et de mouvement hors de ce fichier — elles vivent 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 (images, 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 beat — ne mesurez jamais les beats avec un autre outil ou à l'oreille. Son énergie / densité / roulements / attaques / silences sont toujours fiables. Sonbpmetbeats_secne sont fiables que lorsque la musique est véritablement rythmique ; sur une musique calme, la grille est un métronome imposé par le tracker, donc rythmez par phrases et énergie et ne coupez jamais brutalement dessus. Déterminer dans quel cas vous vous trouvez est lepacingde chaque image (Étape 2). - Une image = un fichier ; les groupes vivent à l'intérieur. L'Étape 2 découpe le morceau en images, et chaque image devient un fichier de composition
compositions/frames/NN-<frame_id>.html, construit par un frame-worker. Une image 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 d'images suit des 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 qu'il ne réponde — son flow/storyboard en dérivent le mode (contrat de brief § 1). (2) Pas de BRIEF.md mais le projet existe → reprenez depuis ce qui est sur 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, 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 de modification ignorent tout cela.
La musique est l'épine dorsale — établissez un morceau avant toute autre chose. Cette compétence est réglée pour des BGM rapides et à haute énergie : une grille rythmique forte guide les coupes (les morceaux 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 pour extraire l'audio — utilisez-le. Sinon, choisissez l'humeur à partir de la demande et générez un morceau via /media-use (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 l'état et continuez via le fournisseur local disponible.
Si aucun fournisseur hors ligne ne peut satisfaire la capacité musicale requise, exposez 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 vivent dans /media-use references/setup-providers.md § Fournisseurs. Le morceau résultant atterrit dans assets/bgm.mp3. Placez les images ou vidéos fournies pour que les images puissent les utiliser sur la grille rythmique ; 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 à l'utilisateur le texte des paroles et placez les lignes sur la grille rythmique.
Initialisez seulement 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 --skill=music-to-video
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<musique-utilisateur>" "$PROJECT_DIR/assets/bgm.mp3" # extrayez d'abord d'une vidéo 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 en amont — les actifs ne sont qu'un ingrédient optionnel, et le genre émerge des choix par image.
Porte : hyperframes.json + assets/bgm.mp3 existent ; l'aspect / la durée / le 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 beat — ne mesurez 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é / ambiance), 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 véritablement 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 images (structure uniquement)
Objectif : Lire la musique et disposer les images — 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 images aux changements musicaux réels (hard_stops, SURGE / DROP key_moments, les bords d'un roulement, un tronçon sans attaques, un gros saut d'énergie), en accrochant chaque limite à un ancrage de l'audiomap. Pour chaque image, 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 fait correspondre à un template). Classez et disposez uniquement ici : laissez chaque ### Groups de l'image comme TBD (Étape 3) et le style d'en-tête vide — pas de templates, copie, couleur ou polices. Attendez-vous à ~1–6 images.
Porte : les images 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 (seulement 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 dans
../hyperframes-creative/frame-presets/en utilisant le tableau dans../hyperframes-creative/references/design-spec.md(faites correspondre l'humeur du morceau ; seules ses polices et couleurs comptent — les templates possèdent la composition). Copiez-le dansframe.mdsans modification et remplissez l'en-têtestyle(police + une palette de ≤4–6 nuances) à partir de celui-ci. - Remplissez chaque image. Décidez de ses groupes et donnez à chacun un traitement : un template apparié 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'actif 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 — "scanlines CRT", "glitch", "grain de film", "balayage chatoyant" — 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 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 deaddpréalable, pas de compte. Composez librement un look uniquement après qu'une recherche pour celui-ci n'ait rien donné qui convienne. Écrivez la copie. Vous possédez QUOI (template / primitives + contenu + ancrages) ; le frame-worker possède COMMENT — n'écrivez jamais d'interpolations 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 : inadéquation de durée, images ne couvrant pas le morceau, src manquant) ; les avertissements sont au mieux. Présentez ensuite le résumé image par image 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 contrôle : publiez le résumé comme notification et continuez (le passage de 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 se termine avec le code 0 ; l'utilisateur a approuvé le plan (autonome : le résumé a été publié comme notification).
Étape 4 : Construire les images à partir du plan
Objectif : Construire chaque image comme un fichier de composition autonome.
Créez compositions/frames/. Lisez sub-agents/frame-worker.md et ../hyperframes/references/subagent-dispatch.md. Dépêchez un frame-worker par image, en parallèle si possible (sinon par vagues). Chaque ouvrier reçoit exactement une image et ce contexte :
PROJECT_DIR : <chemin absolu>
frame_id : <NN-frame_id> # = le nom du fichier image, p. ex. 02-f2 ; l'id de composition
Votre bloc : le bloc `## Image N — <frame_id>` dans PROJECT_DIR/STORYBOARD.md
audimap : 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
L'ouvrier forke les matériaux cités, convertit chaque ancrage en secondes locales à l'image (local_t = track_t − span_sec[0]), délimite ses groupes avec des coupes à 0ms, et écrit un fichier image sécurisé pour la recherche. L'ouvrier 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. L'ouvrier se contente d'écrire selon le contrat et s'arrête ; vous vérifiez après assemblage (Étape 6). Au retour de chaque ouvrier, vous pouvez confirmer que son fichier a atterri sur le disque.
Porte : chaque image a son compositions/frames/NN-*.html sur le disque.
Étape 5 : Assembler
Objectif : Connecter les images construites + BGM dans l'index.html lisible.
assemble-index.mjs est déterministe — pas de sous-agent, pas de jugement. Il référence chaque fichier image à son data-start cumulatif, monte assets/bgm.mp3 sur la piste 11, et coupe image → image (les images couvrent le morceau sans trous, 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 image manquant ou vide signifie que cet ouvrier a écrit un fichier partiel ; redépêchez-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 ouvriers par image ne pouvaient pas l'exécuter). check effectue la lint structurelle et l'exécution du navigateur sans tête, la disposition, le mouvement et la porte de contraste en un seul passage ; --snapshots émet également les images de révision.
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
Inspectez à t=0, chaque début d'image, le DROP / SURGE le plus fort, chaque hard_stops[].t, ...