vincesector/talking-head-pipeline

/autocut

Rohaufnahme rein, saubere vorgeschnittene Datei raus. Du führst alle Befehle aus; der Mensch genehmigt einen Plan und sieht sich das Ergebnis an. Gib ihm niemals eine Befehlszeile zum Ausführen.

Repo-Root (Skripte leben dort):

THP_HOME=${THP_HOME:-$(cat ~/.config/talking-head-pipeline/root)}

Umfang

Situation	Pipeline
Rohaufnahme; Stille, Patzer und Sync müssen korrigiert werden	diese hier
Bereits geschnittenes Filmmaterial einer Person vor der Kamera, das dynamisch wirken soll	/dynamic-edit, gefüttert mit der clean.mp4 dieses Skills

Dieser Skill fügt keine Effekte, Untertitel oder Grafiken hinzu. Er produziert die Datei, die /dynamic-edit als Eingabe benötigt. Die Verkettung ist der normale Weg: /autocut dann /dynamic-edit.

Warum es funktioniert (erkläre es so)

Zwei Fakten führen dazu, dass naive Auto-Cutter Wörter „abkauen“ und aus dem Takt geraten:

1. Drahtlose Mikrofone und Aufnahmesoftware liefern Audio zu früh oder zu spät, und zwar um einen Betrag, der zwischen den Sitzungen variiert (+240 ms wurden bei einem Setup gemessen). Daher wird der Sync pro Datei anhand der Lippenbewegungen (SyncNet) gemessen und vor allem anderen angewendet. Niemals fest codiert.
2. Die Wortzeitstempel von Whisper landen nur etwa 2 von 12 Mal auf einer echten Wortgrenze. Eine Auffüllung um eine falsche Zahl schneidet dennoch Wörter ab. Daher wird jedes Wort mit einem Forced-Aligner zeitlich neu festgelegt, und beim Rendern wird jede Schnittkante an der Wellenform selbst ausgerichtet.

Und ein Fakt führt dazu, dass sie Fehler übersehen: Whisper glättet Wiederholungen weg. „Also lasst uns darüber reden, also lasst uns darüber reden, was passiert ist“ kommt als ein einziger sauberer Satz zurück. Eine zweite, wörtliche Transkription (CrisperWhisper) behält jeden Fehlstart, jede Wiederholung und jedes Füllwort; Stolperer und Neustarts werden darin gefunden.

Arbeitsablauf

1. Datei finden, niemals berühren

Verwende die vom Menschen benannte Datei oder die neueste Aufnahme in seinem Aufnahmeordner (frage einmal, wo der ist). Bestätige Dateinamen und Dauer in einer Zeile. Die Rohdatei ist für den gesamten Job schreibgeschützt; jede Ausgabe geht nach <raw dir>/<raw stem>_autocut/.

2. Planmodus

python3 "$THP_HOME/scripts/autocut/autocut.py" "<raw.mp4>"

Die Sync-Erkennung ist der langsame Teil (3 bis 10 Minuten, mehr auf einem ausgelasteten Rechner oder CPU-only Linux). Sag das, bevor du beginnst. Der Rest des Planmodus dauert etwa eine Minute, sobald die Modelle gecached sind; der erste Lauf pro Sprache lädt Modelle herunter (mehrere Minuten). Füge --lang en|pt|it|es|fr|de|nl nur hinzu, wenn die erkannte Sprache falsch ist. --offset SECONDS überspringt die Erkennung, wenn der Offset bereits bekannt ist; --no-sync für reine Bildschirmaufnahmen ohne Gesicht.

Wenn die Erkennung fehlschlägt (kein Gesicht, niedrige Konfidenz), sagt das Skript dies und fährt mit Offset 0 fort. Erfinde keine Zahl. Sage dem Menschen, dass es nicht gemessen werden konnte und frage: Fortfahren ohne Sync, oder einen von ihm angegebenen Wert verwenden.

3. Zeige den Plan als kompakte Tabelle an, dann STOPP

Lies plan.md aus dem Arbeitsverzeichnis und präsentiere es (kopiere niemals die Rohdatei ein):

  Quelle      take-01.mp4   01:47.9
  Sync        +240 ms (Audio zu früh), Konfidenz 5.5, Streuung 0 ms
  Ergebnis    01:40.5 geplant, 7.3 s entfernt, 5 Schnitte

  00:00.0-00:02.8   cut   Stille 3.0 s          2.8 s
  00:23.6-00:24.9   cut   Stille 2.0 s          1.3 s

  Stolperer (angewendet):  "also lasst uns darüber reden, | also lasst uns darüber reden"   behalte den zweiten Take
  Neustarts (vorgeschlagen): 01:12.4 "da wird ein Verlust sein bei" x2 ...      apply_spans Befehl aufgelistet
  Neuaufnahme-Vorschläge (nicht angewendet):
  1  01:45.9-01:47.0  "und so"  ->  behalte 01:47.0-01:48.1 "und so"

Markiere im selben Block: Sync-Streuung über 40 ms oder Konfidenz unter 3,5; Alignment-Start-Shift p90 über 500 ms (das Transkript ist wackelig); jede Neuaufnahme-Zeile, die als Whisper-Decoder-Schleife gekennzeichnet ist.

Wiederholungen und Fehlstarts werden standardmäßig geschnitten. Dafür ist der Wort-für-Wort-Durchlauf da. Präzision ist wichtiger als Trefferquote: Ein falscher Schnitt kostet eine Neuaufnahme, ein übersehener Stolperer kostet einen weiteren Schnitt. Sichere Treffer (sofortige Wiederholungen, eine Aufgabe ohne Satzzeichen zwischen den Takes) werden angewendet; unscharfe Fälle werden als Restart?-Kandidaten aufgelistet. Lese jeden Kandidaten im Kontext. Lehne alles ab, was eine bewusste rhetorische Wiederholung ist („unter 60, unter 70, unter 80“). Füllwörter (ähm, äh) werden aufgelistet, niemals automatisch geschnitten. Behalte den LETZTEN Take; wenn eine Pause zwischen zwei Takes liegt, markiert die Pause, wo der zweite Take beginnt.

Stelle eine Frage: Genehmigen wie vorgeschlagen, oder etwas benennen, das wieder eingefügt werden soll. Wenn eine Phrase mehrdeutig ist, frage gezielt danach; rate nicht. Nichts wird ohne eine Antwort gerendert.

4. Änderungen anhand der Zahlen anwenden, niemals aus dem Gedächtnis

• Akzeptiere einen Retake oder Neustart anhand seiner Wörter, nicht durch eingegebene Zeitstempel:

  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --drop "[email protected]"   # Phrase nahe 22 s
  python3 "$THP_HOME/scripts/autocut/apply_spans.py" <workdir> --span 71.20:74.85     # aus dem aufgelisteten Befehl von plan.md
  

  Lese jede Kontextzeile, die es zurückgibt.
• Lese vor dem Rendern erneut plan.json von der Festplatte; der Mensch könnte es bearbeitet haben. Ein nach einem Schnitt bearbeiteter Plan wird automatisch neu geschnitten.
• Skriptierte Pausen sind Inhalt: ein bewusster Schlag („und die Antwort ist... [Pause] nichts“) kommt in plan.json als keep_silences: [[s, e]] (Quellsekunden), damit der Cutter es niemals strafft.

5. Rendern

python3 "$THP_HOME/scripts/autocut/autocut.py" "<raw.mp4>" --render

Was Rendern bewirkt, damit du Fehler erklären kannst:

• 09p Lange Takes (über 3 Min): Begrenzt Pausen über 0,65 s auf 0,30 s nach dem letzten Ton + 0,20 s vor dem nächsten. Stille bedeutet hier jeden 5-ms-Frame unter -55 dB. Erhöhe diese Schwelle niemals: Wortausläufe klingen durch -42..-55 dB ab und eine höhere Schwelle frisst Endkonsonanten.
• 09a Rastet jede Schnittkante aus Tonläufen heraus und mindestens 50 ms entfernt von dem Ton, den sie entfernt; trimmt Kopf und Ende bis zum ersten und letzten echten Wort; Schnitte klammern Geräusche ([UH], [Lippenschmatzen]) in Lücken von 0,4 s oder mehr ein.
• 09b Verschiebt jeden behaltenen Start, in den hinein Ton läuft, zurück in die Stille (stellt einen abgeschnittenen Einsatz wieder her).
• Der Cutter verwirft jedes Stück unter 1 s ohne Ton (ein „stilles Splitter“ zwischen zwei Sprungschnitten) und gibt CHECK kurzes Stück mit Ton für behaltene Stücke unter 1 s aus. Höre dir jedes an.

6. Überprüfen des Schnitts (nicht optional, in dieser Reihenfolge)

1. qa.md ## Entfernte-Span-Prüfung zuerst. Jede entfernte Lücke wird auf zurückgebliebene Sprache überprüft (Energie + eine isolierte Transkription). Eine FLAGGED-Zeile bedeutet, dass der Schnitt nicht versandfertig ist: Untersuche (zuerst dB des lautesten Fensters, dann höre qa/removed/spanNN.wav), korrigiere keep, und rendere erneut. Ein einzelnes Ein-Wort-Fragment mit niedrigem dB-Wert des lautesten Fensters ist normalerweise ein Klick oder Atemzug, keine Sprache; vertraue der Energienummer mehr als dem Transkriptionstext. approved cut-Zeilen sind in Ordnung.
2. Lies qa/verbatim_cut.txt komplett durch, wie ein Editor. Es ist CrisperWhispers wörtliches Transkript DES SCHNITTS. Suche nach wiederholten Phrasen, Fragmenten oder Ganzsatz-Retakes, die überlebt haben. Überprüfe einen Schnitt niemals mit einem normalen Whisper-Transkript: Es versteckt genau diese. Ganzsatz-Retakes, die hintereinander nach einer Pause gesagt werden, werden nur so erkannt.
3. ## Neustarts noch im Schnitt und ## Kanten-Clipping in qa.md: Löse jede FLAGGED-Zeile auf (Zahlenfolgen wie „928 ... 939“ können Fehlalarme sein; lies sie).
4. Überprüfungen, die die Skripte nicht können:
   • Ausgabedauer vs. geplant: Eine Abweichung über 0,6 s ist ein Problem;
   • Überprüfe jede Verbindung bei 5 fps (Frames 0,5 s auf jeder Seite, aus timemap.json): Keine Verbindung auf einem Gestenunschärfe oder einem duplizierten Frame;
   • Keine interne Pause über 1,0 s; kein Stück ohne einen Frame über -45 dB;
   • Konstante Bildrate: Gezählte Frames / Stream-Dauer muss exakt der nominellen fps entsprechen (30.0000, nicht 29.98). Rekorder lassen unter Last Frames fallen, und jedes frame-indizierte Tool stromabwärts driftet, wenn dies nicht stimmt.

Führe nur die Qualitätssicherung ohne neuen Schnitt erneut aus: autocut.py --qa-only --workdir <dir>.

Öffne clean.mp4 für den Menschen (open auf macOS, xdg-open auf Linux).

7. Bericht und Übergabe

Was entfernt wurde (Tabelle), wo clean.mp4 ist, und eine Zeile: Dies ist der vorgeschnittene Input; sage „mach es dynamisch“, um mit /dynamic-edit fortzufahren. Untertitel für die nächste Stufe kommen von den wörtlichen Wörtern, abgebildet auf die geschnittene Zeitleiste:

python3 "$THP_HOME/scripts/autocut/verbatim_cut_words.py" <workdir> -o words.json

8. Aufräumen, nur wenn der Mensch sagt, dass das Video fertig ist

Das Arbeitsverzeichnis enthält synced.mp4 (eine vollständige Kopie des Takes) und tmp/ Render-Teile. Frage vor dem Löschen. plan.json, transcript.json, verbatim.json und qa.md sind klein; behalte sie.

Harte Regeln

• Plan-Sperre ist obligatorisch. Kein Rendern ohne das Okay des Menschen.
• Hardcode niemals einen Sync-Offset. Miss ihn pro Datei oder verwende einen, den der Mensch dir gibt.
• Die Rohdatei wird niemals modifiziert.
• Überprüfe einen Schnitt mit dem wörtlichen Transkript des Schnitts, niemals mit einem normalen Whisper-Transkript.
• Fixiere niemals eine automatisch generierte Kante. _meta.pinned_edges ist für Kanten, die ein Mensch gegen die Wellenform überprüft hat; das Fixieren von Maschinenkanten überspringt den Freigabeprüfung des Snappers und frisst Wörter.
• Stille ist nur unter -55 dB. Nichts zwischen -40 und -55 dB ist Stille bei einem begrenzten Mikrofon.
• Kein zusammengesetztes Stück unter 1 s ohne Sprache.
• Wenn ein Wort oder eine Anweisung mehrdeutig ist, stelle eine gezielte Frage.

Fallstricke

• Whisper halluziniert leere Segmente auf nachklingendem Raumton, mit Zeitstempeln nach dem Ende der Datei. Erwartet; der Retake-Finder filtert sie. Tausend „Retakes“ in zwei Sekunden am Ende sind eine Decoder-Schleife, keine echten Retakes, und plan.md sagt das.
• Die Sync-Erkennung benötigt ein Gesicht auf dem Bildschirm. Reine Bildschirmaufnahmen: --no-sync, und sage das.
• Viele Mikrofone zeichnen leise auf (um -30 LUFS). autocut normalisiert nicht. Lautstärke gehört zum endgültigen Master (scripts/master/sync_trim.sh --loudnorm); wende sie niemals stillschweigend an.

Vollständige schrittweise Referenz: $THP_HOME/docs/AGENT_GUIDE.md.