Walkthrough-vidéo

Vidéo de visite guidée

Transforme une application web en cours d'exécution en une vidéo narrée complète, qui peut être régénérée à chaque modification de l'application. Tout s'exécute en local : pas d'éditeur vidéo, pas de service payant.

texte de narration -> voix locale -> un WAV par scène + timings des légendes
application réelle -> scènes Playwright -> clips + temps des marqueurs   -> assemble.py -> walkthrough.mp4 + .srt

Pourquoi cela fonctionne ainsi : les séquences proviennent de l'application réelle, donc elles sont toujours vraies ; les étapes lentes (une réponse IA, un chargement de page) sont supprimées pendant l'enregistrement ; et les « marqueurs » enregistrés par chaque scène permettent à l'assembleur de synchroniser le moment clé avec les mots correspondants.

Avant de commencer

1. Demandez uniquement ce qui manque : ce qu'est l'application, ce que la vidéo doit montrer, qui la regarde, la durée cible (2 à 4 minutes fonctionnent bien), le ton.
2. Vérifiez les outils (détails dans references/setup.md) : Node 20+, Playwright avec Chromium, FFmpeg avec xfade, zoompan, loudnorm, libx264, et Python 3.11 ou 3.12 avec kokoro-onnx. Installez la voix (environ 350 Mo) en dehors du dépôt, par exemple dans ~/video-tools.
3. Copiez les fichiers de travail dans le projet de l'utilisateur et conservez les fichiers générés hors de git :

   mkdir -p e2e/video-kit && cp -R <this skill>/scripts/. e2e/video-kit/ && cp <this skill>/templates/*.mjs e2e/video-kit/
   printf '\ne2e/video-kit/clips/\ne2e/video-kit/vo/\ne2e/video-kit/build/\ne2e/video-kit/*.mp4\ne2e/video-kit/*.srt\ne2e/video-kit/spec.json\ne2e/video-kit/.*.json\n' >> .gitignore
   

   Les scripts écrivent leur sortie à côté d'eux-mêmes, c'est pourquoi ils sont copiés plutôt qu'exécutés depuis ici.
4. Lisez references/toolkit-api.md une fois. Il documente les aides de l'enregistreur et la syntaxe PLAN. Ne réécrivez pas rec.mjs, speak.py, overlays.mjs ou assemble.py ; modifiez uniquement les parties nommées par le guide.

Le flux de travail : trois jalons

Arrêtez-vous à chaque jalon et attendez l'utilisateur. Le libellé et la structure sont faciles à modifier avant l'enregistrement, mais coûteux après.

Jalon 1 : storyboard. Examinez le projet (sa documentation, ses routes, ses tests Playwright existants) et proposez 8 à 12 scènes. Pour chacune : ce qui est affiché à l'écran, la narration (20 à 35 mots, simple), et comment elle sera enregistrée. Incluez des diapositives d'ouverture si l'utilisateur souhaite du contexte : le problème, ce qui a été fait ou audité, la solution et la pile technologique. Ne décrivez rien que l'application ne fasse pas réellement ; demandez en cas de doute.

Jalon 2 : libellé et voix. Écrivez chunks.txt sous forme de lignes scène|texte, d'environ 12 mots maximum chacune (chaque ligne deviendra une légende). Ajoutez les noms de produits et les acronymes à PRONOUNCE dans speak.py. Lancez python speak.py et signalez la durée de chaque scène. L'utilisateur écoute et approuve avant tout enregistrement.

Jalon 3 : enregistrer, assembler, vérifier.

1. Écrivez les scènes dans scenes.mjs (partez de scenes.template.mjs), un clip par scène, nommé scene-N pour correspondre au plan par défaut. Enregistrez une scène à la fois en arrière-plan : node scenes.mjs <nom>. Ne réenregistrez que celles qui échouent.
2. Rendez les diapositives si elles sont utilisées (slides.template.mjs), puis remplissez PLAN et LABEL dans assemble.py : quel clip apparaît dans quelle scène, et quel marqueur atterrit sur quelle ligne de narration.
3. Lancez python assemble.py all. Il génère walkthrough.mp4 et walkthrough.srt.
4. Vérifiez le résultat à partir d'une seule planche contact (une ou deux images par scène, disposées en mosaïque) plutôt que de nombreuses images séparées : noms, dates, légendes, rien de coupé, rien de privé. Corrigez, réassemblez, livrez.

Règles importantes

• Confidentialité. Utilisez un compte de démonstration ou de test. Floutez ou masquez tout ce qui montre de vraies personnes, e-mails, numéros de téléphone, noms de compte, clés, identifiants, jetons ou facturation (opts.cover, opts.init). Ne gérez jamais de mots de passe : lorsqu'une scène nécessite une connexion, faites en sorte que l'utilisateur se connecte manuellement une fois dans un navigateur visible (templates/auth.template.mjs) et réutilisez la session enregistrée. Ne tapez ni n'affichez de mots de passe ou de codes 2FA devant la caméra. Gardez .env, les connexions enregistrées et les profils de navigateur hors de git.
• N'agissez pas sur des comptes réels. Ne cliquez jamais sur quoi que ce soit qui envoie, publie, planifie ou supprime sur des comptes réels. Survolez le bouton et dites ce qu'il fait.
• Pas de fonctionnalités inventées. Décrivez uniquement ce que le code et l'application en cours d'exécution font.
• La voix et l'audio du microphone ne peuvent pas être capturés par le navigateur. Montrez l'interface et dites ce qui se passe.
• Vérifiez les ports avant de démarrer les serveurs ; arrêtez ce que vous avez démarré. Lancez toute tâche de plus d'une minute (enregistrement, voix, assemblage) en arrière-plan et attendez-la plutôt que de la sonder en boucle.
• Gardez les réponses courtes. Rapportez ce que vous avez fait, les chemins de fichiers et tout ce que vous n'avez pas pu vérifier.

Leçons tirées d'une utilisation réelle

Lisez references/lessons.md avant d'écrire les scènes. La version courte : vérifiez que les données amorcées existent réellement (des données de test aléatoires peuvent entrer en conflit avec des données plus anciennes) ; attendez un localisateur qui prouve qu'une page lente s'est affichée ; effacez les filtres de recherche mémorisés avant de taper ; fermez les pop-ups ; liez directement aux enregistrements ; enveloppez les fioritures non essentielles pour qu'un seul échec ne puisse pas arrêter une scène ; et gardez les 200 pixels inférieurs des diapositives libres pour les légendes.

Fichiers

• scripts/rec.mjs enregistreur : curseur glissant, ondulations de clic, zoom, marqueurs, think() pour couper les attentes.
• scripts/speak.py narration vers WAV et timings de légendes.
• scripts/overlays.mjs légendes, étiquettes et cartes titres sous forme d'images.
• scripts/assemble.py retiming des clips sur la voix, assemblage, superposition, mixage audio, écriture MP4 et SRT.
• templates/ points de départ pour les scènes, une connexion enregistrée, les diapositives et le fichier de narration.
• references/ le guide de la boîte à outils, l'installation, et les leçons.

En cas d'échec

• La parole échoue avec espeakng_loader/phontab: No such file : consultez references/setup.md.
• Une scène expire en attendant du texte : la page n'a peut-être pas fini de se dessiner, ou un filtre mémorisé masque l'élément. Prenez une capture d'écran au moment de l'échec et examinez-la.
• La vidéo montre une attente : enveloppez l'étape lente dans think().
• L'image et la voix dérivent : réenregistrez la scène, car les temps des marqueurs changent chaque fois qu'un script est modifié.