Demo Narrator
Pipeline : images → comprendre → brouillon de script → ⛔ VALIDATION UTILISATEUR → SFX + TTS → rendu → vérification.
Sortie : output_final.mp4 (H.264/AAC, -16 LUFS, sous-titres incrustés) + subtitles.srt.
SKILL="<chemin absolu du répertoire contenant ce SKILL.md>" # ex. ~/.claude/skills/demo-narrator ou ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
Résolvez SKILL une fois au début (cela dépend de l'endroit où le skill a été installé) et utilisez ensuite des chemins absolus.
0. Pré-vol
- Si
$PYn'existe pas, dites à l'utilisateur que l'installation ajoute ffmpeg + espeak-ng (Homebrew/apt), un environnement virtuel Python 3.12, PyTorch et environ 400 Mo de poids de modèles ; sur un oui, exécutezbash "$SKILL/setup.sh"(prend quelques minutes ; lancez-le en arrière-plan). - Choisissez un répertoire de travail à côté de la vidéo :
WORK="<répertoire vidéo>/demo-narrator-work/<nom vidéo>". N'écrivez jamais dans le répertoire du skill. - Demandez (un seul message, seulement ce qui est inconnu) : nom du produit + ce qu'il fait, public, ton (par défaut : amical, confiant, concis), préférence vocale (par défaut
af_heart) et tout ce qui doit être dit (CTA, URL). Ne bloquez pas si l'utilisateur a déjà dit « vas-y » — déduisez des images.
1. Extraire les images + vérifier la durée
"$PY" "$SKILL/scripts/extract_frames.py" "<video>" --out "$WORK"
- Affiche la durée/résolution, échantillonne 1 image / 2 s, détecte les changements de scène, construit des planches de contact 3×3.
- Refuse les vidéos de moins de 3 s ou de plus de 15 min (
--force/--max-durationpour ignorer ; utilisez--interval 4pour les longues vidéos). - Examinez d'abord
$WORK/sheets/*.jpg(chacune est étiquetée avec les timestamps). Ouvrez les$WORK/frames/*.jpgindividuelles uniquement là où vous avez besoin de détails (petit texte d'interface, moment exact d'un clic). $WORK/frames.json→duration,scene_changes(meilleurs endroits pour les whoosh), liste d'images.
Construisez une liste des moments clés : ce qui est à l'écran à chaque instant, quelles actions se produisent (clic, saisie, changement de page, état de réussite) et ce que le spectateur doit retenir.
2. Brouillon $WORK/script.json
{
"video": "/chemin/abs/vers/ma-demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Découvrez Relay, le moyen le plus rapide de transformer vos appels clients en tickets."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Importez un enregistrement, et Relay extrait pour vous chaque bug, demande et suivi."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
Règles de timing
- Budget de mots par segment ≈
(end − start) × 2.5mots (Kokoro ≈ 150 mots/min à vitesse 1.0). Restez en dessous. - Laissez ≥ 0.3 s entre les segments ; commencez la première ligne vers 0.3-0.8 s ; laissez la vidéo respirer après les grands moments.
- Ancrez
startau moment où la chose décrite apparaît, pas avant. La narration peut précéder une action d'environ 0.3 s. - Les segments ne doivent pas dépasser la vidéo ; le dernier segment doit se terminer ≥ 1 s avant la fin de la vidéo.
Écrire pour l'oreille
- Conversationnel, deuxième personne (« vous »), contractions, verbes actifs. Une idée par segment.
- Décrivez le bénéfice de ce qui se passe, pas les pixels. Jamais « Ici nous voyons… » ou « Comme vous pouvez le voir… ».
- Épelez les mots comme ils doivent être dits : « deux-x plus rapide », « A-P-I » seulement s'il faut l'épeler, « point com ». Évitez les symboles, emoji, URL avec barres obliques et parenthèses.
- Phrases courtes. Terminez par un CTA clair si l'utilisateur en a donné un.
SFX (whoosh, whoosh_soft, pop, click, ding) — at est le temps absolu de la vidéo.
whooshlors des transitions de page/écran (utilisezscene_changes),whoosh_softpour les panneaux/modales qui glissent,poppour les éléments/toast qui apparaissent,clickpour les pressions de boutons importantes,dingpour le succès/achèvement.- Retenue : environ 1 signal par 4-6 s maximum. N'empilez pas les signaux à moins de 0.3 s. Niveau par défaut -9 dB sous la voix ; définissez
gain_db(ex. -14) pour les signaux subtils.
Voix (Kokoro) : af_heart (US féminine chaleureuse, par défaut), af_bella, am_michael / am_fenrir (US masculin), bf_emma (UK féminine), bm_george (UK masculin). Les autres voix se téléchargent une fois à la première utilisation.
3. ⛔ Validation du script — obligatoire
Ne générez aucun audio tant que l'utilisateur n'a pas explicitement approuvé le script.
-
Présentez le script sous forme de tableau et arrêtez-vous :
# Temps Mots / budget Narration SFX 1 0:00.4–0:04.6 11 / 10 ⚠ Découvrez Relay, … — Signalez les segments au-dessus du budget avec ⚠. Mentionnez la voix + la durée totale de la narration. Terminez par : « Approuvez ce script, ou dites-moi ce qu'il faut changer. »
-
Terminez votre tour et attendez. Le silence, « ça a l'air bien ? », ou l'approbation d'une version antérieure n'est pas l'approbation de celle-ci.
-
En cas de modifications : mettez à jour
script.json, re-présentez les lignes modifiées, attendez à nouveau. -
Seulement après un oui explicite (« approuve », « oui », « go », « c'est parti ») pour le texte actuel, apposez le cachet :
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approveLe cachet est un condensé du texte de narration.
generate_tts.pyetrender_video.pyrefusent de s'exécuter sur un script non cacheté ou si un texte a changé après le cachetage — vous devez repasser par cette validation. Ne définissez jamaisapproved/approved_digestà la main. Les modifications de timing (start/end) et desfxne nécessitent pas de re-validation.
4. Générer SFX + voix off
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS écrit
$WORK/audio/seg_###.wav+tts.json. Moteur : Kokoro, repli automatique sur Piper (--engine piperpour forcer). - Chaque clip est ajusté à son créneau (jusqu'au début du segment suivant) ; les dépassements sont re-synthétisés plus rapidement jusqu'à
--max-speed 1.25. - Si le tableau montre encore
OVER, préférez déplacerstart/endou les segments suivants (pas de re-validation nécessaire). Si le texte doit être raccourci, c'est un changement de texte → retour à la validation. - Re-faire des segments individuels :
--only 3 5. Variation différente des SFX :--seed 7.
5. Rendu
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- Place les clips à leur
start, sans chevauchement ; les petits dépassements reçoivent une compressionatempopréservant la hauteur (≤ 1.12×), le reste décale les clips suivants (imprimé comme dérive). Maintient la dernière image si la narration dépasse la vidéo. - Mélange voix + SFX, normalise le volume à -16 LUFS, grave les sous-titres (cartes rendues par Pillow +
overlayFFmpeg, donc pas besoin de libass), écrit$WORK/output_final.mp4etsubtitles.srt. - Musique de fond optionnelle (originale, synthétisée localement, sans licence) :
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <secondes vidéo> --out "$WORK/bgm.wav"(styles :positive(par défaut) = guitare acoustique en doubles-croches avec cordes à vide résonnantes, accord chaleureux à chaque temps, grosse caisse 4/4, rim/claps syncopés, basse contre-temps, lead pincé doux, 111 BPM, break au milieu, modelé sur une référence de démo B2B ;demo-bright/demo-dorian= groove de démo SaaS modelé sur des pistes de démo produit standard : 110 BPM, accords chaleureux pulsant sur les croches et pompant avec une grosse caisse douce, claps sur 2 et 4, charleston en croches, basse sur les fondamentales, ligne tenue en haut, mélodie légère pincée, intro → groove → break de 8 mesures au milieu → groove → fin propre ;uke,marimba,pluck,kalimba= fonds lumineux pour démos logicielles, un motif pincé/marteau sur un rythme simple grosse caisse douce + claquement/clap + shaker et un peu de basse, 100-112 BPM, tonalité majeure ;lofi(par défaut) = rythme chill balancé avec batterie ;keys= piano électrique ;upbeat= 4/4 + arpège ;ambient= nappe seulement.--bpm,--key(styles brillants),--mood(autres),--seed Npour une variation). Faites des prévisualisations de 30-40 s avec--duration 40et laissez l'utilisateur choisir avant de tout rendre, puis rendez avec--bgm "$WORK/bgm.wav".--bgmaccepte aussi une piste fournie par l'utilisateur (mp3/m4a/wav) : elle est automatiquement nivelée à la même référence, bouclée avec un fondu enchaîné de 2.5 s si plus courte que la vidéo, et fondue à la fin. Demandez à l'utilisateur de confirmer qu'il a les droits sur toute piste qu'il fournit. La musique s'auto-atténue sous la voix ; ajustez avec--bgm-db(par défaut -2.5) et--duck-db(par défaut -5). - Options utiles :
--out <chemin>,--orig-volume 0.15(conserver l'audio original en sourdine),--sfx-gain-db -12,--no-subs(écrit quand mêmesubtitles.srt; à utiliser quand la vidéo a déjà des sous-titres à l'écran près du bas),--font <ttf>,--font-scale 0.05,--crf 20.
6. Vérifier avant de signaler
- Vérifiez la sortie du rendu : colonne de dérive ~0, pas d'avertissement de maintien d'image (ou expliquez-le).
- Vérifiez les sous-titres :
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"à 2-3 milieux de segments, puis visualisez les images — légendes lisibles, ne couvrant pas l'interface clé. Si elles couvrent quelque chose d'important, envisagez--font-scaleou informez l'utilisateur. - Rapportez : chemin de sortie, durée, moteur/voix utilisé, segments accélérés ou décalés, et comment ajuster (éditer
script.json→ relancer les étapes 4-5 ; les modifications de texte repassent par la validation).
Dépannage
| Symptôme | Correction |
|---|---|
kokoro unavailable … trying fallback | Relancez setup.sh ; vérifiez que Python est 3.10-3.12 dans .venv. La sortie Piper est correcte mais moins naturelle. |
| Mot / nom mal prononcé | Ré-écrivez phonétiquement dans text (ex. « Kubernetes » → « kou-ber-né-tiz »), obtenez l'approbation, régénérez ce segment avec --only. |
| Voix pressée | Réduisez speed à 0.95, élargissez les fenêtres de segments ou réduisez les mots. |
| Sous-titres trop petits/grands | --font-scale 0.035–0.06. |
| Mauvaises couleurs / bégaiement VFR | Ajoutez --fps 30. |
| La vidéo a de la musique à conserver | --orig-volume 0.12–0.2. |
Tout s'exécute hors ligne après le téléchargement unique des modèles. Licences : Kokoro-82M Apache-2.0, Piper GPL-3.0 (piper-tts ≥1.3), voix selon la fiche du modèle, FFmpeg LGPL/GPL.