media-use : avant de sourcer l'audio/les images, appelez
/media-usepour trouver BGM/SFX/images depuis le catalogue HeyGen. Lancez--adoptd'abord pour enregistrer les assets existants. Voir le skill/media-use.
Que fait PR vers HyperFrames ?
Utilisez ce skill pour ingérer une pull request GitHub, comprendre le changement, planifier un explicateur de changement de code et le construire frame par frame 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'assets 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. Ce skill est destiné à une pull request GitHub (un changement de code). Aiguillez les autres intentions ailleurs : un lancement/promo de produit →
/product-launch-video; une visite de site web général →/website-to-video; un explicateur de sujet sans PR →/faceless-explainer; des sous-titres sur des séquences existantes →/embedded-captions; un court graphique animé sans narration →/motion-graphics; une présentation de release multi-PR ou de dépôt entier →/general-video. Hors champ : données en direct / au moment du rendu — les faits de la PR sont lus une fois au moment de l'auteur 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/<project>/. Exécutez les étapes dans l'ordre et passez chaque porte avant de continuer. Les étapes avec porte 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 frame. Ne mettez pas de règles de conception ou d'animation ici ; elles vivent dans le sous-agent de travail des frames, hyperframes-creative, et hyperframes-animation.
Workflow : É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 frames → 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 <owner>/<repo>#<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 champ et pré-remplissez tout ce que /hyperframes a déjà défini : angle (journal des modifications / révélation de fonctionnalité / explication de correction / présentation de refactorisation — par défaut : déduire de la PR), public (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. Ne procédez qu'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 du changement de la PR, pas d'une supposition fixe. Avant de confirmer le brief, jetez un coup d'œil à la PR une fois — un appel en lecture seule qui fonde également l'angle (l'Étape 1 fait toujours la récupération déterministe complète) :
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
Choisissez le palier à partir de additions + deletions (ajusté par changedFiles) et proposez-le comme valeur par défaut (l'utilisateur peut modifier ; limite maximale ~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 |
| important (≳ 600 lignes, ou 25+ fichiers) | ~110–180s |
Indiquez la base en une phrase lorsque vous la proposez (par ex. « ~40s — petit changement, +44/−13 dans 12 fichiers »). Une PR énorme ne signifie pas une vidéo longue — si l'histoire est un changement clé, restez concis et dites-le.
Initialisez seulement si hyperframes.json est manquant. Nommez <project> à 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/<project>" --non-interactive --example=blank — 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.
Affichez le statut 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, si non connecté, comment se connecter. Si non 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 note passagère ; ne glissez 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 le statut 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 ; le statut 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ète la liste des fichiers via l'API gh api paginée pour qu'une grande PR ne soit pas tronquée à ~100 fichiers, et écrit seulement capture/pr.json + capture/diff.patch (pas de répertoire temporaire). Ensuite ingest.mjs l'intègre dans le package de capture synthétique hors ligne.
PR="<url | owner/repo#N | N>"
# Récupère la PR de manière déterministe : exécute gh, complète la liste des fichiers via l'API gh paginée
# (pour 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 / introuvable / privée sortent avec le code 1 ici.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformation hors ligne → capture/extracted/{tokens.json (couleurs:[] → palette claude),
# visible-text.txt (le brief), people.json (contributeurs, filtrés des bots, avatarFile=assets/<login>.png)}.
(cd "videos/<project>" && node <SKILL_DIR>/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écharge l'avatar GitHub de chaque contributeur vers
# assets/<login>.png pour un crédit optionnel en fin. Au mieux ; sort toujours avec le code 0.
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs sort avec le code 1 (gh auth / introuvable / privée), signalez sa sortie d'erreur et arrêtez-vous — ne fabriquez pas de contenu de PR. Si ingest.mjs sort avec le code 1, lisez sa sortie d'erreur (généralement un pr.json malformé), corrigez et relancez (déterministe). fetch-people-avatars.mjs sort toujours avec le code 0 ; des avatars manquants signifient simplement pas de crédit final 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 preset de frame claude ; un script le transforme en frame.md de cette vidéo + skin de sous-titres.
Le style est fixe — claude (éditorial chaleureux ; une surface de code marine conçue pour les diffs). Exécutez :
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
Le script copie le FRAME.md du preset claude → frame.md, le remixe sur tous les tokens de marque dans capture/extracted/tokens.json (une PR n'en a pas → couleurs:[]/polices:[] garde la propre palette de claude, un design complet), copie le skin de sous-titres du preset vers .hyperframes/caption-skin.html, et s'auto-valide (sort avec le code 1 sur un mapping cassé). Procédez dès qu'il sort avec le code 0 — pas de modification manuelle.
Porte : build-frame.mjs est sorti avec le code 0 — frame.md existe depuis le preset claude, et .hyperframes/caption-skin.html existe comme source du skin de sous-titres.
Étape 3 : Storyboard et Script
Objectif : Transformer la PR en un plan d'explication frame par frame 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é / explication de correction / présentation de refactorisation), les types de frames natifs de la PR, l'accroche, la persuasion, les temps forts, le budget de mots par frame et le crédit optionnel de fin. La séquence vient de la conception narrative, pas de l'ordre des fichiers du diff — expliquez le changement, ne lisez pas le diff à voix haute. Proposez 2 à 4 extraits de diff réels (de capture/diff.patch), chacun un petit extrait lisible ; nommez le bloc code-* que chacun souhaite dans la scene de la frame. Les frames ne portent pas de asset_candidates à l'exception d'un crédit de fin 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é frame par frame. 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) — ne l'ouvrez que sur un oui. Itérez jusqu'à approbation ; reportez le choix de l'aperçu à l'Étape 6.
Porte : STORYBOARD.md existe, chaque frame 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 timings des mots, la musique et les métadonnées audio à partir du script approuvé.
Commencez l'audio après l'approbation de l'Étape 3. Lancez-le en arrière-plan, puis continuez à l'Étape 4.
node <SKILL_DIR>/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 BGM dans la bibliothèque musicale de HeyGen et les métadonnées de timing. L'humeur du BGM provient du champ music: du storyboard. Il utilise l'API Audio HeyGen pour la récupération, pas la génération, et la même credential ~/.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. Le BGM peut toujours être exécuté si le storyboard a une humeur musicale.
Porte : le travail audio a commencé, ou le projet est marqué comme silencieux.
Étape 4 : Conception Visuelle des Frames
Objectif : Ajouter la direction visuelle, l'intention de mise en page et les choix d'animation à chaque frame 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 de frame requis et le bloc requis ## Direction vidéo, 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, refactor = code-morph, nouveau code = code-typing, …). Utilisez composition.md pour la mise en page/hiérarchie/points focaux et motion-language.md + ../hyperframes-animation/ pour les IDs d'effet et de blueprint valides. N'inventez pas de noms d'effet ou d'IDs de bloc/blueprint.
Pour chaque frame, ajoutez les champs visuels et d'animation requis, y compris effects et focal et/ou roles. Pour un temps fort 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 ## Direction vidéo à 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 dans cette étape. Il n'y a pas d'étape de préparation d'assets — les seuls assets réels sont les avatars de crédit, déjà dans assets/.
Porte : chaque frame a effects plus focal et/ou roles ; les frames de code nomment un bloc code-* ; ## Direction vidéo existe.
Étape 5 : Construire les Frames
Objectif : Construire chaque frame du storyboard en une composition HTML et assembler la vidéo jouable.
Attendez que l'audio de l'Étape 3.1 se termine si l'audio a été démarré. Ensuite synchronisez les durées et récupérez les SFX ; ignorez les deux si le projet est silencieux.
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/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 frames silencieuses gardent les estimations ; ne modifiez jamais manuellement les durées synchronisées.
Pré-installez les blocs de registre nommés dans STORYBOARD.md en une fois, avant l'envoi, pour que les workers parallèles ne se concurrencent pas sur le registre :
for b in <chaque bloc de 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 frame, en parallèle si possible ; sinon exécutez les workers par vagues. Chaque worker reçoit exactement une frame. Le contexte de chaque worker doit inclure PROJECT_DIR, frame_id, la taille du canevas, le statut des sous-titres et la bande de réserve si les sous-titres sont activés, ANIM_DIR (chemin absolu vers ../hyperframes-animation/) et le chemin absolu vers references/code-vocabulary.md. Chaque worker lit frame.md, son propre bloc ## Frame N, le corps de la recette pour chaque ID d'effet/blueprint cité et — pour un temps fort de code — code-vocabulary.md pour les entrées du bloc nommé. Chaque worker écrit seulement compositions/frames/NN-*.html ; les workers ne modifient jamais STORYBOARD.md.
Lorsque chaque worker revient, marquez cette frame comme animée dans STORYBOARD.md.
Une fois les timings audio existants, construisez les sous-titres en arrière-plan et assemblez l'index :
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/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 tokens de marque depuis frame.md ; sous-titres : ignorés (<raison>) pour les projets marqués comme silencieux. assemble-index.mjs produit compositions/index.html — un seul fichier HTML avec toutes les frames disposées et minutées. Une fois index.html écrit, appelez npx hyperframes status pour rapporter l'avancement, y compris les frames restant à animer et tout warning. Porte : compositions/index.html existe, et npx hyperframes status ne signale aucune frame manquante.
Étape 6 : Rendu Final
Objectif : Produire la vidéo finale et montrer le résultat à l'utilisateur.
Confirmez avec l'utilisateur qu'il est prêt pour le rendu. Proposez l'aperçu en direct s'il a été demandé à l'Étape 3 (la porte l'attend, pas un rappel). Le rendu peut prendre de quelques secondes à plusieurs minutes — aucune réduction de taille prédéfinie ; la taille du fichier vidéo est déterminée par la résolution du canevas (par défaut 1920×1080). Si le projet est silencieux, la vidéo sera sans son — aucune durée n'est forcée.
npx hyperframes render videos/<project> --output ./renders/video.mp4
Après que le rendu se termine avec succès, montrez le résultat : ouvrez le fichier rendu ou rapportez son chemin dans votre réponse. Si le rendu échoue, lisez les logs de rendu, corrigez le problème directement (fichiers HTML cassés, IDs de blueprint invalides, etc.) et relancez.
Porte : renders/video.mp4 existe, et la vidéo a été montrée à l'utilisateur.
Références
references/story-design.md— modèles narratifs spécifiques aux PRreferences/visual-design.md— champs de direction visuelle requisreferences/composition.md— mise en page, hiérarchie, points focauxreferences/motion-language.md— langage d'animation et IDs de blueprintreferences/code-vocabulary.md— blocs d'affichage de code (diff, morph, typing, …)sub-agents/frame-worker.md— contrat du sous-agent de construction de frame../hyperframes-animation/— catalogue complet des blueprints d'effet../hyperframes-core/references/storyboard-format.md— format requis du storyboard../hyperframes-core/references/script-format.md— format requis du script../hyperframes-core/references/subagent-dispatch.md— modèle d'envoi des sous-agents../hyperframes-media/references/tts.md— fournisseur de synthèse vocale (HeyGen)