lanceriedel/narrated-demo-skill

Démo commentée

Un agent, un après-midi, un .mov qu'un VP peut regarder sur son téléphone. La recette (testée sur cinq clips, 69–188 s chacun) :

1. Interviewer l'utilisateur — cinq questions, pas plus (ci-dessous). Rédigez l'histoire à partir du contexte que vous avez déjà ; l'utilisateur édite, n'écrit pas.
2. Écrire un scénario (clips/<nom>.yaml) : 4 à 8 scènes, ~25–45 mots de narration chacune (≈ 10–18 s parlées). Chaque scène a un point culminant — le moment où la chose apparaît — et la vidéo est montée pour que le point culminant apparaisse tôt, pas à la fin.
3. Rendre : scripts/render_clip.py clips/<nom>.yaml. Par scène : TTS → capture → caler la vidéo sur l'audio → sous-titrer → multiplexer ; puis concaténer.
4. Réviser les images fixes que le rendu écrit (out/_<clip>_<scene>.png) avec l'outil read avant de déclarer terminé. Re-rendre une seule scène avec --only s2.
5. Publier (optionnel) : scripts/slack_post.py <channel_id> out/<clip>.mov "<description>".

Tout est ré-exécutable et mis en cache (TTS par hash du texte, vidéo par scène), donc itérer sur une phrase ne coûte que quelques secondes.

1. L'interview (posez ces questions, puis rédigez)

Posez les cinq questions en un seul message ; acceptez les réponses partielles et complétez le reste à partir du contexte, en étiquetant ce que vous avez supposé.

1. À qui est-ce destiné, et combien de temps ont-ils ? (ingénieur pair 3 min · cadre 90 s · défilement Slack 60 s) → détermine le nombre de scènes et le rythme.
2. Quelle est la seule chose qu'ils doivent croire après avoir regardé ? → devient la première phrase de la scène 1 et la dernière phrase de la dernière scène.
3. Que doit-on voir à l'écran ? (une interface, un terminal, un document, un graphique, un fichier) → détermine les types de capture. Demandez les URLs / commandes / chemins.
4. Quel est le moment « vivant » ? Quelque chose qui se passe visiblement (une requête qui revient, une compilation qui se termine, un nombre qui apparaît). Au moins un par clip.
5. Voix et ton ? Par défaut : onyx, « narration de démo technique calme, claire, confiante, rythme moyen, léger accent sur les nombres ». Proposez alloy/nova s'ils veulent quelque chose de plus léger.

Ensuite, proposez le storyboard sous forme de tableau (scène · ce qui est à l'écran · résumé de la narration en une ligne · point culminant) et obtenez un accord avant de lancer le rendu. Le rendu d'un clip de 5 scènes prend ~3–6 min ; ne lancez pas le rendu sans l'accord.

2. Spécification de scène

clip: 1-setup                 # nom de sortie → out/1-setup.mov
taille: 1440x900               # optionnel : taille commune pour toutes les scènes (fit + padding) — à définir quand on mélange des scènes d'écran et de navigateur
voice: onyx
instructions: "Narration de démo technique calme, claire, confiante. Rythme moyen, pauses naturelles aux points. Léger accent sur les nombres."
scenes:
  - id: s1                    # identifiants courts et stables → clés de cache
    caption: "Thèse · un graphique, quatre preuves"     # tiers inférieur ; ≤ 60 caractères
    narration: "…25–45 mots…"                        # écrivez les nombres en lettres si le TTS les déforme ("dix-huit mille")
    # exactement une source de capture par scène :
    url: "http://127.0.0.1:4300/#mode=purchase"       # (a) navigateur via Playwright — plus des actions optionnelles :
    actions:                                          #     exécutées après le chargement, dans l'ordre ; `ready` marque le point culminant
      - fill: ["#prompt", "Acne Studios"]
      - press: ["#prompt", "Enter"]
      - wait: ".layer-chip"                           #     sélecteur (timeout 45 s) → définit ready
      - click: "button:has-text('fit')"
      - select: ["#graph-layout", "marque"]
      - scroll_to: "#join"                            #     scrollIntoView (pour les longs documents) → définit ready
      - hover: ".card"
    # video: "cache/cr_s3"                            # (b) répertoire pré-enregistré (page.mov + marks.json) ou un fichier — voir record_screen.sh
    # still: "docs/figure.png"                        # (c) une image statique (graphique, diapositive) — sans Ken-Burns, maintenue pour la narration
    hold: 2                                           # secondes supplémentaires après la dernière action
    speed: 1                                          # pré-accélérer la source (8 = un lent défilement montré à 8×)
    scale: 2560                                       # largeur de sous-échantillonnage par scène (captures d'écran) ; font: 28 = taille de la légende en px pour cette scène

Règles qui ont fait la qualité des clips :

• Le point culminant en premier. Le rendu commence chaque scène ~2,5 s avant ready, prolonge la dernière image si la narration est plus longue, rogne si elle est plus courte. Une scène dont le point culminant est à la seconde 40 d'un enregistrement de 45 s devient une scène de 12 s qui s'ouvre sur le point culminant.
• La narration et l'écran s'accordent. Chaque nom en capitale et chaque nombre dans la narration doivent être visibles ou sur le point de l'être. Coupez les phrases qui ne le sont pas.
• Une idée par scène. Si une phrase commence par « aussi », c'est une nouvelle scène ou elle est coupée.
• Les sous-titres sont le plan. Lire uniquement les sous-titres doit donner toute l'histoire.
• N'inventez jamais un nombre pour la narration. Prenez-le à partir d'un fichier de résultat ou d'une réponse en direct que vous venez de faire ; dites « environ » si arrondi.

3. Sources de capture

• Navigateur (url + actions) — Playwright Chromium, 1440×900, sans tête, enregistre au format webm. Nécessite un projet Node avec @playwright/test et Chromium installé ; définissez PW_REPO=/chemin/vers/ce/projet (par défaut : le propre dossier pw/ de la compétence — exécutez scripts/setup.sh une fois pour le créer).
• Écran / terminal (video) — scripts/record_screen.sh <scene> <seconds> [--rect x,y,w,h] -- <commande…> : lance screencapture -V, exécute votre commande, écrit marks.json avec started (ms) lorsque la commande signale le point culminant en imprimant MARK. Piège : screencapture -V n'avance que lorsque les pixels changent ; un terminal statique figera l'enregistrement. Gardez quelque chose qui tourne (une ligne d'horloge à 1 Hz) ou utilisez show_file.sh qui affiche un fichier avec une horloge. Sous-échantillonnez les captures larges avec DEMO_SCALE=2560. Confidentialité : enregistrez un rectangle (--rect, en points ; screencapture -R) pour ne capturer que le volet souhaité — pas de titre de fenêtre, barre d'onglets, barre latérale, dock, notifications ni fenêtres d'arrière-plan. Avant de publier, lisez chaque image de révision et demandez : y a-t-il quelque chose à l'écran qui identifie un employeur, un hôte, une URL interne, une autre personne ? Neutralisez le texte que vous affichez (show_file.sh) — c'est la démo, pas vos fichiers réels.
• Image fixe (still) — un PNG/JPG maintenu pendant la narration ; utilisez pour les graphiques, tableaux, diapositives.
• Pré-enregistré (video: file.mov) — avec ready: <secondes> dans la scène.

4. Rendu, révision et publication

export OPENAI_API_KEY=…                     # TTS (gpt-4o-mini-tts) ; ou TTS_URL=https://<proxy>/v1/audio/speech TTS_API_KEY=… pour un proxy compatible
scripts/render_clip.py clips/1-setup.yaml            # clip complet → out/1-setup.mov (+ images fixes out/_1-setup_<scene>.png)
scripts/render_clip.py clips/1-setup.yaml --only s2  # re-rendre une seule scène, re-concaténer
DEMO_FONT=26 scripts/render_clip.py …                # taille des sous-titres (22 pour 1440 px, 26–30 pour les sources 2560 px)

Révision : read deux ou trois images fixes out/_*.png. Si une scène navigateur enregistre wait failed: … Timeout, l'application était lente ou le sélecteur a changé : la scène est tout de même rendue à partir de t=0 (pas de coupe du point culminant) — corrigez le sélecteur ou relancez simplement cette scène avec --only <id> lorsque l'application est inactive (image d'ouverture de chaque scène) — vérifiez que le sous-titre est lisible, que le point culminant est à l'écran, et qu'aucune information sensible n'est visible (jetons, lignes de niveau acheteur, messages d'autres personnes). Regardez les 5 premières et 5 dernières secondes du .mov si possible.

Publiez sur Slack avec une description de ≤ 3 lignes : ce qu'elle montre · durée · un nombre. scripts/slack_post.py C0123… out/1-setup.mov "…" utilise les identifiants de session navigateur slack-mcp dans ~/.config/slack-mcp/credentials.json ; si absent, remettez le fichier et la description à l'utilisateur.

5. Conventions (gardez le projet propre)

clips/ spécifications · cache/ TTS + vidéo par scène (gitignoré) · out/ fichiers finaux + images fixes · blurbs/ textes Slack. Nommez les clips dans l'ordre de lecture (0-…, 1-…, 2a-…). Conservez un storyboard.md avec le tableau de l'interview ; c'est l'artefact que les gens demandent après la vidéo.

Dépendances : ffmpeg/ffprobe, node ≥ 18, Playwright Chromium (pour les scènes navigateur), screencapture macOS (pour les scènes d'écran), une clé TTS. scripts/setup.sh vérifie et installe ce qu'il peut.