Walkthrough-Video

Was macht Walkthrough-Video?

Verwandle „Erkläre diese Funktion“ in ein kurzes MP4: die echte App auf dem Bildschirm, eine Stimme, die sie erklärt, Untertitel, ein Cursor, der sich wie ein Mensch bewegt, und ein Ring um das, was gerade besprochen wird. Der Benutzer gibt das Briefing und prüft das Ergebnis. Du erledigst alles andere.

Die Arbeit hat einen Prüfschritt, der über allen anderen steht: Der Benutzer genehmigt das Skript, bevor irgendetwas aufgezeichnet wird. Eine Umformulierung kostet Sekunden in einem Skript und Minuten in einem Video, und eine falsche Behauptung ist auf dem Papier viel günstiger zu erkennen.

Was du brauchst

• Den Quellcode der App und eine Instanz, die du öffnen und anmelden kannst (lokal oder eine Dev-/Staging-Umgebung). Zeichne niemals gegen die Produktion auf: Der Take klickt auf echte Buttons.
• Playwright im Projekt der App (node_modules/playwright oder @playwright/test). Die meisten Projekte mit E2E-Tests haben es bereits. Wenn nicht: npm i -D playwright && npx playwright install chromium.
• ffmpeg und python3 im PATH.
• Einen Text-to-Speech-Schlüssel für die endgültige Stimme (Murf oder ElevenLabs). Ohne einen verwendet --provider say die macOS-Stimme, die für einen Entwurf ausreicht. Siehe references/voices.md.

Überprüfe diese zuerst und sage klar, was fehlt. Bitte den Benutzer nicht, einen API-Schlüssel in den Chat einzufügen: Bitte ihn, ihn in eine Umgebungsvariable oder eine git-ignorierte Datei zu setzen und dir mitzuteilen, wo sie ist.

Der Workflow

1. Das Briefing aufnehmen

Du brauchst vier Dinge. Frage nur nach dem, was die Anfrage nicht bereits sagt.

• Ziel und Zielgruppe. „Mit dem CTO auf der neuen Berechtigungsseite abstimmen“ produziert ein anderes Video als „Neuen Mitgliedern beibringen, wie man eine App veröffentlicht“. Die Zielgruppe bestimmt die Länge, das Vokabular und wie viel erklärt werden muss.
• Der Ablauf. Was gezeigt werden soll, in der richtigen Reihenfolge. Wenn der Benutzer einen angibt, verbessere ihn und sage, was du geändert hast und warum: eine bessere Reihenfolge, ein fehlender Schritt, ein Schritt, der nichts bringt. Sie haben nach einem Video gefragt, nicht nach einer Transkription ihrer Liste.
• Länge. Standardmäßig 60-120 Sekunden und ein Thema. Wenn der Ablauf mehr benötigt, schlage zwei Videos vor.
• Stimme. Anbieter und Stimme, falls sie eine Präferenz haben. Ansonsten verwende die Standardeinstellungen.

2. Den Ablauf in der echten App durchgehen, bevor du ein Wort schreibst

Starte die App, melde dich mit einem Demo-Konto an und führe jeden Schritt des Ablaufs selbst mit Playwright oder dem Browser aus. Du überprüfst, dass alles, was die Erzählung behaupten wird, auch wahr ist.

Hier liegt der meiste Wert dieses Skills. Funktionen werden oft aus dem Gedächtnis oder anhand des Lastenhefts beschrieben, und die App macht etwas leicht anderes. Wenn die App nicht das tut, was der Benutzer gesagt hat, stoppe und informiere ihn mit deiner Beobachtung. Schreibe keine Erzählung, die darüber hinwegtäuscht, und lasse den Schritt nicht stillschweigend weg.

Notiere dir die genauen Bezeichnungen auf Buttons und Menüs, während du dort bist. Die Erzählung sollte die Wörter auf dem Bildschirm verwenden.

3. Demo-Daten anlegen

Ein Walkthrough auf einem leeren oder halb defekten Konto sieht aus wie ein Bug-Report. Erstelle, was die Geschichte braucht: eine Organisation, ein paar Benutzer mit unterschiedlichen Rollen, Elemente mit glaubwürdigen Namen. Verwende nur erfundene Namen (Acme, Northwind, example.com): Diese Videos werden weitergeleitet.

Führe eine Liste von allem, was du erstellst oder änderst. Du wirst es in Schritt 9 rückgängig machen.

4. Das Skript schreiben, dann für die Überprüfung anhalten

Schreibe es als Tabelle und speichere es neben dem Ort, an dem das Video abgelegt wird, als <nn>-<slug>.script.md:

| # | Auf dem Bildschirm | Voice-Over | ~Sek |
|---|---|---|---|
| 1 | Aufgabenliste im Ruhezustand. Ring auf der Liste. | Das ist die Team-Aufgabenliste. / Alle im Team sehen die gleichen Aufgaben. | 5 |
| 2 | Cursor zu **Aufgabe hinzufügen**, Formular öffnet sich. Gib einen Namen ein, klicke **Aufgabe speichern**. | Um eine hinzuzufügen, wähle Aufgabe hinzufügen, / gib ihr einen Namen, / und speichere sie. | 7 |

Der / teilt die Erzählung einer Szene in Untertitelzeilen. Lese references/narrative.md, bevor du schreibst: Es behandelt Tempo, Zeilenlänge, Vorher-/Nachher-Karten und die Fehler, die diese Videos schwer verständlich machen.

Zeige dem Benutzer die Tabelle und warte. Gib die erwartete Gesamtlänge an. Falls du ihren Ablauf geändert hast, teile dies hier mit. Fahre nur fort, wenn sie zustimmen; wenn sie Änderungen wünschen, sende die überarbeitete Tabelle erneut.

5. Die Sprachausgabe generieren

Schreibe die genehmigte Erzählung in scenes.json, ein Eintrag pro Zeile, Zeilen geteilt an den /-Markierungen:

[{ "id": "02", "lines": ["Um eine hinzuzufügen, wähle Aufgabe hinzufügen,", "gib ihr einen Namen,", "und speichere sie."] }]

python3 scripts/tts.py scenes.json --audio-dir work/audio --provider murf

Dies schreibt einen Clip pro Szene und durations.json. Die Stimme kommt absichtlich vor der Aufnahme: Jede Szene wird auf dem Bildschirm gehalten, solange ihr Clip dauert, daher müssen die Clip-Längen zuerst existieren. Ein erneutes Ausführen generiert nur Szenen neu, deren Text sich geändert hat.

6. Das Aufzeichnungsskript schreiben und einen Probelauf machen

Kopiere example/record.cjs und schreibe seine Szenen für diesen Ablauf um. scripts/walkthrough.cjs bietet dir:

Helfer	Verwendung
scene(id, async () => {...})	Eine erzählte Szene. Zeigt ihre Untertitel und wartet, bis die Stimme fertig ist.
clickAt(locator)	Gleite mit dem Cursor zum Element, zeige den Druck, klicke es. Verwende dies, nicht locator.click(), sonst passieren Dinge ohne sichtbare Ursache.
moveTo(locator)	Zeige auf etwas, ohne zu klicken.
typeInto(locator, text)	Klicke ein Feld und tippe mit lesbarer Geschwindigkeit.
ring(locator) / ring(null)	Hebe hervor, worüber die Stimme spricht; entferne es, wenn die Stimme weitermacht.
step('Schritt 2 von 4 · Speichern')	Das Label unten links, das dem Zuschauer zeigt, wo er sich befindet.
card({ title, subtitle })	Vollbild-Titelkarte, für die Schlussszene.
card({ before, after })	Vorher-/Nachher-Vergleich. card(null) blendet es aus.
login: async (page) => {...}	Option von record(). Meldet sich hinter den Kulissen an, sodass das Video dort beginnt, wo die Geschichte beginnt.

Bevorzuge Rollen- und Label-Locators (getByRole, getByLabel) gegenüber CSS: Sie überleben ein Restyling und sind die Namen, die die Erzählung verwendet. Lese Namen zur Laufzeit vom Bildschirm ab, wenn die Daten in verschiedenen Umgebungen unterschiedlich sein können.

Führe es zuerst mit dry aus:

node record.cjs <app-repo> work/rec work/audio/durations.json dry

Ein Probelauf zeichnet nichts auf und wartet nicht auf die Stimme, also kostet ein falscher Selektor Sekunden, nicht einen kompletten Take. Behebe Fehler, bis jede Szene läuft.

7. Aufnehmen und zusammenfügen

node record.cjs <app-repo> work/rec work/audio/durations.json
python3 scripts/mux.py --rec work/rec --audio-dir work/audio --output walkthrough-videos/<nn>-<slug>.mp4

Der Rekorder gibt die Clip-Länge jeder Szene neben der Dauer ihrer Aktionen aus. Eine Szene, die nach der Stimme mit Sekunden Stille markiert ist, hat zu viel Aktion für das, was gesagt wird: Kürze die Aktionen oder gib der Stimme mehr zu sagen.

mux.py schreibt die MP4-Datei, eine passende .srt-Datei und <name>.sheet.jpg.

8. Überprüfe es selbst, bevor der Benutzer es tut

Öffne das Kontaktblatt: ein Bild pro Szene. Achte auf einen Ring auf dem falschen Element oder fehlend, einen Untertitel, der das Besprochene verdeckt, eine Szene auf dem falschen Bildschirm, ein Dev-Tools-Abzeichen oder Error-Toast im Bild, echte persönliche Daten. Extrahiere mit ffmpeg einzelne Bilder, wenn das Blatt zu klein ist, um es zu erkennen.

Übergib dann das Video mit: seiner Länge, was sich gegenüber dem genehmigten Skript geändert hat (falls etwas), und allem, was du nicht überprüfen konntest.

Wenn der Benutzer Änderungen wünscht, gehe zuerst zum Skript zurück. Überarbeite die Tabelle, zeige sie, hole das Ja, und generiere dann nur das Geänderte neu. Das meiste Feedback („zu schnell“, „ich habe den Überblick verloren, was sich geändert hat“, „erwähne auch den Filter“) ist Feedback zum Skript, und es nur in der Aufnahme zu beheben, erzeugt ein Video, das nicht mehr zu seinem Skript passt.

9. Dinge rückgängig machen

Mache rückgängig, was der Take geändert hat, unter Verwendung der Liste aus Schritt 3 und dessen, was die Aufnahme selbst angeklickt hat: geänderte Einstellungen, erstellte oder entfernte Elemente, Zustand der Demo-Konten. Teile dem Benutzer dann mit, was wiederhergestellt ist und was du bewusst belassen hast (z. B. Seed-Daten, die sie für das nächste Video vielleicht behalten möchten). Wenn etwas nicht rückgängig gemacht werden kann, sage es.

Dateien

Die Ergebnisse gehen zusammen an einen Ort, den der Benutzer finden kann, standardmäßig walkthrough-videos/ im Projekt:

walkthrough-videos/
  03-add-a-task.mp4
  03-add-a-task.srt
  03-add-a-task.script.md

Halte die Arbeitsdateien (scenes.json, Audio, Rohaufnahme, das Aufzeichnungsskript) außerhalb des Repositorys oder in einem git-ignorierten Ordner. Sie sind groß, und das Aufzeichnungsskript enthält Selektoren für einen bestimmten Moment im Leben der App. Das Skript und die .srt-Datei sind es wert, aufbewahrt zu werden: Sie machen die nächste Überarbeitung zu einer kleinen Änderung.

Dinge, die schief gehen können

• Native Steuerelemente werden nicht aufgezeichnet. Ein natives <select>-Dropdown, eine Dateiauswahl oder ein Browser-Dialog wird vom Browser außerhalb der Seite gezeichnet. Zeige mit moveTo auf das Steuerelement, setze den Wert mit selectOption / setInputFiles und lasse die Erzählung sagen, was ausgewählt wurde.
• Das Overlay verschwindet nach der Navigation. Es wird bei jedem Seitenaufbau neu erstellt und der aktuelle Schritt sowie die Untertitel werden wiederhergestellt. Wenn eine Seite document.body vollständig ersetzt, rufe step() erneut auf, nachdem sie sich beruhigt hat.
• Eine Szene beginnt, bevor die Seite bereit ist. Warte auf das, worum es in der Szene geht (await locator.waitFor()), bevor du scene() aufrufst, nicht innerhalb davon, damit die Ladezeit nicht mit Erzählung überbrückt wird.
• Die ersten Sekunden sind eine leere Seite. mux.py trimmt alles vor der ersten Szene. Führe Navigation und Warten vor scene('01') durch.
• Anmeldung vor der Kamera. Verwende die login-Option. Niemand muss ein Passwortfeld sehen, und Anmeldedaten dürfen in einem geteilten Video nicht sichtbar sein.