Communitygithub.com

product-explainer-video

Transformez n'importe quel projet logiciel (dépôt GitHub, dossier local, scraper, automation, bot, site Web, CLI, API ou un portfolio entier d'outils) en une vidéo explicative animée, personnalisée avec voix off, sous-titres et musique.

Qu'est-ce que product-explainer-video ?

Product Explainer Video est une compétence d'agent IA dédiée à la création de vidéos explicatives animées pour des projets logiciels. Elle analyse le code source d'un projet spécifique (dépôt GitHub, dossier local, site live, etc.) pour en extraire des faits réels, génère un storyboard personnalisé avec une métaphore visuelle unique, et produit une vidéo MP4 (paysage ou portrait) avec voix off neuronale, sous-titres SRT et un lecteur HTML intégrable. La compétence prend en charge les dépôts GitHub, les dossiers locaux, les scrapers, les bots, les APIs, les sites Web, les outils CLI et les portfolios multi-outils. Elle utilise plusieurs moteurs de synthèse vocale (ElevenLabs, OpenAI, Edge TTS) et génère de la musique libre de droits. L'utilisateur n'a pas besoin de mentionner explicitement le mot 'vidéo' : la compétence peut être invoquée pour toute demande de démonstration, promotion, 'comment ça marche', vidéo de lancement ou clip social (Reels/Shorts/TikTok/LinkedIn/X). Elle vérifie la disposition via une planche contact, s'assure que la voix off n'est jamais coupée, et ne produit jamais de template générique.

Compatible avec✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cheransanketh070-afk/claude-explainer-skill/tree/HEAD/product-explainer-video

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Vidéo Explicative de Produit

L'utilisateur pointe vers quelque chose qu'il a construit ; vous lui rendez une vidéo explicative animée et avec voix off qu'un inconnu comprend en moins d'une minute. La vidéo doit être conçue pour ce projet : sa propre métaphore visuelle, ses propres animations sur mesure. Ne produisez jamais une vidéo générique avec les noms échangés.

analyser (faits) → brief de conception → storyboard.json (scènes intégrées + personnalisées) → valider → contrôle qualité planche contact → corriger → rendu (+voix, +musique) → livrer

Les scripts se trouvent dans scripts/ à côté de ce fichier. $SK = le dossier de cette compétence (là où se trouve ce SKILL.md).

0. Vérification de l'environnement (10 secondes)

python3 -c "import playwright, PIL, numpy" && which ffmpeg && python3 $SK/scripts/voiceover.py --list

Éléments manquants : pip install playwright pillow numpy edge-tts --break-system-packages && playwright install chromium. Pas de ffmpeg → prévenir l'utilisateur (nécessaire pour MP4 ; --html-only donne quand même le lecteur HTML). Le --list de la voix off montre quels moteurs vocaux fonctionnent actuellement.

1. Comprendre ce qu'il faut expliquer

Inférer d'abord, demander rarement : le sujet (un produit, ou un portfolio), le public/objectif (développeurs sur GitHub, clients, réseaux sociaux), la source (chemin local, zip uploadé, URL GitHub, site live, ou juste une description). Valeurs par défaut : 16:9, 45–75 s, développeurs plus spectateurs curieux non techniques, voix off activée. Ne posez une question courte que si c'est vraiment ambigu (ex. 15 dépôts, aucun indice sur lequel choisir). Sinon, énoncez l'hypothèse en une ligne et allez-y. N'interviewez pas l'utilisateur.

2. Rassembler les faits (ne jamais sauter : cela garde la vidéo honnête)

python3 $SK/scripts/analyze_project.py /chemin/ou/git-url [plus...] -o facts.json
python3 $SK/scripts/capture_site.py https://leur-site.com -o site-capture     # sites live : captures d'écran + faits de page

L'analyseur affiche la description, les langages, les capacités, les vraies commandes README, les flags CLI, les routes, les domaines contactés, les sorties, les variables d'environnement, le CI/cron et les STATISTIQUES RÉELLES sûres à montrer. Lisez-le, puis lisez le README et 1 à 3 fichiers source clés vous-même lorsque les faits sont minces (quelle est la boucle principale ? que lance réellement un utilisateur ? à quoi ressemble la sortie ?). Clone échoué ou réseau coupé → demandez un zip ou le README. Capture de site bloquée → demandez des captures d'écran ou dessinez une UI avec des scènes personnalisées.

3. Brief de conception, puis le storyboard

Lisez references/narrative-playbook.md (arc, règles de véracité), references/storyboard-schema.md (tous les types/champs de scènes) et references/custom-scenes.md (comment écrire des scènes sur mesure). Les storyboards de référence dans assets/examples/ montrent ce qui est bien ; ce sont des sources d'inspiration, pas des modèles : ne réutilisez pas leur contenu, structure ou formulation.

Décidez d'abord (notez-le brièvement) :

  1. La promesse en une phrase.
  2. Ce que le produit fait physiquement (les choses qui se déplacent entre des endroits) et l'unique métaphore visuelle qui le montre.
  3. La scène du « déclic ».
  4. Le thème, la couleur d'accent (la couleur de marque de l'utilisateur si connue), le style bg, le rythme : adapté à la personnalité du produit.
  5. Quelles 2 à 4 scènes seront personnalisées (dessinées pour ce produit) et quels segments génériques utilisent des composants intégrés (titre, problème, étapes, CTA...).

Écrivez ensuite storyboard.json :

  • Arc : accroche → problème → comment ça marche → preuve de simplicité → résultat tangible → pourquoi c'est bien → CTA ; 7 à 10 scènes, 45–75 s.
  • Niveau de qualité : au moins une scène est personnalisée sauf si le produit est vraiment un simple CLI ; la scène du déclic est toujours personnalisée ou un composant intégré soigneusement choisi. Un bot montre une conversation ; un scraper montre une page devenant des lignes ; une API montre une requête et une réponse ; un tableau de bord montre des chiffres en direct.
  • narration sur chaque scène : style parlé, 15–35 mots. Elle devient la voix off, les sous-titres et le SRT.
  • Vérité uniquement : les commandes, flags, fonctionnalités, routes et chiffres proviennent des faits ou de l'utilisateur. La sortie du terminal et les lignes du tableau peuvent être illustratives mais génériques ; n'inventez jamais de benchmarks, de nombres de clients ou de capacités. Les scènes de statistiques n'utilisent que les STATISTIQUES RÉELLES/READ ME/chiffres de l'utilisateur.
  • Définissez meta.url sur le dépôt/site et terminez par un CTA clair.

4. Valider, puis regarder avant le rendu

python3 $SK/scripts/storyboard.py explicateur/storyboard.json
python3 $SK/scripts/render_video.py explicateur/storyboard.json --contact-sheet

La planche contact (~20 s) exécute l'audit de mise en page (texte hors scène, coupé, tronqué, en collision avec les sous-titres, et erreurs JS des scènes personnalisées) et écrit explicateur-output/contact-sheet.png. Regardez-la et vérifiez : rien n'est à l'étroit ou coupé, le texte est lisible, les scènes sont visiblement différentes les unes des autres, les scènes personnalisées semblent intentionnelles. Une planche contact montre une image tardive par scène, donc pour chaque scène personnalisée, inspectez aussi une image précoce et une intermédiaire : --still 3.2,6.5. Corrigez et répétez jusqu'à ce que ce soit propre.

5. Rendu avec voix off

cd explicateur
setsid nohup python3 $SK/scripts/render_video.py storyboard.json --quality final --gif \
  > render.log 2>&1 < /dev/null &
sleep 100; tail -c 300 render.log

Continuez à interroger (sleep 100; tail -c 300 render.log) jusqu'à TERMINÉ. Dans les environnements cloisonnés (claude.ai), le travail en arrière-plan progresse uniquement pendant l'exécution d'un appel d'outil, donc la boucle d'interrogation fait avancer le rendu ; ne terminez pas votre tour pendant qu'il tourne. Préréglages : draft (960×540, 15 ips), standard (1280×720, 30 ips, défaut), final (1920×1080, 30 ips). Plus de cœurs CPU → plus rapide (--workers N). Vertical : meta.aspect: "9:16" ou --vertical. Machine lente : --fps 24.

La voix off est automatique (--voice auto, défaut). Le rendu génère un fichier audio par scène, étire les scènes pour que la narration ne soit jamais coupée, réduit la musique sous la voix et met en cache l'audio pour que les re-rendus soient gratuits. Priorité du moteur : ElevenLabs (ELEVENLABS_API_KEY) → OpenAI TTS (OPENAI_API_KEY) → Edge neural voices (pip install edge-tts, gratuit, pas de clé, nécessite internet) → Piper (hors ligne neuronal) → macOS say → espeak-ng. Options : --voice-name fr-FR-DeniseNeural (nom de voix de n'importe quel moteur), --voice-rate +8% (Edge), --voice none pour musique uniquement, --voice-dir dossier/ pour utiliser vos propres fichiers scene-01.mp3…, meta.voice pour stocker le choix dans le storyboard.

Si le rendu affiche ATTENTION voix off : aucun moteur vocal disponible, la vidéo est quand même rendue (musique uniquement) et voiceover.txt contient le script. Dites-le clairement à l'utilisateur, avec la correction en une ligne : activez internet et pip install edge-tts (gratuit), ou définissez une clé API, ou installez espeak-ng ; puis relancez la même commande (seuls la voix et l'encodage sont refaits ; le lecteur et le storyboard sont inchangés). Dans claude.ai, le bac à sable n'a généralement pas internet, donc attendez-vous à cela : dites-le, livrez la vidéo muette avec musique et le script, et expliquez qu'ils peuvent ajouter la voix en exécutant le pipeline localement dans Claude Code ou avec une clé API. Ne prétendez jamais que la vidéo a une voix off sauf si le journal dit voix off : utilisation de '<moteur>'.

Musique : générée libre de droits (--mood calm|upbeat|tech ou meta.music_mood) ; --music none ou --music file.mp3.

6. Livrer

Sorties dans explicateur-output/ : <nom>.mp4, <nom>-poster.png, player.html (lecteur interactif autonome ; intégrez avec <iframe src="player.html?embed"> ; il a du mouvement et des sous-titres mais pas d'audio), captions.srt, voiceover.txt, storyboard.resolved.json, voice/, .gif optionnel.

Vérifiez : ffprobe -v error -show_entries stream=codec_type -of csv=p=0 <nom>.mp4 montre un flux audio ; la durée correspond ; regardez le poster. Copiez les livrables dans /mnt/user-data/outputs/ et present_files avec le MP4 en premier, puis le poster, les sous-titres, player.html et storyboard.json (afin qu'ils puissent éditer et refaire le rendu). Gardez le message court : une ligne par scène, ce qui a été supposé, quel moteur vocal a été utilisé, comment modifier. Proposez des variantes uniquement si utile : un clip social 9:16 (~30 s), une voix ou couleur de marque différente, une vidéo pour un autre dépôt.

Édition et re-rendu

Modifiez storyboard.json (texte, ordre, couleurs, code de scène personnalisée), relancez la planche contact, puis le rendu. Les changements de narration ne re-synthétisent que les scènes modifiées. Définissez la duration d'une scène pour l'allonger ; elle n'est jamais raccourcie en dessous de ce dont l'animation et la narration ont besoin.

Portfolio / « tous mes outils »

Analysez tous les dépôts en un seul appel, choisissez 3 à 4 produits phares qui montrent la diversité, donnez à chacun une scène personnalisée ou la mieux adaptée avec sa propre métaphore visuelle, terminez par une grille features du reste et un CTA vers le profil. Proposez ensuite des vidéos approfondies par produit.

Dépannage

  • Playwright n'est pas installé → commande de l'étape 0.
  • Images noires/vides ou lignes scene error → le JS d'une scène personnalisée a levé une exception ; l'audit affiche l'exception. Corrigez le code.
  • Texte coupé/tronqué → raccourcissez, supprimez des éléments ou faites une mise en page personnalisée.
  • Voix robotique → c'est espeak ; utilisez Edge/OpenAI/ElevenLabs/Piper à la place.
  • La voix ne correspond pas au timing de la scène → le timing est automatique (les scènes s'étirent pour l'audio) ; si les sous-titres semblent en avance, raccourcissez la narration.
  • Le journal ne bouge pas / le rendu est tué → il a été lancé attaché ou rien ne l'a interrogé ; relancez en détaché et interrogez.
  • Sortie trop longue → supprimez les scènes les plus faibles ; le validateur avertit au-dessus de ~90 s.

Limites honnêtes

Graphiques animés (diagrammes, terminaux, code, maquettes UI, animation sur mesure), pas d'enregistrements d'écran ni de séquences photoréalistes. Pour une vraie UI, passez des captures d'écran ou dessinez l'interface. La qualité de la voix dépend du moteur disponible.

Skills associés