morrimoz/talking-head-clip-review

Was macht talking-head-clip-review?

Rohmaterial von Talking-Head-Aufnahmen in genehmigte Auswahlen verwandeln, ohne dass jemand manuell durchspulen muss. Der Agent transkribiert, gleicht ab und schlägt vor. Eine Person genehmigt auf einer Seite. Der Agent setzt dann genau das zusammen, was genehmigt wurde.

Die Transkription bleibt auf dem Rechner. Quellvideos werden niemals modifiziert.

Harte Regeln

• Die Quellvideos niemals modifizieren, verschieben oder neu exportieren. Alles besteht aus In/Out-Punkten plus abgeleiteten Dateien.
• Niemals das Filmmaterial des Benutzers löschen oder den Papierkorb leeren. Bei knappem Speicherplatz Bescheid sagen und den Benutzer selbst handeln lassen.
• In einem Arbeitsordner arbeiten. Nur Vorschauen, Poster, die Review-Seite und Auswahlen landen neben dem Medienmaterial.
• Keine Formulierungen erfinden. Clip-Text stammt aus dem Transkript. Optionale Phrasenkorrekturen befinden sich in einer JSON-Map, die mit --fix übergeben wird (siehe references/term-corrections.example.json). Die Beispiel-Datei nicht anwenden.
• Fakten, die vor der Kamera genannt werden (Zeiten, Zahlen, „vor 10 Minuten“) vor der Auswahl mit der echten Aufnahme abgleichen.
• Keine Blick-auf-Monitor, Mikrofon-Stöße, Klicks oder Atemgeräusche in einem behaltenen Span. Nach jeder Neubearbeitung den Blick-Check (Schritt 5) und jede Schnittstelle abhören, nicht nur bei der ersten Auswahl. Das Geräusch stummschalten oder herausschneiden, niemals das Wort daneben.
• Nachaufnahmen und neu aufgenommene Zeilen müssen Ton, Pegel und Raum der Hauptaufnahme entsprechen (gleiches Mikrofon, Verstärkung, Abstand, EQ und Rauschunterdrückung). Eine Zeile markieren, die dumpf oder eingeschlossen klingen wird, statt sie auszuliefern.
• Bei allem, was für den Benutzer geschrieben wird, Bindestriche verwenden, keine Gedankenstriche.
• Wortgrenzen sind harte Grenzen, selbst wenn eine Aufforderung enge Schnitte oder Blick-Kürzungen verlangt. Clips erhalten einen 0,15s Vorlauf und einen 0,25s Nachlauf um die Whisper-Wortzeiten (deren Wortkanten sind oft zu früh oder zu spät), begrenzt, damit sie nie in ein benachbartes Wort laufen. Pausen- und Blick-Kürzungen schneiden nur innerhalb von Lücken zwischen Wörtern und lassen mindestens 0,1s neben jedem Wort. Wenn ein Wegschauen ein gesprochenes Wort überlappt, das Wort behalten und markieren (away_words, roter Rand in der Stringout), niemals herausschneiden. build_review.py --gaze-trim für Kantenkürzungen verwenden, kein eigenes Schnittskript schreiben. Manuell gesetzte exact_spans werden ebenfalls wieder auf Wortkanten zurückgesetzt.

Einrichtung (einmal pro Rechner)

scripts/check_deps.sh ausführen. Es benötigt ffmpeg, ffprobe, python3 und ein Whisper-Backend. Swift ist optional für den Blick-Schritt. Installationsschritte: references/setup.md.

Verzeichnisstruktur

WORK/                      Arbeitsordner, z. B. ./talk/
  tx/<take>.wav|json|txt   16 kHz Mono-Audio, Whisper JSON mit Wörtern, lesbares Transkript
  picks.json               Beats + Kandidaten (Agent bearbeitet dies)
  picks_resolved.json      Wortgenaue Spans, Text, Dauer (generiert)
  pose.json                Blick-Abwesenheitsintervalle (optional, macOS)
REVIEW/                    Neben dem Medienmaterial, z. B. ./review/
  previews/<take>.mp4      540p H.264-Kopien für die Seite
  posters/<beat>-<i>.jpg
  "<Titel> - Take review.html"
  "<Titel> - Picks stringout (540p).mp4"
SELECTS/                   selects.json, selects.csv, selects.edl, selects.mp4

Die Episode nach dem Stück benennen, z. B. launch-01. Take-Keys kurz halten (A, B, C) und sie in picks.json auf Dateinamen abbilden.

Schritte

1. Inventur. Jeden Take mit ffprobe erfassen (Dauer, Größe, fps, Rotation). Handy-Aufnahmen haben oft variable Bildrate und sind im Hochformat. Vorschauen und Render normalisieren das. Fragen, welche Dateien die exportierten Master zum Schneiden sind und welche Kamera-Originale ignoriert werden sollen.
2. Transkribieren. python3 scripts/transcribe.py --out WORK/tx TAKE... ausführen. Den Interpreter verwenden, den check_deps.sh gemeldet hat, falls das Whisper-Paket nicht im Standard-python3 installiert ist. Wenn Dateien noch exportiert werden, --watch ORDNER --expect N im Hintergrund verwenden: es wartet, bis jede Datei 30s lang nicht mehr gewachsen ist. Bevorzugtes Modell auf Apple Silicon: mlx-community/whisper-large-v3-turbo, Wort-Zeitstempel, mit condition_on_previous_text aus. --lang setzen, wenn die Sprache nicht Englisch ist.
3. Auswahlen entwerfen.
   • Modus (a), mehrere Takes eines Skripts: WORK/script.txt mit einer Zeile oder einem Thema pro Zeile schreiben (id | name | text für IDs). python3 scripts/segment.py takes --tx WORK/tx --script WORK/script.txt --out WORK/picks.json A=take-a B=take-b ... ausführen. Es findet jeden Versuch jeder Zeile in jedem Take (fuzzy Wort-Fenster-Matching, sodass Neustarts als separate Kandidaten erscheinen) und markiert den sprachflüssigsten vor.
   • Modus (b), ein langes Video: python3 scripts/segment.py single --tx WORK/tx --out WORK/picks.json A=long-take schneidet bei Pausen von 1,2s oder mehr und an Satzenden in Clips von 4-40s.
   • Dann die .txt-Transkripte selbst lesen. In/Out-Punkte korrigieren, cut: [[a,b]] für Neustarts und Fehler hinzufügen, Beats zusammenführen oder teilen und eine echte why pro Kandidat schreiben (sauber, Neustart, falsches Wort, passt zur Bildschirmaufnahme). Den Take bevorzugen, der mit der passenden Bildschirmaufnahme gefilmt wurde. Die automatische Bewertung dient nur zum Lösen von Gleichständen.
4. Seite erstellen. python3 scripts/build_review.py --work WORK --media SRC --out REVIEW --title "launch-01" --stringout ausführen. Spans werden bei Wortlücken über 0,6s geteilt und mit silencedetect -35dB / 0.35s gestrafft. keep_pauses: true zu einem Kandidaten hinzufügen, um das zu überspringen. Padding-Flags: --pre 0.15 --tail 0.25 --guard 0.1. --fix Pfad/zu/korrekturen.json nur übergeben, wenn eine echte Phrasen-Map vorhanden ist. Das HTML im Browser öffnen. Videos laden erst bei Klick, die Seite öffnet also schnell.
5. Optional, macOS: Blick. python3 scripts/gaze.py --work WORK --review REVIEW ausführen, dann Schritt 4 mit --stringout --gaze-trim wiederholen. Blick-Abwesenheits-Frames erhalten in der Stringout einen roten Rand. Später mit Bildschirmmaterial überdecken und den Ton behalten.
6. Menschliche Prüfung. Dem Benutzer sagen, was zu tun ist: Abspielen, Behalten/Überspringen, Notizen, dann "Entscheidungen speichern (JSON)". Es lädt <slug>-decisions.json herunter. "Als Text kopieren" ist der Fallback. Unberührte Karten behalten den Vorschlag.
7. Notizen anwenden. Das Entscheidungen-JSON lesen. Jede Notiz in picks.json-Bearbeitungen umsetzen: cut, in/out, audio_only: true, grade: "eq=gamma=1.28:brightness=0.03", optional: true. Zuerst ein Backup erstellen (cp picks.json picks.before-notes.json). Schritt 4 wiederholen und jede Notiz zusammenfassen, was getan wurde.
8. Zusammenstellen. python3 scripts/assemble.py --work WORK --media SRC --decisions /pfad/zu/<slug>-decisions.json --out SELECTS --render ausführen. Man erhält ein frame-genaues selects.mp4 in voller Auflösung, eine CMX3600 selects.edl (für Premiere, Resolve, Final Cut via Import), selects.csv und selects.json mit Blick-Abwesenheitsbereichen und Notizen.
9. Überprüfen. Jede Schnittstelle abhören (keine abgeschnittene erste oder letzte Silbe, kein Blick, kein Rauschen). Die Render-Dauer mit ffprobe gegen die Summe in selects.json prüfen und ein Kontaktblatt erstellen: ffmpeg -i selects.mp4 -vf "fps=1/6,scale=180:-1,tile=10x3" -frames:v 1 sheet.jpg. Ansehen, dann die Länge, die Änderungen und was noch den Benutzer braucht, melden.

picks.json-Format

{"episode":"launch-01","mode":"takes","takes":{"A":"take-a","B":"take-b"},
 "beats":[{"id":"01a","name":"Hook","script":"...","cands":[
   {"take":"B","in":0.82,"out":21.2,"pick":true,"why":"Sauber, passt zum Screen.","cut":[[51.4,53.82]],
    "note":"","audio_only":false,"grade":null,"optional":false,"signals":{"dur":20.1,"wpm":162,"fillers":0,"repeats":0}}]}]}

Tipps

• Wortzeiten im Transkript-JSON stichprobenartig prüfen. Ein Auszug mit wort@start-ende um eine Notiz herum ist der schnellste Weg, einen Schnitt zu setzen.
• Wenn ffmpeg kein drawtext hat, Frames mit drawbox oder hue markieren, nicht mit Text.
• Große Render: Zuerst freien Speicher prüfen. 4K-Takes summieren sich schnell.