Compétences vidéo (every-app/video-skills)

Vidéo narrée

La personne enregistre une prise unique d'elle-même en parlant sur un storyboard. L'agent monte la prise et anime de vraies captures d'écran du produit synchronisées : chaque scène commence, chaque clic atterrit et chaque recherche est tapée sur le mot qui la nomme. La vidéo entière est du code (une composition HyperFrames plus une liste de montage), donc une nouvelle prise, un écran modifié ou un ordre différent est une re-exécution, pas un nouveau montage.

La vidéo s'adapte à la narration, jamais l'inverse. La personne dirige le goût ; l'agent produit les coupes, montre les images et demande.

Configuration

• ffmpeg dans PATH, uv, Node 20+ avec npx (HyperFrames 0.8.62 s'exécute via npx), et Playwright avec Chromium pour les captures. Fonctionne sur macOS, Linux et Windows.
• Whisper s'exécute localement : mlx-whisper sur Apple Silicon, faster-whisper ailleurs. uv run installe la bonne version.
• SK=<chemin du répertoire de cette compétence>/scripts. Chaque outil s'exécute sous la forme uv run $SK/<outil>.py ; chacun déclare ses propres dépendances.
• Travaillez dans un dossier en dehors des fichiers suivis d'un dépôt (un .logs/<video>/ gitignoré, ou un dossier temporaire) :

<travail>/
  assets/            captures, fond, carte de fin
  storyboard.json    les scènes -> storyboard/index.html
  takes/<nom>/       un dossier par prise enregistrée : sortie de la sonde, transcription, edit.json, la narration et la webcam montées
  video.py           le script de composition -> comp/ (index.html, rendus/)
  NOTES.md           chaque décision : coupes et pourquoi, débuts de scène, commandes de reconstruction

1. Brief

Confirmez en un bref échange, en proposant des valeurs par défaut :

• Format : vidéo de lancement, démo de fonctionnalité ou tutoriel (références/formats.md). Une vidéo de lancement reste sous 2:00, carte de fin comprise.
• Public, les trois ou quatre temps forts que la vidéo doit marquer, et l'appel à l'action.
• Exemple de données qui se démontrent bien : une entreprise ou une recherche exemple qui se lit en un coup d'œil pour ce public.
• Marque : une image de fond (ou le dégradé par défaut), une carte de fin (l'image OG du produit fonctionne bien), l'URL affichée dans la barre de titre de la fenêtre.

2. Capture

Vraies captures d'écran du produit en cours d'exécution en 1440x900, 2x, à partir d'un script Playwright basé sur $SK/capture.mjs :

• images par touche pour tout ce qui est tapé à l'écran,
• états avant et après pour tout ce qui est cliqué,
• plans larges pour tout ce qui défile,
• et zones de clic mesurées pour le pointeur.

Si l'application nécessite une connexion, passez login et la première exécution ouvre une fenêtre de navigateur pour que la personne se connecte une fois. Ne dessinez jamais d'UI et ne modifiez jamais de pixels. Examinez chaque capture avant de l'utiliser. Détails et le passage sur la vie privée : références/capture.md.

3. Storyboard

Écrivez storyboard.json, une carte par scène : la capture d'écran, ce qui est à l'écran, trois à six puces de ce qu'il faut dire (notes courtes, pas des phrases), et secondes approximatives. Construisez-le et affichez-le :

uv run $SK/storyboard.py storyboard.json storyboard/

C'est une page simple, une section par scène. Publiez storyboard/ (index.html plus frames/) lorsque l'infrastructure peut publier une page, sinon ouvrez-la localement. Itérez jusqu'à ce que la personne soit prête à enregistrer, puis remettez les notes d'enregistrement dans références/storyboard-and-recording.md. Une fois qu'elle enregistre à partir de celui-ci, ne modifiez pas le storyboard sans demander.

4. Enregistrement

La personne enregistre une prise unique, webcam et voix dans un seul fichier (n'importe quel enregistreur webcam : QuickTime, Photo Booth, Windows Camera, OBS), en parlant à travers les scènes. Les erreurs sont acceptables : elle recommence la phrase et continue. Plusieurs prises sont possibles ; chacune reçoit un dossier de prise.

5. Montage de la prise

uv run $SK/probe.py <enregistrement> takes/<nom>       # take.wav, cam.mp4, take.json ; vérifiez still.jpg, relancez avec --crop si nécessaire
uv run $SK/transcribe.py takes/<nom>              # deux passes : normale, et une qui écrit les tics de langage
uv run $SK/analyze.py takes/<nom>                 # candidats : longues pauses (avec coupes), tics de langage, redémarrages, bruits parasites
uv run $SK/trace.py takes/<nom> <a>:<b>           # placez chaque coupe sur la trace d'énergie (--fine pour des lignes de 5 ms)
uv run $SK/splicetest.py takes/<nom> c1=<a>:<début coupe>,<fin coupe>:<b>   # écoutez une coupe : elle doit donner la phrase voulue
uv run $SK/jump.py takes/<nom> <début coupe>:<fin coupe> --slide 0.3        # à quel point la coupe est visible dans la bulle webcam
# écrivez takes/<nom>/edit.json, puis :
uv run $SK/edit.py takes/<nom>                    # edl.json ; affiche la narration montée et les tics de langage conservés : lisez tout
uv run $SK/build.py takes/<nom>                   # narration-edit.wav, cam-edit.mp4 (fondus enchaînés et dissolutions webcam à chaque coupe)
uv run $SK/master.py takes/<nom>                  # narration.wav à -16 LUFS

Deux niveaux de montage (références/editing.md) :

• Léger, par défaut : coupez les redémarrages et les faux départs, et taillez les blancs (une pause de plus de ~1,1 s conserve 0,7 s, 0,9 s lors d'un changement de scène). Chaque euh et courte hésitation reste.
• Moins de tics de langage, sur demande : supprimez également la plupart des euh isolés entre les phrases, et réduisez les pauses de plus de ~0,8 s à environ 0,55 s. Laissez tout tic de langage collé à un mot voisin.
• Chaque coupe repose dans le bruit de fond sur la trace et passe un test de raccord avant d'être intégrée. Les coupes de redémarrage se font si possible lors des changements de scène, afin que la coupe image cache le saut dans la bulle.

6. Composition sur les mots

uv run $SK/cues.py takes/<nom>       # words.json, la feuille de repères (transcriptions au niveau des clips de la narration finale)
NV_SCRIPTS=$SK ASSETS=assets uv run --with numpy python video.py   # le script de composition -> comp/ ; affiche chaque repère en contexte
uv run $SK/render.py comp lint
uv run $SK/render.py comp snapshot 1,14.2,22.5,40.1

Écrivez video.py à partir de l'exemple travaillé, examples/openseo-launch/video.py : débuts de scène et temps des repères depuis la feuille de repères, calques de la caméra sur les captures, et une chorégraphie synchronisée sur les mots. Les positions des repères de l'exemple ne correspondent qu'à son propre montage : ré-ancrez chacun d'eux, et lisez le tableau des repères qu'il affiche après chaque modification du montage. Les règles de synchronisation sont dans références/composition.md ; les plus importantes :

• Une scène commence 0,3 s avant son premier mot, ou exactement sur une coupe dans la pause qui la précède.
• Chaque action atterrit sur le mot qui la nomme : le clic sur « copier », la frappe lorsque la recherche est prononcée, le zoom sur un nombre lorsqu'il est dit, le pointeur sur chaque élément lorsqu'il est nommé.
• La première image est l'affiche : toute l'application, sans fondu d'entrée. Quelque chose bouge dans chaque image.
• Une courte étiquette par temps fort. Prenez un instantané de chaque début de scène, clic et étiquette, et examinez-les avant de lancer le rendu.

7. Rendu et vérification

uv run $SK/render.py comp render
uv run $SK/composite.py comp takes/<nom> comp/renders/<vidéo>-1080p.mp4
uv run $SK/check.py comp/renders/<vidéo>-1080p.mp4 comp takes/<nom>
uv run $SK/filmstrip.py comp/renders/<vidéo>-1080p.mp4 comp/renders/filmstrip.png

Rien n'est transmis à la personne tant que la vérification montre la fenêtre dans chaque image, chaque point webcam à l'offset d'image 0, une médiane audio de 0 ms, et environ -16 LUFS, et que vous avez lu la transcription et regardé la bande-annonce (références/verification.md).

8. Révision et itération

• Fournissez à la personne le chemin du mp4, ce qui a été coupé, et tout élément à écouter.
• Tenez NOTES.md à jour : chaque coupe avec sa raison, débuts de scène, commandes de reconstruction. Attendez-vous à plusieurs cycles.
• Les variantes sont peu coûteuses : une autre prise, un montage léger et un moins de tics de langage, un ordre de scène différent. Chacune correspond à un dossier de prise ou à un script de composition ; avec des sous-agents, construisez-les en parallèle sous des noms de fichiers distincts pour éviter toute collision.

Règles strictes

• Écrans réels uniquement. Cachez ce qui ne fait pas partie de l'histoire (une bannière, un bandeau de cookies) ; ne peignez jamais sur les pixels.
• Vérifiez les captures et les enregistrements pour les secrets et les données personnelles (clés API, e-mails et noms d'autres personnes, données clients, URL localhost) avant le rendu ; encadrez-les ou recapturez, et révoquez toute clé apparue à l'écran. Le propre nom ou e-mail de la personne dans l'application est acceptable une fois qu'elle l'a confirmé.
• Les enregistrements et la session de connexion de la personne restent sur sa machine. Ne publiez rien sans qu'on vous le demande.

Ce qui pose encore problème : références/gotchas.md.