zenstory-ai/video-recap

1. Positionierung und Arbeitsablauf

Diese Fertigkeit ist eine autarke Produktionsfähigkeit für Videokommentare und -schnitte, die Videoanalyse, Story-Erstellung, Bildschnitt, Voiceover-Text, Sprachsynthese und Ton-Bild-Mischung in einer durchgängigen Arbeitskette zusammenfasst. Alle Phasen teilen sich dasselbe Arbeitsverzeichnis work_dir und die darin enthaltenen JSON- sowie MP4-Artefakte:

understand.py (Videoanalyse) ▶ Agent erstellt Story-/Audio-Bild-Konzept und schreibt clip_plan.json oder narration.json ▶ [cut.py (Schnitt und Neuausgabe-Briefing)] ▶ validate.py (Lokale Mindestvalidierung) ▶ voiceover.py (TTS-Sprachausgabe) ▶ assemble.py (Mischung und Untertitel-Rendering)

Im täglichen Gebrauch kann direkt der Haupteintragspunkt scripts/recap.py verwendet werden, der automatisch die gesamte Kette durchläuft und an den Kreativ-Knotenpunkten pausiert. Alternativ können die einzelnen Phaseneinträge im scripts/-Verzeichnis (understand.py, cut.py, validate.py, voiceover.py, assemble.py) nach Bedarf aufgerufen werden.

Das Zerlegen eines vorhandenen Fertigfilms in eine Produktionsreferenz (production_reference.json) ist nicht Teil der Standard-Produktionskette. Wenn der Benutzer die Zerlegung eines Beispielvideos zur Analyse anfordert: Zuerst understand.py auf dem Beispielvideo ausführen (empfohlen ASR_SEGMENT_SECONDS=5), dann mit einer separaten Zerlegungsfertigkeit nacheinander Messung (measure), Annotation, Prüfung (check) und Export (export) durchführen. Die exportierte production_reference.json wird entweder in das work_dir des nächsten Durchlaufs kopiert oder als production_reference-Vorlage in der Ressourcenbibliothek registriert und über --project gebunden. Der Hauptworkflow führt kein automatisches Zerlegen durch und vergleicht auch keine neuen Fertigfilme mechanisch mit Referenzfilmen.

Der gesamte Workflow unterstützt die schrittweise Wiederaufnahme: Nachdem der Agent clip_plan.json oder narration.json geschrieben hat, kann der gleiche recap.py-Befehl erneut ausgeführt werden, um fortzufahren. Bei der Wiederaufnahme überprüft das Skript die in recap_run_manifest.json aufgezeichneten Quelldaten (Videopfad, Dateigröße, Änderungsdatum und Laufparameter); stellt es fest, dass das Arbeitsverzeichnis von einem anderen Video oder einer anderen Parameterkombination stammt, wird die Wiederverwendung direkt abgelehnt. Der Videoanalyse-Cache wird nur getroffen, wenn Quellvideo und Konfiguration exakt übereinstimmen. Der bei jeder Pause in der Konsole ausgegebene Fortsetzungsbefehl behält die ursprüngliche Aufrufweise bei, wandelt Video- und Pfadparameter automatisch in absolute Pfade um und ergänzt --work-dir. Der Befehl kann so in jedes beliebige Verzeichnis kopiert und direkt ausgeführt werden.

Der Bildablauf --edit-mode full|cut und die Audiostrategie --audio-mode narration|source-mix sind voneinander unabhängig: narration durchläuft die Standard-Kommentar-Sprachkette, source-mix erzeugt kein Voiceover, sondern mischt direkt den Originalton und optionale Hintergrundmusik. Das System unterstützt nur die fünf in der folgenden Tabelle aufgeführten legalen Routen; andere Kombinationen werden beim Start sofort mit einer Fehlermeldung abgewiesen:

Eingabe	--edit-mode	--audio-mode	Agent-Pause	Ablauf	Details
Einzelvideo	full	narration	1 Mal: narration.json schreiben	Analyse → Text schreiben → Prüfen → Sprachausgabe → Mischung	§4
Einzelvideo	cut	narration	2 Mal: Zuerst clip_plan.json schreiben, nach dem Schnitt narration.json zum fertigen Video schreiben	Analyse → Schnitt → Neuausgabe-Zeitplan-Briefing → Text schreiben → Prüfen → Sprachausgabe → Mischung	§4
Mehrere Videos	cut	narration	2 Mal: Wie oben, jedes Segment muss source_id haben	Quelldatenanalyse → Schnitt → Text schreiben → Prüfen → Sprachausgabe → Mischung	§4.5
Einzelvideo	full	source-mix	Keine Pause	Direkte Mischung des aktuellen gesamten Videos (keine Analyse oder TTS)	§4.7
Einzel / Mehrere Videos	cut	source-mix	1 Mal: clip_plan.json schreiben	Analyse → Schnitt → Mischung (kein Voiceover-Text)	§4.7

2. Kreative Verantwortung

Die kreative Entscheidungsbefugnis liegt vollständig beim Agenten. Bevor mit der Arbeit begonnen wird, ist der Kreativkontrollmodus dieser Runde zu bestimmen (CREATE offene Kreation / DIRECTED gezielte Kreation / REVISION Überarbeitung finaler Fassung, unabhängig von --edit-mode). Vor dem Einstieg in die Sprachausgabe und das Rendering werden als derselbe kreative Geist in einem Durchgang fünf Entscheidungen getroffen:

1. Regie-Entscheidung: Klären, warum das Publikum hereinkommt, wessen Perspektive (POV) durchgehend verfolgt wird, was der zentrale Spannungsbogen (Suspense) ist, wo die Emotion beginnt und endet, und welche Trumpfkarte bis zum Schluss aufgespart wird.
2. Story-Editierung: Jeder Beat muss vermitteln, „welche substanzielle Wendung die Situation genommen hat". Es werden auf keinen Fall langweilige Szenenzusammenfassungen geschrieben.
3. Bildschnitt: Die packendsten Aktionen, Reaktionsaufnahmen und die besten Ein- und Ausstiegspunkte auswählen, schleppende Überleitungen entfernen.
4. Ton / Voiceover: Zuerst für jeden Beat entscheiden, ob Bild, Originaldialog, Actionsound, Stille oder Voiceover die Führung übernehmen. Dann nach dem Prinzip „eine halbe Phrase vorbereiten, eine halbe Phrase lassen, eine halbe Phrase anknüpfen" den Text schreiben.
5. Publikumsprüfung: Aus der Perspektive eines Erstzuschauers dreimal prüfen: Das Bild ohne Voiceover ansehen, die Augen schließen und nur den Ton hören, und die Einlösung von Anfang und Ende überprüfen.

Die Aufgabenverteilung der drei Kontrollmodi, die Regel zum Schutz gesperrter Elemente unter REVISION, spezifische Schnitt- und Schreibttechniken sowie die Formatspezifikationen für recap_story_plan.json, visual_audio_board.json und style_card.json finden sich in references/creative-editing-playbook.md. Diese JSONs dienen dazu, überprüfbare kreative Entscheidungen festzuhalten und sicherzustellen, dass Bildauswahl, Dialogpausen und Kommentartext von Anfang bis Ende an derselben Story-Absicht festhalten.

3. Umgebung und Hinweise zum Fernzugriff

# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***

Ein und derselbe MIMO_API_KEY kann die gesamte Standardkette antreiben. Um die Transparenz des Datenflusses zu gewährleisten, werden die Netzwerkaufrufe dieser Fertigkeit wie folgt erläutert:

• Videoanalyse (understand.py): Sendet segmentierte Audiofenster an MiMo ASR (mimo-v2.5-asr), und extrahierte JPEG-Frames zusammen mit einer Zusammenfassung des background_research.json an MiMo VLM (mimo-v2.5). Wenn das Arbeitsverzeichnis bereits vollständige Analyse-Artefakte enthält, wird mit --brief-only oder --edited-storyboard-only rein lokal gearbeitet, ohne Netzwerkanfragen zu initiieren.
• Voiceover-Sprachausgabe (voiceover.py): Sendet den Kommentartext abhängig vom --tts-provider (Standard auto wählt bevorzugt den konfigurierten MiMo, dann Fish Audio, wählt niemals automatisch index-tts) an den entsprechenden TTS-Dienst:
  • mimo-tts: Sendet an MiMo TTS (mimo-v2.5-tts); wenn explizit --voice-ref <audio> übergeben wird, wird das Referenzaudio-Segment an mimo-v2.5-tts-voiceclone gesendet (bitte vor Verwendung sicherstellen, dass die Genehmigung zur Nutzung der Stimme vorliegt).
  • fish-audio: Benötigt Konfiguration von FISH_API_KEY, sendet jedes Voiceover-Textsegment zusammen mit FISH_TTS_REFERENCE_ID an FISH_TTS_API_URL (Standard https://api.fish.audio/v1/tts).
  • index-tts: Wird nur aktiviert, wenn explizit --tts-provider index-tts angegeben ist. Sendet den Text und INDEX_TTS_VOICE an den benutzereigenen INDEX_TTS_ENDPOINT (Details in references/index-tts.md).
• Kommentarvalidierung (validate.py), Videoschnitt (cut.py, shot_review.py) und Ton-Bild-Mischung (assemble.py): Reine lokale deterministische Logik und Aufrufe von ffmpeg / ffprobe, initiieren keine Netzwerkanfragen.

Token-Plan-Schlüssel, die mit tp- beginnen, werden standardmäßig an den China-Cluster gesendet. Der Cluster kann über MIMO_TOKEN_PLAN_CLUSTER umgeschaltet werden. Alle Konfigurationsoptionen finden sich in references/config-playbook.md, die Formate aller Zwischenprodukte in references/data-schema.md. Alle Pfadangaben wie scripts/... im Folgenden beziehen sich auf das Verzeichnis dieser Fertigkeit.

4. Der durchgängige Kreativ- und Schnitt-Workflow

4.1 Hintergrundrecherche und Videoanalyse

Sobald Filmtitel, Serienname oder populärwissenschaftliches Thema aus dem Dateinamen oder Benutzerbefehl erkannt werden können, wird vor dem Start gemäß references/research-guide.md die Figurenkonstellation und Vorgeschichte recherchiert und in work_dir/background_research.json geschrieben. So können bei der anschließenden Bildanalyse die Rollennamen direkt korrekt verwendet und Subtext verstanden werden, anstatt nur „Mann in Schwarz" oder „junge Frau" zu schreiben. Bei der Verkettung mehrerer Videos wird dies ebenfalls im Projekt-Wurzelverzeichnis work_dir geschrieben; das Skript synchronisiert es automatisch in die Quell-Unterverzeichnisse sources/<source_id>/.

Anschließend wird der Einstiegspunkt für Analyse und Orchestrierung gestartet:

python3 scripts/recap.py <video> --work-dir <work_dir> --context "Hintergrund"

Nachdem das Skript Audio-Extraktion, Erkennung von Stille- und Satzend-Ankerpunkten (speech_boundary_anchors.json), Szenenwechsel, VLM-Frame-Analyse und ASR-Transkription durchgeführt hat, generiert es das Storyboard-Puzzle storyboard/storyboard_*.jpg und das Kreativ-Briefing agent_narration_brief.md und pausiert automatisch.

4.2 Regie-Intention und Einstellungsplan (cut Phase 1)

Nach dem vollständigen Lesen von agent_narration_brief.md und der direkten Betrachtung der Storyboard-Frames werden zuerst recap_story_plan.json (mindestens 2 Kandidatenpläne auflisten, mit Auswahl der Haupt-POV, des Einstiegs-Hooks, des emotionalen Bogens und der zurückgehaltenen Trumpfkarte) und visual_audio_board.json (für jeden Beat festlegen, welcher Moment ausgewählt wird, warum ein- und ausgestiegen wird, und wer den Ton dominiert) geschrieben.

In der ersten Phase des cut-Modus wird anschließend der auf der Original-Zeitachse (SOURCE) basierende work_dir/clip_plan.json geschrieben (zu diesem Zeitpunkt wird noch kein narration.json geschrieben):

{
  "target_duration": "3m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=沈曼 | 撞见未婚夫搂着千金谈联姻 | 入点=推门看清两人动作 | 出点=转身攥紧户口本"
    }
  ],
  "required_evidence": {
    "nodes": [
      {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "推门撞见两人拥抱"}
    ],
    "before": []
  }
}

Die Einstellungsauswahl und Schnittpunkte müssen die folgenden Grundregeln strikt einhalten:

• reason-Sieben-Teile-Struktur: Nacheinander beat_id | narrative Funktion | Zustandsänderung der Situation (A→B) | POV=Person | Substantieller Höhepunkt dieses Segments | Einstiegspunkt = spezifische Aktion / Audio-Anker | Ausstiegspunkt = spezifische Reaktion / Zielpunkt. Dies zwingt jeden Bildabschnitt dazu, der Story-Entwicklung zu dienen.
• Unverzichtbare Bild- und Audio-Beweise (required_evidence): Endgültig beschlossene Schlüsselmomente (Highlights, Reaktionsaufnahmen, Schlüsselfragen/-antworten im Originalton) werden in das oberste required_evidence eingetragen (nodes registriert id/sourceabsoluter Pfad/start/end/track/content, before registriert unumkehrbare Paare). Sollte die Kantenadsorption einen dieser Muss-Intervalle entfernen oder die Reihenfolge ändern, wird das Skript dies direkt blockieren und einen Fehler melden.
• Später Einstieg und Auswahlverzicht: Standardmäßig wird im Zeitablauf „spät eingestiegen" (direkt in den Konfliktausbruch, die absurde Diskrepanz oder die Schlüsselaktion geschnitten, langsame Vorbereitungen wie Türöffnen, Begrüßungszeremoniell usw. werden weggelassen). Nur wenn der Konflikt im linearen Ablauf zu spät auftritt, ist ein <= 2.5s kurzer Cold-Open-Suspense-Moment erlaubt. Dieser muss jedoch ohne Vorbereitung verständlich sein, darf nicht dieselbe Kameraposition wie das Hauptvideo wiederholen, darf nur Spannung aufbauen und auf keinen Fall das Ergebnis des Twists vorwegnehmen. Wenn das Voiceover den Originalton unterdrückt, werden bevorzugt Reaktionsaufnahmen, Aktionsdetails oder statische Einstellungen gewählt; es wird vermieden, Bilder von Figuren, die ununterbrochen den Mund aufreißen und reden, während der Ton stummgeschaltet ist, unter das Voiceover zu legen. Gleiche Nicken- oder Starren-Reaktionen nicht mehr als zweimal wiederholen.
• Sichere Schnittpunkte am Satzende und Atem-Nachlauf: Der Schnittpunkt muss am Anfang/Ende des Originals, innerhalb eines Satzende-Ankerpunktes oder eines Stillefensters liegen, oder zu einer nahtlosen direkten Verbindung benachbarter Segmente aus derselben Quelle gehören. Bei Adsorption an Satzenden wird automatisch ein Reaktions-/Atemraum von maximal 0.30s innerhalb des Stille-Fensters reserviert, ohne jemals harte Schnittpunkte zu überschreiten. Die Mindestlänge eines Segments beträgt 0.8s. Der letzte Beat am Ende des Films muss, nachdem die finale Aktion oder Zeile abgeschlossen ist, 1.5–2.5s Ausdrucks-Nachhall lassen und sauber abschließen, bevor die nächste Szene beginnt. Ein Schnitt mitten in eine Originalton-Zeile löst eine unsafe_clip_sentence_boundary-Blockade aus und gibt einen nearest_safe-Hinweis. Wenn ein Zurückweichen auf einen harten Schnitt gleichzeitig einen <= 0.20s kurzen Bildsprung und einen abgehackten Satz verursacht, wird direkt eine shot_speech_conflict-Blockade gemeldet.
• Häufige schnelle Schnitte und Erkennung von Bruchstücken: Nachdem cut.py die edited_source.mp4 gerendert hat, wird automatisch shot_review.py aufgerufen, um shot_review.json zu generieren. Es führt eine direkte harte Blockade für extrem kurze Rest-Frames (flash_slivers) mit einer Dauer von <= 0.20s (ca. 1–5 Frames) durch. Bei Actionszenen oder dichten Schuss-Gegenschuss-Sequenzen kann auch manuell ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null - oder das schreibgeschützte Werkzeug scripts/shot_review.py (Verwendung siehe references/shot-review.md) verwendet werden, um Hochdruck-Schnittpunkte zu lokalisieren. Es muss jedoch unterschieden werden zwischen Schnittpunkten, die aus dem Originalfilm stammen und Schnittpunkten, die durch die aktuelle Montage entstanden sind. Handelt es sich um Schnittpunkte aus dem Originalfilm, die durch das vollständige Löschen eines irrelevanten kurzen Shots oder das Verschieben des Schnittpunktes an den Rand einer Schnittwolke entstanden sind, ist dies in Ordnung. Handelt es sich um durch die aktuelle Montage erzeugte Schnittpunkte (z. B. Reste weniger Frames eines benachbarten Shots an einer harten Schnittkante, zerhackte Schuss-Gegenschuss-Sequenzen), werden die Ein- und Ausstiegspunkte erweitert oder benachbarte Segmente aus derselben Quelle verschmolzen. Es ist strengstens verboten, dies durch das Einfügen von Übergängen zu kaschieren.

Nach dem Schreiben von clip_plan.json wird recap.py erneut ausgeführt. Das Skript ruft cut.py auf, das eine dreistufige Grenzadsorption (harter Schnitt → Stille-Am-Ende-Adsorption mit Nachlauf → Frame-Raster-Ausrichtung) durchführt, die edited_source.mp4 mit konstanter Bildrate rendert und einen Blitzlicht-Bild-Scan durchführt. Anschließend werden die ASR-, VLM- und Satzende-Ankerpunkte auf die Ausgabe-Zeitachse des fertigen Videos umgerechnet (speech_boundary_anchors_output.json, storyboard/edited_storyboard.*), und erneut wird pausiert, um auf das Schreiben des Voiceover-Textes zu warten.

4.3 Erstellung von Voiceover-Text und Originalton-Dialogpausen (full / cut Phase 2)

In der Text-Erstellungsphase (Phase 1 bei full-Modus, Phase 2 nach dem Schnitt von edited_source.mp4 bei cut-Modus) wird zuerst das geschnittene Storyboard betrachtet, visual_audio_board.json um die Ausgabe-Zeit des fertigen Videos ergänzt, und nach Bedarf style_card.json erstellt. Anschließend wird work_dir/narration.json verfasst:

[
  {
    "start": 0.2,
    "end": 5.0,
    "narration": "Fünf Jahre Beziehung, mit dem Haushaltsbuch in der Tasche zum Heiratsantrag unterwegs, öffnet Shen Man die Tür und sieht, wie ihr Verlobter eine junge Erbin umarmt und über eine Verbindung spricht.",
    "pause_after_ms": 250,
    "overlaps_speech": true
  }
]

Hinweis: Im cut-Modus muss narration.json direkt die OUTPUT-Zeitstempel des geschnittenen Endvideos verwenden (0 .. Gesamtdauer des Endvideos) (Bei separatem Aufruf des Validators validate.py --mode cut_output). Beim Schreiben sind neun Kern-Schreibregeln zu befolgen (Details und positive/negative Beispiele in references/creative-editing-playbook.md):

1. Innerhalb der ersten 2,5 Sekunden den Hook oder Audio-Highlight präsentieren, direkt eine konkrete Kontrastaktion oder den Kern-Suspense zeigen. Keine Biographie, Datumsangabe oder einleitende Floskel schreiben; ein kalter Start länger als 2.5s ohne Voiceover oder Originaldialog löst eine weak_cold_open_silence-Blockade aus.
2. Hintergrund, Figurenbeziehungen und Kausalitäten klar darstellen, die Anzahl der Namensnennungen kontrollieren und „Bildbeschreibung" vermeiden: Wenn background_research.json Rollennamen bereitstellt, ist die Verwendung vager äußerlicher Beschreibungen wie „Mann in Schwarz" oder „junge Frau" strengstens verboten (Verstoß führt zur generic_character_label-Blockade). In Kurzfilmen unter 60 Sekunden maximal 1–2 Kernfiguren namentlich nennen (im ersten Satz maximal 1 Person nennen und gleichzeitig ihre Identität klarstellen). Alle anderen Nebenfiguren werden einheitlich mit ihrer Beziehung/Identität bezeichnet (z. B. „Ex-Freundin", „ihr Vorgesetzter", „kaiserlicher Arzt"). Jeder Satz muss die Handlung vorantreiben: „Situation → Aktion → unmittelbare Konsequenz".
3. Ton-Bild-Korrespondenz: „eine halbe Phrase vorbereiten, eine halbe Phrase lassen, eine halbe Phrase anknüpfen"; bei starken visuellen Elementen muss Frequenzgleichheit herrschen: Bei hochkarätigen Originalton-Zeilen, Ohrfeigen-Geräuschen, stummen Reaktionsaufnahmen wird entschlossen geschwiegen und Platz gemacht. Nachdem der Originalton verklungen ist, wird eine halbe Phrase angeknüpft, um den Subtext zu enthüllen. Bei starken visuellen Aktionen wie Küssen, Ohrfeigen, Niederknien, Ohnmacht, Vorzeigen eines Andenken muss der Originalton erhalten bleiben oder das direkt benachbarte Voiceover den Grund dafür klar benennen. Es ist verboten, dass Bild und Ton aneinander vorbeitreden. Im gesamten Film ist eine tote Stille ohne Voiceover oder Originaldialog von mehr als 5.0s Dauer verboten (Verstoß führt zur excessive_dead_air-Blockade).
4. Strenge Einhaltung der roten Linien für das Ein- und Ausblenden von Originalton: Beim Absenken des Originaltons für das Voiceover (overlaps_speech: true) muss start dicht an einem Satzende-Anker oder in einer Stillezone liegen (Verstoß führt zur interrupts_source_sentence-Blockade). Ebenso darf der Originalton nach Ende des Voiceovers nicht mitten in einer halbgesprochenen Zeile plötzlich wieder auf volle Lautstärke gebracht werden (Verstoß führt in der Validierungs- und Mischphase zu unsafe_source_release bzw. unsafe_source_handoff-Blockade).
5. Strenge Kontrolle des Zeichenbudgets pro Zeitfenster, natürliches Sprechtempo und vollständige Satzendungen beibehalten: Jeder Abschnitt muss mit einem vollständigen Satzende-Zeichen abgeschlossen sein (unvollständige Sätze führen zur incomplete_sentence-Hardblockade). Die Wortanzahl muss durch Präzision an das Zeitfenster angepasst werden; es wird nicht auf hohe Geschwindigkeit gesetzt, um Text hineinzuzwängen. Im full-Modus führt eine Überschreitung des Budgets um das 1,25-fache direkt zur over_budget-Blockade. Der Validator wird niemals eigenmächtig Wörter für den Agenten löschen.
6. Keine kommentierenden, verallgemeinernden oder telegrammstilartigen Formulierungen; das Ende muss das Bild die Geschichte erzählen lassen: Es werden natürliche, zusammenhängende mündliche Sätze (kurz und lang) geschrieben; keine einsilbigen, abgehackten Sätze. Kommentierende und verallgemeinernde Floskeln wie „Das bedeutet...", „Dies ist ein Kampf um...", „Macht und Stolz treten ab", „Das Rad des Schicksals" sind strengstens verboten (löst editorial_commentary_tone-Warnung aus). Das Ende der Geschichte muss direkt durch das Bild und den Originalton dargestellt werden. Es ist verboten, nach der Auflösung des Endes noch einen überflüssigen zusammenfassenden oder verallgemeinernden Voiceover-Satz anzuhängen. Ebenso darf nach dem abschließenden Voiceover kein Originalsatz angehängt werden, der dasselbe Ergebnis wiederholt.
7. An konkrete Bildbeweise halten und Disziplin bei reiner Instrumentalmusik: Mit sichtbaren Blicken, Requisiten, Aktionsdetails sprechen; keine psychologischen Aktivitäten der Figuren außerhalb des Bildes erfinden. Wenn externe Hintergrundmusik verwendet wird (BGM_PATH), muss es sich um reine Instrumentalmusik (keine gesungenen Texte) handeln. Wenn der Originalfilm bereits unvermeidbare laute gesungene Einspieler enthält, wird keine externe Hintergrundmusik mehr darübergelegt, um Konflikte zwischen mehreren Tonspuren zu vermeiden.
8. Untertitel für Originalton-Dialogpausen überprüfen: Wenn die Untertitel-Blende des Originalfilms aktiviert ist und hochkarätige Originalton-Passagen erhalten bleiben, werden gleichzeitig in work_dir/original_subtitles.json die korrigierten Original-Dialogzeilen auf der Basis der Endzeit des Films aufgeschrieben, um ASR-Homophonfehler zu korrigieren.
9. Nach dem Schreiben zuerst eine dreifache Selbstprüfung durchführen: Zuerst den gesamten Text lesen, um zu prüfen, ob die Storyline stimmig ist und die Fakten mit dem Originalfilm übereinstimmen. Dann anhand des Zeitfensters prüfen, ob es Überschneidungen oder Wortzahlüberschreitungen gibt. Abschließend validate.py ausführen (oder direkt recap.py erneut laufen lassen). Wenn ein externer Promotion-Titel, Cover-Frame und Text-Overlay-Plan (packaging_plan.json) erstellt werden müssen, muss dies nach Abschluss der Haupt-Story gemäß references/promotional-copy.md erfolgen.

4.4 Sprachsynthese und Ton-Bild-Misch-Rendering

Nach dem Schreiben von narration.json wird derselbe recap.py-Befehl erneut ausgeführt:

1. Lokale deterministische Validierung (validate.py): Erzeugt narration_lint.json. Führt eine harte Zugangskontrolle für Zeitüberschneidungen, Grenzüberschreitungen, Wortzahl-Budgetüberschreitungen, unvollständige Sätze, kalte Starts, tote Stille über 5 Sekunden, Unterbrechung von Originalton, halb gesprochenen Originalton beim Zurückschalten, vage Rollenbezeichnungen und Platzhalter-Leaks durch. Bei einem Error wird sofort angehalten.
2. TTS-Sprachausgabe (voiceover.py): Synthetisiert Sprachsegmente abschnittsweise und schreibt sie in tts_segments/ und tts_meta.json. Der Cache wird exakt auf Text, Stimmfarbe, Modell und Referenz-Audio-Fingerabdruck getroffen. Wenn die Audiolänge eines Segments unter der unteren Grenze des normalen Sprechtempos (TTS_MIN_SPEECH_RATE) liegt (mögliches Halluzinieren des Modells), wird automatisch ein erneuter Versuch gestartet und die abgelehnte Datei als *.rejected.wav gespeichert (nicht in den Cache aufgenommen).
3. Ton-Bild-Synthese (assemble.py): Mischt und rendert das Bild, das abschnittsweise Voiceover, den abgesenkten und am Satzende wieder angehobenen Originalton (Details zur source_handoff_status in references/data-schema.md), optionale BGM (BGM_PATH), optionale dekorative Übergangs-Soundeffekte und eine anspruchsvolle visuelle Verpackung (work_dir/packaging_plan.json: Unterstützt 9:16 vertikale Bühnen-/Serien-Doppelgoldlinien-Bildformat, 16:9 Kino-Stempel und cremeweiße Papiergefühl-Untertitelstreifen, @2x-überabgetastete Personen-Namensschilder/Datenkarten/kalligrafische Text-Overlays, sowie zweischichtige weiche Hervorhebungspunkt-Beleuchtungs-Untertitel; oder packaging_layers.json statische Overlays), und eine sanfte Abblende am Ende (Standard 350ms) zu einem finalen MP4. Zusätzlich wird ein backend-unabhängiges timeline.json ausgegeben (mit --export-jianying kann gleichzeitig ein Jianying-Entwurf exportiert werden).

Sollte ein Voiceover-Abschnitt trotz der erlaubten mikroskopischen Beschleunigungsobergrenze nicht in das verfügbare Zeitfenster passen, meldet der Synthesizer direkt no_safe_stitch und blockiert. Der Voiceover-Endton wird niemals abgeschnitten. Weitere Audiomodi, Audio-Routing und Spezifikationen für die äußere visuelle Verpackung finden sich in references/audio-modes.md, references/audio-routing.md und references/packaging.md.

4.5 Mehrfach-Video-Schnitt und Ressourcenbibliothek

Die Eingabe mehrerer Videos wird nur im cut-Modus unterstützt. Das Projekt-Briefing listet für jedes Video eine feste source_id auf. Beim Schreiben von clip_plan.json muss jedes Segment die zugehörige source_id angeben:

python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep

Wenn die Analyseergebnisse einer Episode zur Wiederverwendung über mehrere Episoden hinweg in einem lokalen Verzeichnis gespeichert werden sollen, kann die leichte Datei-Materialbibliothek aktiviert werden (--material-library-dir .video-materials --save-materials und --use-materials). JSON/MD-Dateien können dann direkt mit grep durchsucht werden. Im selben Bibliotheks-Wurzelverzeichnis können auch wiederverwendbare Produktionsressourcen (BGM, Soundeffekte, Stimmfarben, Schriftarten, Overlays) sowie Vorlagen mit Annahmeaufzeichnung (subtitle_style, packaging, production_reference) und Beispielvideos registriert werden. Diese können über scripts/library.py check|list|show abgefragt und über --project recap_project.json auf einen Durchlauf gebunden werden. Nach jeder Synthese wird in work_dir/resource_lock.json die tatsächlich verwendete Ressource und deren Autorisierungsstatus aufgezeichnet. Details in references/resource-library.md.

Um die vertikalen Pixelintervalle von festen Untertiteln im Originalfilm zu messen und eine präzise Maske zu ermöglichen, kann im vollständigen Quellcode-Repository tools/measure_subtitle.py <video> ausgeführt werden, oder es können direkt die extrahierten Frames betrachtet werden, um die oberen/unteren Grenzen abzulesen, die dann als --subtitle-y-top und --subtitle-y-bot übergeben werden.

4.6 Finale Sichtung und Auslieferungsprüfung

Kein Skriptindikator, keine Anschlusspunktbewertung, kein Frame-Raster-Bild und kein automatischer QC-Bericht kann die visuelle und auditive Prüfung durch den Menschen ersetzen. Vor jeder Auslieferung muss die finale, dem Benutzer auszuliefernde Datei direkt geöffnet und einer fünfstufigen Prüfung unterzogen werden:

1. Einmal in Originalgeschwindigkeit durchschauen: Von Anfang bis Ende ohne zu beschleunigen oder zu überspringen, dabei alle störenden oder ruckelnden Stellen notieren.
2. Jeden Schnittpunkt einzeln prüfen: Jeden Schnittpunkt 0.5–1 Sekunde davor und danach herauszoomen und auf Blitzframes, halbe Überblendungen, Aktionssprünge und abgehackte halbe Originalsätze prüfen.
3. Mit geschlossenen Augen nur zuhören: Ohne Bild nur den Ton hören, prüfen, ob das Voiceover nicht zu abgehacktem Telegrammstil zersplittert ist, ob die Übergänge klanglich glatt sind und die wichtigen Originalton-Zeilen klar verständlich sind.
4. Drei dramaturgische Höhepunkte einzeln herausgreifen: Die ersten 5 Sekunden (Einstiegs-Hook), den mittleren emotionalen Höhepunkt und die letzte Szene des Films einzeln erneut ansehen. Bestätigen, dass der Einstiegszeitpunkt, der emotionale Verweilmoment und der Nachhall am Ende alle funktionieren.
5. Überarbeitungsabgleich und Spezifikationsprüfung: Im REVISION-Modus zuerst Punkt für Punkt bestätigen: „Die benannten Änderungen wurden korrekt umgesetzt, die nicht benannten gesperrten Elemente wurden nicht angetastet." Abschließend die Decodierungsintegrität, Gesamtdauer, Rest-Frame-Scan und Audio-/Video-Codec-Spezifikationen in final_qc.json überprüfen (--require-final-qc ist standardmäßig aktiviert; blockierende Elemente bestimmen direkt den Exit-Code. Nur zum Debuggen kann --no-require-final-qc übergeben werden).

Bei der Auslieferung des Endprodukts müssen die metadata.warnings in final_qc.json überprüft werden: Solange diese nicht leer sind (z. B. partial_tts aufgrund teilweiser Fehlertoleranz oder subtitle_burn_degraded aufgrund fehlender libass-Bibliothek im lokalen ffmpeg, was zu einem Downgrade auf externes .srt führt), muss der Benutzer ehrlich informiert werden. Es reicht nicht, nur „Rendering erfolgreich" zu melden.

4.7 Originalton-Fertigfilm ohne Kommentar

# Misch und synthetisiere direkt das gesamte aktuelle Eingabevideo; führt keine implizite Analyse, ASR oder TTS durch
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# Generiere einen Schnittplan gemäß dem cut-Workflow, schneide und synthetisiere dann direkt den Originalton-Fertigfilm, ohne auf narration.json zu warten
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix

source-mix durchläuft die vollständige Mischung, sanfte Abblende am Ende und Audio-Neucodierung. Beim Wechsel des Audiomodus muss ein neues Arbeitsverzeichnis verwendet werden. Details in references/audio-routing.md.

5. Selbsttest und schreibgeschütztes Dashboard

python3 scripts/doctor.py
python3 scripts/dashboard_server.py --root <Verzeichnis> [--port 0] [--open]

doctor.py überprüft die lokale Installation von ffmpeg/ffprobe, Untertitelfilter und die Konnektivität zu den verschiedenen Remote-Dienst-Schlüsseln. dashboard_server.py startet auf 127.0.0.1 eine streng schreibgeschützte, minimalistische Sichtungsplattform (reagiert nur auf GET und HEAD), scannt automatisch die Fertig-Arbeitsverzeichnisse und library.json im --root-Verzeichnis und zeigt übersichtlich die Wiedergabe des Fertigfilms, die synchrone Gegenüberstellung von Voiceover-Text und Einstellungen sowie eine Vorschau der Materialbibliothek an.

6. Ausgabe und Parameter

Kern-Liefergegenstände:

• recap_<video>.mp4: Finaler Kommentar- oder Originalton-Fertigfilm.
• subtitles.srt / subtitles.ass: Generierte Untertiteldateien.
• work_dir/: Komplette Sammlung von Analyse-, Planungs- und Validierungszwischenprodukten. Feldspezifikationen in references/data-schema.md.
• work_dir/recap_story_plan.json und visual_audio_board.json: Die vom Agenten festgelegten Regie-Intentionen sowie Storyboard- und Audio-/Bild-Entscheidungen.

Die vollständigen Kommandozeilenparameter basieren auf der Ausgabe von python3 scripts/recap.py --help sowie dem --help der einzelnen Phasenskripte. --style ist ein unverändert an den Text-Agenten weitergeleiteter Freitext; es handelt sich nicht um eine feste Voreinstellung oder einen Aufzählungsschalter.

7. Fähigkeitsgrenzen

• Die lokale deterministische Basisvalidierung (Rest-/Bruch-Einstellungen, Dialogabschneidung, Voiceover-über-Dialog, harte Wortzahl-Obergrenze pro Zeitfenster, überlanger Schwanzabgleich, Verlust von Muss-Bildern, Platzhalter-Leak, Decodierungs- und Container-Spezifikationen) läuft stets als harte Zugangskontrolle. Die Skripte sind nur für die mechanische Ausführung und das Abfangen auf der Engineering-Ebene verantwortlich.
• Für semantische und narrative Qualitätsmerkmale wie die Story-Arc, den Einstiegs-Hook, die Atmung von Bild und Ton sowie die inhaltliche Konsistenz gibt es keine modellbasierte Bewertungs-Zugangskontrolle. Diese werden vom Agenten eigenständig anhand der Bildbeweise, der Originalton-Zeitachse und des references/creative-editing-playbook.md gesteuert und durch eine abschließende audiovisuelle Prüfung vor der Auslieferung sichergestellt.