Skill: Video analysieren (Hauptanweisung)
Dies ist das Playbook des Haupt-Threads für den Workflow-Schritt Video analysieren. Führe es nach der Bibliothekseinrichtung und vor jeglichen Schnittarbeiten aus. Es deckt die drei Artefakte ab, die pro Clip erstellt werden: Audio-transcript, contact_sheet und Markdown-summary. Der Roughcut-Agent liest bei Bedarf Dialoge aus, indem er script_extractor.rb über das Transkript-JSON ausführt – es gibt kein separates Skript-Artefakt.
SKILL.md ist die Einsatzanweisung des Haupt-Threads. Die Arbeitsanweisung für den Sub-Agenten befindet sich in agent_prompt.md – dessen Inhalt beim Starten eines Task-Agenten inline einfügen. SKILL.md nicht übergeben.
Begriffe
- Gegenüber dem Benutzer: „Filmmaterial-Analyse“ oder „Filmmaterial analysieren“ verwenden.
- Intern/Dateinamen: „Transkription“ (library.yaml-Feld
transcriptusw.).
Voraussetzungen
- Die Bibliothekseinrichtung ist abgeschlossen (
library.yamlexistiert, Schema ist aktuell – falls nicht, Migrationen aus AGENTS.md ausführen). libraries/settings.yamldirekt lesen fürwhisper_model. Für Bibliotheksfelder den Snapshot überruby lib/buttercut/library.rb <name> summarylesen und die benötigten Werte aus dem JSON ziehen –library.yamlnicht inline parsen.
Erstelle an dieser Stelle eine für den Benutzer sichtbare Aufgabenliste mit übergeordneten, nicht-technischen Schritten, damit er den Gesamtplan zur Verarbeitung der Bibliothek nachvollziehen kann. Füge Koffeinschritte nur ein, wenn der Benutzer zugestimmt hat. Z.B.:
- [ ] Computer wach halten
- [ ] Transkripte erstellen (0/30)
- [ ] Filmmaterial analysieren (0/30)
- [ ] Computer wieder schlafen lassen
- [ ] Filmmaterial gemeinsam durchgehen
Diese öffentlichen Aufgaben entsprechen den folgenden Schritten: „Computer wach halten“ ist Schritt 1 und „Computer wieder schlafen lassen“ ist Schritt 6; „Transkripte erstellen“ deckt den mechanischen Durchlauf in Schritt 2 plus den optionalen Verfeinerungsdurchlauf in Schritt 3 ab (Zähler von den Fortschrittszeilen [transcript …] aus Schritt 2 erhöhen; bei eingeschalteter Verfeinerung während Schritt 3 als „in Bearbeitung“ belassen); „Filmmaterial analysieren“ verfolgt die Zusammenfassungen in Schritt 4 (Zähler erhöhen, wenn Clips zusammengefasst werden, nicht nach Kontaktbögen); „Filmmaterial gemeinsam durchgehen“ ist Schritt 5.
Beziehe dich im öffentlichen Chat auf diese nicht-technischen Schritte. Halte die technische Arbeit (WhisperX, Kontaktbogen-Generierung, Sonnet-Zusammenfassungen) im Hintergrund.
Schritt 1 – Schlaf während der Verarbeitung verhindern
Bevor du mit der Analyse beginnst, frage den Benutzer (über AskUserQuestion): „Die Verarbeitung kann eine Weile dauern – möchtest du, dass ich deinen Computer wach halte, bis sie fertig ist?“ Optionen: „Ja (empfohlen)“ und „Nein“.
Wenn ja, starte den Keep-Awake-Helfer der Plattform im Hintergrund und speichere die PID – du beendest ihn in Schritt 6, sobald die Analyse abgeschlossen ist. (Ein Backup wird vom aufrufenden Skill – process-library – nach der Rückkehr dieses Skills übernommen.)
macOS:
caffeinate -i -w $$ &
KEEPAWAKE_PID=$!
Windows (Git Bash):
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/keep_awake.ps1 &
KEEPAWAKE_PID=$!
Beide verhindern den Schlaf im Leerlauf, während Filmmaterial verarbeitet wird (der Bildschirm kann sich trotzdem ausschalten, was in Ordnung ist).
Schritt 2 – Filmmaterial verarbeiten (Transkripte, dann Kontaktbögen)
(Wenn du diesen Skill direkt und nicht über process-library erreicht hast, teile dem Benutzer zuerst mit: „[N] Videos gefunden ([Gesamtgröße]). Starte Filmmaterial-Analyse...“)
Dies sind zwei mechanische Befehle, die du nacheinander ausführst – zuerst Transkripte, dann Kontaktbögen. Führe sie niemals gleichzeitig aus: WhisperX ist RAM-hungrig, und eine Überlappung der beiden soll vermieden werden. Führe keinen von beiden manuell mit Sub-Agenten durch; jeder läuft jedes Mal identisch ab, ~2 Clips gleichzeitig, und zeichnet jeden Clip in der library.yaml auf, sobald er fertig ist. Beide sind idempotent – sie bearbeiten nur Clips, denen das jeweilige Artefakt noch fehlt – daher erledigt ein erneuter Durchlauf nur das, was noch übrig ist. Sie laufen in einem Miniatur-Sidekiq-ähnlichen Job-Dienst. Du führst den Befehl aus und beobachtest dann die Logdatei, die zurückgegeben wird, um den Fortschritt zu verfolgen.
Schritt 2a – Transkripte. Wenn du Claude Code verwendest, führe mit run_in_background: true auf dem Bash-Tool aus. Verwende andernfalls das korrekte Tool/Argument, um im Hintergrund auszuführen.
ruby lib/buttercut/process_footage.rb transcripts <library-name>
Richte unmittelbar nach dem Start einen Monitor oder ein Äquivalent für die Logdatei ein, um eine Benachrichtigung für jedes abgeschlossene oder fehlgeschlagene Clip zu erhalten:
tail -f tmp/logs/processing/<library-name>/$(date +%Y-%m-%d).log | grep --line-buffered -E "TranscribeJob (done|error)|transcript: [0-9]+/[0-9]+|Error|error:|failed|Traceback"
ruby lib/buttercut/library.rb <name> pending transcript # JSON-Liste; done = N − seine Länge
Aktualisiere „Transkripte erstellen 5/20“, also Anzahl_abgeschlossene_Clips/Gesamtanzahl_Clips, während Clips fertig werden, damit der Benutzer den Fortschritt sehen kann. Wenn die Hintergrundaufgabe abgeschlossen ist, wird sie mit einem Fehlercode beendet, wenn ein Clip fehlgeschlagen ist. Bei Fehlschlag einmal wiederholen. Wenn es erneut fehlschlägt, untersuche die Ursache und erstelle entweder einen Fix, um das Problem elegant zu handhaben, oder informiere den Benutzer über das Problem mit dem Clip und ziehe ihn möglicherweise aus der Bibliothek.
Warte, bis 2a abgeschlossen ist, bevor du mit 2b beginnst.
Schritt 2b – Kontaktbögen. Sobald die Transkripte fertig sind, erstelle die Bögen (ein schneller ffmpeg-Durchlauf – im Vordergrund ist in Ordnung):
ruby lib/buttercut/process_footage.rb contact-sheets <library-name>
Kontaktbögen bleiben im Hintergrund – zeige sie nicht als öffentlichen Zähler an. Markiere „Transkripte erstellen“ als erledigt, sobald Schritt 2a abgeschlossen ist und eine eventuelle Verfeinerung (Schritt 3) beendet ist.
Optimierung (optional): Beide Schritte lesen parallel_jobs aus libraries/settings.yaml (Standard 2); für einen Durchlauf mit --jobs N überschreiben. Jeder schreibt einen Zeitstempel-Log unter tmp/logs/processing/<library>/ für die spätere Überprüfung.
Neuverarbeitung. Jeder Schritt überspringt Clips, die sein Artefakt bereits haben. Um einen zu wiederholen – z. B. ein Transkript, das einen Namen falsch verstanden hat – führe den Schritt mit --force --clips NAME.mov erneut aus. --force allein erstellt jedes Clip neu.
Schritt 3 – Transkripte verfeinern (Ermessensentscheidung – nur wenn transcript_refinement: true)
Die Verfeinerung ist der einzige Teil der Transkription, der eine Ermessensentscheidung darstellt – das Korrigieren falsch verstandener Eigennamen aus dem Bibliothekskontext – daher bleibt es ein Modellschritt, der nach dem mechanischen Durchlauf ausgeführt wird. Überspringe diesen gesamten Schritt, wenn transcript_refinement der Bibliothek false ist.
Wenn es true ist, verteile Verfeinerungs-Sub-Agenten (2-4 parallel, rollierend) über die Transkripte, die Schritt 2a gerade geschrieben hat. Füge skills/transcribe-audio/refine_instructions.md als Prompt für jeden Sub-Agenten ein und übergib inline:
transcript_path– absoluter Pfad zum Transkript-JSON des Clips unterlibraries/<library>/transcripts/user_contextundfootage_summary– aktuelle Werte ausruby lib/buttercut/library.rb <name> summary(leere Zeichenketten sind in Ordnung; die Verfeinerung fängt trotzdem unsinnige Token- und Selbstzeugnis-Korrekturen)
Sub-Agenten bearbeiten das Transkript-JSON direkt und geben eine kurze Liste der Korrekturen zurück. Sie verändern NICHT library.yaml – Schritt 2a hat das Feld transcript bereits gesetzt. Markiere die öffentliche Aufgabe „Transkripte erstellen“ als erledigt, sobald die Verfeinerung abgeschlossen ist.
Schritt 4 – Zusammenfassungen (Sonnet-Sub-Agenten, gestapelt, rollierend)
Verteile analyze-video-Sub-Agenten auf dem Sonnet-Modell. Sonnet liest den Kontaktbogen mit deutlich mehr visueller Genauigkeit als Haiku (erkennt Kleidung, Architektur, Kameraeinstellungen) – das lohnt sich, da die Zusammenfassungen jede spätere Schnittentscheidung beeinflussen.
Stapel 10 Clips pro Sub-Agent, bis zu 10 Sub-Agenten parallel, mit rollierender Verteilung. Jeder Sub-Agent verarbeitet seine 10 Clips sequenziell; die Stapelung amortisiert den ~5–10s Overhead pro Agent. Für eine Bibliothek mit 93 Clips sind das insgesamt ~10 Sub-Agenten statt 93. Starte den nächsten Sub-Agenten, sobald einer zurückkommt – warte nicht, bis die gesamte Welle von 10 fertig ist, sonst verschenkst du ~30% der Wanduhrzeit an den langsamsten Agenten in der Welle.
Übergib für jeden Sub-Agenten eine Liste von 10 Clip-Datensätzen inline. Jeder Clip-Datensatz benötigt:
video_filename– Basisname des Videos (wird im Zusammenfassungs-Header und in der Antwortzeile verwendet)duration– Dauerstring auslibrary.yaml(z. B.00:01:19); der Agent rendert ihn im Zusammenfassungs-Headercontact_sheet_path– absoluter Pfad zum_full.jpg(aus Schritt 2)transcript_path– absoluter Pfad zum Audio-Transkript-JSON (aus Schritt 2); der Sub-Agent extrahiert bei Bedarf Dialoge überscript_extractor.rbsummary_output_path– absoluter Pfad, in den der Agent die Zusammenfassung als Markdown schreiben soll. Erstelle diesen Dateinamen nicht selbst; frage die Bibliothek nach dem kanonischen Pfad:ruby lib/buttercut/library.rb <name> field_path summary <clip>(behandelt die Konventionsummaries/summary_<clip>.mdfür dich, mit oder ohne Dateierweiterung)
Sobald jeder Sub-Agent seinen Stapel zurückgibt, aktualisiere library.yaml mit summary für jeden Clip in diesem Stapel:
ruby lib/buttercut/library.rb <name> complete summary <filename> [<filename>...]
Das Feld contact_sheet wurde bereits in Schritt 2 befüllt, daher liefert die Rückkehr des Sub-Agenten nur Zusammenfassungen.
Wenn ein Sub-Agent Zusammenfassungen inline zurückgibt, anstatt sie auf die Festplatte zu schreiben (manchmal halluziniert Sonnet „Das Schreib-Tool ist blockiert“ und wirft das Markdown in seine Antwort), wiederhole nicht blind – extrahiere einfach jede Zusammenfassung aus der Antwort des Agenten und schreibe sie in den passenden summary_output_path aus dem Haupt-Thread. Führe dann den Befehl complete summary wie gewohnt aus. Schneller als erneutes Verteilen, und der Inhalt ist bereits vorhanden.
(Pro-Segment-Kontaktbögen, die für lange Clips erstellt wurden, liegen neben dem _full-Blatt auf der Festplatte und sind per Konvention auffindbar – sie sind nicht in library.yaml aufgeführt.)
Fahre erst fort, wenn alle Zusammenfassungen abgeschlossen sind. Erhöhe den Zähler für „Filmmaterial analysieren“, während Clips zusammengefasst werden; markiere es als erledigt, wenn es fertig ist.
Bilder. Standbilder überspringen die Schritte 2–3 vollständig (kein Audio zu transkribieren, kein Kontaktbogen zu erstellen) – eine summary ist das einzige Artefakt, das sie benötigen, und sie tauchen in ruby lib/buttercut/library.rb <name> pending summary direkt neben den Videos auf. Das Bild ist das, was du dir ansehen sollst, also fasse es direkt zusammen: Lies die Bilddatei (sie ist klein) aus dem Haupt-Thread oder einem Sonnet-Sub-Agenten und schreibe eine 3-4-sätzige Beschreibung – Motive, Umgebung, Komposition, eventueller Text im Bild – in den kanonischen Pfad aus ruby lib/buttercut/library.rb <name> field_path summary <image-filename>. Beachte, dass Bild-Clip-Schlüssel die Erweiterung enthalten (title-card.png → summaries/summary_title-card_png.md), was field_path für dich erledigt. Dann zeichne es auf die gleiche Weise auf: ruby lib/buttercut/library.rb <name> complete summary <image-filename>.
Schritt 5 – Verständnis des Filmmaterials mit dem Benutzer bestätigen
(Dies ist die Aufgabe „Filmmaterial gemeinsam durchgehen“.) Sobald jede Zusammenfassung geschrieben ist, sprich durch, was das Filmmaterial tatsächlich zeigt – bestätige Charakternamen, Orte, den narrativen roten Faden, eventuelle Ausreißer oder nicht zum Thema gehörende Clips und die kreative Absicht des Benutzers für diese Bibliothek. Verwende einfache Konversation; greife nur auf AskUserQuestion zurück, wenn du eine konkrete Wahlmöglichkeit anbietest. Aktualisiere während des Gesprächs:
footage_summaryunduser_contextüberruby lib/buttercut/library.rb <name> update_metadata footage_summary "..."(und dasselbe mituser_context)- einzelne
summary_*.md-Dateien, wenn eine Zusammenfassung jemanden falsch bezeichnet oder ein wichtiges Detail übersieht (z. B. „ein Mann in einer braunen Jacke“ → der Name des Benutzers)
Dies ist der einzige Ort, um diesen gründlichen Durchlauf durchzuführen. Jeder spätere Roughcut-Planungsdurchlauf erbt den resultierenden Kontext, anstatt die Bibliothek erneut zu befragen.
Schritt 6 – Keep-Awake-Helfer stoppen
Wenn du in Schritt 1 einen gestartet hast, beende ihn jetzt (beide Plattformen):
kill $KEEPAWAKE_PID 2>/dev/null
Paralleles Sub-Agenten-Muster (Referenz)
Verwendet in den Schritten 3 und 4.
Aufgaben des Haupt-Agenten:
library.yamlundsettings.yamleinmal lesen, um alle von Sub-Agenten benötigten Werte zu sammeln.- Task-Agenten starten und alle benötigten Werte inline im Prompt übergeben.
library.yamlsequenziell aktualisieren, während Agenten abgeschlossen werden (über dieLibrary-API – siehe AGENTS.md).- Fehler und Wiederholungen behandeln.
Aufgaben des Kind-Agenten:
- Seine zugewiesenen Clips nur mit den vom Haupt-Agenten inline übergebenen Eingaben verarbeiten.
- Ein Transkript-JSON direkt verfeinern (Verfeinerung) oder den vorab generierten Kontaktbogen lesen, Dialoge aus dem Transkript über
script_extractor.rbextrahieren und die Zusammenfassung als Markdown in einem einzigen Write-Aufruf schreiben (Analyse-Video). (WhisperX ist kein Sub-Agent mehr –process_footage.rb transcriptsführt es in Schritt 2a aus.) - Eine kurze strukturierte Antwort mit Dateipfaden zurückgeben.
Jeder Skill dokumentiert in seiner agent_prompt.md seinen eigenen IO-Vertrag – einschließlich der Frage, ob der Sub-Agent library.yaml liest oder schreibt. (Spoiler: Er schreibt nie library.yaml. Nur der Haupt-Agent schreibt, über die Library-API.)
Wenn der Benutzer vor Abschluss der Analyse einen Roughcut anfordert
Warne: „Ich kann jetzt einen Roughcut erstellen, aber ich werde bessere Arbeit leisten, nachdem ich das gesamte Filmmaterial analysiert habe. Trotzdem fortfahren?“ Wenn der Benutzer bestätigt, fahre fort. Andernfalls warte, bis die Analyse abgeschlossen ist.