Communitygithub.com

tldraw/tldraw

Créer une vidéo de présentation commentée d'une pull request avec des diapositives de code et une narration audio. Utilisez cette compétence lorsque l'on vous demande de créer une présentation de PR, une vidéo de PR ou une vidéo de présentation.

Qu'est-ce que tldraw ?

Cette compétence permet de générer automatiquement une vidéo de présentation commentée pour une pull request GitHub, en combinant des diapositives de code, une narration audio et des sous-titres synchronisés. Elle est conçue pour remplacer une vidéo de type Loom que l'auteur de la PR aurait pu enregistrer, en offrant une explication structurée des modifications de code, de leur raison d'être et de leur impact. Supportée sur les plateformes comme Claude Code, Cursor et Codex, elle fonctionne en lisant la PR, en rédigeant un script de narration, en générant des clips audio via l'API Gemini TTS, en synchronisant les sous-titres avec Whisper, et en assemblant le tout en une vidéo MP4 1280×720. Le processus met l'accent sur une narration claire et didactique, en montrant le code modifié dans un ordre logique plutôt que par fichier, et en expliquant le 'pourquoi' des changements, pas seulement le 'quoi'.

Compatible avec✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/tldraw/tldraw/tree/HEAD/skills/pr-walkthrough

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Vidéo de présentation de PR

Créez une vidéo de présentation commentée pour une pull request. C'est un artefact interne, offrant le même avantage qu'une vidéo Loom créée par l'auteur de la pull request — parcourir les modifications de code, expliquer ce qui a été fait et pourquoi, afin que toute personne regardant la vidéo puisse comprendre rapidement la PR.

Entrée : Une URL de pull request GitHub (par exemple https://github.com/tldraw/tldraw/pull/7924). Si seul un numéro de PR ou une autre description est donné, supposez que la PR se trouve sur le dépôt tldraw/tldraw.

Sortie : Une vidéo MP4 en 1280×720 (30 images par seconde) avec narration audio, sous-titres jaunes sur fond noir synchronisés par Whisper, et des diapositives d'introduction / conclusion standardisées, sauvegardée dans out/pr-<numero>-walkthrough.mp4.

Tous les fichiers intermédiaires (audio, manifeste, scripts) vont dans tmp/pr-<numero>/ relatif au répertoire de cette compétence. Ce répertoire est ignoré par git. Seul le fichier .mp4 final se trouve dans out/.

Exécutez les commandes qui référencent ./scripts ou ./video depuis le répertoire de cette compétence.

Philosophie

Ceci est une présentation du point de vue de l'auteur. L'objectif est le même que si l'auteur de la PR s'asseyait avec quelqu'un et lui expliquait les modifications — montrer du code spécifique, expliquer ce qui a changé et pourquoi, dans un ordre qui construit la compréhension. Le spectateur doit comprendre à la fois ce que fait le code et comment réfléchir aux changements.

Cela signifie :

  • La narration guide tout. Rédigez d'abord la narration de la présentation, comme une explication continue de la PR. Ensuite, déterminez ce qui doit être affiché à l'écran à chaque moment pour appuyer ce qui est dit.
  • Montrez le code. Le visuel par défaut est un diff de code ou un fichier source. Les diapositives de texte sont l'exception (introduction, brèves transitions, conclusion), pas la règle. Quand la narration parle d'une fonction, le spectateur doit regarder cette fonction.
  • Parcourez les changements dans un ordre logique, pas nécessairement par ordre de fichier ou de commit — mais toujours ancré dans du code concret, pas dans des descriptions abstraites.
  • Expliquez le « pourquoi », pas seulement le « quoi ». Le code à l'écran montre ce qui a changé. La narration ajoute le raisonnement — pourquoi cette approche, quel problème elle résout, quels cas limites elle gère.

Flux de travail

Étape 1 : Comprendre la PR

Lisez les commits, le diff et la description de la PR. Comprenez l'arc narratif :

  • Quel problème cela résout-il ?
  • Quelle est l'approche ?
  • Quels sont les mécanismes clés ?
gh pr view <numero> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat

Ignorez les fichiers générés. En lisant le diff, ignorez les fichiers qui sont auto-générés plutôt que modifiés à la main. Ceux-ci ajoutent du bruit sans informer la présentation. Exemples courants dans ce dépôt :

  • **/api-report.md, **/api-report.api.md — rapports de surface API générés
  • **/*.api.json, **/temp/*.api.json — sortie de l'extracteur API
  • apps/docs/content/reference/** — documentation de référence générée
  • pnpm-lock.yaml, package-lock.json — fichiers de verrouillage
  • **/CHANGELOG.md — journaux de modifications auto-générés
  • Tout fichier que les outils du dépôt régénèrent (instantanés, vidages de schéma, actifs regroupés)

En cas de doute sur le fait qu'un fichier soit généré, vérifiez la présence d'un commentaire d'en-tête comme "NE PAS MODIFIER" ou vérifiez si le dépôt dispose d'une commande de génération qui le produit. Filtrez-les lors du choix des fichiers à mettre en avant dans les diapositives diff/code.

Étape 2 : Rédiger la narration

Rédigez la narration comme un texte continu, divisé en segments logiques. Chaque segment est un temps fort de la présentation — un concept, un changement ou un groupe de changements liés. Sauvegardez-le dans tmp/pr-<numero>/SCRIPT.md.

La narration doit ressembler à l'auteur expliquant la PR à un collègue : "Alors voici ce que nous faisons… Le problème principal était X… L'approche que j'ai adoptée était Y… Si vous regardez cette fonction ici…"

Structure : introduction → contexte/problème → parcours du code → résumé. Voir Structure du script ci-dessous.

Si les commits sont simples et bien organisés (souvent sur une branche avec -clean dans son nom), vous pouvez suivre leurs messages et descriptions de commit pour guider votre narration. Sinon, examinez le code et créez votre propre récit. Introduisez les concepts dans un ordre qui s'appuie sur les précédents.

Évitez les redondances, en particulier entre l'introduction et le premier segment de contenu.

Étape 3 : Générer l'audio et les horodatages

Générez des clips audio par segment avec un appel TTS par segment. Cela évite entièrement le découpage, l'alignement et la séparation — chaque segment est suffisamment court pour un seul appel TTS fiable.

Écrivez un fichier narration.json, puis exécutez l'outil CLI generate-audio.sh :

./scripts/generate-audio.sh narration.json tmp/pr-<numero>/

Clé API : Récupérée automatiquement à partir du fichier .env du dépôt (GEMINI_API_KEY).

Format du fichier narration.json

{
	"style": "Lisez la narration suivante de la présentation sur un ton calme, stable et professionnel. Parlez à un rythme mesuré, comme si l'auteur d'une pull request expliquait les modifications de code à un collègue.",
	"voice": "Iapetus",
	"slides": [
		"Cette pull request ajoute la résolution de liaison tenant compte des groupes à l'outil flèche...",
		"Le problème principal était que les liaisons de flèche cassaient lorsque la forme cible...",
		"Si vous regardez la méthode getBindingTarget dans ArrowBindingUtil.ts..."
	]
}
  • style — Personnalité vocale et instructions de rythme. Restez court et précis.
  • voice — Nom de la voix Gemini (par défaut : Iapetus).
  • slides — Tableau de textes de narration, une entrée par segment.

Comment cela fonctionne

  1. Pour chaque segment, le script construit une invite : préambule de style + texte du segment.
  2. Un appel API à gemini-3.1-flash-tts-preview par segment génère directement un clip WAV.
  3. Chaque clip est validé (vérification de durée vs nombre de mots) et réessayé automatiquement si la sortie est mauvaise.
  4. Le silence de début et de fin est supprimé de chaque clip.

Sortie : Clips audio par segment (audio-00.wav, ...) et un fichier durations.json mappant chaque nom de fichier audio à sa durée en secondes.

Dépendances : ffmpeg / ffprobe. Aucun package Python requis au-delà de la bibliothèque standard.

N'UTILISEZ PAS les balises de balisage [pause long] ou [pause moyen] dans le texte de la narration — le modèle pourrait les lire littéralement à voix haute.

Étape 4 : Écrire le manifeste

Lisez durations.json de l'étape 3 pour chaque longueur de clip, puis écrivez manifest.json à côté des fichiers audio. Il répertorie une entrée par diapositive, dans l'ordre, chacune avec son type, audio et durationInSeconds.

Voir references/manifest.md pour les types de diapositives et leurs champs.

Étape 5 : Rendre la vidéo

Exécutez le script render.sh :

./video/render.sh \
  tmp/pr-<numero>/manifest.json \
  out/pr-<numero>-walkthrough.mp4

Le script :

  1. Copie les fichiers audio/image référencés dans video/assets/.
  2. Exécute la transcription Whisper sur chaque fichier audio → video/transcripts/audio-NN.json (idempotent — ne retranscrit que si l'audio est plus récent que la transcription existante).
  3. Exécute build.mjs <manifest> pour générer video/index.html — une composition hyperframes avec des clips minutés pour chaque diapositive, une chronologie GSAP pour les transitions et les panoramiques de focus de code, et des sous-titres jaunes sur fond noir avec des heures de début/fin dérivées des transcriptions Whisper.
  4. Vérifie la composition et rend les images 1920×1080 via npx hyperframes render.
  5. Réduit la résolution à 1280×720 / 30ips et recompresse avec ffmpeg (CRF 26 + AAC 96k) pour obtenir le fichier MP4 final petit mais net.

Dépendances : Node.js 22+, ffmpeg, Python 3 (utilisé par render.sh pour analyser le manifeste). hyperframes est invoqué via npx --yes, donc aucune étape d'installation. Whisper s'exécute localement (modèle small.en, ~150 Mo au premier téléchargement).

Synchronisation des sous-titres via Whisper

Les sous-titres apparaissent sous forme de texte jaune sur un bloc noir uni, ancré en bas de l'image. Leurs heures de début/fin proviennent des transcriptions au niveau des mots de Whisper regroupées en morceaux de 5 à 7 mots, avec une rupture précoce sur les pauses naturelles (écart >450 ms = limites de phrase). Une implication : Whisper transcrit les noms de marque/code phonétiquement — "tldraw" → "TL Draw", "OverlayUtil" → "overlay util". Cela est acceptable pour les sous-titres mais pourrait être normalisé ultérieurement via une table de substitution dans build.mjs.

Réglages de taille de fichier

Le rendu par défaut cible ~30–60 Mo pour une vidéo de 8 minutes. Pour ajuster :

  • --crf <n> dans l'étape de réduction de résolution ffmpeg dans render.sh — 22 est quasi sans perte, 26 est la valeur par défaut, 30+ est beaucoup plus petit. CRF 28–30 est une bonne plage pour un résultat de qualité documentation.
  • Le rendu hyperframes 1080p utilise -q draft --crf 30 pour garder le fichier intermédiaire petit (la réduction de résolution domine de toute façon la taille finale).

Organisation des fichiers

La sortie finale se trouve dans le répertoire de cette compétence. Tous les fichiers intermédiaires vont dans tmp/ (ignoré par git) :

pr-walkthrough/
├── SKILL.md                    # Ce fichier
├── scripts/                    # Outils CLI (sous suivi de version)
│   └── generate-audio.sh       # narration.json → WAVs par diapositive + durations.json
├── video/                      # Projet Hyperframes (sous suivi de version)
│   ├── hyperframes.json        # Configuration hyperframes
│   ├── meta.json               # Méta-projet
│   ├── build.mjs               # manifest.json → composition index.html
│   ├── render.sh               # manifest.json → MP4 720p (pipeline complet)
│   ├── assets/                 # Rempli automatiquement au moment du rendu (ignoré par git)
│   ├── transcripts/            # JSON au niveau des mots de Whisper (ignoré par git, mis en cache)
│   └── renders/                # Rendu intermédiaire 1080p (ignoré par git)
├── out/                        # Sorties finales (ignoré par git)
│   └── pr-XXXX-walkthrough.mp4
└── tmp/                        # Fichiers intermédiaires (ignoré par git)
    └── pr-XXXX/
        ├── SCRIPT.md           # Script de narration
        ├── narration.json      # Entrée pour generate-audio.sh
        ├── durations.json      # Nom de fichier audio → durée en secondes
        ├── manifest.json       # Entrée pour render.sh
        └── audio-XX.wav        # Clips audio par segment

Configuration de l'API

  • Clé API Gemini : Stockée comme GEMINI_API_KEY dans le fichier .env racine du projet. Utilisée pour le TTS et l'alignement audio.
  • Modèle TTS : gemini-3.1-flash-tts-preview
  • Voix TTS : Iapetus (toujours)

Structure du script

La présentation suit un arc narratif cohérent. Toutes les sections n'ont pas besoin de leur propre segment — combinez ou sautez des sections en fonction de la complexité de la PR. L'objectif est de 8 à 12 segments au total, la grande majorité montrant du code.

Introduction (1 segment)

La carte d'introduction : logo tldraw + titre de la PR + date. La narration doit être une seule phrase qui cadre ce que fait cette PR à un haut niveau. N'entrez pas dans les détails pour l'instant.

Type de diapositive du manifeste : intro.

Contexte (0-1 segments)

Brève orientation avant de plonger dans le code. Quelle était la situation avant cette PR ? Quel problème ou besoin a motivé le travail ? Gardez cela court — juste assez de cadre pour que la présentation du code ait du sens.

  • Soyez concret : "Les liaisons de flèche cassaient lorsque la forme cible était à l'intérieur d'un groupe" pas "Il y avait des problèmes avec les liaisons"
  • Nommez la zone de la base de code affectée

Si le contexte peut être expliqué tout en montrant le premier morceau de code pertinent, sautez le segment de contexte autonome et intégrez-le dans le premier segment de code.

Type de diapositive du manifeste : text ou diff (si montrer le code problématique).

Parcours du code (6-10 segments)

L'essentiel de la vidéo. Parcourez les modifications de code réelles, en montrant des diffs et des fichiers spécifiques tout en expliquant ce qui a été fait et pourquoi.

Chaque segment doit montrer du code. Utilisez des diapositives diff pour les changements et des diapositives code pour le code de référence inchangé.

Directives :

  • Nommez les fichiers et les fonctions. Chaque segment narré doit référencer au moins un fichier ou une fonction spécifique.
  • Montrez le diff. Le visuel de chaque segment doit être le diff réel en cours de discussion. Utilisez git diff main..HEAD -- chemin/vers/fichier pour obtenir le diff, puis extrayez les sections pertinentes.
  • Ordonnez par compréhension, pas par fichier. Présentez les changements dans l'ordre qui construit la compréhension. Si un nouveau type est défini dans un fichier et utilisé dans un autre, montrez d'abord la définition.
  • Expliquez le « pourquoi », pas seulement le « quoi ». Le diff montre ce qui a changé — la narration ajoute le raisonnement, les cas limites qu'il gère, les alternatives qui ont été envisagées.
  • Sautez le code standard, mais mentionnez-le. Ne dédiez pas un segment à chaque changement d'import ou d'export de type, mais mentionnez en passant : "Il y a aussi quelques exports de type ajoutés dans index.ts — ce ne sont que des réexports des nouveaux types que nous verrons ensuite."
  • Regroupez les petits changements connexes. Si trois fichiers ont tous reçu le même correctif d'une ligne, un segment peut couvrir les trois. Mentionnez chaque fichier par son nom.

Résumé (1 segment)

Récapitulez brièvement ce que la PR a accompli. C'est une brève conclusion — une ou deux phrases résumant le changement global, mentionnant les limitations connues ou les travaux futurs si pertinent.

Type de diapositive du manifeste : text.

Conclusion (1 segment, silencieux)

Le logo tldraw, 3 secondes de silence. Incluez toujours cela comme dernière diapositive.

Type de diapositive du manifeste : outro avec durationInSeconds: 3.

Conseils pour la rédaction de la narration

  • Soyez précis sur le code. Dites "Dans BindingUtil.ts, le gestionnaire onAfterChange vérifie maintenant les ancêtres de groupe" — pas "Le système de liaison a été mis à jour." Nommez les fichiers et les fonctions pour que le spectateur puisse relier la narration à ce qui est à l'écran.
  • Chaque segment = un changement ou un groupe étroitement lié de changements. Si vous ne pouvez pas pointer un diff spécifique pour le segment, il est probablement trop abstrait.
  • Écrivez comme l'auteur. Le ton doit être explicatif et naturel — comme si vous expliquiez votre travail à quelqu'un. "Donc le truc principal ici est…" ou "La partie délicate était…" sont acceptables.
  • Évitez les redondances entre l'introduction et le premier segment de contenu.
  • Mentionnez les fichiers qui ne sont pas montrés. Si une PR touche 15 fichiers mais que seulement 6 sont intéressants, reconnaissez brièvement les autres : "Les changements restants sont des exports de type et des fixtures de test." -** Visez 5-7 minutes de narration totale.

Liste de contrôle

  • Lire tous les commits de la PR et comprendre le diff complet
  • Rédiger la narration dans SCRIPT.md (8-12 segments)
  • Générer l'audio par segment (voix Iapetus)
  • Lire durations.json pour obtenir les durées par segment
  • Écrire manifest.json

…

[truncated for translation]

Skills associés