omerozgul11/app-training-video-skill

Vidéo de formation d'application

Réalisez une vidéo de formation professionnelle d'une application réelle. La vidéo est au format 1920 × 1080 H.264 avec narration AAC. Chaque phrase parlée est sous-titrée, chaque chapitre s'ouvre par une carte, et les longues attentes sont coupées. Elle est reproductible : lorsque l'interface change, relancez la capture et le rendu et la vidéo est à jour.

Comment ça marche :

1. Un storyboard contient le texte de la narration, les chapitres et l'identité visuelle.
2. narrate.py prononce chaque segment avec la voix hors ligne Kokoro : pas de service cloud, pas de compte, pas de coût.
3. Un script de capture pilote l'application réelle avec Playwright (mouvement de souris réel, curseur visible et ondulations de clic). Il enregistre les trames du screencast de Chrome et maintient chaque segment jusqu'à la fin de sa narration.
4. render.py assemble les clips, les cartes, la bande de sous-titres et la piste de narration à la normalisation du volume.
5. review.py vérifie le résultat et construit une planche contact à regarder avant la publication.

Les scripts sont dans scripts/ à côté de ce fichier. Lisez references/storyboard.md avant d'écrire la narration et references/capture-guide.md avant d'écrire le script de capture. Les deux contiennent des leçons qui évitent les réenregistrements habituels.

0. Installation unique

bash <skill>/scripts/setup.sh

Ceci crée ~/.cache/app-training-video/ (remplacez par TRAINING_VIDEO_HOME) contenant :

• un environnement Python 3.10–3.13 privé avec des paquets figés ;
• le modèle vocal Kokoro (~350 Mo) et la police Inter, vérifiés par SHA-256 ;
• Chromium.

Exécutez chaque script avec le Python de cet environnement (PY=~/.cache/app-training-video/venv/bin/python) et passez le chemin du storyboard. Si les fichiers du modèle existent déjà quelque part, exécutez d'abord MODEL_SOURCE=<dir> pour les réutiliser. ffmpeg est fourni (imageio-ffmpeg) ; rien n'est installé à l'échelle du système.

1. Comprendre l'application et le public

Avant d'écrire quoi que ce soit, utilisez l'application vous-même (ou lisez son guide d'utilisation) et découvrez :

• Qui regarde : nouveaux clients, personnel terrain, utilisateurs internes.
• Le seul workflow qu'ils doivent maîtriser : de l'entrée au résultat.
• Quelles données de démonstration peuvent être montrées en toute sécurité.
• Comment lancer l'application dans un état propre : URL ou commande de lancement, plus un dossier de données frais ou un compte de démonstration.
• Identité visuelle : nom de l'entreprise, nom du produit, version, logo PNG, couleur d'accent, lignes de contact pour l'outro.

Demandez à l'utilisateur tout ce que vous ne trouvez pas. Six à sept minutes est idéal pour un workflow complet, et 60 à 90 secondes pour une fonctionnalité unique.

2. Rédiger le storyboard

Copiez assets/storyboard.example.json à côté du projet en tant que storyboard.json et rédigez-le en suivant references/storyboard.md. En résumé :

• 10 à 35 secondes de parole par segment ;
• chapitres "n · Titre", avec card: "chapter" sur le premier segment de chaque chapitre ;
• cartes intro et outro ;
• acronymes épelés pour la voix, avec caption_replacements restaurant la forme écrite.

Montrez la narration à l'utilisateur avant le tournage : il est peu coûteux de la changer maintenant et coûteux plus tard.

3. Narration

$PY <skill>/scripts/narrate.py storyboard.json

Cela affiche la longueur de chaque segment. Cela ne répète que les segments dont le texte a changé. Écoutez un ou deux WAV dans video-build/audio/ si la prononciation est importante, ajustez l'orthographe et relancez-le.

4. Écrire et exécuter le script de capture

Copiez scripts/capture_template.py dans capture.py à côté du storyboard, définissez le chemin vers le dossier scripts/ du skill, et écrivez un bloc with rec.segment('<id>'): par segment filmé, dans l'ordre du storyboard. À l'intérieur, effectuez exactement ce que la narration décrit :

• rec.click, rec.hover, rec.type, rec.drag, rec.scroll, rec.park ;
• rec.cut() autour de tout ce qui est lent, en attendant un résultat visible.

L'enregistreur refuse un dossier frames/ non vide, donc les anciennes trames ne sont jamais mélangées.

$PY capture.py storyboard.json

Chaque segment affiche sa durée filmée par rapport à sa narration. L'exécution échoue (statut incomplete) à la première étape cassée, à toute erreur de page ou à tout segment non filmé. Corrigez l'étape, videz video-build/frames/, et relancez-le.

5. Rendu et révision

$PY <skill>/scripts/render.py storyboard.json
$PY <skill>/scripts/review.py storyboard.json

Sorties dans le dossier de construction :

• <nom_sortie>.mp4
• Sous-titres .srt
• -chapters.txt (collez dans une description YouTube)
• -poster.jpg
• -timeline.json
• -review.jpg : une image par segment.

Ouvrez la planche contact et regardez-la, et vérifiez le MP4 lui-même. Vérifiez :

• le bon écran dans chaque segment ;
• pas de bannières d'erreur, de graphiques vides ou de boîtes de dialogue parasites ;
• le curseur ne couvre jamais ce qui est expliqué ;
• les sous-titres se lisent correctement.

Les sélecteurs peuvent correspondre alors que l'écran est mauvais, donc ce regard est requis avant de déclarer la vidéo terminée.

6. Livraison

Donnez à l'utilisateur le MP4, le SRT (la plupart des lecteurs le chargent automatiquement lorsque les noms correspondent) et la liste des chapitres. Mentionnez la durée et la taille. Pour publier, téléchargez le MP4 et le SRT ensemble. Conservez storyboard.json et capture.py avec le projet : après le prochain changement d'interface, relancez les étapes 4–5 (et l'étape 3 si le texte a changé).

Dépannage

Symptôme	Correction
Need Python 3.10–3.13	Installez python3.12, ou définissez PYTHON= avant d'exécuter setup.sh
launch() expire bien que l'application ait démarré	L'application met en mémoire tampon sa sortie : exécutez les serveurs Python avec python -u, ou vérifiez l'expression régulière ready
Chromium ne démarre pas sous Linux	$PY -m playwright install --with-deps chromium
Le localisateur expire ou correspond à deux éléments	Limitez-le à une région, ou utilisez get_by_role avec exact=True (voir le guide de capture)
Segment beaucoup plus long que sa narration	Quelque chose de lent n'est pas à l'intérieur de rec.cut()
Mauvaise prononciation	Réécrivez dans speech, ajoutez une règle caption_replacements, relancez narrate.py
Sous-titres désynchronisés	Le timing des sous-titres suit la longueur de la narration : raccourcissez les longues phrases, ou divisez le segment