zenstory-ai/video-reference

1. Positionierung

Diese Fähigkeit dient dazu, auf Anfrage ein bereits fertiggestelltes, hochwertiges Erklärvideo zu zerlegen und dessen Bearbeitungsrhythmus, Tonaufteilung und narrative Techniken in Methodenkarten und quantitative Metriken zu extrahieren, die als direkte Referenz für die nächste Produktion dienen. Der gesamte Vorgang läuft lokal und gibt nur Messdaten, Annotationsmarkierungen und eine anonymisierte Referenzdatei aus. Es wird weder MiMo aufgerufen noch der tägliche Produktionsablauf bewertet oder blockiert.

Der Agent agiert hier als Zerlegungs-Redakteur: Zunächst wird sachlich festgehalten, „wie genau dieses fertige Video geschnitten und vertont wurde“ (Fakten des Originalvideos). Daraus werden dann Erkenntnisse abgeleitet, „wie man diese Techniken auf neues Material übertragen kann“ (übertragbare Methoden). Fakten und Methoden müssen strikt getrennt werden: Fakten, die Namen, Handlungsdetails und spezifische Dialoge des Originalvideos enthalten, verbleiben ausschließlich im lokalen Zerlegungsverzeichnis. Die endgültig exportierte production_reference.json enthält nur die allgemeinen Methoden und gemessenen Rhythmuswerte.

2. Eingabe

• Die zu zerlegende Videodatei (unterstützt .mp4 / .mov / .mkv / .webm).
• Das Verzeichnis U mit den Ergebnissen der Videoanalyse für dieses spezifische Video (es wird empfohlen, in der Analysephase ASR_SEGMENT_SECONDS=5 zu setzen; je feiner die Fensterung, desto genauer die berechnete Erzählgeschwindigkeit). Diese Fähigkeit liest daraus optional asr_result.json, asr_timing_evidence.json und background_research.json (die darin registrierten Charakternamen, Aliasnamen und ASR-Dialoge werden alle in die Anti-Spoiler-Leak-Prüfung einbezogen); bei der manuellen Annotation sollte der Agent zusätzlich das Storyboard-Puzzle (storyboard) und die vlm_analysis.json zu Rate ziehen.

Selbst wenn keine Videoanalyse durchgeführt wurde, kann diese Fähigkeit eigenständig ausgeführt werden. Die exportierte Erzählgeschwindigkeit bleibt dann jedoch leer, die Anti-Spoiler-Wortliste für die Leckprüfung basiert nur auf den manuell vom Agenten geschriebenen entities, und der check gibt entsprechende Warnungen aus. In diesem Fall kann frames --span 0,<Dauer> --step 2 verwendet werden, um Einzelbilder für ein Puzzle zur visuellen Unterstützung zu extrahieren.

Die folgenden scripts/... Pfade beziehen sich auf das Verzeichnis dieser Fähigkeit.

3. Zerlegungsablauf

python3 scripts/reference.py measure <Video> --work-dir U        # Einmalige ffmpeg-Messung von Schnittpunkten und Lautstärke, Zwischenspeicherung anhand der Dateiidentität
python3 scripts/reference.py frames  <Video> --work-dir U --review          # Überprüfung vermeintlicher Schnittpunkte durch Frame-für-Frame-Bildausgabe
python3 scripts/reference.py frames  <Video> --work-dir U --longest 5       # Extrahiert die 5 längsten Aufnahmen zur Überprüfung auf übersehene Schnittpunkte
python3 scripts/reference.py check   --work-dir U [--json]      # Validiert die Zerlegungsdatei und gibt abgeleitete Metriken aus
python3 scripts/reference.py export  --work-dir U --out <work_dir der nächsten Produktion>/production_reference.json

1. Messung von Aufnahmen und Lautstärke (measure): Das Skript erstellt U/reference_measurements.json (nicht manuell bearbeiten). Es zeichnet die Schnittpunkte des gesamten Videos, die Verteilung der Aufnahmelängen, die Anzahl der Schnitte pro Minute, die Dichtekurve der Schnitte im gleitenden 10-Sekunden-Fenster, die integrierte Lautstärke (Integrated LUFS), den Lautstärkedynamikumfang (LRA), den True Peak sowie die kurzfristige Lautstärke pro Sekunde auf. Dieser Schritt erfordert eine vollständige Decodierung des gesamten Videos (ein 5-minütiges 720p-Video benötigt ca. 15–70 Sekunden, ein 4K-Video ca. 7 Minuten); solange die Videodatei unverändert ist, wird der Cache direkt wiederverwendet. Eine separate Anpassung der Schwellenwerte --soft-score oder --hard-score erfordert keine erneute Decodierung.
   • Logik der Schnitterkennung: Frames mit einem scdet-Szenenwechsel-Score ≥10 werden direkt als Schnittpunkte gewertet. Bei Scores zwischen 4 und 10 wird ein Frame nur dann als Schnittpunkt gewertet, wenn sein Score mehr als das Doppelte des höchsten Scores der anderen, nicht benachbarten Frames in einem Fenster von 0,3 Sekunden davor und danach beträgt (d. h. ein herausragender lokaler Peak). Dies filtert die meisten Kamerabewegungen, schnellen Zooms und Blitze heraus und ordnet diese unsicheren Frames dem Überprüfungsfenster shots.review_windows zu. Da der scdet-Score außerdem die Bildveränderung zum vorherigen Frame abzieht, kann der scdet-Score bei einem harten Schnitt von einer stark bewegten Aufnahme zu einem statischen Bild auf etwa 1 Punkt gedrückt werden. Daher werden auch die Peaks der Frame-Differenz (mafd) selbst in shots.review_windows aufgenommen, um sie manuell zu überprüfen, aber nicht automatisch als Schnitt gewertet.
2. Visuelle Überprüfung der Schnitte (frames): Jeder feste Schwellenwert wird in der Realität unweigerlich Kompromisse eingehen (ein harter Schnitt in einer dunklen Nachtszene kann nur 5–7 Punkte haben, während ein langer Shot in einer heftigen Kampfszene alle 0,2 Sekunden einen Peak von 7–8 Punkten erzeugen kann). Daher ist eine visuelle Überprüfung zwingend erforderlich. Die Ausführung von frames --review erstellt für jedes zu überprüfende Fenster eine Frame-für-Frame-Collage. Die Ausführung von frames --longest 5 extrahiert aus den 5 längsten Aufnahmen des gesamten Videos gleichmäßig verteilt 12 Frames und erstellt eine Collage. Die Bilder werden in U/reference_frames/ ausgegeben, und das Terminal gibt die Zeitsekunden für jedes Bild aus. Nach der visuellen Überprüfung werden die Korrekturen in labels.cut_fixes eingetragen: add für echte Schnittpunkte, die der Algorithmus übersehen hat (Sekunden), remove für falsche Schnittpunkte, die der Algorithmus fälschlicherweise gemeldet hat (Sekunden; sie werden als passend erkannt, wenn die Abweichung vom gemessenen Schnittpunkt ±0,1 Sekunden beträgt). Wenn bestätigt wird, dass alles korrekt ist und keine Änderungen erforderlich sind, muss explizit "cut_fixes": {} gesetzt werden, um anzuzeigen, dass die Überprüfung abgeschlossen ist. Hinweis: Sobald measure erneut ausgeführt wird und sich die zu überprüfenden Fenster ändern, sind die alten cut_fixes ungültig. Der Agent muss die Überprüfung anhand der neuen Fenster erneut durchführen und aktualisieren. Nach Abschluss der Überprüfung werden alle nachfolgenden Statistiken zu den Aufnahmen, die Schnittdichte der Abschnitte und das endgültige Exportobjekt auf Basis der korrigierten Schnittpunkte neu berechnet.
3. Annotation von Tonspuren und Abschnitten (labels): Vom Agenten in U/reference_breakdown.json unter dem Schlüssel labels auszufüllen – einschließlich der Tonquellen (audio_spans), der narrativen Funktionsabschnitte (sections), des Untertitelstils (subtitles) und der Annotationsgrundlage (basis).
   • Tonspurgrenzen müssen an den tatsächlichen Start- und Endpunkten der Audiospuren liegen: Die Wechselpunkte von audio_spans müssen auf den Moment fallen, in dem das Ohr tatsächlich den Beginn oder das Ende einer menschlichen Stimme hört, nicht auf den Zeitpunkt, an dem ein Untertitel ein- oder ausgeblendet wird. (Wenn das Ende einer Erzählung nach dem Frame des Untertiteleinblendens markiert wird, liegt es in der Praxis oft 0,24–0,42 Sekunden später als das tatsächliche Ende der Audiospur.) Wenn im Verzeichnis U/speech_boundary_anchors.json vorhanden ist, verwenden Sie direkt die darin enthaltenen acoustic_pauses (start ist der Endpunkt des vorherigen Satzes, end ist der Startpunkt des nächsten Satzes), um die Grenzen auszurichten. Da die Audio-Video-Synchronumschaltungsrate (switch_on_cut_share) nur Fehlertoleranzen von ±0,25 Sekunden um die Schnittpunkte erkennt, führt eine falsche Markierung der Grenzen zu einer stark verzerrten Berechnung der Umschaltungsrate. Voice-over oder innere Monologe von Charakteren des Originalvideos gehören weiterhin zur Tonspur des Originals und werden einheitlich als original_dialogue markiert. Wenn Sie in der Vorgehensweise unterscheiden möchten, schreiben Sie dies in die folgenden source_facts und methods.
   • Nach dem Ausfüllen der labels kann zunächst check ausgeführt werden, um die im Terminal ausgegebenen abgeleiteten Statistikwerte (derived) einzusehen (Anteil der einzelnen Tonspuren an der Gesamtzeit, Schnittdichte der einzelnen Abschnitte, Wortgeschwindigkeit der Erzählung, Anteil der Tonspurwechsel, die auf harte Bildschnitte fallen, die Positionsverteilung der narrativen Funktionsabschnitte auf der Zeitachse structure, sowie die relative Position des ersten Auftretens der Originalstimme first_original_at).
4. Extraktion von Fakten und übertragbaren Methoden (source_facts und methods): Basierend auf den soeben berechneten objektiven Daten werden in derselben reference_breakdown.json die Fakten des Originalvideos (source_facts – müssen an konkrete Zeitintervalle oder Messpfade gebunden sein und die beteiligten Eigennamen explizit als entities auflisten) und die übertragbaren Methoden (methods – enthalten die Verfahrensregel rule, den Anwendungsbereich applies_when, die Vermeidungsbedingungen avoid_when, die betroffenen nachgelagerten Dateien applies_to, die unterstützenden Beweise evidence und die quantitativen Referenzindikatoren targets) weiter ausgefüllt. Hinweis: In targets sind nur Referenzpfade {"from": "<Messpfad>"} erlaubt. Es ist strengstens verboten, konkrete Zahlen direkt in den Regeltext zu schreiben. Beim Export werden die gemessenen Werte automatisch vom Skript eingefügt.
5. Validierung und Export (check → export): Nachdem check null Fehler bestätigt hat, wird export ausgeführt, um production_reference.json zu exportieren. Vor dem Schreiben auf die Festplatte führt der Exporter eine erneute vollständige Anti-Spoiler-Leak-Prüfung aller Felder des Exportobjekts durch.

Die vollständigen Felddefinitionen, Aufzählungstabellen und Vergleiche von guten/schlechten Methodenschreibweisen finden Sie in references/reference-schema.md.

4. Validierungs- und Anti-Leak-Regeln

reference.py check bricht mit Exit-Code 1 ab, wenn einer der folgenden Fehler (error) auftritt:

Regel-Nr.	Validierungsanforderung
R1	Top-Level, labels, fact, method, target, cut_fixes verwenden alle strikt geschlossene Schlüsselsets und geschlossene Aufzählungen; fact darf keine Felder von method enthalten, method keine Felder von fact; IDs müssen das Format f1… / m1… haben und global eindeutig sein; der Feldtyp subtitles ist festgelegt; die Begründung reason für skipped_dimensions muss ein nicht-leerer String sein
R2	audio_spans und sections müssen aufsteigend nach Zeit sortiert, nicht überlappend, mit einer maximalen Lücke von ≤0,5 Sekunden zwischen benachbarten Elementen sein und die gesamte Videolänge vollständig abdecken; die Zeitstempel für Untertitelbeweise müssen innerhalb der Videolänge liegen; cut_fixes.remove muss mit einem gemessenen Schnittpunkt übereinstimmen, add darf nicht mit einem vorhandenen Schnittpunkt duplizieren
R3	Jedes fact muss entweder einen Zeitanker t: [a, b] (innerhalb der Videolänge) oder einen Messanker measure: [Pfad] (der auf einen nicht-String-Wert unter shots / loudness / derived auflöst) haben und muss explizit das entities-Array ausfüllen
R4	Jede method muss mindestens einen unterstützenden Beweis binden: entweder eine Referenz auf eine definierte fact-ID oder eine Referenz auf measure:<Pfad> (auch hier nur die drei genannten Root-Pfade)
R5	target darf nur den Schlüssel from enthalten, der auf einen numerischen Blattknoten oder ein weißgelistetes abgeleitetes Objekt unter shots, loudness oder derived verweist (siehe Schema); die Verwendung von Listenindizes ist strengstens verboten
R6	In rule, applies_when, avoid_when sowie in der Begründung reason von skipped_dimensions dürfen nicht vorkommen: Eigennamen des Originalvideos (unter Ignorierung von Leerzeichen), mit ASR-Text/Hintergrundinformationen/source_facts vollständig übereinstimmende zusammenhängende 8 chinesische Zeichen (auch über Satzzeichen und benachbarte ASR-Fenster hinweg) oder 5 aufeinanderfolgende englische Wörter, absolute Zeitcodes, „N-te Sekunde“ oder „N Minuten M Sekunden“ (auch mit chinesischen Ziffern), lokale absolute Pfade
R7	Für jede der fünf Produktionsdimensionen (narrative_structure, pacing, shots_editing, narration_subtitles, audio_visual) muss mindestens eine method extrahiert werden; wenn für eine Dimension tatsächlich keine Methode extrahiert werden kann, muss der Grund in skipped_dimensions angegeben werden
R8	Beim Export von production_reference.json wird für alle Schlüsselnamen und String-Werte erneut die Anti-Leak-Prüfung R6 durchgeführt. Außerdem dürfen in keiner Ebene des Exportobjekts die Schlüssel source_facts, labels, entities, evidence, statement, from, path vorkommen

Die Anti-Leak-Wortliste fasst automatisch zusammen: source_facts[].entities, die Charaktere und character_details-Aliase aus background_research.json, cultural_notes-Einträge mit maximal 5 Zeichen sowie kurze Begriffe in Anführungszeichen wie «»「」 aus den Daten. Wenn eine Kollision mit source_facts über 8 zusammenhängende Zeichen gemeldet wird, reicht es aus, die allgemeine Schnittbeschreibung auf einer der beiden Seiten umzuformulieren.

Die folgenden Situationen geben nur eine Warnung (warning) aus und blockieren den Export nicht: method hat kein applies_when, in rule wurden direkt arabische Ziffern geschrieben, die ASR-Genauigkeit ist nicht AVAILABLE_COARSE, das Video enthält chinesische Dialoge, aber die Analyseergebnisse und die Datenbank haben keine Personennamen geliefert (in diesem Fall verlässt sich die Prüfung nur auf die manuell geschriebenen entities), basis ist leer, die vom Analyseergebnis aufgezeichnete Videodateiidentität stimmt nicht mit dem aktuell gemessenen Video überein, es gibt zu überprüfende Schnittfenster, aber cut_fixes wurde nicht ausgefüllt.

Hinweis: R6 kann nur wörtliche Übereinstimmungen abfangen, nicht jedoch Schreibweisen, die die Handlung des Originalvideos mit anderen Worten nacherzählen. Beim Schreiben der method muss zusammengefasst werden, „wie man bei bestimmten Materialmerkmalen vorgeht“, keinesfalls „wie der Protagonist nach dem Betreten der Tür geschnitten wird“. Darüber hinaus prüft der Validator nicht, ob die natürliche Sprachsemantik mit den Daten übereinstimmt – bevor Sie schreiben, „welche Art von Abschnitt dichter geschnitten ist“, müssen Sie zuerst die von check ausgegebenen gemessenen cuts_per_min-Werte überprüfen. Vermeiden Sie es, aus dem Gedächtnis Schlussfolgerungen zu schreiben, die den gemessenen Daten widersprechen.

5. Liefergegenstand und spätere Verwendung

Die endgültig exportierte production_reference.json enthält nur: die Gesamtlänge und die Bildschirmgröße des Videos, cut_detection (Schnittpunkterkennungsparameter und die Anzahl der manuell hinzugefügten/entfernten Schnitte), profile (Kern-Rhythmus- und Lautstärkeindikatoren, mit einer Datenquellenmarkierung provenance: measured für rein algorithmische Messung, reviewed für manuelle Überprüfung mittels cut_fixes, labeled für abhängig von manueller Tonspur-/Abschnittsannotation), die relative Positionsverteilung der narrativen Abschnitte auf der Zeitachse (structure), den Untertitelstil (subtitles), die Liste der übertragbaren Methoden (methods) und die Erklärung für übersprungene Dimensionen (skipped_dimensions).

Verwendungsmethode: Legen Sie die exportierte production_reference.json in das work_dir der nächsten Produktionsaufgabe (oder binden Sie sie über die production_reference-Vorlage des Ressourcenpools ein). Wenn die nachgelagerte Manuskripterstellungsphase diese Datei findet, wird sie aktiv gelesen und im optionalen Feld reference_methods von recap_story_plan.json die Annahmeentscheidung (adopt / adapt / skip) für jede Methode protokolliert. Beim Übernehmen von Referenzmethoden orientieren Sie sich stets an den tatsächlichen Bildern und Dialogbeweisen des neuen Materials und übertragen keinesfalls die Schnittdichte oder den Leerraumanteil des Referenzvideos als starres Kontingent. Kein Produktionsskript validiert diese Datei mechanisch, und ihre Existenz oder Abwesenheit ändert auch nicht das Freigabeergebnis einer Zugangskontrolle.

Die Verzeichnisse U/reference_breakdown.json und U/reference_frames/ enthalten Fakten und Bilder der Handlung des Originalvideos und dienen nur der lokalen Zerlegung. Kopieren Sie sie nicht in neue Projekte oder laden Sie sie in öffentliche Repositories hoch.

6. Fähigkeitsgrenzen

• Der gesamte Prozess läuft rein lokal, es wird weder MiMo noch ein anderes großes Modell aufgerufen, die vorgelagerten Ergebnisse der Videoanalyse werden nicht modifiziert, und es wird keine Bewertung des fertigen Videos vorgenommen oder eine „Differenz zwischen neuem und Referenzvideo“ berechnet.
• Die Erkennung von Aufnahmenschnitten basiert auf dem ffmpeg scdet-Score plus manueller visueller Überprüfung: Langsame Überblendungen können vom Algorithmus nicht automatisch erkannt werden; zwei aufeinanderfolgende schnelle Schnitte mit einem Abstand von weniger als 0,3 Sekunden, Schnitte, die genau auf dem soft_score-Grenzwert liegen (verschiedene ffmpeg-Versionen können geringfügige Unterschiede wie 4.00 vs. 3.989 berechnen), sowie harte Schnitte nach starker Bewegung in einen dunklen Bereich (der Score kann auf 0,9 fallen) werden nicht automatisch als Schnittpunkte gewertet, sondern einheitlich in das zu überprüfende Fenster aufgenommen und durch manuelle Bildbetrachtung abgesichert. In einem Test mit einer 5-minütigen Serienerklärung erkannte der Algorithmus initial 82 Schnittpunkte und erfasste in 11 zu überprüfenden Fenstern alle 5 echten, übersehenen Schnittpunkte (die restlichen 7 Fenster waren schnelle Zooms, Seitenumbrüche und Bewegungsaufnahmen). Nachdem die manuelle Bildbetrachtung diese 5 Schnittpunkte ergänzte, stimmte die Erkennung zu 100 % mit der manuellen Frame-für-Frame-Grundwahrheit (insgesamt 27 Schnittpunkte) an drei Stellen (Vorspann, dunkle Szenen, Mittelteil) überein, ohne Fehlalarme.
• Die Genauigkeit des Erzählanteils und der Sprechgeschwindigkeit liegt auf dem Niveau labeled: Sie wird aus den manuell annotierten Tonspurintervallen in Kombination mit grobkörnigen ASR-Fenstern geschätzt, nicht auf der Basis von Wort-für-Wort-Zeitstempeln.
• Die Anti-Spoiler-Leak-Prüfung basiert auf wörtlichem String-Vergleich. Der Agent muss beim Verfassen dennoch eine aktive Selbstprüfung durchführen, um sicherzustellen, dass die methods allgemeine kreative Techniken und keine Zusammenfassung der Handlung des Originalvideos sind.