media-use : Avant de sourcer l'audio/les images, appelez
/media-usepour résoudre la BGM/SFX/les images depuis le catalogue HeyGen. Exécutez--adoptd'abord pour enregistrer les ressources existantes. Voir la compétence/media-use.
PR vers HyperFrames
Utilisez cette compétence pour ingérer une pull request GitHub, comprendre le changement, planifier un explicatif de changement de code et le construire image par image dans HyperFrames. L'entrée est un changement de code (lu via gh), pas un site Web — il n'y a pas d'étape de capture et aucune ressource réelle au-delà des avatars des contributeurs.
Confirmez la route avant l'Étape 0. Vous êtes l'orchestrateur. Exécutez chaque étape, vérifiez sa porte, et continuez seulement ensuite. Cette compétence est destinée à une pull request GitHub (un changement de code). Acheminez les autres intentions ailleurs : un lancement/promo de produit →
/product-launch-video; une visite de site Web général →/general-video; un explicatif de sujet sans PR →/faceless-explainer; des légendes sur des images existantes →/embedded-captions; un court graphique animé sans narration →/motion-graphics; une présentation de version complète du dépôt ou multi-PR →/general-video. Hors de portée : données en direct / au moment du rendu — les faits de la PR sont lus une fois au moment de la création et intégrés. Si l'utilisateur dit seulement "fais une vidéo" ou si la route est incertaine, lisez/hyperframesd'abord.
Vous êtes l'orchestrateur. Travaillez dans videos/<projet>/. Exécutez les étapes dans l'ordre et passez chaque porte avant de continuer. Les étapes gérées par l'utilisateur sont l'Étape 0, l'Étape 3 et l'Étape 6. Faites chaque étape vous-même sauf l'Étape 5, où vous dépêchez un sous-agent par image. Ne mettez pas de règles de conception ou de mouvement ici ; celles-ci vivent dans le sous-agent trame, hyperframes-creative et hyperframes-animation.
Flux de travail : Étape 0 configuration → hyperframes.json ; Étape 1 ingestion → capture/extracted/ + assets/<login>.png ; Étape 2 système de design → frame.md ; Étape 3 storyboard/script → STORYBOARD.md et SCRIPT.md ; Étape 3.1 audio → audio_meta.json ; Étape 4 conception visuelle → STORYBOARD.md enrichi ; Étape 5 images → compositions/frames/NN-*.html et index.html ; Étape 6 rendu final → renders/video.mp4.
Étape 0 : Configuration et Brief
Objectif : Verrouiller la référence de la PR et le brief vidéo principal, et créer le projet HyperFrames si nécessaire.
Obtenez la référence de la PR (une URL complète, une référence <propriétaire>/<dépôt>#<N>, ou "cette PR" dans un dépôt cloné) et, en un seul message, confirmez le brief — proposez une valeur par défaut recommandée pour chacun et préremplissez tout ce que /hyperframes a déjà défini : angle (journal des modifications / révélation de fonctionnalité / explicatif de correctif / présentation de refactorisation — par défaut : déduire de la PR), audience (par défaut : développeurs), durée (par défaut : adaptée à la taille du changement de la PR — voir ci-dessous), format (par défaut 16:9), langue. Le style est toujours claude. Procédez seulement après que l'utilisateur a répondu ; un "go" accepte les valeurs par défaut.
Recommandez la durée à partir de la taille du changement de la PR, pas une estimation fixe. Avant de confirmer le brief, jetez un coup d'œil à la PR une fois — un appel en lecture seule qui ancre également l'angle (l'Étape 1 fait toujours la récupération déterministe complète) :
gh pr view <REF_PR> --json title,additions,deletions,changedFiles
Choisissez le niveau à partir de additions + deletions (ajusté à la hausse par changedFiles) et proposez-le comme valeur par défaut (l'utilisateur peut passer outre ; limite dure ~3 min) :
| Taille du changement de la PR | Durée recommandée |
|---|---|
| trivial (≲ 50 lignes modifiées) | ~20–40s |
| ciblé (~50–200 lignes) | ~40–70s |
| substantiel (~200–600 lignes) | ~70–110s |
| grand (≳ 600 lignes, ou 25+ fichiers) | ~110–180s |
Indiquez la base en une phrase lorsque vous la proposez (par exemple, "~40s — petit changement, +44/−13 dans 12 fichiers"). Une grosse PR ne signifie pas une longue vidéo — si l'histoire est un seul changement majeur, restez concis et dites-le.
Initialisez seulement si hyperframes.json est manquant. Nommez <projet> à partir de la PR en kebab-case, par exemple acme-sdk-pr-1842 ; n'utilisez jamais le nom de l'espace de travail ou un horodatage.
npx hyperframes init "videos/<projet>" --non-interactive --example=blank — init vérifie les compétences installées par rapport aux dernières sur GitHub et met à jour l'ensemble global si des compétences sont obsolètes.
Affichez l'état de connexion avant le brief — exécutez npx hyperframes auth status et relayez sa sortie textuellement (ne paraphrasez pas et ne réécrivez pas). Il indique si la voix/la BGM utilisera les moteurs HeyGen ou locaux et, lorsqu'il n'est pas connecté, comment se connecter. S'il n'est pas connecté, ARRÊTEZ-VOUS et attendez que l'utilisateur choisisse — connectez-vous, ou dites "go"/"hors ligne" pour continuer avec les moteurs locaux — avant de demander le brief ou quoi que ce soit d'autre. Traitez-le comme un vrai point de décision, pas une note de passage ; n'intégrez pas le choix dans la question du brief et n'écrivez pas de clés dans un .env par dépôt. (En mode autonome, notez l'état et continuez hors ligne.) Voir ../hyperframes-media → Preflight pour les instructions canoniques.
Porte : hyperframes.json existe ; la référence de la PR est capturée ; l'angle, la durée, le rapport hauteur/largeur et la langue sont verrouillés ; l'état de connexion a été affiché (connecté, ou continuation hors ligne).
Étape 1 : Ingérer la PR (pas de capture)
Objectif : Récupérer les faits de la PR et les intégrer dans le projet comme source d'information. Il n'y a pas de capture de site Web. fetch-pr.mjs exécute gh de manière déterministe — complétant la liste des fichiers via l'API gh paginée afin qu'une grande PR ne soit pas tronquée à ~100 fichiers, et écrivant seulement capture/pr.json + capture/diff.patch (pas de répertoire temporaire). Ensuite, ingest.mjs intègre cela dans le package de capture synthétique hors ligne.
PR="<url | propriétaire/dépôt#N | N>"
# Récupérer la PR de manière déterministe : exécute gh, complète la liste des fichiers via l'API gh paginée
# (afin qu'une grosse PR ne soit pas tronquée à ~100 fichiers), écrit seulement capture/pr.json +
# capture/diff.patch — pas de répertoire temporaire. Les erreurs gh auth / introuvable / privé renvoient 1 ici.
(cd "videos/<projet>" && node <REP_COMP>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformation hors ligne → capture/extracted/{tokens.json (colors:[] → palette claude),
# visible-text.txt (le brief), people.json (contributeurs, filtrés des bots, avatarFile=assets/<login>.png)}.
(cd "videos/<projet>" && node <REP_COMP>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# Le front des personnes, une étape réseau — télécharger l'avatar GitHub de chaque contributeur vers
# assets/<login>.png pour un éventuel générique de crédits. Au mieux ; toujours renvoie 0.
(cd "videos/<projet>" && node <REP_COMP>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs renvoie 1 (gh auth / introuvable / privé), signalez sa stderr et arrêtez-vous — ne fabriquez pas le contenu de la PR. Si ingest.mjs renvoie 1, lisez sa stderr (généralement un pr.json malformé), corrigez et réexécutez (déterministe). fetch-people-avatars.mjs renvoie toujours 0 ; les avatars manquants signifient simplement qu'il n'y a pas de générique de crédits pour l'auteur.
Porte : capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt et capture/extracted/people.json existent ; vous pouvez énoncer le changement de la PR en une phrase claire. assets/<login>.png est au mieux — son absence n'est pas un échec.
Étape 2 : Système de Design
Objectif : Adopter le préréglage d'image claude ; un script le transforme en frame.md de cette vidéo + skin de légende.
Le style est fixe — claude (éditorial chaleureux ; une surface de code bleu marine conçue pour les diffs). Exécutez :
node <REP_COMP>/scripts/build-frame.mjs --preset claude --hyperframes .
Le script copie le FRAME.md du préréglage claude → frame.md, le remixe sur tous les jetons de marque dans capture/extracted/tokens.json (une PR n'en a aucun → colors:[]/fonts:[] conserve la propre palette de claude, un design complet), copie le skin de légende du préréglage vers .hyperframes/caption-skin.html et s'auto-valide (renvoie 1 en cas de mappage cassé). Procédez dès qu'il renvoie 0 — pas d'édition manuelle.
Porte : build-frame.mjs a renvoyé 0 — frame.md existe à partir du préréglage claude, et .hyperframes/caption-skin.html existe comme source du skin de légende.
Étape 3 : Storyboard et Script
Objectif : Transformer la PR en un plan d'explication image par image approuvé.
Lisez references/story-design.md, ../hyperframes-core/references/storyboard-format.md et ../hyperframes-core/references/script-format.md. Utilisez-les pour écrire STORYBOARD.md et, lorsque la narration est nécessaire, SCRIPT.md.
Utilisez story-design.md pour l'archétype de la PR (journal des modifications / révélation de fonctionnalité / explicatif de correctif / présentation de refactorisation), les types d'images natifs de la PR, l'accroche, la persuasion, les temps forts, le budget de mots par image et le générique de crédits optionnel. La séquence provient de la conception narrative, pas de l'ordre des fichiers du diff — expliquez le changement, ne lisez pas le diff à voix haute. Présentez 2 à 4 extraits de diff réels (depuis capture/diff.patch), chacun un petit extrait lisible ; nommez le bloc code-* que chacun veut dans la scene de son image. Les images ne portent pas de asset_candidates sauf un générique credits optionnel (2 à 6 avatars assets/<login>.png). Utilisez les champs exacts requis des références de storyboard et de script.
Après la rédaction, montrez un résumé image par image. Dans ce même message, demandez à l'utilisateur (a) d'approuver ou de demander des modifications, et (b) s'il souhaite un aperçu en direct de l'échafaudage du storyboard (npx hyperframes preview) — ouvrez-le seulement sur un oui. Itérez jusqu'à approbation ; reportez le choix de l'aperçu à l'Étape 6.
Porte : STORYBOARD.md existe, chaque image a les champs narratifs requis, SCRIPT.md existe lorsque la narration est nécessaire et l'utilisateur a approuvé le plan.
Étape 3.1 : Audio
Objectif : Générer la narration, les temporisations des mots, la musique et les métadonnées audio à partir du script approuvé.
Démarrez l'audio après l'approbation de l'Étape 3. Exécutez-le en arrière-plan, puis continuez à l'Étape 4.
node <REP_COMP>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
Le script audio gère la narration, les temporisations des mots, la recherche de BGM dans la bibliothèque musicale de HeyGen et les métadonnées de temporisation. L'ambiance de la BGM provient du champ music: du storyboard. Cela utilise l'API Audio de HeyGen pour la récupération, pas la génération, et les mêmes identifiants ~/.heygen que pour TTS. Pour les détails du fournisseur, lisez ../hyperframes-media/references/tts.md.
S'il n'y a pas de narration et pas de SCRIPT.md, ignorez la génération vocale. La BGM peut toujours s'exécuter si le storyboard a une ambiance musicale.
Porte : le travail audio a démarré, ou le projet est marqué silencieux.
Étape 4 : Conception Visuelle des Images
Objectif : Ajouter la direction visuelle, l'intention de mise en page et les choix de mouvement à chaque image du storyboard.
Modifiez STORYBOARD.md sur place. Ne créez pas un autre storyboard. Utilisez frame.md comme source de vérité pour la couleur, la typographie, le ressenti de la mise en page et le style.
Lisez references/visual-design.md, references/composition.md, references/motion-language.md, references/code-vocabulary.md et ../hyperframes-animation/. Utilisez visual-design.md pour les champs requis des images et le bloc requis ## Video direction, et pour la façon dont un temps fort de code nomme un bloc code-* comme son focal. Utilisez code-vocabulary.md pour choisir le bon bloc par temps fort (diff = code-diff, refactorisation = code-morph, nouveau code = code-typing, …). Utilisez composition.md pour la mise en page/la hiérarchie/les points focaux et motion-language.md + ../hyperframes-animation/ pour les identifiants d'effets et de plans valides. N'inventez pas de noms d'effets ou d'identifiants de blocs/plans.
Pour chaque image, ajoutez les champs visuels et de mouvement requis, y compris effects et focal et/ou roles. Pour un temps fort de code, nommez le bloc code-* comme le focal et laissez effects chorégraphier la Surface de Code claude environnante (pas l'animation du code, qui appartient au bloc). Ajoutez un bloc ## Video direction à l'échelle de la vidéo.
Ne modifiez pas l'histoire, le script, transition_in, asset_candidates ou la source de la PR. N'écrivez pas de HTML à cette étape. Il n'y a pas d'étape de préparation des ressources — les seules ressources réelles sont les avatars des crédits, déjà dans assets/.
Porte : chaque image a effects plus focal et/ou roles ; les images de code nomment un bloc code-* ; ## Video direction existe.
Étape 5 : Construire les Images
Objectif : Construire chaque image du storyboard en tant que composition HTML et assembler la vidéo lisible.
Attendez la fin de l'audio de l'Étape 3.1 si l'audio a été démarré. Ensuite, synchronisez les durées et récupérez les SFX ; ignorez les deux si silencieux.
node <REP_COMP>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <REP_COMP>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
La synchronisation des durées est mécanique : la durée réelle de la voix gagne ; les images silencieuses gardent les estimations ; ne modifiez jamais manuellement les durées synchronisées.
Pré-installez les blocs du registre nommés dans STORYBOARD.md une fois, avant l'envoi, afin que les travailleurs parallèles ne se fassent pas concurrence sur le registre :
for b in <chaque bloc du registre nommé dans le storyboard>; do npx hyperframes add "$b"; done
Avant l'envoi, lisez sub-agents/frame-worker.md et ../hyperframes-core/references/subagent-dispatch.md. Envoyez un sous-agent par image, en parallèle si possible ; sinon, exécutez les travailleurs par vagues. Chaque travailleur reçoit exactement une image. Le contexte de chaque travailleur doit inclure PROJECT_DIR, frame_id, la taille du canevas, l'état des légendes et la bande de garde si les légendes sont activées, ANIM_DIR (chemin absolu vers ../hyperframes-animation/) et le chemin absolu vers references/code-vocabulary.md. Chaque travailleur lit frame.md, son propre bloc ## Image N, le corps de la recette pour chaque identifiant d'effet/plan cité et — pour un temps fort de code — code-vocabulary.md pour les entrées du bloc nommé. Chaque travailleur écrit seulement compositions/frames/NN-*.html ; les travailleurs ne modifient jamais STORYBOARD.md.
Dès que chaque travailleur revient, marquez cette image animated dans STORYBOARD.md.
Après l'existence des temporisations audio, construisez les légendes en arrière-plan et assemblez l'index :
node <REP_COMP>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <REP_COMP>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs utilise le .hyperframes/caption-skin.html du projet (celui de claude, copié à l'Étape 2), en injectant les jetons de marque depuis frame.md ; captions: skipped (<raison>) est v