explainer

Que fait explainer ?

Un fichier de spécification liste les scènes ; les scripts capturent le matériel, vocalisent la narration, construisent une sous-composition HyperFrames par scène, et vérifient le tout avant la livraison.

1. comprendre    lire le code / la doc / l'application concernée
2. capturer      scripts/capture.py      captures d'écran, boîtes d'éléments, enregistrements, masquage
3. spec          vous écrivez explainer.json (scènes + narration + affirmations avec sources)
4. vérifier faits scripts/verify.py facts (barrière : rien n'est vocalisé tant qu'elle n'est pas passée)
5. construire    scripts/build_explainer.py (voix, légendes, scènes ; pas de personnage par défaut)
6. vérifier      scripts/verify.py all   (ressources, build, rendu, audio) – boucle jusqu'à nettoyage
7. rendre        scripts/render.py

Les chemins sont relatifs à la racine de ce paquet : le dossier qui contient .claude-plugin/, deux niveaux au-dessus de ce fichier (résoudre d'abord les liens symboliques). Nécessite les compétences HyperFrames publiques (hyperframes, hyperframes-cli ; hyperframes-registry et media-use pour les extras). Lisez hyperframes une fois avant de modifier manuellement les compositions générées.

0. Prévol (toujours en premier)

Exécutez python3 scripts/setup.py doctor (ajoutez --json pour le parser). Il liste chaque dépendance, son utilité, et la commande d'installation exacte pour cette machine ; il quitte avec le code 1 si un élément requis est manquant.

• Manquant requis (ffmpeg, Node.js 18+, les compétences HyperFrames, et la clé ElevenLabs ou say quand cette voix est configurée) : dites à l'utilisateur en une ligne à quoi sert chacun et proposez la commande affichée. Exécutez-la seulement après que l'utilisateur a dit oui. Ne saisissez ni ne demandez jamais de clé API vous-même : dites à l'utilisateur d'exporter ELEVENLABS_API_KEY dans son shell.
• Manquant optionnel : proposez-les une fois et dites ce que chacun débloque. Playwright donne les captures web avec des boîtes de zoom d'élément et des captures pleine page, tesseract (OCR) donne l'analyse des secrets sur les captures d'écran, et ASR (mlx-whisper / openai-whisper) donne la vérification audio et les timings exacts des mots. Ignorez-les si l'utilisateur refuse ; les vérifications correspondantes deviennent alors des étapes de review manuelles.
• Compétences HyperFrames (hyperframes, hyperframes-cli, hyperframes-registry, media-use) : si manquantes, recommandez npx hyperframes skills. Lisez hyperframes (et hyperframes-cli pour les problèmes de rendu) avant de construire ou modifier une composition.

Configuration (première exécution, ou lorsque l'utilisateur veut changer quelque chose)

python3 scripts/setup.py show affiche la configuration active. S'il n'y en a pas, interviewez l'utilisateur (une question courte à la fois, proposez la valeur par défaut) et écrivez-la :

Question	Drapeau	Options
Quelles parties ?	--features	explainer seul (aucun fichier de personnage nécessaire), ou character,explainer pour permettre un présentateur
Langue de narration	--language	Code ISO (en, es, ...) : choisit une voix say claire et indique à l'ASR à quoi s'attendre
Voix de narration	--narration-voice	voice (le fournisseur configuré), say (gratuit, macOS), none (légendes seulement)
Fournisseur de voix	--voice	elevenlabs (sa ELEVENLABS_API_KEY depuis l'env + --voice-id), say, none
Garde-fous de crédit	--max-chars, --max-seconds, --daily-credit-cap	les chiffres de l'utilisateur
Rendu	--render	local, cloud, preview
Taille	--size	1080x1920 (par défaut), 1920x1080, 1080x1080

python3 scripts/setup.py init --features explainer --voice say --render local --yes

init exécute d'abord le doctor et propose les mêmes installations. Si une configuration existe, il demande avant d'écraser (passez --force en mode non interactif). setup.py voices --lang <code> liste les voix macOS pour une langue et les voix ElevenLabs de l'utilisateur ; --say-voice "<nom>" en choisit une. Ne demandez, n'imprimez ni n'écrivez jamais de clés API.

1. Comprendre, puis scripter

• Obtenez d'abord les faits à partir de la source : lisez le code, la PR, le document ou l'application. Une explication erronée est pire qu'aucune. Montrez la forme de la chose avant les détails, parcourez un cas réel (vrais noms, vraies valeurs), et gardez chaque scène sur une seule idée.
• Forme (≤ styles.explainer.max_seconds) : 3 à 5 scènes d'environ 6 à 12 s chacune et un titre de fermeture. La synthèse vocale lit environ 2,4 mots par seconde : maintenez la narration d'une scène à moins de ~25 mots.

Choisir un style pour cette vidéo

Le paquet ne fournit que des valeurs neutres par défaut. Choisissez un style par vidéo en fonction du sujet, du public et de la marque ou des préférences de l'utilisateur, et demandez quand c'est important (une marque, une chaîne publique, une série). Ne répétez pas par habitude l'apparence de la vidéo précédente. Mettez-le dans le bloc style de la spécification :

Clé	Valeurs
palette	background, panel, ink, muted, accent, highlight (couleurs CSS ; gardez le contraste texte ≥ 4,5:1)
typographie	font, mono (polices incluses dans HyperFrames), title_scale (0,6-1,6)
disposition	align (left, center), radius (0-60), background_style (solid, gradient)
animation	motion (calm, normal, lively) : durées et easing de chaque mouvement
légendes	caption_style (box, outline, plain, none), caption_position (bottom, top)

Un kit brand dans la configuration (mêmes clés) remplace votre choix clé par clé. L'ensemble du présentateur suit l'arrière-plan de la vidéo sauf si son bloc a son propre style (voir talking-clip).

2. Capturer le matériel

python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit"   # nécessite Playwright
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12          # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48   # ou --blur
python3 scripts/capture.py list

• url utilise Playwright lorsqu'il est installé (requis pour --box et --full-page), sinon Chrome sans tête. Sans Playwright, donnez les boîtes de focus sous forme de rectangles de pixels [x, y, w, h] lus depuis le PNG (le double des pixels CSS à l'échelle par défaut). Si Playwright vit dans un virtualenv, exécutez les scripts avec cet interpréteur (.venv/bin/python scripts/capture.py ...). --box enregistre la boîte d'un élément en pixels image afin qu'une scène puisse y zoomer directement. Par défaut --scale 2 garde le texte net lorsqu'il est zoomé.
• Capturez la plus petite région qui raconte l'histoire ; un bureau complet réduit dans un cadre de téléphone est illisible. Utilisez des boîtes de focus pour zoomer.
• Un site Web entier comme projet au lieu de prises uniques : npx hyperframes capture <url> (hyperframes-cli).

3. Écrire la spécification

examples/explainer/explainer.json est un exemple complet et fonctionnel. Placez la spécification à la racine du matériel : les fichiers de code et les captures qu'elle référence doivent se trouver à l'intérieur du dossier de la spécification. Types de scènes :

type	nécessite	ce qu'il montre
screen	capture, optionnel focus: [{"box": "#sel" ou [x,y,w,h], "label": "...", "at": s}]	la capture d'écran, puis un mouvement de caméra vers chaque boîte avec un surlignage et une étiquette
recording	capture (une vidéo), optionnel focus	l'enregistrement d'écran, muet, mêmes caméra et étiquettes
code	file, lines: "a-b" (≤ 24, lignes ≤ ~49 caractères en vertical), highlight: [{"lines": [a, b], "at": s}]	le code sur une carte, les lignes apparaissant, des bandes sur les lignes clés
diagram	nodes: [{"id","label","sub"?,"highlight"?}], edges: [[a, b]], optionnel flow: [ids]	des boîtes et des flèches qui se construisent, un jeton voyageant le long de flow
title	text, optionnel sub, dur	une carte de fermeture ou de section

Animation, sur n'importe quelle scène (optionnel ; les couleurs et le timing proviennent du style, variez-les donc par vidéo comme le reste de l'apparence) :

Clé	Quoi
callouts: [{"type": "circle" ou "arrow", "box": [x,y,w,h] ou "#sel", "at": s, "note": "..."}]	boucle ou flèche dessinée à la main qui se trace ; pixels d'image sur les scènes écran/enregistrement, pixels de cadre ailleurs
kinetic: [{"text", "at", "dur", "y"?, "from"?}]	mots qui claquent pour insister ; à utiliser avec parcimonie (un ou deux par vidéo)
counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?}	un compteur qui atteint la valeur exacte
niveau supérieur transition: "wipe" ou "fade"	une transition à chaque coupe (par défaut none)

Ils suivent les éléments du registre count-up, caption-kinetic-slam, hw-callout-circle et hw-arrow (voir /hyperframes-registry). style.hand_font: "Caveat" récupère cette police manuscrite avec npx hyperframes add. Ne faites pas utiliser chaque fonctionnalité à chaque vidéo ; choisissez ce dont l'histoire a besoin.

Chaque scène avec narration doit comporter des claims : chaque affirmation technique qu'elle fait, avec une source (path:lines relative à la spécification, capture:<nom>, https://..., doc:<nom>) et status: "supported" une fois que vous l'avez vérifiée par rapport à cette source. "claims": [] signifie que la narration ne fait aucune affirmation technique. Les affirmations non étayées sont corrigées ou supprimées, jamais vocalisées.

Pas de personnage par défaut. Une explication est narration, légendes et visuels. N'ajoutez le personnage comme présentateur que lorsque l'utilisateur le demande, ou si vous jugez qu'il ajoute de la valeur (une série avec un hôte, une intégration conviviale) et vous le dites à l'utilisateur avec la raison. Ajoutez alors un bloc presenter (intro / outro, chacun {"text", "plan"?, "mood"?, "style"?, "claims"} ; les plans suivent le format talking-clip) et construisez avec --presenter. Cela nécessite aussi features.character. Les scènes du présentateur ont aussi des légendes (sauf si la spécification définit "captions": false). examples/explainer/explainer-with-presenter.json est l'exemple.

4-5. Barrière des faits, puis construction

python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]

--estimate imprime la durée et les crédits ElevenLabs ; informez l'utilisateur avant de dépenser, puis construisez avec --confirm. Le constructeur exécute également la barrière des faits et s'arrête si elle échoue. Les légendes affichent les propres mots du script (casse, ponctuation, chiffres) chronométrés à partir de l'alignement ElevenLabs, de l'ASR ou d'une estimation.

6. Vérifier (boucle requise)

python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4

Étape	Réussite quand	En cas d'échec
faits	chaque affirmation narrée a une source existante et un statut supported	vérifiez la source ; corrigez ou supprimez l'affirmation
ressources	les captures et le code sont lisibles à la taille de sortie ; OCR (tesseract) / analyse de texte ne trouve aucun email, clé, jeton ou numéro de carte	ajoutez des boîtes de focus ou recapturez en plus petit ; capture.py redact ; remplacez les secrets dans le code par des espaces réservés
build	npx hyperframes check --json n'a aucune erreur ni avertissement (sauf verify.ignore_rules)	corrigez la spécification ou la composition générée
rendu	vous avez regardé la planche contact (début, chaque changement de scène, milieu de scène, fin) : pas de débordement, chevauchement, coupure ou texte illisible ; les visuels correspondent à la narration	corrigez, reconstruisez, re-rendez
audio	l'ASR de l'audio rendu correspond au script (verify.min_asr_similarity) et la durée est dans la limite	régénérez la voix ou raccourcissez

Comment piloter la boucle :

1. Exécutez verify.py all. Chaque exécution est une itération (comptée dans <projet>/.verify/state.json).
2. render revient toujours d'abord comme review : ouvrez les planches contact qu'il liste, vérifiez chaque image, puis enregistrez ce que vous avez vu : python3 scripts/verify.py mark render pass --project out/explainer --note "<ce que vous avez vérifié>" (ou fail, puis corrigez). La marque est liée à ces fichiers exacts ; toute reconstruction l'invalide.
3. Sans OCR ou ASR installé, assets / audio deviennent aussi review : vérifiez à l'œil ou à l'oreille et indiquez-le dans le rapport.
4. Corrigez ce qui a échoué, reconstruisez ou re-rendez, et exécutez à nouveau verify.py all. Code de sortie 0 = livrez.
5. Lorsque le nombre atteint verify.max_iterations (par défaut 3), il sort avec le code 2 : arrêtez-vous et dites à l'utilisateur ce qui échoue encore. Ne livrez pas en silence. Supprimez .verify/state.json pour recommencer un nouveau compteur après un changement majeur.

VERIFY.md montre les chiffres : images OCR scannées et résultats, similarité ASR avec les mots entendus et attendus, durée par rapport à la limite. Citez-les lorsque vous faites votre rapport. Les scènes sont allongées automatiquement pour que la dernière légende reste lisible ; si un avertissement line_unread persiste, donnez à cette scène plus de min_dur.

Gardez le HOME normal de l'utilisateur lors de l'exécution des scripts : un HOME temporaire fait tout télécharger à nouveau à npx, Playwright et whisper, et casse l'authentification gh/npx.

Les incohérences audio sur les chiffres, les acronymes ou les mots étrangers : définissez language dans la configuration et écrivez ces mots dans la narration comme ils devraient sonner ("quinze", "A P I"). VERIFY.md dans le projet est le rapport de liste de contrôle ; incluez son résumé lorsque vous remettez la vidéo.

7. Rendre

python3 scripts/render.py out/explainer --out out/explainer.mp4 utilise render.backend (local, cloud ou preview) ; render.max_mb ré-encode pour respecter une limite de téléchargement. Ne commettez jamais de fichiers mp4 ou wav.