tzezhang1-crypto/claude-motion-explainer-video

Motion explainer (version vidéo enrichie) — Animation des principes, photos comme preuves, vidéo AI pour l'émotion

Ce skill enchaîne les étapes suivantes : « Rechercher en ligne → écrire le script → narration chinoise → animer image par image → sous‑titres → palette de couleurs → trouver des photos libres de droits, générer des schémas → générer des vidéos AI → auto‑relecture → exporter MP4 ». Par rapport à la version de base motion-explainer, il ajoute la section 7.5 (calque d'images), la section 7.6 (calque de vidéos AI) et la section 4 (correction des erreurs de prononciation) ; toutes les autres étapes sont identiques. Les éléments vidéo sont principalement générés par AI : actualités, bandes‑annonces, séquences libres de droits sont presque toutes protégées par le droit d'auteur et ne sont pas utilisées dans les vidéos éducatives. Ce skill repose sur trois piliers :

• HyperFrames (open source de HeyGen, HTML + GSAP pour produire du MP4) et ses skills officiels, notamment l'entrée /hyperframes et le workflow /faceless-explainer. La méthode à suivre est celle de la documentation officielle.
• Les règles motion-design de ce dépôt (règles de goût : easing, rythme, pauses, typographie chinoise) et review-loop (auto‑relecture avec contact sheet). L'aspect visuel doit respecter ces deux règles.
• Les outils du dossier scripts/ : ils complètent les parties que le workflow officiel ne gère pas bien : narration chinoise, sous‑titres, cohérence des polices et thème tricolore.

references/lessons.md recueille les erreurs rencontrées en pratique. À lire impérativement avant de commencer – chaque leçon a été vécue sur la première vidéo.

0. Vérification de l'environnement (lors de la première utilisation)

• Lancez d'abord python scripts/hw_check.py --project <projet> : il détecte le CPU, la mémoire, le GPU et le disque dur, puis suggère quel moteur de narration utiliser, combien de --workers paramétrer, et s'il faut répartir les sous‑agents en lots. Expliquez les recommandations à l'utilisateur en vous référant à references/hardware.md ; ces suggestions sont des estimations, pas des résultats de benchmarck.
• Node.js 22+, ffmpeg/ffprobe, Python 3 + Pillow + fonttools (pip install fonttools ; si brotli est installé, la police sera exportée en woff2, sinon en ttf).
• HyperFrames CLI : npm install -g hyperframes, puis hyperframes doctor (Docker, Whisper, Kokoro, MusicGen sont optionnels).
• Skills officiels : hyperframes skills update. Pour ce type de vidéo, il faut aussi hyperframes skills update faceless-explainer.
• Les statistiques d'utilisation anonymes sont activées par défaut ; demandez à l'utilisateur s'il souhaite les désactiver : hyperframes telemetry disable.
• TTS (choisir un, demander à l'utilisateur) :
  • edge-tts (par défaut) : pip install edge-tts, ne nécessite pas de GPU, doit être en ligne pour générer. Voix taïwanaises disponibles : zh-TW-HsiaoChenNeural (femme), zh-TW-HsiaoYuNeural (femme), zh-TW-YunJheNeural (homme).
  • Breeze TTS 2 (avancé) : nécessite un GPU NVIDIA local (environ 7.7 Go VRAM, 12 Go recommandés ; fichier modèle ~7 Go). Permet de décrire la voix avec du texte, puis de la cloner ; contrôle le plus fin de l'accent et de l'émotion.
  • Autres moteurs possibles : ils doivent pouvoir générer assets/voice/raw/NN.wav pour chaque phrase. Pour les vidéos en anglais, on peut utiliser Kokoro/HeyGen intégré à HyperFrames.

1. Recherche (avec recherche en ligne)

• Recherchez les dernières informations sur le sujet, au moins deux sources indépendantes. Notez les incohérences numériques et retenez la valeur cohérente entre les sources.
• Chaque chiffre sera classé en trois catégories, à afficher plus tard dans la vidéo : chiffre officiel / mesure ou reportage / estimation personnelle.
• Faites des calculs simples de physique ou de mathématiques pour que le spectateur puisse « vérifier par lui‑même » – c'est la partie la plus précieuse d'une vidéo pédagogique. Les estimations doivent toujours être confrontées à la réalité (exemple : « une voiture normale ne dépasse pas 1,2 g » est contredit par une voiture de série qui atteint 1,8 g en 1,8 seconde ; il faut rectifier à 1,5 g).
• N'utilisez pas de photos de marque ni de logos ; le sujet principal doit être un schéma que vous dessinez vous‑même, marqué « schéma indicatif ».
• Pendant la recherche, notez déjà les indices d'image : y a‑t‑il des « précédents », des « anciens modèles », des « photos d'expériences » qui pourraient servir de preuves (par exemple des photos historiques de la NASA, des produits similaires déjà existants) ? Ce seront les vraies photos à trouver dans la section 7.5.

2. Interview des besoins (suivre la couche d'intention de /hyperframes, poser toutes les questions en une fois)

Confirmez impérativement : la plateforme de diffusion (détermine le ratio – cours/YouTube → 16:9), la durée (recommander 60–90 secondes, la longueur de la narration détermine la durée réelle), avec ou sans narration (recommander avec), avec ou sans validation préalable du storyboard, automatisation ou ajustements progressifs.

Ajoutez trois questions sur les couleurs (nouveauté de ce skill), comme un thème de présentation :

• Couleur de fond, couleur principale (texte et traits), couleur d'accentuation (réservée aux réponses, conclusions, chiffres clés, cartes de chapitre).
• Si pas de préférence, recommander : fond noir #121212, texte blanc #F2F0EA, accent orange #FF7A1A.
• Police : une seule police pour toute la vidéo. Par défaut : GenSeki Gothic Bold (Gras, licence OFL, utilisée pour le chinois, l'anglais, les chiffres et les sous‑titres). Si l'utilisateur spécifie une police, l'utiliser mais vérifier qu'elle est libre d'utilisation.
• Les couleurs et la police sont écrites dans theme.json du projet (format dans templates/theme.example.json : bg/fg/accent/font).

Résumez les besoins en deux sections : « réponses de l'utilisateur » et « mes déductions ». Ne commencez qu'après confirmation.

3. Création du projet et storyboard

1. hyperframes init videos/<nom-en-kebab> --non-interactive --example=blank --skill=faceless-explainer, puis écrivez BRIEF.md, puis suivez les étapes 0–2 de /faceless-explainer (capture/extracted/, choisir un preset de frame pour générer frame.md).
2. Lors du choix du preset, privilégiez ceux aux traits clairs (par exemple cobalt-grid). Ce n'est qu'une « palette source » ; elle sera remplacée par les trois couleurs de l'utilisateur via theme.py.
3. Dans frame.md, ajoutez une surcharge pour le chinois traditionnel (police, graisse, espacement, interlignage, taille minimale pour projecteur), selon la section 5 de motion-design.
4. Lancez bash scripts/fetch_fonts.sh <projet> pour télécharger GenSeki Gothic Bold (depuis la release officielle GitHub), la police latine utilisée par les frame workers et Noto TC, dans assets/fonts/. Ne dépendez pas d'un chargement en ligne via Google Fonts.
5. Écrivez STORYBOARD.md et SCRIPT.md (format selon storyboard‑format / script‑format officiels). La narration doit être découpée par « proposition » : chaque virgule correspond à un moment de révélation à l'écran. Écrivez les chiffres en toutes lettres (par exemple « zéro virgule huit un seconde » en chinois) pour que le TTS ne se trompe pas.

4. Narration

1. Générez assets/voice/raw/NN.wav (un fichier par phrase, NN = numéro de case) :
   • edge-tts : python scripts/edge_tts_voice.py --project <p> --voice zh-TW-HsiaoChenNeural [--rate -5%]. Utilisez la même voix pour toute la vidéo pour une cohérence naturelle ; --list zh-TW liste toutes les voix.
   • Breeze TTS 2 : python scripts/breeze_voice.py --project <p> --breeze-repo … --model … --voice "<description vocale>" --only-ref, créez d'abord une voix de référence pour que l'utilisateur l'écoute, puis retirez --only-ref pour générer toutes les phrases (chacune copie cette voix de référence). S'il existe un runner par lot, utilisez scripts/tts_jobs.py pour générer une liste de tâches.
   • Si l'utilisateur n'a pas encore installé ou ne sait pas quoi choisir : donnez des conseils selon references/tts-setup.md, étape par étape, sans installer automatiquement.
2. Faites d'abord écouter les premières phrases à l'utilisateur ; c'est son oreille qui juge l'accent et l'émotion, pas un score. S'il n'est pas satisfait, changez de voix ou de vitesse, supprimez les anciens WAV et regénérez.
   • Si un mot est mal prononcé après la fin de la vidéo (par exemple un nom de marque anglais, un caractère polysémique) : ne réenregistrez pas toute la phrase, sinon le timing de cette case serait complètement décalé. Solution : avec la même voix, générez 4 à 6 candidats de la même phrase – on peut changer le seed ou l'orthographe (par exemple Road-ster ou des homophones), les sous‑titres restent en texte original ; placez‑les dans assets/voice/fix/cand/NN_X.wav. Puis lancez python scripts/fix_voice.py --project . audition --line N --clauses <la proposition contenant le mot>, qui concatène le segment clé en un fichier d'écoute pour que l'utilisateur choisisse à l'oreille. Une fois choisi, lancez apply --line N --take NN_X : il étirera ou comprimera la phrase entière pour qu'elle ait exactement la même durée que l'originale, égalisera le volume, recalculera les timings des sous‑titres de cette phrase, et ne modifiera pas la durée des autres cases. Ensuite : reconstruire les sous‑titres → patch_captions.py → supprimer .hyperframes/pre-theme/compositions/captions.html (sinon theme.py reprendra l'ancien) → theme.py → place_media.py → réexporter. Ne découpez pas la phrase réenregistrée en sous-propositions : les pauses ne seront pas aux mêmes endroits, les coupures tomberaient au milieu des mots, entraînant des mots manquants ou répétés (c'est arrivé en pratique). L'ASR ne sert qu'à éliminer les erreurs évidentes ; il ne détecte pas les tons faux (exemple réel : « pneu » détecté correct par l'ASR, mais faux à l'oreille de l'utilisateur).
3. python scripts/voice_meta.py --project <p> : supprime le silence initial/final, mesure la durée de chaque proposition, écrit audio_meta.json.
4. node <faceless-explainer>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md.
5. Niveau sonore : la vidéo finale doit être à environ −14 LUFS, true peak ≤ −1 dBFS. Si la narration est trop basse, appliquez un gain uniforme avec limiteur, en conservant les volumes relatifs entre phrases.

5. Conception des prises de vue (étape 4)

• Dans shots.json (cf. templates/shots.example.json), pour chaque case, écrivez « n-ième proposition → ce qui apparaît à l'écran », puis lancez python scripts/apply_shots.py --project <p> pour convertir en secondes réelles et réécrire dans STORYBOARD.md.
• Le champ blueprint doit être uniquement <id> (Adapt), <id> (Reproduce) ou compose ; les explications supplémentaires vont dans note.
• Cherchez d'abord des composants existants avec hyperframes catalog --query, puis dessinez vous‑même si rien n'est trouvé.
• Les sujets récurrents (voiture, personne, instrument) qui apparaissent dans plusieurs cases doivent d'abord être dessinés comme un SVG commun, avec des coordonnées fixes pour chaque composant ; tous les workers doivent recopier ce SVG. Sinon, le sujet aura une apparence différente à chaque case.

6. Réalisation parallèle de chaque case

1. node <faceless-explainer>/scripts/frame-packets.mjs --project <p> --storyboard <p>/STORYBOARD.md
2. Copiez templates/dispatch_context.md dans .hyperframes/frame-packets/_dispatch_context.md et remplissez les valeurs du projet : direction vidéo, ressources communes, règles temporelles, police.
3. Assignez un sous-agent à chaque case, tous en parallèle. Le prompt lit dans l'ordre : _role.md → _dispatch_context.md → le packet de la case → frame.md → ressources communes.
4. Quand deux cases adjacentes doivent montrer la même scène (par exemple une même règle graduée), la case terminée en premier transmet immédiatement ses coordonnées géométriques exactes à la case encore en cours.
5. Une fois toutes les cases terminées : python scripts/unify_frames.py --project <p>, unifie les polices et la position des lignes.

7. Assemblage, sous‑titres, palette

node <fe>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
node <fe>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json
python scripts/patch_captions.py --project .     # police et graisse des sous‑titres chinois (gras 700 par défaut)
python scripts/theme.py --project .              # applique les trois couleurs et la police du theme.json (index, chaque case, sous‑titres)
node <fe>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
node <fe>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
hyperframes lint && hyperframes check

(<fe> = dossier du skill faceless-explainer installé.) Chaque fois que les sous‑titres sont reconstruits, relancez patch_captions.py puis theme.py. Dans theme.json, le champ accents spécifie quels éléments de chaque case utilisent la couleur d'accentuation (block/fill/text) ; font remplace toutes les polices des cases et sous‑titres par une seule police et graisse, écrasant les réglages des workers. Après changement de police, les caractères peuvent devenir plus larges ; relancez hyperframes check pour vérifier les débordements ou chevauchements.

En dernier, réduisez la police : python scripts/subset_fonts.py --project .. Il ne conserve que les caractères chinois utilisés dans la vidéo (une police CJK passe de 12‑17 Mo à quelques centaines de Ko) et met à jour les @font-face de chaque case vers le fichier réduit. Toute modification ultérieure de texte, sous‑titres ou palette nécessite de relancer : theme.py part toujours des fichiers originaux (avant palette) qui pointent vers la police complète ; les nouveaux caractères non présents dans la police réduite seront remplacés par la police système.

7.5 Calque d'images (nouveauté de ce skill)

Règles complètes dans references/images.md. Points essentiels :

1. Planification : 3 à 5 images par vidéo. Les vraies photos servent de cartes preuve (« quelqu'un l'a vraiment fait »), les images générées par Codex servent d'ambiance émotionnelle pour le début et la fin. L'animation reste le corps principal ; les images ne doivent pas prendre le pas sur l'explication des principes.
2. Recherche de photos : python scripts/find_images.py search "<mot-clé>" → get "File:…" --name <nom court> --project .. Acceptez uniquement le domaine public, CC0, CC BY, CC BY‑SA ; la source est automatiquement écrite dans assets/images/web/CREDITS.md. Après téléchargement, vérifiez visuellement chaque image : rognez les passants, les logos d'autres marques, les filigranes.
3. Génération de schémas : écrivez le prompt dans gen_prompts.json (cf. templates/gen_prompts.example.json), puis lancez python scripts/codex_images.py --project .. Nécessite Codex CLI déjà connecté localement, utilise l'image_gen intégrée, pas de clé API. Après génération, vérifiez visuellement qu'aucun texte ou logo n'apparaît. Sans Codex, dites à l'utilisateur qu'il peut utiliser un autre outil ; placez les PNG dans assets/images/gen/.
4. Application de la palette : écrivez dans media.json le recadrage, la taille et le mode de chaque image (les photos en duotone, les images générées en keep), puis lancez python scripts/treat_images.py --project ..
5. Placement : examinez d'abord le contact sheet finalisé de chaque case, trouvez une zone vraiment vide, puis écrivez dans media.json le champ placements : frame, mode (card/background), box, at, label, credit. Si vous voulez remplacer un dessin vectoriel existant par une photo, utilisez hide. Ensuite, après theme.py, lancez python scripts/place_media.py --project ..
6. Marquage à l'écran : pour les photos, indiquez « Photo : Auteur · Licence · Source » ; pour les images générées, « Schéma généré par IA ».
7. Lancez hyperframes check (contraste du texte sur les photos, chevauchements), et seulement ensuite subset_fonts.py, car les légendes et les sources contiennent aussi du texte.

7.6 Calque vidéo AI (nouveauté de ce skill)

Règles complètes dans references/ai-video.md. Points essentiels :

1. Planification : 2 à 4 segments par vidéo. Utilisez‑les pour l'accroche du début, une action impossible à filmer mais qui correspond parfaitement à la narration (par exemple « on ne peut sauter qu'une fois » → une voiture qui retombe), ou pour l'émotion de fin. Les scènes nécessitant des chiffres précis ou des directions de forces restent en dessin vectoriel.
2. Première image fixe générée par Codex : générez d'abord une image statique conforme à la palette du thème (section 7.5), puis MiniMax H3 animera à partir de cette image, garantissant la cohérence stylistique.
3. Écrivez la spécification : assets/videos/gen/specs/<nom>.json (exemples dans templates/video-specs/). Chaque segment dure 4‑15 secondes, le sujet est « sans marque, sans texte », l'action est décrite comme un événement clair, avec mouvement de caméra et description sonore.
4. Génération : python scripts/ai_video.py prompt --project . (format officiel en six sections) → run (nécessite un runner dans video_config.json ; cf. templates/video_config.example.json). Sans runner, donnez à l'utilisateur le fichier prompt.txt et la première image, demandez‑lui de générer avec le template officiel MiniMax H3 R2V de ComfyUI, enregistrez sous assets/videos/gen/<nom>/clip.mp4.
5. Vérification : python scripts/ai_video.py check --project ., examinez visuellement chaque image check-1.png : déformation, apparition de pièces, texte ou logo, synchronisation temporelle avec la narration. Insatisfaisant ? changez le seed et regénérez.
6. Placement : dans media.json, dans placements, utilisez "video": "assets/videos/gen/<nom>/clip.mp4", ajoutez duration, et si nécessaire out (fondu de la carte avant la fin de la vidéo). Lancez place_media.py après theme.py, puis hyperframes lint (la vidéo doit avoir un id, ne peut pas être placée dans un élément minuté) et hyperframes check.
7. Marquage à l'écran : « Vidéo générée par IA (H3) » ; toutes les vidéos sont en silencieux, seul le son de la narration est utilisé.

8. Relecture (review-loop)

• Lancez d'abord hyperframes check, puis exportez la vidéo entière en qualité draft (hyperframes render --quality draft --workers <valeur recommandée par hw_check> ; en relecture, utilisez toujours draft). Capturez une image 0,15 seconde avant la fin de chaque proposition (pour figer l'état final), assemblez en contact sheet avec review-loop/scripts/sheet.py --video … --at …. Examinez visuellement chaque image.
• Comparez avec la checklist de references/lessons.md, corrigez, réexportez, revérifiez jusqu'à ce qu'un tour complet ne pose aucun problème.
• Ce n'est qu'après que vous exportez la version finale : hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4, puis mesurez à nouveau le niveau sonore.

9. Livraison

Fournissez : le chemin du MP4, la durée de la vidéo, une contact sheet de synthèse, et listez : les sources utilisées, quels chiffres sont des affirmations, lesquels sont des estimations, les écarts par rapport aux besoins (par exemple durée excessive), ce qui n'a pas été fait (par exemple pas de musique).