jeider05/narrated-evidence

Aktivierungsvertrag

Laden, wenn der Benutzer ein Video mit Sprachausgabe möchte, das eine Funktion erklärt oder einen Fehler reproduziert, oder wenn Screenshots allein keinen Ablauf zeigen können (Timing, Reihenfolge, sich ändernder Zustand). Für einen einzelnen statischen Zustand reicht ein Screenshot: nicht aufnehmen.

Das CLI befindet sich in C:\Users\DESARROLLADORES\Documents\personal\ai-video-evidence (node bin/narrate.mjs). Es benötigt Node 22+, ffmpeg/ffprobe im PATH, Google Chrome und pip install edge-tts.

Harte Regeln

• Schreibe zuerst das Drehbuch (narration.json), validiere es und nimm dann auf. Niemals von Hand aufnehmen und kommentieren.
• Eine Szene = eine Idee und ein oder zwei Sätze. Die Stimme muss beschreiben, was in dieser Szene auf dem Bildschirm zu sehen ist, niemals, was als Nächstes kommt.
• Die Erzählsprache entspricht dem Publikum (Spanisch für Trip2 PRs). Standardstimme es-CO-SalomeNeural; männlich: es-CO-GonzaloNeural.
• Niemals Passwörter eingeben. Bei authentifizierten Apps führt der Benutzer narrate login <url> aus und meldet sich an; setze browser.storageState auf die gespeicherte Datei. Lösche diese Datei nach der Aufnahme und halte sie aus Git heraus.
• Verwende nur vom Benutzer bestätigte Testdaten. Neue Datensätze erhalten ein QA_-Präfix; bearbeite oder lösche niemals vorhandene Datensätze.
• Halte Ausgaben aus Git heraus (out/, pr-assets/).
• Nichtdeterministische Abläufe (LLM, asynchrone Jobs): Überprüfe das Ergebnis in den aufgezeichneten Frames. Wenn die App etwas anderes tut, als die Erzählung sagt, nimm erneut auf; versende niemals ein Video, dessen Stimme dem Bildschirm widerspricht.

Entscheidungstabellen

Situation	Aktion
Fehlerbericht	assets/bug-template.json: Kontext → Schritte → Ist-Zustand (roter Callout) → Soll-Zustand (grün) → Beweis → Auswirkung
Feature / PR-Demo	assets/feature-template.json: Was wird gelöst → Durchlauf → Randfälle
Backend-Wartezeit oder langsames Laden	In eine eigene Szene mit "speedup": 4 packen; nur der Teil nach der Erzählung wird beschleunigt
Nativer <select>-Popup, OS-Dialog oder die App benötigt die reale Ego-Sitzung des Benutzers (Trip2 eingeloggt)	"recorder": "gdigrab" (nur Windows). Vor dem Ausführen: der Benutzer meldet sich in der App in ego an, hält Monitor 1 frei und ist bereit, ego auf den Task-Bereich narrate-<name> umzuschalten, wenn der Runner dies anfordert (ego behält Agent-Fenster versteckt; der Runner hebt es mit Win32 hervor, aber ego malt nur den ausgewählten Bereich). Unbeaufsichtigter Lauf = playwright verwenden
gdigrab-Skript verwendet call/actionsModule oder waitForResponse	Nicht unterstützt (Validierungsfehler): ein echtes Backend oder einen lokalen Server verwenden (examples/bug-demo/server.mjs) und waitFor auf das UI-Ergebnis
gdigrab-Lauf schlägt fehl mit "never became visible on screen"	Das Task-Bereich-Fenster war versteckt oder verdeckt. Bitte den Benutzer, den Bereich in ego auszuwählen und erneut auszuführen; den eigenen Bereich oder Tabs des Benutzers nicht beanspruchen oder wiederverwenden
Mocking oder komplexe Schritte erforderlich	actionsModule mit exportierten async (page, ctx)-Funktionen, aufgerufen mit { "call": "name" }
Beweisschritt eines Fehlers	out/<name>/evidence.json (fehlgeschlagene Antworten, Konsolenfehler) aus einem ersten Lauf lesen und die tatsächliche Anfrage/Status in den evidencia-Callout einfügen

Ausführungsschritte

1. Kopiere die passende Vorlage neben die Arbeit (Trip2: pr-assets/<name>.json) und fülle title, baseUrl, Szenen, Selektoren aus.
2. node bin/narrate.mjs validate <datei>; korrigiere jeden gemeldeten Pfad.
3. Wenn die App eine Sitzung benötigt: bei playwright den Benutzer bitten, node bin/narrate.mjs login <url> --save pr-assets/state.json auszuführen, dann browser.storageState setzen. Bei gdigrab meldet sich der Benutzer vorher in der App in ego an (Trip2-Pfad: baseUrl = die lokale Trip2-URL, recorder: "gdigrab", kurze Szenen, kein call).
4. node bin/narrate.mjs run <datei> (oder tts, record, assemble separat; assemble allein rendert neu, ohne erneut aufzunehmen).
5. Ergebnis prüfen: Frames zu Szenenbeginnen extrahieren (scenes.json) mit ffmpeg -ss <t> -frames:v 1 und ansehen; Audio mit volumedetect bestätigen; evidence.json lesen (bei gdigrab leer). Bei gdigrab bestätigen, dass die Frames nur die Seite zeigen (kein Desktop, Taskleiste oder anderes Fenster darüber).
6. <name>.mp4 (H.264 + AAC + weiche Untertitel) und <name>.srt ausliefern. Für Trip2 PRs folge trip2-pr-delivery: Artefakte in pr-assets/, an den PR angehängt, in der Beschreibung aufgelistet.

Aktionsreferenz

goto (relativ zu baseUrl), click, hover, check (Selektor), fill/select {selector, value}, press {key, selector?}, scroll {selector? | y?}, wait (ms), waitFor (Selektor oder {selector, state, timeoutMs}), waitForResponse (URL-Teilzeichenfolge, akzeptiert auch eine bereits in der Szene gesehene Antwort), overlay {kind: actual|expected|info, title?, text | html, durationMs?}, screenshot (Name), call (Export von actionsModule). Selektoren sind Playwright-Locators (#id, text=Guardar, role=button[name="Guardar"]). Mit recorder: "gdigrab" werden Selektoren unverändert an ego weitergegeben: rohes CSS, text=..., loc=role:button[name='Guardar'], @ref; call und waitForResponse werden abgelehnt; check, scroll {selector} und waitFor verwenden page.evaluate/waitForFunction für rohe CSS-Selektoren.

Szenenfelder: id (Slug), say, chapter {title, description?, durationMs?}, actions, speedup. Oberste Ebene: title, baseUrl, recorder (playwright | gdigrab), gdigrab {framerate: 25, drawMouse: true, tab: "new"}, viewport (nur Playwright), tts {engine: edge|deepgram|sapi, voice, rate, fallback}, browser {channel, headless, locale, storageState}, captions, showActions, gapMs, actionsModule, output.

Ausgabevertrag

Rückgabe: Videopfad und -dauer, SRT-Pfad, verwendete TTS-Engine (und etwaiger Fallback), Szenen mit ihren Startzeiten, was evidence.json erfasst hat, und alles, was nicht gezeigt werden konnte (native Popups, instabile Schritte).

Referenzen

• assets/bug-template.json, assets/feature-template.json — Skript-Grundgerüste.
• Repository README.md — Installation, Befehle, Funktionsweise der Synchronisation.
• examples/bug-demo/ — vollständiges funktionierendes Beispiel mit einem gemockten Backend (narration.json, Playwright) und der gdigrab-Variante (narration-ego.json + server.mjs).