media-use : Avant de sourcer l'audio/les images, appelez
/media-usepour résoudre la sélection de BGM/SFX/images à partir du catalogue HeyGen. Exécutez--adoptd'abord pour enregistrer les actifs existants. Voir la compétence/media-use.
PR vers HyperFrames
Utilisez cette compétence pour ingérer une pull request GitHub, comprendre le changement, planifier une vidéo explicative du changement de code et la construire cadre par cadre 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 ni d'actifs réels 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 ensuite seulement continuez. Cette compétence est destinée à une pull request GitHub (un changement de code). Acheminez les autres intentions ailleurs : un lancement de produit/promotion →
/product-launch-video; une visite guidée d'un site Web général →/website-to-video; une explication de sujet sans PR →/faceless-explainer; des légendes sur des séquences existantes →/embedded-captions; un court graphique animé sans narration →/motion-graphics; une présentation d'une 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 avec validation par l'utilisateur sont l'étape 0, l'étape 3 et l'étape 6. Effectuez chaque étape vous-même, sauf l'étape 5, où vous déléguez un sous-agent par cadre. Ne mettez pas de règles de conception ou de mouvement ici ; celles-ci résident dans le sous-agent de travail des cadres, 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 conception → frame.md ; Étape 3 storyboard/scénario → STORYBOARD.md et SCRIPT.md ; Étape 3.1 audio → audio_meta.json ; Étape 4 conception visuelle → STORYBOARD.md enrichi ; Étape 5 cadres → 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 chaque élément et pré-remplissez tout ce que /hyperframes a déjà défini : angle (journal des modifications / présentation de fonctionnalité / explication de correction / présentation de refactorisation — par défaut : déduisez de la PR), public (par défaut : développeurs), durée (par défaut : adaptée à la taille de la modification de la PR — voir ci-dessous), format (par défaut 16:9), langue. Le style est toujours claude. Poursuivez seulement après la réponse de l'utilisateur ; un « go » accepte les valeurs par défaut.
Recommandez la durée en fonction de la taille de la modification de la PR, pas d'une estimation fixe. Avant de confirmer le brief, jetez un œil à la PR une fois — un appel en lecture seule qui permet également de préciser l'angle (l'étape 1 effectue toujours la récupération déterministe complète) :
gh pr view <PR_REF> --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 le modifier ; limite maximale d'environ 3 minutes) :
| Taille de la modification de la PR | Durée recommandée |
|---|---|
| triviale (≲ 50 lignes modifiées) | ~20–40s |
| ciblée (~50–200 lignes) | ~40–70s |
| substantielle (~200–600 lignes) | ~70–110s |
| grande (≳ 600 lignes, ou 25+ fichiers) | ~110–180s |
Indiquez la base en une phrase lorsque vous la proposez (par exemple « ~40s — petite modification, +44/−13 sur 12 fichiers »). Une PR énorme ne signifie pas une vidéo longue — si l'histoire est un changement principal, gardez-la concise 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 certaines 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/BGM utilisera HeyGen ou les moteurs locaux et, lorsqu'il n'est pas connecté, comment se connecter. Si vous n'êtes pas connecté, ARRÊTEZ-VOUS et attendez que l'utilisateur choisisse — se connecter, ou dire « go »/« offline » pour continuer avec les moteurs locaux — avant de demander le brief ou quoi que ce soit d'autre. Traitez-le comme un véritable point de décision, pas une simple remarque ; n'intégrez pas le choix dans la question du brief et n'écrivez pas les 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 conseils canoniques.
Porte : hyperframes.json existe ; la référence de la PR est capturée ; l'angle, la durée, le format d'image et la langue sont verrouillés ; l'état de connexion a été affiché (connecté, ou continuant 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 paginée gh api afin qu'une grande PR ne soit pas tronquée à environ 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 paginée gh api (afin qu'une grande 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 / non trouvé / privé renvoient 1 ici.
(cd "videos/<projet>" && node <REP_COMPETENCE>/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_COMPETENCE>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# L'unique étape réseau du front des personnes — télécharger l'avatar GitHub de chaque contributeur vers
# assets/<login>.png pour un éventuel générique de fin. Au mieux ; se termine toujours par 0.
(cd "videos/<projet>" && node <REP_COMPETENCE>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs se termine par 1 (gh auth / non trouvé / privé), signalez son stderr et arrêtez — ne fabriquez pas le contenu de la PR. Si ingest.mjs se termine par 1, lisez son stderr (généralement un pr.json mal formé), corrigez et réexécutez (déterministe). fetch-people-avatars.mjs se termine toujours par 0 ; les avatars manquants signifient simplement qu'il n'y a pas de générique de fin 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 Conception
Objectif : Adopter le préréglage de cadre claude ; un script le transforme en frame.md + skin de légende de cette vidéo.
Le style est fixe — claude (éditorial chaleureux ; une surface de code bleu marine conçue pour les diffs). Exécutez :
node <REP_COMPETENCE>/scripts/build-frame.mjs --preset claude --hyperframes .
Le script copie le FRAME.md du préréglage claude → frame.md, le remixe avec les éventuels jetons de marque dans capture/extracted/tokens.json (une PR n'en a pas → 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 (se termine par 1 en cas de mapping cassé). Poursuivez dès qu'il se termine par 0 — pas de modification manuelle.
Porte : build-frame.mjs s'est terminé par 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 Scénario
Objectif : Transformer la PR en un plan d'explication cadre par cadre 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 / présentation de fonctionnalité / explication de correction / présentation de refactorisation), les types de cadres natifs de la PR, l'accroche, la persuasion, les séquences, le budget de mots par cadre et le générique de fin 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 (de capture/diff.patch), chacun étant un petit extrait lisible ; nommez le bloc code-* que chacun souhaite dans la scene du cadre. Les cadres ne portent pas de asset_candidates à l'exception d'un générique de fin credits optionnel (2 à 6 avatars assets/<login>.png). Utilisez les champs obligatoires exacts des références de storyboard et de scénario.
Après la rédaction, montrez un résumé cadre par cadre. 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 cadre a les champs narratifs obligatoires, 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 timings des mots, la musique et les métadonnées audio à partir du scénario approuvé.
Commencez l'audio après l'approbation de l'étape 3. Exécutez-le en arrière-plan, puis continuez à l'étape 4.
node <REP_COMPETENCE>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
Le script audio gère la narration, les timings des mots, la recherche de BGM dans la bibliothèque musicale de HeyGen et les métadonnées de timing. L'ambiance 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 la même information d'identification ~/.heygen que pour la synthèse vocale. 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, sautez la génération vocale. La BGM peut toujours être exécutée si le storyboard a une ambiance musicale.
Porte : le travail audio a commencé, ou le projet est marqué comme silencieux.
Étape 4 : Conception Visuelle des Cadres
Objectif : Ajouter la direction visuelle, l'intention de mise en page et les choix de mouvement à chaque cadre 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, la sensation de 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 obligatoires des cadres et le bloc obligatoire ## Video direction, et pour la façon dont un beat de code nomme un bloc code-* comme son focal. Utilisez code-vocabulary.md pour choisir le bon bloc par beat (diff = code-diff, refactor = 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'effet et de blueprint valides. N'inventez pas de noms d'effets ou d'identifiants de blocs/blueprints.
Pour chaque cadre, ajoutez les champs visuels et de mouvement obligatoires, y compris effects et focal et/ou roles. Pour un beat de code, nommez le bloc code-* comme focal et laissez effects chorégraphier la surface de code claude environnante (pas l'animation de code, que le bloc possède). Ajoutez un bloc ## Video direction à l'échelle de la vidéo.
Ne changez pas l'histoire, le scénario, 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 actifs — les seuls actifs réels sont les avatars de crédits, déjà dans assets/.
Porte : chaque cadre a effects plus focal et/ou roles ; les cadres de code nomment un bloc code-* ; ## Video direction existe.
Étape 5 : Construire les Cadres
Objectif : Construire chaque cadre du storyboard en tant que composition HTML et assembler la vidéo lisible.
Attendez que l'audio de l'étape 3.1 soit terminé si l'audio a été démarré. Ensuite, synchronisez les durées et récupérez les SFX ; sautez les deux si silencieux.
node <REP_COMPETENCE>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <REP_COMPETENCE>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
La synchronisation des durées est mécanique : la durée vocale réelle l'emporte ; les cadres silencieux conservent les estimations ; ne modifiez jamais manuellement les durées synchronisées.
Pré-installez les blocs de registre nommés dans STORYBOARD.md une fois, avant la répartition, afin que les travailleurs parallèles ne se précipitent pas sur le registre :
for b in <chaque bloc de registre nommé dans le storyboard>; do npx hyperframes add "$b"; done
Avant la répartition, lisez sub-agents/frame-worker.md et ../hyperframes-core/references/subagent-dispatch.md. Répartissez un sous-agent par cadre, en parallèle si possible ; sinon, exécutez les travailleurs par vagues. Chaque travailleur reçoit exactement un cadre. Le contexte de chaque travailleur doit inclure PROJECT_DIR, frame_id, la taille du canevas, l'état de la légende et la bande de sécurité 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 ## Frame N, le corps de recette pour chaque identifiant d'effet/blueprint cité, et — pour un beat 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.
Au retour de chaque travailleur, marquez ce cadre comme animated dans STORYBOARD.md.
Une fois les timings audio existants, construisez les légendes en arrière-plan et assemblez l'index :
node <REP_COMPETENCE>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <REP_COMPETENCE>/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 de frame.md ; captions: skipped (<raison>) si
... (tronqué pour la traduction)