Avant tout, gardez cette compétence à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update pr-to-video. Une opération rapide, sans effet si tout est à jour ; sinon, elle rafraîchit cette compétence ainsi que les compétences du domaine central dont elle dépend avant que vous ne vous y appuyiez.
media-use : Avant de rechercher de l'audio, des images ou des logos, appelez
/media-usepour résoudre les BGM/SFX/images du catalogue HeyGen et les logos de marque à partir de leurs sources officielles. 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 une vidéo explicative de code et la 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 ni de ressources réelles au-delà des avatars des contributeurs.
La porte d'entrée est
/hyperframes. Vous êtes l'orchestrateur. Exécutez chaque étape, vérifiez son point de contrôle, et continuez seulement ensuite. Cette compétence est destinée à une pull request GitHub (un changement de code). Pour toute autre intention, un simple « crée une vidéo », ou toute incertitude → lisez/hyperframesd'abord — la couche d'intention possède chaque décision de routage, et une nouvelle création arrivant ici sansBRIEF.mdpasse de toute façon par elle (règle d'ouverture de la configuration).
Vous êtes l'orchestrateur. Travaillez dans le PROJECT_DIR externe résolu, jamais dans le dépôt appelant par défaut. Exécutez les étapes dans l'ordre et passez chaque point de contrôle avant de continuer. Les étapes gérées par l'utilisateur sont l'étape 0, l'étape 3 et l'étape 6. Lisez ../hyperframes/references/brief-contract.md avant l'étape 0 — il définit les types de points de contrôle et comment BRIEF.md's flow/storyboard dérivent le mode qui régit les points de contrôle des étapes 3/4/6. Faites chaque étape vous-même, sauf l'étape 5, où vous déléguez à un pool limité d'ouvriers d'images. Ne mettez pas de règles de conception ou de mouvement ici ; elles résident dans le sous-agent ouvrier d'image, dans ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ de cette compétence, et hyperframes-creative.
Workflow : Étape 0 configuration → hyperframes.json ; Étape 1 ingestion → capture/extracted/ + assets/<login>.png ; Étape 2 système de conception → 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
Objectif : Entrer avec un brief confirmé — incluant la référence PR (une URL complète, une référence <propriétaire>/<dépôt>#<N>, ou « cette PR » dans un dépôt cloné) — créer le projet HyperFrames et rendre le brief durable. Le style est toujours code-éditorial (fixé à l'étape 2, jamais demandé).
Le brief est confirmé par la couche d'intention, pas par des questions posées ici. Règle d'ouverture, dans l'ordre : (1) BRIEF.md existe → lisez-le et ne posez aucune question — le brief est réglé, et son flow/storyboard dérivent le mode (contrat du brief § 1). (2) Pas de BRIEF.md mais le projet existe (hyperframes.json / STORYBOARD.md sur le disque) → reprenez à partir du frontmatter du storyboard et des préférences enregistrées ; ne réinterrogez jamais un projet à moitié construit. (3) Ni l'un ni l'autre — une demande de nouvelle création arrivée ici directement → lisez /hyperframes et exécutez sa couche d'intention (references/intent-interview.md) : elle vérifie les recettes et les valeurs par défaut mémorisées, et mène les questions de cette route — y compris la doctrine taille PR → durée, qui réside entièrement dans ../hyperframes/references/routes/pr-to-video.md — puis renvoie le brief verrouillé. Les demandes de modification sautent tout cela — allez faire la modification.
Résolvez le répertoire du projet avant de faire tout autre travail. Préservez un répertoire de projet fourni par l'utilisateur ; sinon, utilisez l'emplacement de cache externe durable renvoyé par le résolveur. Ne créez jamais videos/ dans le dépôt appelant :
PR="<url | propriétaire/dépôt#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "Projet PR vers vidéo : $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
La vérification préalable des capacités s'exécute avant la récupération, le travail sur le storyboard, l'audio ou la distribution des images. Si la CLI installée ne peut pas exécuter la commande de validation requise par cette compétence, arrêtez-vous avec son instruction de mise à niveau plutôt que de consommer le contexte de l'exécution.
Initialisez seulement si $PROJECT_DIR/hyperframes.json est manquant. Son nom de base provient de la PR, par exemple acme-sdk-pr-1842 ; n'utilisez jamais le nom de l'espace de travail ni un horodatage.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — 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.
Chaque commande avec chemin relatif ci-dessous s'exécute avec $PROJECT_DIR comme répertoire de travail. Les exemples sans sous-shell explicite signifient (cd "$PROJECT_DIR" && …) ; ne modifiez jamais l'arbre de travail du dépôt appelant.
Écrivez BRIEF.md immédiatement après init (jamais avant — init refuse un répertoire non vide) : le brief verrouillé de la couche d'intention, format selon ../hyperframes/references/brief-format.md. Résolvez <MEDIA_DIR> comme le répertoire de la compétence /media-use installée. Ensuite, enregistrez chaque réponse basée sur une préférence avec node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md nomme le sous-ensemble). Si la couche d'intention a adopté une recette, exécutez node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <nom> ; elle copie son frame.md dans le projet (l'étape 2 est alors ignorée) et renvoie les squelettes à partir desquels l'étape 3 rédige. Une recette remplit les réponses, pas les approbations ; les points de contrôle de révision s'exécutent toujours.
Affichez l'état de connexion avant de passer la configuration — exécutez npx hyperframes auth status et relayez sa sortie textuellement. Il indique si la voix/BGM utilisera HeyGen ou les moteurs locaux et, en cas de déconnexion, comment se connecter. Appliquez une branche :
- Collaboratif : attendez que l'utilisateur se connecte ou choisisse explicitement
offline/go. - Autonome : indiquez l'état et continuez via les moteurs locaux disponibles.
N'omettez pas silencieusement une capacité requise lorsqu'aucun fournisseur hors ligne n'existe ; signalez le blocage. N'incluez pas cette décision dans une autre question et n'écrivez pas de clés dans un .env par dépôt. Propriété de l'authentification et alternatives hors ligne : /media-use references/setup-providers.md § Fournisseurs.
Point de contrôle : hyperframes.json et BRIEF.md existent ; la référence PR est capturée dans le brief ; les réponses basées sur les préférences ont été enregistrées (contrat du brief § 2) ; 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 gh api paginé afin qu'une grande PR ne soit pas tronquée à environ 100 fichiers, et écrivant uniquement capture/pr.json + capture/diff.patch (pas de répertoire temporaire). Pour les PR FUSIONNÉES, il résout également un shipped_version au mieux (+ version_source) dans pr.json, de sorte que la carte de fin puisse citer une version réelle plutôt que d'en inventer une. 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ère la PR de manière déterministe : exécute gh, complète la liste des fichiers via
# gh api paginé (afin qu'une grande PR ne soit pas tronquée à environ 100 fichiers),
# écrit uniquement capture/pr.json + capture/diff.patch — pas de répertoire temporaire.
# Les erreurs gh auth / introuvable / privé renvoient un code de sortie 1 ici.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformation hors ligne → capture/extracted/{tokens.json (colors:[] → palette code-éditoriale),
# visible-text.txt (le brief), people.json (contributeurs, filtrés par bot, nom+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# L'unique étape réseau de la partie personnes — télécharge l'avatar GitHub de chaque contributeur
# vers assets/<login>.png pour les crédits de fin. Au mieux ; renvoie toujours 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs renvoie 1 (gh auth / introuvable / privé), rapportez sa sortie d'erreur et arrêtez-vous — ne fabriquez pas le contenu de la PR. Si ingest.mjs renvoie 1, lisez sa sortie d'erreur (généralement un pr.json mal formé), corrigez et réexécutez (déterministe). fetch-people-avatars.mjs renvoie toujours 0 ; des avatars manquants signifient simplement qu'il n'y a pas de crédits de fin pour l'auteur.
people.json porte un name pour les contributeurs que gh a déjà nommés (l'auteur de la PR, les auteurs de commits, mergedBy) — null pour les autres (relecteurs, commentateurs, personnes assignées, pour lesquels gh pr view ne donne qu'un simple login). Avant d'écrire les crédits de fin à l'étape 3, résolvez vous-même tout name null pour les 1 à 6 personnes qui apparaîtront réellement sur cette image : gh api users/<login> --jq .name (vous avez déjà gh — pas besoin de script). Si GitHub n'a pas de nom public pour cet utilisateur non plus, revenez au login à l'écran et retirez cette personne de la ligne parlée (voir la section crédits de story-design.md — le voiceover doit toujours dire les noms, jamais les pseudonymes bruts).
Point de contrôle : 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 d'image code-éditorial ; un script le transforme en frame.md de cette vidéo + une couche de sous-titres.
Le style est fixe — code-éditorial (éditorial chaud ; une surface de code marine conçue pour les diffs). Exécutez :
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
Le script copie le FRAME.md du préréglage code-éditorial vers frame.md, le remixe sur les éventuels jetons de marque dans capture/extracted/tokens.json (une PR n'en a pas → colors:[]/fonts:[] conserve la propre palette du code-éditorial, une conception complète), copie la couche de sous-titres du préréglage vers .hyperframes/caption-skin.html, et s'auto-valide (renvoie 1 en cas de mappage cassé). Continuez dès qu'il renvoie 0 — pas de modification manuelle.
Point de contrôle : build-frame.mjs a renvoyé 0 — frame.md existe à partir du préréglage code-éditorial, et .hyperframes/caption-skin.html existe comme source de la couche de sous-titres.
Étape 3 : Storyboard et script
Objectif : Transformer la PR en un plan d'explication image par image approuvé.
Lisez ../hyperframes-creative/references/story-spine.md (langage d'accroche, valeur avant preuve, storyboard comme proposition, visuels traçables par source), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes/references/storyboard-format.md et ../hyperframes/references/script-format.md. Utilisez-les pour écrire STORYBOARD.md et, lorsque la narration est nécessaire, SCRIPT.md. Définissez le duration: du frontmatter à partir du length du brief — une attente approximative ; l'assemblage indique où la coupe se situe par rapport à cela.
Utilisez story-design.md pour l'archétype PR (journal des modifications / révélation de fonctionnalité / explication de correction / présentation de refactorisation), les types d'images natifs PR, l'accroche, la persuasion, les battements, le budget de mots par image et les crédits de fin. 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. Comme guide souple, consultez le menu rôle→plan dans ../hyperframes-animation/blueprints-index.md : pour chaque battement, écrivez le voiceover dans la forme qu'implique son plan candidat et étiquetez cet id blueprint: lorsqu'un cadre correspond (la vérité de l'histoire décide encore quels battements existent — ne forcez jamais un battement à s'adapter à une forme). Présentez 2 à 4 extraits de diff réels (de capture/diff.patch), chacun un petit fragment lisible ; nommez le bloc code-* que chacun souhaite dans la scene de l'image. Les images ne portent pas de asset_candidates à l'exception des crédits de fin (1 à 6 avatars assets/<login>.png). Utilisez les champs obligatoires exacts des références du storyboard et du script.
Après la rédaction, exécutez le passage de plan de la boucle de révision — ../hyperframes/references/review-loop.md § 1 : présentez le plan comme une proposition, et posez les deux questions — approuvez ou modifiez, et croquis d'abord (recommandé) ou passez. Les commentaires arrivent sous forme de réponse dans le chat ; bouclez jusqu'à approbation. C'est un point de contrôle de vérification (contrat du brief § 1) : en mode autonome, il n'y a rien à demander — publiez le même résumé comme un avertissement et continuez ; les croquis se fondent dans la construction, et l'unique question d'aperçu vient à l'étape 6.
Point de contrôle : 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 (autonome : le résumé a été publié comme avertissement).
Étape 3.1 : Audio
Objectif : Générer la narration, les synchronisations de mots, la musique et les métadonnées audio à partir du script approuvé.
Commencez l'audio après l'approbation de l'étape 3. Exécutez-le en arrière-plan, puis continuez à l'étape 4.
Choisissez la voix de narration à partir de la demande de l'utilisateur avant d'invoquer. Si la demande a nommé une voix, un genre ou un ton, choisissez un identifiant de voix correspondant et transmettez-le avec --voice <id>. La valeur par défaut du pipeline est sinon Marcia (féminine) sur HeyGen / am_michael sur Kokoro — donc une demande comme « une voix masculine » est ignorée silencieusement à moins que vous ne passiez le drapeau. Les identifiants de voix sont spécifiques au fournisseur ; résolvez-les par rapport au fournisseur que l'état de connexion de l'étape 0 a sélectionné : HeyGen (connecté) via node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (ou GET /v3/voices?engine=starfish) ; Kokoro (hors ligne) via la table des voix dans <MEDIA_DIR>/audio/references/tts.md (préfixes am_/bm_ masculin, af_/bf_ féminin). Lorsque l'utilisateur n'a exprimé aucune préférence, revenez à la voix mémorisée (contrat du brief § 2) avant la valeur par défaut du pipeline, et dites laquelle vous avez utilisée ; omettez --voice seulement lorsque ni l'un ni l'autre n'en nomme une. Lorsque l'utilisateur a explicitement choisi une voix lors de cette exécution, enregistrez-la (prefs.mjs record --key voice).
`node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STOR
…[tronqué pour la traduction]