Untertitel
Dies ist eine eigenständige Aktion, kein Teil eines Workflows. Sie wird ausgeführt, wann immer der Benutzer es anfordert – direkt nach dem Schnitt oder erneut, wenn nachträglich zwei Zeilen gelöscht wurden.
Es gibt nur eine Voraussetzung: Das Schnittprotokoll (‚Konto‘) muss vorhanden sein. Nicht weil dieser Schritt zeitlich nach dem Schnitt kommt, sondern weil ohne das Protokoll nicht bekannt ist, welche Wörter erhalten bleiben und an welcher Sekunde des fertigen Films sie liegen.
Benötigt edit-list.json (Schnittprotokoll), transcript.json (Wort-für-Wort-Transkript)
Erzeugt subtitles.json
Nach Abschluss wird angehalten – der Benutzer wird nicht zum nächsten Schritt aufgefordert.
Zunächst wird der Phasenvertrag des Geschäfts-Skills gelesen und ausgeführt, die Kriterien finden sich in den Untertitel-Korrekturregeln und die Schreibweise von Eigennamen im KI-Fachwörterbuch.
Wer entscheidet über was
Dies ist das Fundament, von dem alles Weitere abgeleitet wird.
Schnitt/Audio-Edit entscheidet „welche Wörter bleiben, zu welcher Zeit“ ← einzige Quelle der Wahrheit für Zeit
Untertitel entscheidet „was auf dem Bildschirm angezeigt wird“ ← einzige Quelle der Wahrheit für Anzeige
Ein Untertitel-Block speichert eine Liste von Wort-IDs + den anzuzeigenden Text, keine Sekundenangaben. Die Zeit wird jedes Mal aus dem Schnittprotokoll berechnet. Dadurch kann es keine zweite, abweichende Zeitachse zwischen den beiden Protokollen geben, und selbst ein ungültiger Block kann exakt identifiziert werden: „Die Wörter von Block 7 und 12 wurden geschnitten“, nicht die vage Aussage „Untertitel könnten veraltet sein“.
Untertitel speichern bewusst ihren eigenen Text. Das Transkript antwortet auf „Was wurde gesagt?“, der Untertitel auf „Was soll der Zuschauer sehen?“ – Satzzeichen, entfernte Füllwörter, die korrekte Schreibweise von Eigennamen – das darf und soll unterschiedlich sein. Wenn man ein und denselben String für zwei Zwecke zwingt, kann der Untertitel nie ein Komma einfügen.
0. Bereitschaft
Zunächst wird die „Bereitschaftsprüfung“ von Prüfung auf Updates ausgeführt – ob Skills aktuell sind, ob die Runtime kompatibel ist; das Plugin-Root-Verzeichnis wird dort ebenfalls bestimmt (alle <Plugin-Root> in diesem Befehl werden durch den dortigen Pfad ersetzt). Nur bei „Bereit“ wird fortgefahren; bei „Neue Sitzung erforderlich“ oder „Stop“ wird gemäß der dortigen Anweisung verfahren (einschließlich des Verbots „keine selbst gebastelten alternativen Oberflächen“). Der Geschäfts-Skill enthält keine eigene Umgebungslogik.
Falls das Bereitschaftsergebnis runtime.kind=desktop-managed ist, wird direkt die bereits installierte stabile CLI der Desktop-App und der zugehörige launchd-/windows-task-Dienst verwendet; es werden keine Electron-Pfade analysiert, keine zusätzlichen Abhängigkeiten installiert oder eine zweite Runtime gestartet.
1. Einstiegsprüfung
node "<Plugin-Root>/scripts/ensure-running.cjs" --json
node "<Plugin-Root>/scripts/videocut-cli.cjs" inspect "<Projektverzeichnis>" --json
| Prüfung | Bei Nichterfüllung |
|---|---|
edit-list.json existiert und enthält Segmente | Melde, dass das Schnittprotokoll fehlt, und fordere den Benutzer auf, zuerst den Audio-Edit durchzuführen. Führe den Schnicht nicht selbst durch. |
transcript.json existiert | Das Projekt ist nicht bereit, stoppen. Erstelle kein eigenes Transkript. |
Prüfe nicht auf source_cut.mp4 und führe keine Transkription durch. Untertitel benötigen beides nicht – siehe nächster Abschnitt.
2. Textkorrektur: Zuerst Wörterbuch, dann Manuskript
Keine erneute Transkription erforderlich. Das vorhandene Wort-für-Wort-Transkript enthält bereits die Zeitstempel. Das Schnittprotokoll weiß, welche Abschnitte erhalten bleiben – die Position jedes Wortes in der fertigen Sequenz wird berechnet, nicht durch erneutes Abhören ermittelt:
Position des Wortes im Quellmaterial ist im Transkript vorhanden
Welche Abschnitte bleiben sind im Schnittprotokoll vorhanden
Position des Wortes in der Sequenz ergibt sich aus beidem
Ein erneuter ASR-Durchlauf würde dasselbe nur noch einmal anhören, Geld und Zeit kosten und schlechtere Ergebnisse liefern – Eigennamen müssten erneut korrigiert werden. (transcript retranscribe ist ein Überbleibsel des vorherigen Designs, bei dem Untertitel durch erneute Transkription des geschnittenen Videos eine Zeitachse erhalten sollten. Nach der Umstellung auf ID-basierte Untertitel ist dieses Problem gelöst. Verwende es nicht für Untertitel.)
Zwei verschiedene Werkzeuge, beide werden verwendet.
# Wörterbuch: die festgelegte Schreibweise für den Sprecher, benötigt keine Beweise
node "<Plugin-Root>/scripts/videocut-cli.cjs" transcript dictionary "<Projektverzeichnis>" --dictionary "<Plugin-Root>/references/ai-term-dictionary.md" --json
# Manuskript: wird nur verwendet, wenn der Autor ein schriftliches Manuskript hat, jede Korrektur benötigt einen Beleg
node "<Plugin-Root>/scripts/videocut-cli.cjs" transcript align "<Projektverzeichnis>" --script "<Manuskriptdatei>" --json
Wörterbuch wird immer so geschrieben ignoriert den Kontext, ändert direkt, listet die geänderten Stellen auf
Manuskript wird nur geschrieben, wenn der Kontext passt jede Änderung benötigt einen Beleg, bei Unstimmigkeit wird „unsicher“ gemeldet, es wird nicht geraten
Warum ist das Wörterbuch unverzichtbar und das Manuskript allein nicht ausreichend? Bei echten Projekten werden Aufnahmen wiederholt. In einem realen Projekt wurde derselbe Satz viermal aufgenommen, daher tritt der Kontext von „Steckverbinder“ und „Stecker ist“ mehrfach auf. align kann dann nur „unsicher“ melden – es rät nicht, weil ein falsch geschriebener Name schlimmer ist als ein überhörter. Von drei Vorkommen von „Stecker“ würde es nur eines korrigieren. Das Wörterbuch hat dieses Problem nicht: Im Werk dieses Sprechers ist „Stecker“ gleichbedeutend mit „Verbinder“.
Das Wörterbuch gibt es nur einmal, auf Plugin-Ebene in references/ai-term-dictionary.md: Es korrigiert das Transkript, das sowohl vom Audio-Edit als auch von den Untertiteln verwendet wird. Erstelle kein separates Wörterbuch innerhalb dieses Skills.
Die Änderungsliste muss angesehen werden. Das Wörterbuch ignoriert den Kontext, daher kann es auch Fehler machen – z. B. wenn der Sprecher tatsächlich „Skills“ (Claude Skills, Plural-Eigenname) sagt, dies aber zu „Skill“ normalisiert wird. Wenn ein Fehler auffällt, korrigiere das Wörterbuch, nicht die Befehlszeile.
transcript align meldet nur, es ändert nicht. Um die Vorschläge zu übernehmen, erstelle daraus [{wordId, text}] und führe es aus:
node "<Plugin-Root>/scripts/videocut-cli.cjs" transcript correct "<Projektverzeichnis>" --file "<Korrekturdatei>" --json
Nach der Korrektur des Transkripts werden die Untertitelblöcke, die diese Wörter referenzieren, im selben Schritt automatisch aktualisiert, gemeldet als subtitles.updated. Blöcke, die nicht geändert werden konnten (weil der Text manuell überschrieben wurde), werden in needsAttention gemeldet, damit der Benutzer sie überprüft – es wird nicht geraten.
Wenn weder das Wörterbuch noch das Manuskript eine korrekte Schreibweise bestätigen können, darf nicht geraten werden. Melde es dem Benutzer, damit er das Wörterbuch ergänzt – beim nächsten Video wird es automatisch korrekt sein. Einmaliges Erraten hilft nicht, denn beim nächsten Mal müsste wieder geraten werden.
3. Blockbildung (Splitten)
node "<Plugin-Root>/scripts/videocut-cli.cjs" subtitle build "<Projektverzeichnis>" --json
Vier Regeln, in dieser Reihenfolge:
① Hier wurde Text entfernt Die entfernten Teile liegen auf der Zeitachse nebeneinander, haben aber inhaltlich nichts miteinander zu tun.
Entfernte „Stille“ zählt nicht – das Entfernen einer Pause mitten im Satz darf den Satz nicht aufteilen.
② Jegliches Satzzeichen Vom ASR bereitgestellt, sowohl Punkte als auch Kommas – **der gleiche Granularitätsgrad wie beim Audio-Edit-Splitten**,
beide teilen an derselben Stelle. Satzzeichen sind stärker als jeder Zeitbeweis: Ein Sprecher kann zwei Sätze ohne Pause
hintereinander sagen, aber auch innerhalb eines Satzes eine Pause machen.
③ Absatzgrenzen + Pause **Wird nur verwendet, wenn das Wort kein Satzzeichen hat.** Es geht davon aus, dass ein Satz endet, wenn kein
Satzzeichen vorhanden ist, aber die Absatzanalyse darauf hindeutet. Wenn ein Satzzeichen vorhanden ist, sollte Regel ②
mit Kommas greifen – sie berücksichtigt, ob der Block lang genug ist, Regel ③ tut dies nicht.
(Wenn Regel ③ auch an Grenzen mit Satzzeichen ausgelöst wird, kann dies in einem echten Projekt von 40 auf 43 Blöcke
führen, also mehr kleine Blöcke erzeugen.)
④ Zuschauer hört eine lange Pause Für eine Teilung innerhalb eines Satzes ist eine längere Stille erforderlich.
Audio-Edit und Untertitel verwenden dieselben Satzzeichen und denselben Granularitätsgrad: Ein Komma = ein Segment / ein Block.
Fragmente (ein bis zwei Zeichen) werden zusammengelegt, jedoch nicht über Satzpunkte hinweg – „Du siehst“ beginnt einen neuen Satz, es ist kein Ende des vorherigen Satzes. Ein Zusammenlegen würde „…Grok CLI aufrufen Du siehst“ ergeben, zwei Sätze würden verschmelzen.
Kurze Sätze, die der Sprecher schnell sagt, bleiben erhalten (in einem echten Projekt dauerten „jeden Morgen“ und „Aufgabe ausführen“ jeweils 0,6 Sekunden). Das ist seine tatsächliche Sprechweise, kein Alarm. Ein Komma = ein Block erzeugt zwangsläufig solche Blöcke. Sie zu alarmieren bedeutet, normale Sprache zu alarmieren – wenn zu viele Alarme ausgelöst werden, liest sie niemand mehr.
Blöcke, die länger als ein Block sind, werden gleichmäßig auf mehrere Blöcke aufgeteilt, ein Block pro Zeile. Wenn dabei ein bis zwei Zeichen als Fragment übrig bleiben, deutet dies darauf hin, dass die Grenze bei Regel ② eigentlich kein Satzpunkt war – das Fragment wird an den vorherigen Block angehängt.
Der Befehl meldet vier Dinge, die alle überprüft werden müssen:
stale Blöcke, die durch den Schnitt geändert wurden – genaue Angabe, welcher Block und welche Wörter fehlen
tooFast Zu viele Zeichen, zu wenig Zeit zum Lesen
transcriptMoved Das Transkript ist nicht mehr das ursprüngliche
Wenn bereits Untertitel vorhanden sind – hier anhalten und nachfragen
Ohne --replace wird der Befehl direkt abgelehnt. Dies ist die einzige Stelle in diesem Skill, an der die Zustimmung des Benutzers eingeholt werden muss, denn --replace zerstört die manuell erstellten Aufteilungen und Formulierungen, die der Benutzer möglicherweise selbst angepasst hat und die nicht automatisch wiederhergestellt werden können.
Benutzer möchte nur ein paar Zeichen ändern Führe nicht „build“ aus. Lass ihn direkt in Studio ändern oder dir sagen, welche Blöcke geändert werden sollen.
Benutzer möchte alles neu machen Frage erst, ob er sicher ist, dann füge --replace hinzu.
4. Überprüfung: Block für Block in Studio
node "<Plugin-Root>/scripts/videocut-cli.cjs" open "<Projektverzeichnis>" --json
Nach dem Öffnen wechsle zur linken Spalte zum Reiter „Untertitel“. Eine Zeile = ein Block: Links die Nummer und die Zeit, rechts der Text. Klicke hinein, um direkt zu bearbeiten.
- Eingabe = neuen Block ab der Cursorposition erstellen
- Rücktaste am Zeilenanfang = mit vorherigem Block zusammenführen
- Rechte Spalte „Parameter → Untertitel“: Wähle eine der vier Voreinstellungen für das gesamte Video aus
- Auf dem Bildschirm siehst du die Untertitel direkt, Position und Schriftgröße sind proportional zum Bild – Vorschau und fertiges Video verwenden dieselben Werte
Bei der Überprüfung solltest du mindestens Folgendes bestätigen lassen: Sind die Eigennamen korrekt? Werden Zeichen verschluckt? Ist der Zeilenumbruch flüssig lesbar? Reicht die Anzeigedauer eines Blocks zum Lesen?
5. Ende bei subtitles.json
Dieser Abschnitt ist abgeschlossen. Kein physikalischer Schnitt, kein Storyboard, keine Animation, kein Rendering des fertigen Videos, und keine Aufforderung zum nächsten Schritt.
Die Berichterstattung muss getrennt erfolgen: Die strukturierte Rückmeldung des Produkts ist API/readback PASS; die echte visuelle Überprüfung durch eine Person im Projekt-Browser ist visual frame PASS; solange niemand tatsächlich überprüft hat, ob die Untertitel mit dem Bild übereinstimmen, lautet der Status human listening UNVERIFIED. DOM-, Screenshot- oder Dateiprüfungen sind kein Ersatz.
Grenze: Das Einbrennen ins Bild gehört nicht zu diesem Schritt
Die Ausgabemethode ist Einbrennen in das Bild, aber die Bilderzeugung erfolgt im Exportschritt. Die Ausgabe der Untertitel ist subtitles.json – alle darin enthaltenen Größenangaben sind Prozentsätze des Bildes, die beim Export einfach in Pixel der Ausgabeauflösung umgerechnet werden können. Beide Seiten verwenden dieselben Werte.
Das aktuell exportierte mp4 enthält keine Untertitel – dieser Schritt wurde noch nicht durchgeführt. Dieser Konsequenz muss im Bericht klar benannt werden. Sage nicht einfach „Untertitel sind fertig“ – der Benutzer könnte annehmen, dass das Endvideo sie enthält.
Wiederherstellung und Fehlerbehandlung
subtitles_exist: Es sind bereits Untertitel vorhanden. **Frage zuerst, verwende nicht direkt--replace. **revision_conflict: Eine andere Stelle schreibt ebenfalls. Lese erneut, überschreibe nicht automatisch.- Wörterbuch meldet „Zeile N kann nicht gelesen werden“: Das ist eine Zeile mit defektem Tabellenformat. Es werden nur Tabellenzeilen (im Format
| Korrekte Schreibweise | Häufig falsch erkannt |) verarbeitet; Prosa und Listen werden still ignoriert. transcript correctmeldet „must not change any word id, time or gap flag“: Der Korrekturvorschlag enthält Änderungen an der Zeit, nicht nur am Text. Korrigiere nur den Text, nicht die Zeit.runtime_unhealthy: Kein Neuinstallieren in einer Schleife.- Kein Fehler darf dazu führen, dass „Transkription abgeschlossen“ als „Untertitel fertig“ gemeldet wird. Das ASR-Ergebnis ist das Rohmaterial, nicht das Endprodukt.