video-qa

Was macht video-qa?

Analysiert eine Demo-MP4 anhand des zugehörigen Storyboards und gibt eine Checkliste mit Zeitstempeln aus, wie ein scharfer menschlicher Tester sie verfassen würde. Zwei Ebenen: ein deterministischer Prüfschritt (ffmpeg/ffprobe/node – mechanische Erkennung, keine Modelllogik) und ein frischer Analyse-Subagent, der auf der Grundlage des kompakten JSON-Reports und einer begrenzten Anzahl von Frames aus dem Drehbuch argumentiert.

Harte Regel: Die Analyse wird IMMER in einem frischen Subagenten ausgeführt

Der Aufrufer (Sie, im Hauptthread) erledigt das Minimum:

1. Die Eingaben lokalisieren.
2. Das Prüfskript ausführen.
3. Einen frischen, unabhängigen Subagenten (das Agent-Tool) erstellen, der die Analyse durchführt.
4. Die Problemliste des Subagenten an den Benutzer weiterleiten.

Lesen Sie niemals die extrahierten Frames ein oder argumentieren Sie im aufrufenden Thread über den Bericht. Der ganze Sinn ist die Token-Isolierung: Ein 5-minütiges Video erzeugt ~50 Frames und einen großen JSON-Bericht; deren Auswertung kostet Zehntausende von Tokens an Bildern + Analyse. Wenn das in den Kontext des Aufrufers gelangt, vergiftet es die gesamte Sitzung. Der Subagent absorbiert es und gibt nur die kurze Problemliste zurück. Dies ist nicht optional oder ein "wenn es gerade passt" – jeder video-qa-Aufruf übergibt die Aufgabe. Siehe references/handoff.md.

Schritt 1 – Eingaben sammeln

Sie benötigen:

• Videopfad – die zu prüfende MP4 (der fertige Schnitt, den ein Prüfer sehen würde).
• Storyboard / Drehbuch – die beabsichtigten Beats in der richtigen Reihenfolge, Zeiterwartungen und was jedes Segment zeigen soll. Wenn der Benutzer keins angegeben hat, fragen Sie danach (oder nach dem Issue oder dem demo-video-Storyboard, aus dem es stammt). Erfinden Sie keine Beats.
• Erwartete Karten – die geplanten Karten (Titelseite, Agenda, jede Zwischenkarte, Zusammenfassung) in der richtigen Reihenfolge. Schreiben Sie sie in eine kleine JSON-Datei für --cards-file: ein Array von { "label": "Titelseite (Titel + Untertitel)" }-Einträgen (fügen Sie "minRead": <sec> hinzu, um die Lesezeit-Leiste für eine wortreichere Karte zu überschreiben). Dies treibt den deterministischen Kartenabgleich – ein erstklassiges Ergebnis, da Karten dem Drehbuch entsprechen.
• Branding – Karten-/Hintergrundfarben und Cursor-/Annotationsfarben, damit die Prüfung Markenkarten klassifizieren und der Subagent den Kontrast überprüfen kann. Standardwerte falls nicht angegeben: nachfragen; keine Marke erraten.

Schritt 2 – Die deterministische Prüfung ausführen

node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
  --video "<absoluter/pfad/zu/video.mp4>" \
  --out   "<arbeitsverzeichnis>/video-qa-report.json" \
  --frames-dir "<arbeitsverzeichnis>/video-qa-frames" \
  --card-rgb 15,81,255 \          # die Marken-Kartenfarbe als R,G,B (z.B. #0F51FF)
  --cards-file "<arbeitsverzeichnis>/karten.json"   # die erwarteten Storyboard-Karten, in Reihenfolge

Verwenden Sie ein temporäres <arbeitsverzeichnis> (z. B. unter /tmp), nicht das Repository des Benutzers. Die Prüfung schreibt den JSON-Bericht und den begrenzten Frame-Satz und gibt den Berichtspfad aus. Sie führt drei Vollvideo-Filterdurchläufe durch (Einfrieren, Szenenschnitt, Bewegung) plus Stichproben pro Szene – rechnen Sie mit ~1–1,5× der Videolänge. Einstellbare Parameter (alle optional, sinnvolle Standardwerte): --card-tol, --demo-freeze, --annot-freeze, --card-min-read (Lesezeit-Leiste, 2,5s) und --annotate-rgb R,G,B – die Annotations-Callout-Farbe. Wenn angegeben, wird eine Dead-Air-Region mit einem "Schau her"-Annotationsring in dieser Farbe als beabsichtigtes Tempo (annotated: true) behandelt und nicht in die Hauptzählung der Dead-Air aufgenommen, sondern als Defekt gemeldet. Siehe references/detectors.md für Details zu jedem Detektor und warum die Schwellwerte dort gesetzt sind.

Die Erkennung von Annotationen ist auf Dead-Air-Regionen beschränkt, daher bedeutet annotatedRegionCount: 0 NICHT "keine Annotationen im Video". Ein Ring wird nur registriert, wenn er mit einer angehaltenen/eingefrorenen Spanne zusammenfällt; wenn der Build Dead Air wegschneidet (oder der Ring über Bewegung abgespielt wird), wird der Ring zwar auf dem Bildschirm angezeigt, aber keine Dead-Air-Region trägt ihn – der Zähler ist konstruktionsbedingt 0. Melden Sie niemals fehlende Annotationen allein aufgrund dieser Zahl; wenn ein Beat mit einem Ring versehen sein soll, bestätigen Sie dies anhand der Frames dieses Segments (der span-*-Frame pro Szene, oder ziehen Sie den Frame zum Zeitstempel der Annotation).

Überprüfen Sie die ausgegebene Zusammenfassung (Spanne-Zahl, Dead-Air-Regionen, Glitch-Zahl, Frame-Zahl und cardCheck.countMatches) vor der Übergabe. Wenn cardSpans 0 ist, ist --card-rgb wahrscheinlich falsch – korrigieren Sie es und führen Sie es erneut aus, da sonst jede Karte als ui gelesen wird und die Einfrier-/Dead-Air-/Karten-Klassifizierung bedeutungslos ist. Wenn cardCheck eine nicht übereinstimmende Anzahl anzeigt, ist das ein echter Befund (eine fehlende oder zusätzliche Karte), kein Prüffehler – lassen Sie den Subagenten dies anhand der Frames bestätigen.

Schritt 3 – An den Analyse-Subagenten übergeben

Erstellen Sie einen frischen Subagenten mit dem Agent-Tool (subagent_type: general-purpose). Bauen Sie seinen Prompt aus references/analysis-prompt.md, wobei Sie ersetzen:

• {{REPORT_PATH}} → den --out-Pfad aus Schritt 2.
• {{FRAMES_DIR}} → den --frames-dir-Pfad.
• {{OUT_FINDINGS}} → einen Pfad für die Ergebnisdatei, die Sie lesen werden (z. B. <arbeitsverzeichnis>/video-qa-findings.md).
• {{STORYBOARD}} → die beabsichtigten Beats aus Schritt 1, wörtlich.
• {{BRANDING}} → die Branding-Regeln aus Schritt 1.

Weisen Sie den Subagenten – als explizite Anweisung in seinem ersten Prompt – an, seine Ergebnisse als letzten Schritt in {{OUT_FINDINGS}} zu SCHREIBEN. Das Lesen dieser Datei ist der zuverlässige Abrufpfad: Die finale Textnachricht eines erstellten Agenten wird nicht immer an den Aufrufer übermittelt, und nachfolgende "Senden Sie mir Ihre Ergebnisse"-Pings treffen oft auf einen inaktiven Agenten, der sich nicht wieder einschaltet. Die Datei enthält nur die Problemliste (keine Frames), sodass die Token-Isolierung nicht gebrochen wird. Der Subagent liest weiterhin den Bericht + die Frames und argumentiert Beat für Beat; er speichert das Ergebnis nur dort, wo Sie es lesen können.

Schritt 4 – Weiterleiten

Lesen Sie die Ergebnisdatei ({{OUT_FINDINGS}}) und geben Sie die Problemliste unverändert an den Benutzer weiter (sie ist bereits im Lieferformat). Fügen Sie nichts aus Ihrer eigenen Argumentation über die Frames hinzu – Sie haben sie planmäßig nie angesehen. Wenn der Benutzer sie als gebrandetes HTML-Artefakt wünscht, ist das ein separater Folgeschritt.

Überprüfen Sie "konnte nicht ermittelt werden"-Einträge stichprobenartig, bevor Sie sie als Defekte behandeln. Die Prüfung tastet einen begrenzten Satz von Frames ab (Dutzende, nicht jeden Frame), sodass ein Beat, der tatsächlich stattgefunden hat, zwischen die Abtastungen fallen und als "konnte nicht ermittelt werden" oder als "sieht nach Seitenwechsel / nicht angezeigt" markiert werden kann – eine Abtastungslücke, keine echte Abwesenheit. Dies sind die Befunde, bei denen ein Irrtum am wahrscheinlichsten ist. Ziehen Sie für jeden solcher Einträge die wenigen Frames zum genauen Zeitstempel, an dem er auftreten sollte (z. B. ffmpeg -ss <t> -i video.mp4 -frames:v 1 …) und bestätigen Sie direkt, bevor Sie ihn als Defekt melden. Melden Sie nur das, was das vollständige Video tatsächlich vermissen lässt; stufen Sie bestätigte Beats auf ✅ herunter mit einem Hinweis, dass sie außerhalb der abgetasteten Menge verifiziert wurden.

Was es erkennt (und was nicht)

• Zuverlässig, mechanisch: Dead Air / eingefrorene UI-Regionen (Bewegungsdichte-Scan), Szenen-/Segmentstruktur, Branding-Karten vs. UI-Klassifizierung, Glitch-Cluster (Störungen / Seitenwechsel-Flackern), grobe Kontrast-/Luma-Statistiken.
• Subagenten-Argumentation über begrenzte Frames: nicht dem Drehbuch entsprechende UI-Komponenten (Admin-Dashboards, Logs, Fehler-Traces) – einschließlich kurzer Login-/Lade-/Leer-/Admin-Blitze zwischen Beats und Neuladungen in der Mitte eines Segments, die als Polierdefekte behandelt werden, nicht als akzeptable Übergänge; Überbearbeitung / harte Schnitte (das Dead-Air-Trimm hat echte Bewegung entfernt – Cursor-Teleportation ohne Weg, ein Seitenübergang mit hartem Sprung, ein Schnitt mitten in der Aktion), die als unnatürlich wirken; fehlende/falsche Beats; Navigationsstil als erstklassiger Check (durch das Produkt geblättert vs. Sprung in eine tiefe Seite); Karten danach beurteilt, ob sie wirken (lesbare Dauer, nicht untergraben durch eine widersprüchliche/leere Nachbarkarte) und nicht nur nach Anwesenheit, wobei Titelseite vs. Agenda-Karten anhand des Inhalts unterschieden werden; falsche Bildschirmdaten (Zahlen, kaputte Zeilen); fehlende Annotationen; Branding-/Kontrastfallen.
• Blinde Flecken: eine fehlende Bildschirm-Beschriftung während einer sonst aktiven Region (Lade-Animation wird als Bewegung gelesen) und ob eine Aktion wirklich fehlschlug oder aus dem Bild geschnitten wurde. Der Subagent weist diese als "konnte nicht ermittelt werden" aus.

references/validation-notes.md dokumentiert, wie die Skill gegen die von Menschen geprüfte Goldliste der Referenzvorlage abgeschnitten hat.