video-reference

1. Positioning

This skill takes acompleted finished filmand breaks it into methods and values that can be directly referenced for the next production. It is an on-demand reference analysis, not a production stage, and not quality control: it does not call MiMo, does not modify other artifacts, and does not score or block any run.

The Agent's role isbreakdown editor: first faithfully record "how this film was made" (facts), then distill "how it could still be used with a different set of footage" (methods). The two must be kept separate: facts remain only in the local working directory, and the export contains only methods and measured values.

2. Input

• Finished film file (.mp4 / .mov / .mkv / .webm）。
• forthis finished filmthe video understanding artifact directory produced by running U(recommended ASR_SEGMENT_SECONDS=5, the shorter the window, the more accurate the narration speech rate). This skill reads the optional asr_result.json、asr_timing_evidence.json、background_research.json、understanding_index.json (its characters names, aliases, and ASR mentions all enter the name leakage scan); when annotating, the Agent should also look at the storyboard / contact sheet and vlm_analysis.json。

It can also run without understanding artifacts, but the narration speech rate will be empty, and the leakage scan will only have the entitieswritten by the Agent itself, and check will give a warning; to look at the visuals, switch to the contact sheet of frames --span 0,<时长> --step 2 .

The following scripts/... are all relative to this skill directory.

3. Process

python3 scripts/reference.py measure <成片> --work-dir U        # 一次 ffmpeg：切点 + 响度，按文件身份缓存
python3 scripts/reference.py frames  <成片> --work-dir U --review          # 逐帧看被压下的疑似切点
python3 scripts/reference.py frames  <成片> --work-dir U --longest 5       # 看最长镜头里有没有漏切
python3 scripts/reference.py check   --work-dir U [--json]      # 校验并打印派生值
python3 scripts/reference.py export  --work-dir U --out <下次运行的 work_dir>/production_reference.json

1. measure writes U/reference_measurements.json(written only by the script): shot cut points, shot length distribution, cuts per minute, 10-second cut point curve, overall loudness / LRA / true peak, per-second short-term loudness. It must decode the entire film: about 15–70 seconds for 5 minutes of 720p, about 7 minutes for 4K; reuse when the finished film is unchanged, only changing --soft-score/--hard-score without re-decoding. Cut point rules: scdet score ≥10 always counts; ≥4 counts only if it is an isolated peak more than twice other frames within 0.3 seconds before and after (excluding adjacent frames). Moving shots, rapid zooms, and flashes will be suppressed and listed in shots.review_windows; the scdet score subtracts the frame difference of the previous frame, so a hard cut from fast motion into a static shot may score only 1, so one-sided peaks of the frame difference itself (mafd_peaks) also enter the review window, but will not automatically count as cut points.
2. Review cut points: fixed thresholds are wrong at both ends on real finished films (a hard cut in a dark scene scores only 5–7; a single fast-motion shot has a 7–8 score peak every 0.2 seconds), so you must look at the images every time.frames --review stitch each review window frame by frame,frames --longest 5 take 12 frames evenly from the 5 longest shots; the page is at U/reference_frames/, and the command prints the seconds corresponding to each cell. After viewing, write labels.cut_fixes：add the seconds of missed cut points, remove the seconds of false-positive cut points (matching measured cut points within ±0.1 seconds); if viewed and no change is needed, write {}. After re-running measure , if the number of review windows changes, the old cut_fixes no longer counts, and you must review again according to the new windows. After that, all shot values, intra-segment cut point density, and exports use the reviewed cut points.
3. Annotate: the Agent writes U/reference_breakdown.json of labels—audio track attribution audio_spans, narrative segments sections, subtitle form subtitles, annotation basis basis。audio_spans boundaries are placed atthe actual start and end of the sound(the audible start and end of speech), not at the start of a subtitle or narration block (the narration end point set by the subtitle appearance frame is measured 0.24–0.42 seconds late).U/speech_boundary_anchors.json exists, use its acoustic_pauses（start is where the speech stops,end is where the next sentence starts) to align the boundaries;switch_on_cut_share only tolerates ±0.25 seconds, if the boundary is placed wrong it only reflects annotation habits. The original film's own voice-over and inner monologue are also part of the original audio track, record them as original_dialogue; when they need to be distinguished, write it into fact and method. When there are only labels, check can be run, and it will print derived(proportion of each audio track, cut point density within segments, narration speech rate, alignment ratio of sound switches to picture cut points, structure of score positions, position of the first occurrence of original sound).
4. Facts and methods: write in the same file source_facts(with time or measurement anchor, explicit entities) and methods （rule、applies_when、avoid_when、applies_to、evidence、targets）。targets only write {"from": "<测量路径>"}, values are filled in by export from the current measurement; the Agent never hand-writes numbers.
5. check → export: export only when there are zero errors; after export, do another leak scan on the artifacts.

For fields, enums, and good/bad method examples, see references/reference-schema.md。

4. Separation rules

check errors (exit code 1):

Rule	Requirement
R1	top level, labels, fact, method, target,cut_fixes are all closed key sets and closed enums; fact must not carry method fields, method must not carry fact fields; id is f1… / m1… and unique;subtitles value types are fixed;skipped_dimensions values are all non-empty strings
R2	audio_spans、sections sorted by time, non-overlapping, gaps ≤0.5s, covering the entire film; subtitle evidence times are within the duration;cut_fixes.remove match the measured cut points,add do not duplicate the measured cut points
R3	Each fact is anchored in one of two ways:t:[a,b] within the duration, or measure:[路径] resolves to shots / loudness / derived a non-string value under; must explicitly write entities
R4	Each method has at least one piece of evidence: an existing fact id or the same three roots only measure:<路径>
R5	target only writes from：shots / loudness / derived numeric leaves under, or whitelisted derived objects (see schema); must not carry list indices
R6	rule / applies_when / avoid_when and skipped_dimensions reasons must not contain: original film entity names (ignoring whitespace), 8 consecutive Chinese characters shared with dialogue, background material, or facts (punctuation-separated or across adjacent ASR windows also counts) or 5 English words, absolute time codes, "the Nth second" or "N minutes M seconds" (including Chinese numerals), absolute paths
R7	At least one method for each of the five dimensions, or write the reason in skipped_dimensions State the reason
R8	Scan every key and string of the export again for R6, and source_facts、labels、entities、evidence、statement、from、path keys must not appear

Entity names come from fact entities、understanding_index.json of characters / entities / research_glossary names and aliases,background_research.json roles and character_details aliases, ≤5-character cultural_notes entries, and short words in 《》 or 「」 quotes in the material. When 8 characters are shared with a fact, the error will note that it comes from source_facts: rewriting either side with generic editing wording is enough.

Warnings do not block: method missing applies_when, rule body contains numbers, ASR is not AVAILABLE_COARSE, there is Chinese dialogue but neither the understanding artifact nor the background material gives a name (in this case only scan fact entities）、basis is empty, the film identity recorded in the understanding artifact does not match the measured film, there is a pending-review window but no cut_fixes。

R6 can only block literal leakage, not rewritten plot; when writing the method, write "what to do under what circumstances", do not restate "what happened in this film". The rules also do not judge semantics: the direction of the method must be consistent with the derived values printed by check (for example, first look at each audio track's cuts_per_min then write "which type of segments are cut densely").

5. Delivery and usage

production_reference.json contains only: duration and canvas,cut_detection(the parameters of the cut-point rules and the number of cut points added or removed by the Agent), profile(rhythm values,provenance is measured / reviewed(writing cut_fixes，{} also counts) / labeled), score positions' structure, subtitle form,methods、skipped_dimensions。

Usage: copy it into the next production's work_dir. At the scriptwriting stage, read it only when the file exists, and you may record each method's adopt / adapt / skip in the optional field recap_story_plan.json . It is a reference, not a quota: when it conflicts with the evidence of new material, the material prevails. No script reads it, and its presence does not change whether any stage passes or fails. reference_methods of

U/ and reference_frames/ contain original film facts and footage, stay local only, do not copy or commit.

6. Capability boundaries

• Does not call MiMo or any LLM, does not modify the understanding artifact, does not score the final film, does not make a "gap between the new film and the reference" judgment.
• Cut points come from ffmpeg scdet scores: slow dissolves cannot be detected; two true cut points with similar scores within 0.3 seconds of each other, a cut point exactly on the soft line (different ffmpeg builds 4.00 and 3.989 scores), and a dark-scene hard cut after motion (0.9 score) are not counted as cut points, and only enter the pending-review window. On a 5-minute episode commentary, 82 cut points were measured, among 11 pending-review windows, 4 contained 5 missed true cut points, and the rest were fast push-pull, page turns, and moving shots; after supplementing them, three segments of frame-by-frame ground truth (opening, dark scene, and middle section, 27 in total) all matched, with no false positives.
• Narration ratio and speech rate are labeled precision: they come from the Agent's audio track annotations and coarse ASR windows, not word-by-word alignment.
• Leak scanning is based on literal matching, and the Agent still needs to self-check whether the method is restating the original film's plot.