Walkthrough-Video

Was macht Walkthrough-Video?

Verwandelt eine laufende Web-App in ein fertiges, vertontes Video, das bei jeder Änderung der App neu generiert werden kann. Alles läuft lokal: kein Video-Editor, kein kostenpflichtiger Dienst.

Erzähltext -> lokale Stimme -> eine WAV pro Szene + Untertitel-Zeitsteuerung
echte App -> Playwright-Szenen -> Clips + Markierungszeiten -> assemble.py -> walkthrough.mp4 + .srt

Warum das so funktioniert: Das Filmmaterial ist die echte App, also immer wahrheitsgetreu; langsame Schritte (eine KI-Antwort, ein Seitenaufbau) werden während der Aufnahme entfernt; und „Markierungen“, die von jeder Szene protokolliert werden, ermöglichen es dem Assembler, den Schlüsselmoment auf die passenden Worte zu legen.

Bevor Sie beginnen

1. Fragen Sie nur nach dem, was fehlt: Welche App es ist und was das Video zeigen muss, wer es sieht, die gewünschte Länge (2 bis 4 Minuten sind gut), der Ton.
2. Prüfen Sie die Tools (Details in references/setup.md): Node 20+, Playwright mit Chromium, FFmpeg mit xfade, zoompan, loudnorm, libx264 und Python 3.11 oder 3.12 mit kokoro-onnx. Installieren Sie die Stimme (etwa 350 MB) außerhalb des Repos, z. B. in ~/video-tools.
3. Kopieren Sie die Arbeitsdateien in das Projekt des Benutzers und halten Sie generierte Ausgaben aus Git heraus:

   mkdir -p e2e/video-kit && cp -R <this skill>/scripts/. e2e/video-kit/ && cp <this skill>/templates/*.mjs e2e/video-kit/
   printf '\ne2e/video-kit/clips/\ne2e/video-kit/vo/\ne2e/video-kit/build/\ne2e/video-kit/*.mp4\ne2e/video-kit/*.srt\ne2e/video-kit/spec.json\ne2e/video-kit/.*.json\n' >> .gitignore
   

   Die Skripte schreiben ihre Ausgaben neben sich selbst, deshalb werden sie kopiert und nicht von hier aus ausgeführt.
4. Lesen Sie references/toolkit-api.md einmal durch. Es dokumentiert die Recorder-Hilfsfunktionen und die PLAN-Syntax. Bearbeiten Sie nicht rec.mjs, speak.py, overlays.mjs oder assemble.py; bearbeiten Sie nur die Teile, die der Leitfaden nennt.

Der Workflow: drei Tore

Halten Sie an jedem Tor an und warten Sie auf den Benutzer. Formulierungen und Struktur sind billig zu ändern, bevor die Aufnahme beginnt, und teuer danach.

Tor 1: Storyboard. Sehen Sie sich das Projekt an (seine Dokumentation, Routen, vorhandene Playwright-Tests) und schlagen Sie 8 bis 12 Szenen vor. Für jede: Was auf dem Bildschirm zu sehen ist, der Erzähltext (20 bis 35 Wörter, einfach) und wie sie aufgenommen wird. Fügen Sie Eröffnungsfolien hinzu, wenn der Benutzer Kontext wünscht: das Problem, was getan oder geprüft wurde, die Lösung und der Stack. Beschreiben Sie nichts, was die App nicht wirklich tut; fragen Sie bei Unsicherheit nach.

Tor 2: Text und Stimme. Schreiben Sie chunks.txt als szene|text-Zeilen mit jeweils maximal 12 Wörtern (jede Zeile wird ein Untertitel). Fügen Sie Produktnamen und Akronyme zu PRONOUNCE in speak.py hinzu. Führen Sie python speak.py aus und melden Sie die Länge jeder Szene. Der Benutzer hört zu und gibt seine Zustimmung, bevor eine Aufnahme beginnt.

Tor 3: Aufnehmen, zusammenbauen, prüfen.

1. Schreiben Sie die Szenen in scenes.mjs (beginnen Sie mit scenes.template.mjs), ein Clip pro Szene, benannt als scene-N passend zum Standardplan. Nehmen Sie jede Szene einzeln im Hintergrund auf: node scenes.mjs <name>. Nur die fehlgeschlagenen neu aufnehmen.
2. Rendern Sie Folien, falls verwendet (slides.template.mjs), dann füllen Sie PLAN und LABEL in assemble.py aus: Welcher Clip in welcher Szene gezeigt wird und welche Markierung auf welche Erzählzeile fällt.
3. Führen Sie python assemble.py all aus. Es erstellt walkthrough.mp4 und walkthrough.srt.
4. Prüfen Sie das Ergebnis anhand eines Kontaktblatts (ein bis zwei Frames pro Szene, gekachelt) und nicht vieler einzelner Bilder: Namen, Daten, Untertitel, nichts abgeschnitten, nichts Privates. Korrigieren, neu zusammenbauen, ausliefern.

Wichtige Regeln

• Datenschutz. Verwenden Sie ein Demo- oder Testkonto. Blurren oder verdecken Sie alles, was echte Personen, E-Mails, Telefonnummern, Kontonamen, Schlüssel, IDs, Token oder Abrechnungen zeigt (opts.cover, opts.init). Gehen Sie niemals mit Passwörtern um: Wenn eine Szene einen Login benötigt, lassen Sie den Benutzer einmal in einem sichtbaren Browser manuell einloggen (templates/auth.template.mjs) und verwenden Sie die gespeicherte Sitzung erneut. Geben Sie niemals Passwörter oder 2FA-Codes ein oder zeigen Sie sie vor der Kamera. Halten Sie .env, gespeicherte Logins und Browserprofile aus Git heraus.
• Nicht auf echten Konten handeln. Klicken Sie niemals auf etwas, das auf Live-Konten sendet, veröffentlicht, plant oder löscht. Fahren Sie mit der Maus über die Schaltfläche und sagen Sie, was sie tut.
• Keine erfundenen Funktionen. Beschreiben Sie nur, was der Code und die laufende App tun.
• Sprache und Mikrofon-Audio können nicht vom Browser erfasst werden. Zeigen Sie die Benutzeroberfläche und sagen Sie, was passiert.
• Überprüfen Sie Ports, bevor Sie Server starten; stoppen Sie alles, was Sie gestartet haben. Führen Sie alles, was länger als eine Minute dauert (Aufnahme, Stimme, Zusammenbau), im Hintergrund aus und warten Sie darauf, anstatt in einer Schleife zu pollieren.
• Halten Sie Antworten kurz. Berichten Sie, was Sie getan haben, Dateipfade und alles, was Sie nicht überprüfen konnten.

Erkenntnisse aus der Praxis

Lesen Sie references/lessons.md vor dem Schreiben der Szenen. Die Kurzfassung: Überprüfen Sie, ob gesäte Daten wirklich existieren (zufällige Testdaten können mit älteren Daten kollidieren); warten Sie auf einen Locator, der beweist, dass eine langsame Seite geladen hat; löschen Sie gespeicherte Suchfilter vor der Eingabe; schließen Sie Pop-ups; verlinken Sie direkt auf Datensätze; verpacken Sie nicht wesentliche Verzierungen, sodass ein Fehler keine Szene stoppen kann; und halten Sie die unteren 200px der Folien für Untertitel frei.

Dateien

• scripts/rec.mjs Recorder: gleitender Cursor, Klick-Wellen, Zoom, Markierungen, think() zum Kürzen von Wartezeiten.
• scripts/speak.py Erzähltext zu WAVs und Untertitel-Zeitsteuerung.
• scripts/overlays.mjs Untertitel, Beschriftungen und Titelbilder als Bilder.
• scripts/assemble.py Passt Clips an die Stimme an, fügt zusammen, überlagert, mischt Audio, schreibt MP4 und SRT.
• templates/ Startpunkte für Szenen, einen gespeicherten Login, Folien und die Erzähltext-Datei.
• references/ Der Toolkit-Leitfaden, Einrichtung und Erkenntnisse.

Wenn etwas fehlschlägt

• Sprachausgabe schlägt fehl mit espeakng_loader/phontab: No such file: siehe references/setup.md.
• Eine Szene timeoutet beim Warten auf Text: Die Seite hat möglicherweise noch nicht fertig gezeichnet, oder ein gespeicherter Filter verdeckt das Element. Machen Sie einen Screenshot beim Fehler und schauen Sie nach.
• Das Video zeigt eine Wartezeit: Wickeln Sie den langsamen Schritt in think() ein.
• Bild und Stimme driften auseinander: Nehmen Sie die Szene neu auf, da sich die Markierungszeiten ändern, wenn sich ein Skript ändert.