/daniel-video-annotate
Entrée : un fichier vidéo, plus tout ce qui explique pourquoi chaque étape est effectuée (un ticket, une demande de fusion, le message de l'utilisateur). Sortie, à côté de l'entrée : <nom>-trimmed.mp4 et <nom>-explained.mp4. Le fichier d'entrée n'est jamais modifié.
La vidéo expliquée lit l'enregistrement, et à chaque pause, elle immobilise une image pendant la durée d'affichage, assombrit l'écran autour d'une commande encadrée, et montre une légende d'une phrase dans une bande noire en dessous ou au-dessus de l'enregistrement. La bande rend la vidéo plus haute, donc l'enregistrement n'est jamais masqué.
annotate.py se trouve à côté de ce fichier. Dans les commandes ci-dessous, A représente python3 "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/daniel-video-annotate/annotate.py". Il nécessite uniquement ffmpeg, ffprobe et la bibliothèque standard Python. <travail> est un dossier de travail : le bloc-notes de session lorsqu'il y en a un, sinon ${TMPDIR:-/tmp}/video-annotate/<nom>/.
Si la vidéo se trouve sur la VM de développement, copiez-la d'abord avec dvm get <chemin distant> <dossier local>.
0. Choisir la vitesse de lecture
La durée d'affichage est le temps pendant lequel chaque légende reste lisible à l'écran. Chaque pause dure 1,5 s plus le temps de lire sa légende à la vitesse de lecture, et au moins 2,5 s. Utilisez la vitesse en mots par minute que l'utilisateur a donnée, sinon 350 mots/min. Ne demandez pas. Lorsque l'utilisateur a donné une durée d'affichage fixe en secondes, utilisez-la pour chaque pause à la place.
Terminé lorsque vous avez une vitesse de lecture ou une durée d'affichage fixe.
1. Couper les temps d'attente
A trim <video> <nom>-trimmed.mp4
Il trouve chaque segment où l'image reste immobile pendant 1,5 s ou plus, conserve la première seconde de chacun, et coupe le reste. Il affiche le nombre de segments et la durée avant et après. Ignorez cette étape lorsque l'utilisateur souhaite conserver les temps d'attente, et utilisez l'original comme <trimmed> ci-dessous.
Chaque instant dans les étapes ultérieures est un instant dans <trimmed>. Un nouveau découpage déplace tous les instants, donc refaites les étapes 2 à 6 après tout nouveau découpage.
2. Apprendre l'histoire
A sheets <trimmed> <travail>/sheets
Il écrit des planches contact de six images chacune, une image par seconde, avec l'instant exact incrusté dans chaque image. Lisez chaque planche. Lisez le ticket ou autre source pour la raison derrière chaque étape.
Terminé lorsque vous pouvez dire, dans l'ordre, ce que la personne fait à l'écran, quelle valeur chaque action définit, et quel résultat prouve le but de l'enregistrement.
3. Choisir les pauses
Marquez une pause pour chaque choix (une valeur sélectionnée, un bouton pressé, une page ouverte volontairement) et une pour chaque résultat qui prouve le point. Ignorez la navigation qui ne comporte pas de décision.
Pour chaque pause, trouvez l'image et le cadre :
A frames <trimmed> <travail>/frames 23.0 23.2 23.4 23.6
Il écrit un PNG pleine taille par instant, nommé par son instant exact, avec une grille rouge tous les 100 px et les coordonnées en pixels étiquetées le long du bord supérieur et gauche.
- Choisissez une image stable. Les enregistrements contiennent des images à moitié rendues, par exemple un panneau vide pendant quelques images après un clic. Parcourez par pas de 0,2 s jusqu'à ce que la commande et son environnement soient entièrement dessinés.
- Pour un choix dans une liste, préférez l'image où la liste est ouverte et le curseur est sur l'option. Si cette image est à moitié rendue, utilisez l'image juste après, où le champ affiche la nouvelle valeur.
- Lisez le cadre comme
[x, y, largeur, hauteur]à partir des étiquettes de la grille, en pixels source. L'outil Read réduit les grandes images, donc les positions mesurées sur l'image affichée sont erronées ; les étiquettes restent correctes. - Encadrez la commande unique dont parle la légende, avec quelques pixels de marge. Une pause peut omettre
frame, et alors rien n'est assombri.
Terminé lorsque chaque pause a un instant dont vous avez examiné l'image, et un cadre lu depuis cette même image.
4. Écrire les légendes
Une phrase par pause. Elle dit ce que nous faisons et pourquoi, ou ce que l'écran montre maintenant et pourquoi. Nommez la chose concrète : la ligne, le champ, l'ancienne valeur et la nouvelle valeur.
Prenez le « pourquoi » de la source. Lorsque la source ne donne pas la raison d'une étape, écrivez ce qui est visible, et listez cette légende comme inférée dans le rapport. Appliquez le skill writing-tics aux légendes. Gardez chaque légende sous environ 180 caractères, car la bande est aussi haute que la légende la plus longue.
5. Rendu
Écrivez <travail>/spec.json, une liste dans l'ordre temporel :
[
{"at": 12.0, "box": [399, 569, 180, 29], "caption": "Nous changeons la taille de l'élément 1 de M à L dans le tableau, ce qui enregistre L sur le serveur."},
{"at": 23.6, "box": [659, 500, 192, 24], "caption": "..."}
]
at est en secondes dans <trimmed>. Ensuite, définissez hold sur chaque pause :
A holds <travail>/spec.json [--wpm <vitesse>]
Il écrit la durée d'affichage de chaque pause dans la spécification et l'affiche avec le nombre de mots. Avec une durée d'affichage fixe, définissez hold sur chaque pause vous-même. Une pause sans hold dure 6 secondes.
A annotate <trimmed> <travail>/spec.json <nom>-explained.mp4 [--position top|bottom] [--clearance <lignes>]
La bande de légende va là où l'utilisateur l'a demandé. Sans demande, elle va en bas.
--position bottomest la valeur par défaut. Les lecteurs vidéo dessinent leurs commandes sur le bord inférieur, donc la bande obtient un espace vide sous la légende :--clearancelignes de cet espace, 3 par défaut, ce qui dégage les commandes d'un petit lecteur intégré.--position topplace la bande au-dessus de l'enregistrement, où aucun lecteur ne dessine de commandes. Elle ne prend pas de marge.
Les cadres restent dans les coordonnées de <trimmed> pour les deux positions.
6. Vérifier chaque pause
A check <nom>-explained.mp4 <travail>/spec.json <travail>/check
Il écrit une image du milieu de chaque pause. Lisez chacune. Le cadre doit se trouver sur la commande, la légende doit être entière et non coupée sur le bord droit, et l'image doit être celle stable que vous avez choisie. Corrigez la spécification et rendez à nouveau jusqu'à ce que chaque pause soit réussie.
7. Rapport
Donnez le chemin, la taille et la durée de la vidéo expliquée, puis les légendes dans l'ordre, chacune avec la commande qu'elle encadre. Dites quelles légendes sont inférées. Dites que vous avez vérifié une image par pause et que vous n'avez pas regardé la lecture.
Limites
- La sortie n'a pas d'audio. Informez l'utilisateur lorsque l'entrée avait une piste vocale.
- La fréquence d'images est la fréquence moyenne de l'entrée, arrondie et maintenue entre 5 et 30 images par seconde.
trimne coupe que les images complètement immobiles. Un spinner, une barre de progression, un curseur clignotant ou une horloge maintient l'image en mouvement, donc ces temps d'attente restent. Un temps d'attente interrompu par un petit changement est conservé en plusieurs morceaux d'une seconde.trimne coupe que les images à l'intérieur d'un segment immobile, et il conserve la première image de chaque changement. Un changement plus petit que la tolérance--noise(par défaut 0,003), comme un petit caractère, compte comme immobile et peut être coupé. L'étape 2 est la vérification : chaque action doit apparaître dans les planches. Abaissez--noiseà 0,001 lorsqu'une action est manquante.
Erreurs
| Ce que vous voyez | Cause | Correctif |
|---|---|---|
this ffmpeg build has no drawtext filter | ffmpeg a été construit sans libfreetype | Installez une version complète, par exemple brew install ffmpeg |
no font file found | Aucun des chemins de polices macOS ou Linux connus n'existe | Passez --font /chemin/vers/police.ttf à sheets, frames et annotate |
Unrecognized option 'fps_mode' | ffmpeg est plus ancien que 5.1 | Mettez à jour ffmpeg |
no still stretches found, nothing written | L'image ne reste jamais immobile pendant 1,5 s | Utilisez l'original comme <trimmed>, ou abaissez --min-freeze |
| La vidéo rognée semble encore lente | Les temps d'attente animés ont été conservés, ou une seconde par segment immobile s'accumule | Abaissez --keep à 0,5 |
| La vidéo rognée saute trop vite pour suivre | Une seconde par écran est trop courte pour cet enregistrement | Augmentez --keep à 2 et --min-freeze à 3 |
pause N at Ts is past the end of the video | Les instants proviennent de l'original et non de <trimmed> | Relisez les instants à partir de sheets et frames de <trimmed> |
pause N box ... is outside the frame, ou le cadre manque la commande dans check | Le cadre a été mesuré sur une image réduite | Lisez-le à partir des étiquettes de grille du PNG frames |
| La légende est coupée sur le bord droit | La police est plus large que ce que le script suppose | Passez --wrap 80, ou un nombre inférieur, à annotate |
| Les commandes du lecteur couvrent la légende | L'espace sous la légende est plus court que les commandes | Augmentez --clearance à 5, ou passez --position top |
pause N would sit at ..., past the end | check a reçu la vidéo rognée | Donnez-lui la vidéo expliquée |
Any other ffmpeg failed | Inconnu | Exécutez A selftest. Il rogne et annote un clip généré, donc une réussite signifie que ffmpeg fonctionne et que l'entrée ou la spécification est en cause |
dvm get --help échoue avec une erreur scp | dvm get passe chaque argument à scp | Exécutez dvm help |
macOS n'a pas de commande timeout. Une vidéo 720p d'une minute s'affiche en quelques secondes, donc exécutez les commandes simplement.