Communitygithub.com

demo-narrator

Transformez une démonstration silencieuse ou un enregistrement d'écran en une vidéo commentée avec une voix naturelle, des effets sonores, une musique de fond optionnelle et des sous-titres – le tout localement et gratuitement.

Qu'est-ce que demo-narrator ?

Ce skill transforme une vidéo de démonstration ou un enregistrement d'écran en une vidéo commentée professionnelle, entièrement en local. Il extrait les images clés, vous aide à rédiger un script narratif, puis génère une voix naturelle (via Kokoro-82M TTS avec repli Piper), des effets sonores (whoosh, pop, click, ding) et une musique de fond optionnelle avant de rendre la vidéo finale avec sous-titres incrustés. Une étape d'approbation du script est obligatoire avant toute génération audio, ce qui évite les allers-retours coûteux. Toutes les étapes s'exécutent hors ligne, sans clé API ni service payant, ce qui le rend idéal pour les développeurs souhaitant ajouter rapidement une narration à des démos logicielles ou des enregistrements de produits dans un flux de travail 100% local.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

Demander à votre IA préférée

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

Documentation

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

  1. Si $PY n'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écutez bash "$SKILL/setup.sh" (prend quelques minutes ; lancez-le en arrière-plan).
  2. 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.
  3. 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-duration pour ignorer ; utilisez --interval 4 pour les longues vidéos).
  • Examinez d'abord $WORK/sheets/*.jpg (chacune est étiquetée avec les timestamps). Ouvrez les $WORK/frames/*.jpg individuelles 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.5 mots (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 start au 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.

  • whoosh lors des transitions de page/écran (utilisez scene_changes), whoosh_soft pour les panneaux/modales qui glissent, pop pour les éléments/toast qui apparaissent, click pour les pressions de boutons importantes, ding pour 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.

  1. Présentez le script sous forme de tableau et arrêtez-vous :

    #TempsMots / budgetNarrationSFX
    10:00.4–0:04.611 / 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. »

  2. 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.

  3. En cas de modifications : mettez à jour script.json, re-présentez les lignes modifiées, attendez à nouveau.

  4. 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" --approve
    

    Le cachet est un condensé du texte de narration. generate_tts.py et render_video.py refusent 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 jamais approved/approved_digest à la main. Les modifications de timing (start/end) et de sfx ne 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 piper pour 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éplacer start/end ou 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 compression atempo pré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 + overlay FFmpeg, donc pas besoin de libass), écrit $WORK/output_final.mp4 et subtitles.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 N pour une variation). Faites des prévisualisations de 30-40 s avec --duration 40 et laissez l'utilisateur choisir avant de tout rendre, puis rendez avec --bgm "$WORK/bgm.wav". --bgm accepte 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ême subtitles.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

  1. Vérifiez la sortie du rendu : colonne de dérive ~0, pas d'avertissement de maintien d'image (ou expliquez-le).
  2. 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-scale ou informez l'utilisateur.
  3. 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ômeCorrection
kokoro unavailable … trying fallbackRelancez 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éeRé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 VFRAjoutez --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.

Skills associés