belwo-claude-skills (enregistrement de démonstration vidéo)

Créer une vidéo de démonstration commentée

Vous écrivez un fichier de scènes : chaque scène est un morceau de narration plus les clics qui se produisent pendant qu'elle se joue. Les scripts transforment la narration en parole, pilotent l'application dans un Chromium sans tête à une résolution fixe de 1600×900 tout en capturant l'écran, et construisent un MP4 avec la voix off et des sous-titres incrustés. Un curseur visible, des ondulations de clic, des anneaux de surbrillance et des cartes de titre sont ajoutés par-dessus la page.

Toutes les commandes ci-dessous utilisent PY, qui signifie python sur Windows et python3 sur macOS, et DV, qui signifie "${CLAUDE_SKILL_DIR}/scripts/demo_video.py". Chaque commande affiche des lignes de statut simples (SCÈNE …, ENREGISTRÉ …, VÉRIFICATION OK, ERREUR …) ; il faut les lire plutôt que de deviner.

1. Configuration (une fois par machine)

PY "${CLAUDE_SKILL_DIR}/scripts/setup_env.py"

Il crée un environnement privé dans ~/.claude-demo-video avec Playwright, Chromium et edge-tts, puis vérifie ffmpeg. Il se termine par PRÊT, ou exactement par ce qui manque. ffmpeg est un outil système : demandez à l'utilisateur avant de l'installer (winget install --id Gyan.FFmpeg -e sur Windows, brew install ffmpeg sur macOS). Les scripts cherchent également dans les dossiers d'installation habituels (WinGet, Chocolatey, Scoop, Homebrew). Si ffmpeg est ailleurs, définissez DEMO_VIDEO_FFMPEG_DIR sur son dossier pour chaque commande.

2. Se mettre d'accord sur la vidéo avec l'utilisateur avant d'écrire quoi que ce soit

Demandez, ou confirmez à partir du contexte :

• Qui la regardera et pourquoi (un évaluateur approuvant une fonctionnalité, un client, un nouveau collègue). Cela définit le ton et ce qu'il faut expliquer.
• Quoi montrer, dans quel ordre. Proposez une liste de scènes avec une ligne chacune et obtenez un oui. Visez 3 à 8 minutes.
• Voix. La voix par défaut est une voix anglaise naturelle neuronale (edge-tts). Dites à l'utilisateur que le texte de narration est envoyé au service vocal de Microsoft pour générer l'audio. Il ne doit contenir que des explications de fonctionnalités, jamais de données. L'alternative est la voix système hors ligne (--offline) : rien ne quitte la machine, mais elle sonne robotique.
• Données. Enregistrez uniquement des données de démonstration : personnes fictives, adresses email @example.com, projets clairement factices. N'enregistrez jamais de véritables enregistrements clients ou employés, et ne pointez jamais l'enregistreur vers la production.

3. Préparer l'application

• L'application doit être en cours d'exécution et accessible depuis cette machine, généralement une build locale.
• Si les écrans ont besoin de données, écrivez un script de peuplement et un script de nettoyage correspondant pour les données de démonstration, et exécutez le script de peuplement. Étiquetez les lignes de démonstration (par exemple des ID commençant par DEMO-) afin que le nettoyage ne puisse pas toucher à autre chose.
• Assurez-vous que les e-mails sortants et les notifications sont désactivés, ou qu'ils vont uniquement vers des adresses factices, car la visite guidée clique sur de vrais boutons (soumettre, approuver…).
• Les scènes qui modifient des données (approuver, supprimer) ne peuvent être enregistrées qu'une fois par script de peuplement. Repeuplez avant chaque reprise.

4. Écrire le fichier de scènes

Créez-le dans le projet de l'utilisateur, par exemple demo-videos/<nom>.py, jamais dans le dossier de la compétence. Commencez par ${CLAUDE_SKILL_DIR}/reference/scenes-template.py. Pour un exemple réel complet, voir ${CLAUDE_SKILL_DIR}/reference/zentrio-timesheet-example.py, qui a réalisé une vidéo d'approbation de 6 minutes.

CONFIG = {'url': 'https://localhost:7101/MyTimesheet', 'ready': '#tsCards .tsw-card', 'sign_in': True}

async def week(r):
    await r.click('.tsw-row:has-text("Approval screen")')
    await r.spot('.tsw-panel', 3)

SCENES = [
    ('week', "Cliquez sur une ligne de tâche et le panneau de journal s'ouvre juste en dessous.", week),
]

• CONFIG['url'] est la première page. ready est un sélecteur qui n'est visible qu'une fois cette page chargée et connectée. C'est ainsi que l'enregistreur sait que la connexion a fonctionné.
• Narration : une à trois courtes phrases parlées par scène. Expliquez pourquoi quelque chose est important, pas seulement ce qui est à l'écran. Écrivez les nombres et symboles comme ils doivent être prononcés ("deux virgule trois zéro"). Ne mettez pas de données dans la narration.
• Les actions s'exécutent pendant que leur narration est jouée. Gardez-les plus courtes que la narration ; l'enregistreur attend que la narration se termine avant de commencer la scène suivante.

Aides de scène (r est l'enregistreur ; tout le reste est disponible comme r.page, la page Playwright) :

Aide	Fait
await r.goto('/chemin', wait_for=sel)	ouvrir une page (relative à CONFIG['url'])
await r.click(cible, dx=.5, dy=.5)	déplacer le curseur visible là-bas et cliquer ; dx/dy choisissent le point à l'intérieur de l'élément
await r.move_to(cible)	déplacer le curseur sans cliquer
await r.type(cible, 'texte')	cliquer sur un champ et taper du texte dedans visiblement
await r.select(cible, valeur)	choisir une option de liste déroulante
await r.press('ControlOrMeta+K')	raccourci clavier (Ctrl sur Windows, Cmd sur macOS)
await r.spot(cible, secondes, pad)	anneau de surbrillance orange
await r.card(chapeau, titre, lignes, puces) / await r.uncard()	carte de titre plein écran (introduction, résumé, conclusion)
await r.confirm_click(cible, show=4)	pour les boutons qui appellent confirm() : affiche une boîte de dialogue factice, puis accepte
await r.download(cible)	cliquer sur un téléchargement et retourne le chemin du fichier sauvegardé
await r.show_file(chemin)	montrer un fichier local, par exemple un aperçu HTML que vous avez créé d'un rapport téléchargé
await r.scroll_top(), await r.scroll_x(selecteur, px)	défilement fluide
await r.clear_toasts(selecteur)	supprimer les notifications toast qui couvrent les boutons
await r.wait(secondes)	pause

cible est une chaîne de sélecteur CSS ou Playwright ('button:has-text("Approuver")') ou un Locator (r.page.locator('tr', has_text='Aarav').first).

5. Créer la narration, enregistrer et réviser

PY DV voice  demo-videos/<nom>.py     # audio par scène ; affiche la durée de chaque scène
PY DV record demo-videos/<nom>.py     # pilote l'application et capture les images
PY DV stills demo-videos/<nom>.py     # deux images par scène dans <nom>-video/stills/

Connexion. Avec 'sign_in': True, si l'application n'est pas connectée, une fenêtre de navigateur s'ouvre et l'enregistreur affiche SIGN_IN_NEEDED. Dites à l'utilisateur de se connecter dans cette fenêtre. Ne saisissez jamais d'identifiants et ne demandez jamais de mots de passe. La session est sauvegardée dans <nom>-video/.profile afin que les reprises n'aient pas besoin d'une nouvelle connexion.

Révisez chaque image avant de construire, en lisant les images :

• bonne page, panneau ouvert, curseur là où la narration le dit ;
• rien ne cache l'action (toasts, bannières de cookies, menu de profil) ;
• l'image n'est pas étirée ou coupée ;
• aucune donnée personnelle réelle à l'écran.

Une ligne SCENE_ERROR ou une image incorrecte signifie corriger cette fonction de scène et enregistrer à nouveau (repeuplez d'abord si les scènes ont modifié des données). reference/lessons.md liste les échecs observés jusqu'à présent et leurs correctifs. Lisez-le quand quelque chose semble anormal.

6. Construire, vérifier et remettre

PY DV build demo-videos/<nom>.py [--out "chemin/Nom.mp4"]
PY DV check "chemin/Nom.mp4" --size 1600x900

run fait voice, record, stills, build et check en une seule fois, une fois que les scènes sont connues pour fonctionner. Dites à l'utilisateur le chemin et la durée de la vidéo, et ce qu'elle montre. Ne la téléchargez ni ne la partagez nulle part sauf s'il le demande.

7. Nettoyage

• PY DV clean demo-videos/<nom>.py supprime la connexion sauvegardée. Faites-le toujours à la fin, car elle contient une vraie session. --all supprime également les images, les affichages fixes et l'audio.
• Exécutez le script de nettoyage des données de démonstration, et arrêtez tous les processus d'application que vous avez démarrés.

Notes de plateforme

• macOS : utilisez python3. Les sous-titres sont dessinés par Chromium et superposés sur la vidéo, donc ils ont le même aspect partout et ne nécessitent pas un ffmpeg compilé avec libass (celui de Homebrew ne l'a pas). L'enregistrement est sans tête, donc les écrans Retina ne changent pas la taille de la vidéo.
• --headed enregistre dans une fenêtre visible. Utilisez-le uniquement lorsqu'une application refuse les navigateurs sans tête, et demandez à l'utilisateur de ne pas toucher ou redimensionner la fenêtre pendant l'enregistrement.
• DEMO_VIDEO_HOME déplace l'environnement privé ; DEMO_VIDEO_FFMPEG_DIR pointe vers un dossier ffmpeg.