pr-vers-vidéo – point d'entrée de répartition
L'entrée est une pull request GitHub (un changement de code), fournie sous forme d'URL de PR, d'une référence <propriétaire>/<dépôt>#<N>, ou de « cette PR » alors qu'un dépôt avec une PR ouverte est cloné. La sortie est une vidéo explicative du changement de code : ce qui a été livré, pourquoi, et comment cela fonctionne — rendue à partir du diff/commits sous forme de scènes avant-après, surlignage des différences, arborescence de fichiers et d'impact. Longueur par défaut jusqu'à environ 3 min (point idéal ~30-90 s) ; un parcours vraiment plus long ou exhaustif de chaque fichier (5 min+) est un registre différent → /video-generale. Il n'y a pas de scraping de site web ni de Chrome sans tête pour l'ingestion — l'ingestion se fait via l'interface en ligne de commande gh. Le préréglage de style livré est toujours claude (éditorial chaleureux ; fenêtre de code bleu foncé signature).
Confirmez la route avant l'Étape 0. Cette compétence explique une pull request GitHub (un changement de code lu via
gh). Si l'entrée est un site marketing / produit →/video-lancement-produit; un site web général →/site-vers-video; un sujet / article sans PR →/explicateur-sans-visage; une visite de dépôt complet ou une sortie multi-PR →/video-generale. Hors périmètre : 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 on vous donne une entrée autre qu'une PR, ou si vous n'êtes pas sûr ? Lisez/hyperframesd'abord.
Ce flux de travail ne possède que le front spécifique à la PR (ingestion + conception de l'histoire) ; chaque phase marquée partagée réutilise le moteur copié depuis l'explicateur sans visage inchangé (il se trouve sous les propres scripts/ + agents/ + phases/ de cette compétence, donc <SKILL_DIR> se résout en pr-vers-vidéo).
Tous les artefacts vont dans PROJECT_DIR = videos/<nom-du-projet>/ (créé à l'Étape 0) ; tous les chemins ci-dessous lui sont relatifs. La répartition est portable pour le harnais : avant la première répartition de sous-agent, lisez <SKILL_DIR>/../hyperframes-core/references/repartition-sous-agent.md une fois — il mappe les verbes de répartition (déploiement parallèle / arrière-plan / attente) aux primitives de votre harnais ; un plafond de concurrence inférieur à N signifie des vagues de la taille du plafond, jamais moins de travailleurs. Ce fichier est un cahier de route contraignant, pas une lecture de fond : exécutez les étapes dans l'ordre et produisez chaque artefact de phase avec son script ou rôle d'agent désigné — ne substituez pas un pipeline libre, et ne sautez pas une étape de pause parce que la demande semble claire. Une étape que vous ne pouvez pas effectuer → arrêtez-vous et signalez-le.
| Phase | Exécution | Artefact principal | Flux détaillé |
|---|---|---|---|
| init | Bash | hyperframes.json | Étape 0 |
| ingestion (propre) | Bash (gh CLI + ingest.mjs + fetch-people-avatars.mjs, PAS d'agent, PAS de scraping) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | Étape 1 |
| conception-système (partagée) | Bash (pas d'agent, claude déterministe) | design-system/design.html + chunks/ | Étape 1b |
| conception-histoire (propre) | sous-agent | narrator_scripts.json | agents/conception-histoire.md |
| audio (partagée) | audio.mjs dans Bash | audio_meta.json | phases/audio/guide.md |
| conception-visuelle (partagée) | sous-agent | section_plan.md | agents/conception-visuelle.md |
| préparation (partagée) | prep.mjs dans Bash | group_spec.json | scripts/prep.mjs |
| sous-titres (partagée, dét.) | captions.mjs group -> captions.mjs html dans Bash (pas de sous-agent) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| scènes (partagée) | N x sous-agent (parallèle) | compositions/scene_*.html ou compositions/group_w*.html | agents/scenes-hyperframes.md |
| finalisation (partagée) | Prélude Bash (attente-musique-de-fond + assemblage + injection/vérification-transitions + élévation-vidéos + vérification-effets-sonores + précontrôle) -> sous-agent de finalisation (correction des problèmes mineurs sur place + un aperçu type contact-sheet + rendu) | renders/video.mp4 | Étape 7 / agents/hyperframes-finalisation.md |
Prérequis
macOS Apple Silicon ou Linux x64. Outils système : brew install [email protected] node ffmpeg (utilisez Homebrew Python, pas /usr/bin/python3, ou pip install sera bloqué par PEP 668) ; ensuite npx hyperframes doctor une fois (télécharge Chrome — nécessaire pour l'instantané/rendu, pas pour l'ingestion). La porte de chevauchement rendue (scripts/check-overlap.mjs, exécutée dans les auto-vérifications des travailleurs et le précontrôle) réutilise ce même Chrome mis en cache — elle ne télécharge jamais de navigateur ; sa seule dépendance est le module npm puppeteer-core, assuré une fois avant le déploiement des scènes (Étape 5.5, --ensure-deps, ~5 s, pas d'installation complète de puppeteer). Interfaces en ligne de commande : gh (GitHub CLI, authentifié — gh auth status doit réussir) et hyperframes. Clés cloud optionnelles (sinon alternatives locales) — injectez à l'Étape 0.5 :
| Clé / condition | Utilisée pour | Valeur par défaut / alternative |
|---|---|---|
gh auth status OK | Lecture de la PR (publique ou privée) | requis — échouez rapidement avec l'indice d'auth |
HEYGEN_API_KEY (ou hyperframes auth login) | TTS (cloud, horodatages au niveau du mot) | voix : auto (première voix anglaise starfish ; remplacer --voice) |
ELEVENLABS_API_KEY | TTS (cloud ; nécessite pip install elevenlabs) | voix 21m00Tcm4TlvDq8ikWAM (Rachel) |
| ni l'un ni l'autre, et non connecté | TTS | Kokoro local, voix am_michael (non-anglais : passer --voice) |
GEMINI_API_KEY / GOOGLE_API_KEY (alias) | Musique de fond Lyria | non défini -> MusicGen local (première exécution télécharge ~300 Mo) |
Flux
Étape 0.0 - Confirmer le brief (TOUJOURS demander un tour, puis construire)
Avant l'Étape 0, faites toujours une pause et demandez le brief en un seul message, puis attendez l'utilisateur — ne sautez jamais cette étape, même pour une demande qui semble complète. Proposez une valeur recommandée par défaut pour chaque champ et pré-remplissez tout ce que l'utilisateur a déjà donné (confirmez-le plutôt que de le redemander aveuglément) : l'angle (journal des modifications / révélation de fonctionnalité / correction / refactorisation — par défaut : déduire de la PR), l'audience (développeurs vs utilisateurs généraux — par défaut : développeurs), la longueur (par défaut ~60-90 s), et — si /hyperframes ne les a pas définis — l'aspect (par défaut 16:9) et la langue. Le style est toujours claude. Passez à l'Étape 0 seulement après que l'utilisateur a répondu ; une réponse « go » / « utilise les valeurs par défaut » est une réponse valide qui accepte toutes les valeurs par défaut.
Étape 0 - Initialiser le projet vidéo
Le répertoire de travail courant est la racine de l'espace de travail de l'agent (par ex. /tmp/pr-video-...). Écrivez tous les artefacts vidéo sous PROJECT_DIR = videos/<nom-du-projet>/.
<nom-du-projet> : utilisez le répertoire donné par l'utilisateur (par ex. Use ./videos/retry-pr), sinon un nom court en kebab-case dérivé de la PR (<dépôt>-pr-<N>, par ex. widgets-pr-1187). Pas le nom de base de l'espace de travail ou un horodatage.
Uniquement lorsque $PROJECT_DIR/hyperframes.json est absent :
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<nom-du-projet>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes initdépose unAGENTS.md/CLAUDE.mdgénérique dans$PROJECT_DIR; laissez-les en place — ce sont des échafaudages d'agent pour quiconque ouvre le projet terminé plus tard.
Contraintes : n'exécutez jamais hyperframes init / ne générez jamais AGENTS.md / CLAUDE.md à la racine de l'espace de travail ; n'imbriquez jamais un autre hyperframes/ à l'intérieur de PROJECT_DIR ; chaque commande Bash (maître + sous-agents) est un sous-shell (cd "$PROJECT_DIR" && ...) — jamais de cd nu.
Étape 0.5 - Conseil sur les clés API
Sautez si $PROJECT_DIR/.env existe ou si context.log n'est pas vide (= ce n'est pas la première exécution). Sinon, détectez d'abord ce qui est disponible (HeyGen TTS activé si $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY est défini ou si ~/.heygen/credentials existe depuis hyperframes auth login ; ElevenLabs / Gemini uniquement si leurs clés d'environnement sont définies), puis faites toujours une pause et proposez le menu — attendez l'utilisateur ; ne continuez pas par vous-même même si une configuration fonctionnelle est détectée (l'utilisateur peut vouloir ajouter une clé comme Gemini). Indiquez ce qui est détecté, puis : collez les clés (→ Écrivez $PROJECT_DIR/.env, une KEY=valeur par ligne, remplacez le même nom) / « go » (continuez avec ce qui est configuré — env, .env ou hyperframes auth login) / « skip » (continuez avec les alternatives locales pour tout ce qui n'est pas configuré). Passez ensuite à l'Étape 1.
Étape 1 - Ingestion (Bash, PAS d'agent, PAS de scraping)
Résolvez la référence de la PR et extrayez les faits structurés avec gh, puis intégrez-les dans le paquet de capture synthétique attendu par le backend partagé (reflète l'échafaudage sans scraping de l'explicateur sans visage). gh s'exécute ici, dans l'orchestrateur, donc les erreurs d'authentification / introuvable / dépôt privé apparaissent avec le stderr propre à gh ; ingest.mjs est une transformation pure hors ligne.
# Référence PR : une URL complète, "<propriétaire>/<dépôt>#<N>", ou "<N>" dans un dépôt cloné.
PR="<url | propriétaire/dépôt#N | N>"
# Échouez rapidement si gh n'est pas authentifié.
gh auth status || { echo "gh non authentifié — exécutez : gh auth login" ; exit 1 ; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# Intégrez pr.json + diff.patch dans tokens.json (colors:[] → palette native claude) +
# visible-text.txt (le brief narratif) + people.json (auteur de la PR + auteurs de commits avec compteurs +
# relecteurs / commentateurs / assignés, filtrés des bots + dédoublonnés, chacun avec une URL d'avatar GitHub).
# (L'`author` de la PR est seulement l'ouvreur ; les auteurs de commits depuis commits[].authors[] sont également suivis.)
# ingest est HORS LIGNE.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# Étape réseau (la seule du front des personnes — ingest reste hors ligne) : téléchargez l'avatar GitHub
# de chaque contributeur vers public/avatars/<login>.png pour un crédit optionnel /
# un plan de fermeture "livré par". Au mieux — un avatar manquant ou une exécution hors ligne ne bloque jamais (exit 0).
# Les avatars + ce plan sont le SEUL endroit où pr-vers-vidéo assouplit la valeur par défaut sans visage.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Validation :
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo manquant
# public/avatars/ est au mieux — son absence n'est PAS un échec (aucun avatar résolu / hors ligne).
Si gh génère une erreur (authentification / introuvable / privé), signalez le stderr exact et arrêtez-vous — ne fabriquez pas le contenu de la PR. Si ingest.mjs se termine...