PR-Walkthrough-Video
Erstelle ein vertontes Walkthrough-Video für einen Pull Request. Dieses ist als internes Artefakt gedacht, das den gleichen Nutzen bietet wie ein vom PR-Autor erstelltes Loom-Video – es führt durch die Code-Änderungen, erklärt, was gemacht wurde und warum, damit jeder Zuschauer den PR schnell verstehen kann.
Eingabe: Eine GitHub-PR-URL (z.B. https://github.com/tldraw/tldraw/pull/7924). Wenn nur eine PR-Nummer oder eine andere Beschreibung gegeben wird, wird angenommen, dass der PR im Repository tldraw/tldraw liegt.
Ausgabe: Ein MP4-Video mit 1280×720 (30 fps), Audio-Kommentar, Whisper-getimten gelben Untertiteln auf schwarzem Hintergrund und standardisierten Intro-/Outro-Folien, gespeichert unter out/pr-<nummer>-walkthrough.mp4.
Alle Zwischendateien (Audio, Manifest, Skripte) werden relativ zu diesem Skill-Verzeichnis in tmp/pr-<nummer>/ abgelegt. Dieses Verzeichnis ist gitignoriert. Nur die endgültige .mp4-Datei liegt in out/.
Führe Befehle, die auf ./scripts oder ./video verweisen, von diesem Skill-Verzeichnis aus.
Philosophie
Dies ist ein Walkthrough aus der Perspektive des Autors. Das Ziel ist dasselbe, als ob der PR-Autor mit jemandem zusammensitzt und ihn durch die Änderungen führt – konkreten Code zeigt, erklärt, was sich geändert hat und warum, in einer Reihenfolge, die Verständnis aufbaut. Der Zuschauer soll am Ende sowohl verstehen, was der Code tut, als auch, wie man über die Änderungen denkt.
Das bedeutet:
- Der Kommentar treibt alles. Schreibe zuerst das Walkthrough-Skript als durchgehende Erklärung des PR. Überlege dann, was zu jedem Zeitpunkt auf dem Bildschirm sein sollte, um das Gesagte zu unterstützen.
- Zeige den Code. Die Standard-Ansicht ist ein Code-Diff oder eine Quelldatei. Textfolien sind die Ausnahme (Intro, kurze Übergänge, Outro), nicht die Regel. Wenn der Kommentar über eine Funktion spricht, sollte der Zuschauer diese Funktion sehen.
- Gehe die Änderungen in einer logischen Reihenfolge durch, nicht unbedingt in der Datei- oder Commit-Reihenfolge – aber immer verankert an konkretem Code, nicht an abstrakten Beschreibungen.
- Erkläre das „Warum“, nicht nur das „Was“. Der Code auf dem Bildschirm zeigt, was sich geändert hat. Der Kommentar liefert die Begründung – warum dieser Ansatz, welches Problem er löst, welche Randfälle er behandelt.
Workflow
Schritt 1: Verstehe den PR
Lies die PR-Commits, den Diff und die Beschreibung. Verstehe den erzählerischen Bogen:
- Welches Problem wird gelöst?
- Was ist der Ansatz?
- Was sind die Schlüsselmechanismen?
gh pr view <nummer> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat
Überspringe generierte Dateien. Ignoriere beim Lesen des Diffs Dateien, die automatisch generiert und nicht manuell bearbeitet wurden. Diese fügen Rauschen hinzu, ohne das Walkthrough zu informieren. Häufige Beispiele in diesem Repository:
**/api-report.md,**/api-report.api.md– generierte API-Oberflächenberichte**/*.api.json,**/temp/*.api.json– API-Extraktor-Ausgabeapps/docs/content/reference/**– generierte Referenzdokumentationpnpm-lock.yaml,package-lock.json– Sperrdateien**/CHANGELOG.md– automatisch generierte Änderungsprotokolle- Alle Dateien, die von den Tools des Repositorys neu generiert werden (Schnappschüsse, Schema-Dumps, gebündelte Assets)
Wenn du unsicher bist, ob eine Datei generiert ist, überprüfe auf einen Header-Kommentar wie „DO NOT EDIT“ oder schaue, ob das Repository einen Generator-Befehl hat, der sie erzeugt. Filtere diese heraus, wenn du auswählst, welche Dateien in diff/code-Folien gezeigt werden sollen.
Schritt 2: Schreibe den Kommentar
Schreibe den Kommentar als durchgehenden Text, unterteilt in logische Segmente. Jedes Segment ist ein Takt des Walkthroughs – ein Konzept, eine Änderung oder eine Gruppe zusammengehöriger Änderungen. Speichere dies als tmp/pr-<nummer>/SCRIPT.md.
Der Kommentar sollte klingen, als würde der Autor einem Kollegen den PR erklären: „Also, hier machen wir Folgendes… Das Kernproblem war X… Der Ansatz, den ich gewählt habe, war Y… Wenn du dir diese Funktion hier ansiehst…“
Struktur: Intro → Kontext/Problem → Code-Walkthrough → Zusammenfassung. Siehe Skriptstruktur unten.
Wenn die Commits einfach und gut organisiert sind (oft in einem Branch mit -clean im Namen), kannst du ihre Commit-Nachrichten und -Beschreibungen als Leitfaden für deinen Kommentar verwenden. Andernfalls untersuche den Code und erstelle deine eigene Erzählung. Führe Konzepte in einer Reihenfolge ein, die auf vorherigen aufbaut.
Vermeide Redundanz, insbesondere zwischen Intro und erstem Inhaltssegment.
Schritt 3: Generiere Audio und Zeitstempel
Generiere pro Segment Audio-Clips mit einem TTS-Aufruf pro Segment. Dies vermeidet Chunking, Alignment und Aufteilung vollständig – jedes Segment ist kurz genug für einen einzigen zuverlässigen TTS-Aufruf.
Schreibe eine narration.json-Datei und führe dann das CLI-Tool generate-audio.sh aus:
./scripts/generate-audio.sh narration.json tmp/pr-<nummer>/
API-Schlüssel: Wird automatisch aus der .env-Datei des Repositorys bezogen (GEMINI_API_KEY).
JSON-Format für Narration
{
"style": "Lies den folgenden Walkthrough-Kommentar in einem ruhigen, stetigen, professionellen Ton. Sprich in einem gemessenen Tempo, als ob der Autor eines Pull Requests einen Kollegen durch die Code-Änderungen führen würde.",
"voice": "Iapetus",
"slides": [
"Dieser Pull Request fügt eine gruppenbewusste Bindeauflösung zum Pfeilwerkzeug hinzu...",
"Das Kernproblem war, dass Pfeilbindungen brachen, wenn die Zielform...",
"Wenn du dir die getBindingTarget-Methode in ArrowBindingUtil.ts ansiehst..."
]
}
style– Stimmpersona und Tempovorgaben. Halte es kurz und spezifisch.voice– Gemini-Stimmenname (Standard:Iapetus).slides– Array von Kommentartexten, ein Eintrag pro Segment.
Wie es funktioniert
- Für jedes Segment erstellt das Skript einen Prompt: Style-Präambel + Segmenttext.
- Ein API-Aufruf an
gemini-3.1-flash-tts-previewpro Segment erzeugt direkt einen WAV-Clip. - Jeder Clip wird validiert (Plausibilitätsprüfung der Dauer im Vergleich zur Wortanzahl) und bei schlechter Ausgabe automatisch wiederholt.
- Führende/nachfolgende Stille wird von jedem Clip entfernt.
Ausgabe: Pro-Segment-Audio-Clips (audio-00.wav, ...) und eine durations.json-Datei, die jeden Audio-Dateinamen auf seine Dauer in Sekunden abbildet.
Abhängigkeiten: ffmpeg / ffprobe. Es werden keine Python-Pakete außerhalb der Standardbibliothek benötigt.
Verwende NICHT Markup-Tags wie [pause long] oder [pause medium] im Kommentartext – das Modell könnte sie wörtlich vorlesen.
Schritt 4: Schreibe das Manifest
Lese durations.json aus Schritt 3 für jede Clip-Länge, schreibe dann manifest.json zusammen mit den Audio-Dateien. Es listet einen Eintrag pro Folie in der richtigen Reihenfolge, jeweils mit type, audio und durationInSeconds.
Siehe references/manifest.md für die Folientypen und ihre Felder.
Schritt 5: Rendere das Video
Führe das Skript render.sh aus:
./video/render.sh \
tmp/pr-<nummer>/manifest.json \
out/pr-<nummer>-walkthrough.mp4
Das Skript:
- Kopiert referenzierte Audio-/Bilddateien in
video/assets/. - Führt Whisper-Transkription für jede Audio-Datei aus →
video/transcripts/audio-NN.json(idempotent – transkribiert nur neu, wenn das Audio neuer ist als das vorhandene Transkript). - Führt
build.mjs <manifest>aus, umvideo/index.htmlzu generieren – eine Hyperframes-Komposition mit getimten Clips für jede Folie, GSAP-Timeline für Übergänge und Code-Fokus-Pans sowie gelbe Untertitel-Clips mit Start-/Endzeiten aus den Whisper-Transkripten. - Lint die Komposition und rendert 1920×1080 Frames mit
npx hyperframes render. - Skaliert herunter auf 1280×720 / 30fps und komprimiert mit ffmpeg neu (CRF 26 + AAC 96k) für das endgültige kleine, aber scharfe MP4.
Abhängigkeiten: Node.js 22+, ffmpeg, Python 3 (wird von render.sh zum Parsen des Manifests verwendet). hyperframes wird mit npx --yes aufgerufen, daher kein Installationsschritt. Whisper läuft lokal (small.en-Modell, ~150 MB beim ersten Download).
Untertitel-Synchronisation via Whisper
Untertitel erscheinen als gelber Text auf einem soliden schwarzen Pill, verankert am unteren Bildrand. Ihre Start-/Endzeiten stammen aus Whisper-Wort-Transkripten, die in 5–7-Wort-Blöcke gruppiert werden, mit Unterbrechungen bei natürlichen Pausen (>450ms Lücken = Satzgrenzen). Eine Auswirkung: Whisper transkribiert Marken-/Codenamen phonetisch – „tldraw“ → „TL Draw“, „OverlayUtil“ → „Overlay Util“. Dies ist für Untertitel akzeptabel, könnte aber später durch eine Ersetzungstabelle in build.mjs normalisiert werden.
Stellschrauben für die Dateigröße
Der Standard-Render zielt auf ~30–60 MB für ein 8-minütiges Video ab. Zur Anpassung:
--crf <n>im ffmpeg-Herunterskalierungsschritt inrender.sh– 22 ist nahezu verlustfrei, 26 ist der Standard, 30+ ist viel kleiner. CRF 28–30 ist ein guter Bereich für ein ergebnis in Dokumentationsqualität.- Der 1080p-Hyperframes-Render verwendet
-q draft --crf 30, um die Zwischendatei klein zu halten (die Herunterskalierung dominiert ohnehin die endgültige Größe).
Dateiorganisation
Die endgültige Ausgabe liegt in diesem Skill-Verzeichnis. Alle Zwischendateien kommen in tmp/ (gitignoriert):
pr-walkthrough/
├── SKILL.md # Diese Datei
├── scripts/ # CLI-Tools (eingecheckt)
│ └── generate-audio.sh # narration.json → Pro-Folie-WAVs + durations.json
├── video/ # Hyperframes-Projekt (eingecheckt)
│ ├── hyperframes.json # Hyperframes-Konfiguration
│ ├── meta.json # Projekt-Meta
│ ├── build.mjs # manifest.json → index.html-Komposition
│ ├── render.sh # manifest.json → 720p MP4 (vollständige Pipeline)
│ ├── assets/ # Wird zur Renderzeit automatisch befüllt (gitignoriert)
│ ├── transcripts/ # Whisper-Wort-JSON (gitignoriert, gecached)
│ └── renders/ # Zwischen-Renders in 1080p (gitignoriert)
├── out/ # Endgültige Ausgaben (gitignoriert)
│ └── pr-XXXX-walkthrough.mp4
└── tmp/ # Zwischendateien (gitignoriert)
└── pr-XXXX/
├── SCRIPT.md # Kommentarskript
├── narration.json # Eingabe für generate-audio.sh
├── durations.json # Audio-Dateiname → Dauer in Sekunden
├── manifest.json # Eingabe für render.sh
└── audio-XX.wav # Pro-Segment-Audio-Clips
API-Konfiguration
- Gemini-API-Schlüssel: Gespeichert als
GEMINI_API_KEYin der.env-Datei des Projektstamms. Wird für TTS und Audio-Ausrichtung verwendet. - TTS-Modell:
gemini-3.1-flash-tts-preview - TTS-Stimme:
Iapetus(immer)
Skriptstruktur
Das Walkthrough folgt einem konsistenten erzählerischen Bogen. Nicht jeder Abschnitt benötigt ein eigenes Segment – kombiniere oder überspringe Abschnitte je nach Komplexität des PR. Ziel sind 8–12 Segmente insgesamt, wobei die überwiegende Mehrheit Code zeigt.
Intro (1 Segment)
Die Intro-Karte: tldraw-Logo + PR-Titel + Datum. Der Kommentar sollte ein einzelner Satz sein, der auf hoher Ebene einordnet, was dieser PR tut. Gehe noch nicht ins Detail.
Manifest-Folientyp: intro.
Kontext (0–1 Segmente)
Kurze Orientierung vor dem Eintauchen in den Code. Wie war die Situation vor diesem PR? Welches Problem oder welcher Bedarf hat die Arbeit motiviert? Halte es kurz – genug Einordnung, damit das Code-Walkthrough Sinn ergibt.
- Sei konkret: „Pfeilbindungen brachen, wenn die Zielform innerhalb einer Gruppe war“, nicht „Es gab Probleme mit Bindungen“
- Nenne den betroffenen Bereich der Codebasis
Wenn der Kontext erklärt werden kann, während das erste relevante Code-Stück gezeigt wird, überspringe das eigenständige Kontextsegment und integriere es in das erste Code-Segment.
Manifest-Folientyp: text oder diff (wenn der problematische Code gezeigt wird).
Code-Walkthrough (6–10 Segmente)
Der Hauptteil des Videos. Gehe die tatsächlichen Code-Änderungen durch, zeige spezifische Diffs und Dateien und erkläre, was gemacht wurde und warum.
Jedes Segment sollte Code zeigen. Verwende diff-Folien für Änderungen und code-Folien für unveränderten Referenzcode.
Richtlinien:
- Nenne Dateien und Funktionen. Jedes kommentierte Segment sollte mindestens eine bestimmte Datei oder Funktion referenzieren.
- Zeige den Diff. Die visuelle Darstellung für jedes Segment sollte der tatsächlich besprochene Diff sein. Verwende
git diff main..HEAD -- path/to/file, um den Diff zu erhalten, und extrahiere dann die relevanten Hünken. - Ordne nach Verständnis, nicht nach Datei. Präsentiere Änderungen in der Reihenfolge, die das Verständnis aufbaut. Wenn ein neuer Typ in einer Datei definiert und in einer anderen verwendet wird, zeige zuerst die Definition.
- Erkläre das „Warum“, nicht nur das „Was“. Der Diff zeigt, was sich geändert hat – der Kommentar liefert die Begründung, die behandelten Randfälle, die in Betracht gezogenen Alternativen.
- Überspringe Boilerplate, aber erwähne es. Widme nicht jedem Import oder Typ-Export ein Segment, erwähne es aber beiläufig: „Es gibt auch einige Typ-Exporte in
index.ts– das sind nur Re-Exporte der neuen Typen, die wir als nächstes sehen werden.“ - Gruppiere zusammenhängende kleine Änderungen. Wenn drei Dateien alle die gleiche einzeilige Korrektur erhalten haben, kann ein Segment alle drei abdecken. Nenne jede Datei beim Namen.
Zusammenfassung (1 Segment)
Fasse kurz zusammen, was der PR erreicht hat. Dies ist ein kurzer Abschluss – ein Satz oder zwei, die die Gesamtänderung zusammenfassen, und bei Bedarf bekannte Einschränkungen oder Folgearbeiten erwähnen.
Manifest-Folientyp: text.
Outro (1 Segment, still)
Das tldraw-Logo, 3 Sekunden Stille. Füge dies immer als letzte Folie ein.
Manifest-Folientyp: outro mit durationInSeconds: 3.
Tipps zum Schreiben des Kommentars
- Sei spezifisch in Bezug auf Code. Sage „In
BindingUtil.tsprüft deronAfterChange-Handler jetzt auf Gruppen-Vorfahren“ – nicht „Das Bindungssystem wurde aktualisiert.“ Nenne Dateien und Funktionen, damit der Zuschauer den Kommentar mit dem auf dem Bildschirm Gezeigten verbinden kann. - Jedes Segment = eine Änderung oder eine eng verwandte Gruppe von Änderungen. Wenn du für das Segment nicht auf einen bestimmten Diff zeigen kannst, ist es wahrscheinlich zu abstrakt.
- Schreibe als der Autor. Der Ton sollte erklärend und natürlich sein – wie wenn jemand durch seine Arbeit führt. „Also das Wichtigste hier ist…“ oder „Der knifflige Teil war…“ sind in Ordnung.
- Vermeide Redundanz zwischen Intro und erstem Inhaltssegment.
- Erwähne Dateien, die nicht gezeigt werden. Wenn ein PR 15 Dateien berührt, aber nur 6 interessant sind, erkenne die anderen kurz an: „Die restlichen Änderungen sind Typ-Exporte und Test-Fixtures.“
- Ziele auf 5–7 Minuten Gesamtkommentar.
Checkliste
- Alle PR-Commits gelesen und den gesamten Diff verstanden
- Kommentar in SCRIPT.md geschrieben (8–12 Segmente)
- Pro-Segment-Audio generiert (Iapetus-Stimme)
- durations.json gelesen, um die Dauer pro Segment zu erhalten
- manifest.json geschrieben mit allen Folientypen, Audiodateien und Dauern
- Video gerendert mit render.sh
- Endgültige Ausgabe auf korrekte Auflösung, Dauer und Ton überprüft
- Dateien aus tmp/-Verzeichnissen bereinigt (optional)
Referenzen
references/manifest.md– Vollständige Dokumentation der Manifest-Folientypen und ihrer Felderreferences/hyperframes.md– Hyperframes-Referenz für Folien-Layouts, Animationen und Code-Fokus