@oh-story/dsh 0.1.11 → 0.1.13

package/lib/video-recap/skills/video-reference/scripts/reference_frames.py

@@ -0,0 +1,122 @@
+"""Contact sheets for looking at a finished video: suppressed cut candidates, longest shots, or a span.
+
+The measurement can miss cuts (dissolves, dark scenes, rapid montage) or keep a few false ones,
+and when no understanding run exists the agent has no pictures at all. Each sheet row is one
+ffmpeg seek tiled to CELLS frames; rows are stacked into pages under U/reference_frames/ and the
+printed legend gives every cell's time, so no drawtext/font support is needed.
+"""
+import math
+import tempfile
+from pathlib import Path
+
+from lib import ffprobe, run_cmd
+
+FRAMES_DIR = "reference_frames"
+CELLS = 12
+CELL_WIDTH = 160
+ROWS_PER_PAGE = 8
+LONGEST_EDGE_S = 0.1
+
+
+def _row(label, start, end, cells):
+    """Evenly spaced cell times over [start, end]; a single time when the range is a point."""
+    cells = max(1, min(CELLS, cells))
+    step = (end - start) / (cells - 1) if cells > 1 else 0.0
+    return {"label": label, "times": [round(start + i * step, 2) for i in range(cells)], "step": step}
+
+
+def review_rows(measurements, fps):
+    """Every frame of each suppressed-candidate window, CELLS frames per row."""
+    frame_s = 1.0 / fps if fps else 0.04
+    rows = []
+    for start, end in measurements["shots"].get("review_windows") or []:
+        for row in span_rows(start, end, frame_s):
+            rows.append({**row, "label": f"待复核 {start}–{end}s"})
+    return rows
+
+
+def longest_rows(measurements, count):
+    """One row per longest measured shot: a long 'shot' is where a missed cut hides."""
+    duration = measurements["source"]["duration_s"]
+    bounds = [0.0, *measurements["shots"]["cuts"], duration]
+    shots = sorted(zip(bounds, bounds[1:]), key=lambda s: s[1] - s[0], reverse=True)[:count]
+    return [_row(f"镜头 {a:.2f}–{b:.2f}s（{b - a:.1f}s）", a + LONGEST_EDGE_S, b - LONGEST_EDGE_S, CELLS)
+            for a, b in sorted(shots) if b - a > 2 * LONGEST_EDGE_S]
+
+
+def span_rows(start, end, step):
+    """Cells every `step` seconds over [start, end], CELLS per row."""
+    if step <= 0 or end <= start:
+        raise ValueError("--span 需要 A<B，--step 必须为正数")
+    times = [round(start + i * step, 3) for i in range(int(math.floor((end - start) / step + 1e-9)) + 1)]
+    return [{"label": f"{chunk[0]:g}–{chunk[-1]:g}s，每 {step:g}s", "times": chunk, "step": step}
+            for chunk in (times[i:i + CELLS] for i in range(0, len(times), CELLS))]
+
+
+def _render_row(video, row, out_path):
+    times, step = row["times"], row["step"]
+    # Cell i is the first frame at or after times[0] + i * step (the unrounded step). The fps filter
+    # would instead pick the frame nearest each slot, which can be a frame of the *next* shot and hide
+    # where a cut is. Only len(times) frames are picked: a short row leaves its other cells blank.
+    pick = f"select='gte(t\\,selected_n*{step:.6f}-0.001)*lt(selected_n\\,{len(times)})'"
+    cmd = ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", "-ss", f"{times[0]:.3f}",
+           "-t", f"{step * (len(times) - 1) + 0.2:.3f}", "-i", video,
+           "-vf", f"{pick},scale={CELL_WIDTH}:-2,tile={CELLS}x1", "-frames:v", "1", out_path]
+    result = run_cmd(cmd)
+    if result.returncode != 0 or not Path(out_path).is_file():
+        raise RuntimeError(f"ffmpeg 取帧失败（{row['label']}）: {result.stderr.strip()[-400:]}")
+
+
+def render(video, work_dir, rows, name):
+    """Write pages <name>_<n>.jpg under work_dir/reference_frames; return [(page, rows)]."""
+    out_dir = Path(work_dir) / FRAMES_DIR
+    out_dir.mkdir(parents=True, exist_ok=True)
+    pages = []
+    with tempfile.TemporaryDirectory(prefix="reference-frames-") as scratch:
+        for page_index in range(0, len(rows), ROWS_PER_PAGE):
+            page_rows = rows[page_index:page_index + ROWS_PER_PAGE]
+            parts = []
+            for i, row in enumerate(page_rows):
+                part = Path(scratch) / f"row_{page_index + i}.jpg"
+                _render_row(video, row, part)
+                parts.append(str(part))
+            page = out_dir / f"{name}_{page_index // ROWS_PER_PAGE + 1}.jpg"
+            if len(parts) == 1:
+                cmd = ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y", "-i", parts[0], str(page)]
+            else:
+                cmd = ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y"]
+                for part in parts:
+                    cmd += ["-i", part]
+                cmd += ["-filter_complex", f"vstack=inputs={len(parts)}", str(page)]
+            result = run_cmd(cmd)
+            if result.returncode != 0:
+                raise RuntimeError(f"ffmpeg 拼页失败: {result.stderr.strip()[-400:]}")
+            pages.append((page, page_rows))
+    return pages
+
+
+def legend(pages):
+    """Printable mapping from page/row/cell to seconds."""
+    lines = []
+    for page, rows in pages:
+        lines.append(str(page))
+        for i, row in enumerate(rows, 1):
+            lines.append(f"  第 {i} 行 {row['label']}：" + " ".join(f"{t:g}" for t in row["times"]))
+    return "\n".join(lines)
+
+
+def frames(video, work_dir, measurements, *, mode, longest=5, span=None, step=2.0):
+    """Build the rows for `mode` (review | longest | span) and render them."""
+    if mode == "span":
+        start, end = span
+        rows = span_rows(start, end, step)
+    else:
+        if measurements is None:
+            raise ValueError("先运行 measure：review / longest 需要 reference_measurements.json")
+        if mode == "review":
+            rows = review_rows(measurements, measurements["source"].get("fps") or ffprobe(video)["fps"])
+        else:
+            rows = longest_rows(measurements, longest)
+    if not rows:
+        return []
+    return render(str(video), work_dir, rows, mode)

package/lib/video-recap/skills/video-reference/scripts/reference_measure.py

@@ -0,0 +1,253 @@
+"""One ffmpeg pass over a finished video: hard-cut times (scdet) and loudness (ebur128).
+
+scdet reports a per-frame score; a fixed score threshold is wrong in both directions on real
+recaps (threshold 10 missed about a third of the cuts in a dark scene; threshold 6 counted a
+fast-moving single shot as nine cuts). So every frame scoring >= SCORE_FLOOR is kept and a cut is
+a frame that scores >= hard, or >= soft while scoring at least ISOLATION_RATIO times every other
+frame within ISOLATION_WINDOW_S (the adjacent frames excluded: they carry the cut's own
+after-image). Suppressed candidates are grouped into `shots.review_windows` for the agent to look
+at; the agent's corrections live in the breakdown (labels.cut_fixes), never in this file.
+
+The score is min(mafd, |mafd - previous mafd|), so a cut out of fast motion scores near zero (a
+dark hard cut after a fight scored 0.9). Every cut is still a one-sided peak of mafd itself: at
+least every other frame within the window and ISOLATION_RATIO times every frame on one side.
+Such peaks (`mafd_peaks`) join the review windows; they never become cuts on their own.
+
+The result is cached in `reference_measurements.json` by the video's {size, mtime_ns}; the raw
+scores are cached too, so changing the score settings re-derives the cuts without decoding again.
+Shot statistics are computed from these cuts directly; an understanding run's scene list merges
+short shots and would inflate the median shot length.
+"""
+import bisect
+import math
+import re
+from pathlib import Path
+
+from lib import ffprobe, file_identity, log, read_json, run_cmd, write_json
+
+MEASUREMENTS_FILE = "reference_measurements.json"
+MEASUREMENTS_SCHEMA = "video-reference.measurements.v3"
+DETECTOR = "scdet-isolated-v1"
+DEFAULT_HARD_SCORE = 10.0     # always a cut
+DEFAULT_SOFT_SCORE = 4.0      # a cut only when isolated
+ISOLATION_RATIO = 2.0
+ISOLATION_WINDOW_S = 0.3
+SCORE_FLOOR = 2.0             # below soft / ratio a frame can neither be a cut nor suppress one;
+                              # also the least mafd a review peak needs
+REVIEW_PAD_S = 0.2
+REVIEW_JOIN_S = 0.5
+CURVE_WINDOW_S = 10.0
+EDGE_S = 0.05                # cuts this close to either end are not cuts between two shots
+SILENT_LUFS = -70.0          # ebur128 reports -120.7 for digital silence / warm-up blocks
+
+_SCDET = re.compile(
+    r"lavfi\.scd\.score\s*[:=]\s*(-?\d+(?:\.\d+)?)\s*,?\s*lavfi\.scd\.time\s*[:=]\s*(-?\d+(?:\.\d+)?)")
+_MAFD = re.compile(r"\[Parsed_metadata[^\]]*\]\s*(?:frame:.*?pts_time:\s*(\S+)|lavfi\.scd\.mafd=(\S+))")
+_EBU_FRAME = re.compile(r"\bt:\s*(\d+(?:\.\d+)?)\s.*?\bS:\s*(-?\d+(?:\.\d+)?|-?inf|nan)")
+_SUMMARY_I = re.compile(r"\bI:\s*(-?\d+(?:\.\d+)?)\s*LUFS")
+_SUMMARY_LRA = re.compile(r"\bLRA:\s*(-?\d+(?:\.\d+)?)\s*LU\b")
+_SUMMARY_PEAK = re.compile(r"True peak:\s*\n\s*Peak:\s*(-?\d+(?:\.\d+)?|-inf)")
+
+
+def parse_scdet(stderr, duration=None):
+    """Sorted [time, score] pairs from scdet log lines (`score: 4.2, time: 2.6` or `score=4.2 time=2.6`).
+
+    Frames within EDGE_S of either end are dropped: they are not cuts between two shots.
+    """
+    scores = {}
+    for match in _SCDET.finditer(stderr or ""):
+        score, t = float(match.group(1)), round(float(match.group(2)), 3)
+        if t <= EDGE_S or (duration is not None and t >= duration - EDGE_S):
+            continue
+        scores[t] = max(score, scores.get(t, score))
+    return [[t, round(scores[t], 3)] for t in sorted(scores)]
+
+
+def _sides(series, times, i, adjacent):
+    """Highest value before and after series[i] within ISOLATION_WINDOW_S, adjacent frames excluded."""
+    t = series[i][0]
+    lo = bisect.bisect_left(times, t - ISOLATION_WINDOW_S - 1e-9)
+    hi = bisect.bisect_right(times, t + ISOLATION_WINDOW_S + 1e-9)
+    return (max((v for u, v in series[lo:i] if t - u > adjacent), default=0.0),
+            max((v for u, v in series[i + 1:hi] if u - t > adjacent), default=0.0))
+
+
+def mafd_peaks(stderr, fps, duration=None):
+    """[time, mafd] of frames whose mafd (metadata print) is a one-sided peak >= SCORE_FLOOR."""
+    series, t = [], None
+    for time_text, value in _MAFD.findall(stderr or ""):
+        if time_text:
+            t = _number(time_text)
+        elif t is not None:
+            series.append((round(t, 3), _number(value) or 0.0))
+            t = None
+    adjacent = 1.5 / fps if fps else 0.06
+    times = [u for u, _ in series]
+    peaks = []
+    for i, (t, value) in enumerate(series):
+        if value < SCORE_FLOOR or t <= EDGE_S or (duration is not None and t >= duration - EDGE_S):
+            continue
+        before, after = _sides(series, times, i, adjacent)
+        if value >= max(before, after) and value >= ISOLATION_RATIO * min(before, after):
+            peaks.append([t, round(value, 3)])
+    return peaks
+
+
+def detect_cuts(scores, fps, *, hard=DEFAULT_HARD_SCORE, soft=DEFAULT_SOFT_SCORE, peaks=()):
+    """(cuts, review_windows) from [time, score] pairs and mafd peaks; see the module docstring."""
+    frame_s = 1.0 / fps if fps else 0.04
+    adjacent = 1.5 * frame_s
+    times = [t for t, _ in scores]
+    cuts, suppressed = [], [t for t, _ in peaks]
+    for i, (t, score) in enumerate(scores):
+        if score < soft:
+            continue
+        if score < hard and score < ISOLATION_RATIO * max(_sides(scores, times, i, adjacent)):
+            suppressed.append(t)
+            continue
+        if cuts and t - cuts[-1][0] <= adjacent:     # one cut spread over two frames
+            if score > cuts[-1][1]:
+                cuts[-1] = (t, score)
+            continue
+        cuts.append((t, score))
+    cut_times = [t for t, _ in cuts]
+    windows = []
+    for t in sorted(set(suppressed)):
+        if any(abs(t - c) <= adjacent for c in cut_times):
+            continue
+        if windows and t - windows[-1][1] <= REVIEW_JOIN_S:
+            windows[-1][1] = t
+        else:
+            windows.append([t, t])
+    return cut_times, [[round(max(0.0, a - REVIEW_PAD_S), 2), round(b + REVIEW_PAD_S, 2)] for a, b in windows]
+
+
+def _number(text):
+    try:
+        value = float(text)
+    except ValueError:
+        return None
+    return value if math.isfinite(value) else None
+
+
+def parse_ebur128(stderr, duration):
+    """Integrated loudness, LRA, true peak (Summary block) and a 1 s short-term series."""
+    stderr = stderr or ""
+    head, marker, summary = stderr.rpartition("Summary:")
+    if not marker:
+        return None
+    seconds = max(1, math.ceil(duration))
+    series = [None] * seconds
+    for match in _EBU_FRAME.finditer(head):
+        bucket = int(float(match.group(1)))
+        value = _number(match.group(2))
+        if 0 <= bucket < seconds:
+            series[bucket] = None if value is None or value < SILENT_LUFS else round(value, 1)
+
+    def pick(pattern):
+        match = pattern.search(summary)
+        return None if match is None else _number(match.group(1))
+
+    return {
+        "integrated_lufs": pick(_SUMMARY_I),
+        "lra_lu": pick(_SUMMARY_LRA),
+        "true_peak_dbtp": pick(_SUMMARY_PEAK),
+        "short_term_1s": series,
+    }
+
+
+def _percentile(sorted_values, q):
+    if not sorted_values:
+        return None
+    position = (len(sorted_values) - 1) * q
+    low = math.floor(position)
+    high = min(low + 1, len(sorted_values) - 1)
+    return sorted_values[low] + (sorted_values[high] - sorted_values[low]) * (position - low)
+
+
+def shot_stats(cuts, duration):
+    """Shot-length distribution and cut density for cuts inside [0, duration]."""
+    bounds = [0.0, *cuts, duration]
+    lengths = sorted(b - a for a, b in zip(bounds, bounds[1:]) if b > a)
+    count = len(lengths)
+    minutes = duration / 60.0
+    windows = max(1, math.ceil(duration / CURVE_WINDOW_S))
+    curve = [0] * windows
+    for cut in cuts:
+        curve[min(windows - 1, int(cut // CURVE_WINDOW_S))] += 1
+    # Scale each window by its own length: the last one is usually partial (6.66 s on a 126.66 s
+    # video). Floor at 1 s so a sliver of a window cannot turn one cut into hundreds per minute.
+    per_min = [60.0 / max(1.0, min(CURVE_WINDOW_S, duration - i * CURVE_WINDOW_S)) for i in range(windows)]
+    return {
+        "cuts": list(cuts),
+        "count": count,
+        "mean_s": round(sum(lengths) / count, 3) if count else None,
+        "median_s": round(_percentile(lengths, 0.5), 3) if count else None,
+        "p10_s": round(_percentile(lengths, 0.1), 3) if count else None,
+        "p90_s": round(_percentile(lengths, 0.9), 3) if count else None,
+        "share_under_1s": round(sum(1 for x in lengths if x < 1.0) / count, 3) if count else None,
+        "share_over_8s": round(sum(1 for x in lengths if x > 8.0) / count, 3) if count else None,
+        "cuts_per_min": round(len(cuts) / minutes, 2) if minutes > 0 else None,
+        "curve": {"window_s": CURVE_WINDOW_S, "values": [round(c * k, 1) for c, k in zip(curve, per_min)]},
+    }
+
+
+def _ffmpeg_command(video, scaled, has_audio):
+    video_filter = f"scdet=threshold={SCORE_FLOOR:g},metadata=mode=print:key=lavfi.scd.mafd"
+    if scaled:
+        video_filter = "scale=320:-2," + video_filter
+    cmd = ["ffmpeg", "-hide_banner", "-nostats", "-i", video, "-map", "0:v:0", "-vf", video_filter]
+    if has_audio:
+        cmd += ["-map", "0:a:0", "-af", "ebur128=peak=true:framelog=info"]
+    return cmd + ["-f", "null", "-"]
+
+
+def _reusable(cached, identity, scaled):
+    """The cached decode (scores + loudness) is valid for this file and scaling."""
+    if not isinstance(cached, dict) or cached.get("schema") != MEASUREMENTS_SCHEMA:
+        return False
+    source = cached.get("source") or {}
+    settings = cached.get("settings") or {}
+    same_file = {k: source.get(k) for k in identity} == identity
+    return same_file and settings.get("scaled") == scaled and settings.get("score_floor") == SCORE_FLOOR
+
+
+def measure(video, work_dir, *, hard=DEFAULT_HARD_SCORE, soft=DEFAULT_SOFT_SCORE, scaled=True):
+    """Measure `video` into work_dir/reference_measurements.json; reuse the decode when the file is unchanged."""
+    if not SCORE_FLOOR * ISOLATION_RATIO <= soft <= hard:
+        raise ValueError(f"需要 {SCORE_FLOOR * ISOLATION_RATIO:g} ≤ soft ≤ hard，收到 soft={soft} hard={hard}")
+    video = Path(video)
+    out_path = Path(work_dir) / MEASUREMENTS_FILE
+    identity = file_identity(video)
+    settings = {"detector": DETECTOR, "hard_score": float(hard), "soft_score": float(soft),
+                "isolation_ratio": ISOLATION_RATIO, "isolation_window_s": ISOLATION_WINDOW_S,
+                "score_floor": SCORE_FLOOR, "scaled": bool(scaled)}
+    cached = read_json(out_path)
+    if _reusable(cached, identity, bool(scaled)):
+        if cached.get("settings") == settings:
+            log(f"复用 {MEASUREMENTS_FILE}（成片与设置未变）")
+            return cached
+        log("成片未变，只按新的分数设置重算切点（不重新解码）")
+        source, scores, loudness = cached["source"], cached["scdet_scores"], cached.get("loudness")
+        peaks = cached.get("mafd_peaks") or []
+    else:
+        source = {**identity, **ffprobe(video)}
+        result = run_cmd(_ffmpeg_command(video, scaled, source["audio_streams"] > 0))
+        if result.returncode != 0:
+            raise RuntimeError(f"ffmpeg 测量失败: {result.stderr.strip()[-600:]}")
+        scores = parse_scdet(result.stderr, source["duration_s"])
+        peaks = mafd_peaks(result.stderr, source.get("fps"), source["duration_s"])
+        loudness = parse_ebur128(result.stderr, source["duration_s"]) if source["audio_streams"] else None
+    cuts, review_windows = detect_cuts(scores, source.get("fps"), hard=hard, soft=soft, peaks=peaks)
+    payload = {
+        "schema": MEASUREMENTS_SCHEMA,
+        "source": source,
+        "settings": settings,
+        "shots": {**shot_stats(cuts, source["duration_s"]), "review_windows": review_windows},
+        "loudness": loudness,
+        "scdet_scores": scores,
+        "mafd_peaks": peaks,
+    }
+    write_json(out_path, payload)
+    log(f"写入 {out_path}：{len(cuts)} 个切点，{len(review_windows)} 个待复核窗口，时长 {source['duration_s']:.1f}s")
+    return payload

package/lib/video-recap/skills/video-reference/scripts/reference_profile.py

@@ -0,0 +1,271 @@
+"""Pure functions: derive labeled metrics from labels + measurements, and project the export.
+
+`derived` only ever lives in memory: `check` prints it so the agent can write methods against
+it, `export` copies the needed values into production_reference.json. The agent never types a
+number — a method target names a measurement path and the export fills the value in.
+
+The agent's cut review (labels.cut_fixes) is applied first: every shot number, derived cut
+density and export value is computed from the reviewed cut list, never from the raw detector.
+"""
+import statistics
+
+from reference_measure import shot_stats
+
+PRODUCTION_SCHEMA = "video-reference.production.v1"
+CUT_MATCH_S = 0.1          # a removal or addition this close to a detected cut refers to that cut
+OWNERS = ("narration", "original_dialogue", "action_sound", "ambience", "music", "silence")
+SWITCH_TOLERANCE_S = 0.25
+MIN_WINDOW_COVERAGE = 0.8
+NULL_ASR_STATUSES = ("EXPLICITLY_SKIPPED",)
+
+
+def cut_fix_counts(labels):
+    fixes = (labels or {}).get("cut_fixes") or {}
+    return len(fixes.get("add") or []), len(fixes.get("remove") or [])
+
+
+def apply_cut_fixes(measurements, labels):
+    """Measurements whose `shots` come from the reviewed cut list (unchanged without fixes)."""
+    fixes = (labels or {}).get("cut_fixes") or {}
+    if not any(cut_fix_counts(labels)):
+        return measurements
+    removed = fixes.get("remove") or []
+    cuts = [c for c in measurements["shots"]["cuts"] if not any(abs(c - r) <= CUT_MATCH_S for r in removed)]
+    cuts = sorted({*cuts, *(round(float(t), 3) for t in fixes.get("add") or [])})
+    shots = shot_stats(cuts, measurements["source"]["duration_s"])
+    shots["review_windows"] = measurements["shots"].get("review_windows") or []
+    return {**measurements, "shots": shots}
+
+
+def _overlap(a0, a1, b0, b1):
+    return max(0.0, min(a1, b1) - max(a0, b0))
+
+
+def _seconds_in(spans, start, end):
+    return sum(_overlap(start, end, s["start"], s["end"]) for s in spans)
+
+
+def _cuts_inside(cuts, start, end):
+    return sum(1 for c in cuts if start < c < end)
+
+
+def _per_min(count, seconds):
+    return round(count * 60.0 / seconds, 2) if seconds > 0 else None
+
+
+def _r(value, digits=3):
+    return None if value is None else round(value, digits)
+
+
+def _merged_blocks(spans, owner):
+    """Contiguous runs of one owner (adjacent spans with different narration_job join)."""
+    blocks = []
+    for span in spans:
+        if span["owner"] != owner:
+            continue
+        if blocks and abs(blocks[-1][1] - span["start"]) < 1e-6:
+            blocks[-1][1] = span["end"]
+        else:
+            blocks.append([span["start"], span["end"]])
+    return blocks
+
+
+def _mean_lufs(series, blocks):
+    values = [
+        series[i] for i in range(len(series or []))
+        if series[i] is not None and any(a <= i + 0.5 < b for a, b in blocks)
+    ]
+    return _r(sum(values) / len(values), 1) if values else None
+
+
+def _by_owner(spans, cuts, duration, series):
+    result = {}
+    for owner in OWNERS:
+        blocks = _merged_blocks(spans, owner)
+        if not blocks:
+            continue
+        seconds = sum(b - a for a, b in blocks)
+        result[owner] = {
+            "seconds": _r(seconds, 2),
+            "share": _r(seconds / duration),
+            "blocks": len(blocks),
+            "block_median_s": _r(statistics.median(b - a for a, b in blocks), 2),
+            "cuts_per_min": _per_min(sum(_cuts_inside(cuts, a, b) for a, b in blocks), seconds),
+            "mean_short_term_lufs": _mean_lufs(series, blocks),
+        }
+    return result
+
+
+def _visible_chars(text):
+    return sum(1 for ch in str(text or "") if ch.isalnum())
+
+
+def narration_rate(spans, asr_windows, asr_status):
+    """Chars/s over ASR windows that narration spans cover by >= 80%; null when unusable."""
+    narration = [s for s in spans if s["owner"] == "narration"]
+    usable = asr_status is None or not (
+        asr_status.startswith("FAILED_") or asr_status in NULL_ASR_STATUSES
+    )
+    used, chars, seconds, lengths = 0, 0, 0.0, []
+    for window in asr_windows if usable else []:
+        start, end = float(window.get("start", 0)), float(window.get("end", 0))
+        if end <= start:
+            continue
+        lengths.append(end - start)
+        if _seconds_in(narration, start, end) / (end - start) >= MIN_WINDOW_COVERAGE:
+            used += 1
+            chars += _visible_chars(window.get("text"))
+            seconds += end - start
+    return {
+        "value": _r(chars / seconds, 2) if seconds > 0 and chars > 0 else None,
+        "windows_used": used,
+        "window_s": _r(statistics.median(lengths), 2) if lengths else None,
+        "precision": "coarse_asr_windows",
+    }
+
+
+def switch_on_cut_share(spans, cuts):
+    """Share of audio-owner switch points that land within ±0.25 s of a picture cut."""
+    switches = [b["start"] for a, b in zip(spans, spans[1:]) if a["owner"] != b["owner"]]
+    if not switches:
+        return None
+    hits = sum(1 for t in switches if any(abs(t - c) <= SWITCH_TOLERANCE_S for c in cuts))
+    return _r(hits / len(switches))
+
+
+def _lead_owner(spans, start, end):
+    totals = {}
+    for span in spans:
+        totals[span["owner"]] = totals.get(span["owner"], 0.0) + _overlap(
+            start, end, span["start"], span["end"])
+    return max(totals, key=totals.get) if totals and max(totals.values()) > 0 else None
+
+
+def derive(labels, measurements, asr_windows=(), asr_status=None):
+    """All labeled metrics from well-formed labels; see references/reference-schema.md."""
+    duration = measurements["source"]["duration_s"]
+    cuts = measurements["shots"]["cuts"]
+    series = (measurements.get("loudness") or {}).get("short_term_1s") or []
+    spans = sorted(labels.get("audio_spans") or [], key=lambda s: s["start"])
+    sections = sorted(labels.get("sections") or [], key=lambda s: s["start"])
+    narration = [s for s in spans if s["owner"] == "narration"]
+
+    by_section = {}
+    for section in sections:
+        entry = by_section.setdefault(section["function"], {"seconds": 0.0, "cuts": 0, "narr": 0.0})
+        entry["seconds"] += section["end"] - section["start"]
+        entry["cuts"] += _cuts_inside(cuts, section["start"], section["end"])
+        entry["narr"] += _seconds_in(narration, section["start"], section["end"])
+    first_original = next((s for s in spans if s["owner"] == "original_dialogue"), None)
+    derived = {
+        "by_owner": _by_owner(spans, cuts, duration, series),
+        "narration_chars_per_s": narration_rate(spans, asr_windows, asr_status),
+        "switch_on_cut_share": switch_on_cut_share(spans, cuts),
+        "by_section": {
+            function: {
+                "seconds": _r(e["seconds"], 2),
+                "cuts_per_min": _per_min(e["cuts"], e["seconds"]),
+                "narration_share": _r(e["narr"] / e["seconds"]) if e["seconds"] > 0 else None,
+            }
+            for function, e in by_section.items()
+        },
+        "structure": [
+            {
+                "function": s["function"],
+                "at": [_r(s["start"] / duration), _r(s["end"] / duration)],
+                "lead_owner": _lead_owner(spans, s["start"], s["end"]),
+            }
+            for s in sections
+        ],
+        "first_original_at": None if first_original is None else {
+            "s": _r(first_original["start"], 2),
+            "fraction": _r(first_original["start"] / duration),
+        },
+    }
+    jobs = {}
+    for span in narration:
+        if span.get("narration_job"):
+            jobs[span["narration_job"]] = jobs.get(span["narration_job"], 0.0) + span["end"] - span["start"]
+    narration_seconds = sum(s["end"] - s["start"] for s in narration)
+    if jobs and narration_seconds > 0:
+        derived["narration_jobs"] = {job: _r(sec / narration_seconds) for job, sec in jobs.items()}
+    return derived
+
+
+_MISSING = object()
+
+
+def resolve(path, measurements, derived):
+    """Value at a dot path in measurements (or in derived for `derived.*`); _MISSING if absent."""
+    parts = str(path).split(".")
+    node = {"derived": derived} if parts[0] == "derived" else measurements
+    for part in parts:
+        if isinstance(node, dict) and part in node:
+            node = node[part]
+        elif isinstance(node, list) and part.isdigit() and int(part) < len(node):
+            node = node[int(part)]
+        else:
+            return _MISSING
+    return node
+
+
+def is_resolved(value):
+    return value is not _MISSING
+
+
+def _metric(value, provenance, **extra):
+    return {"value": value, "provenance": provenance, **extra}
+
+
+def build_production(breakdown, measurements, derived):
+    """production_reference.json: methods + numbers only; no facts, labels, evidence or paths."""
+    labels = breakdown["labels"]
+    shots = measurements["shots"]
+    loudness = measurements.get("loudness") or {}
+    added, removed = cut_fix_counts(labels)
+    shot_provenance = "reviewed" if "cut_fixes" in labels else "measured"   # {} = looked, no change
+    profile = {
+        "shot_median_s": _metric(shots.get("median_s"), shot_provenance),
+        "cuts_per_min": _metric(shots.get("cuts_per_min"), shot_provenance),
+        "integrated_lufs": _metric(loudness.get("integrated_lufs"), "measured"),
+        "narration_share": _metric(
+            (derived["by_owner"].get("narration") or {}).get("share", 0.0), "labeled"),
+        "narration_chars_per_s": _metric(
+            derived["narration_chars_per_s"]["value"], "labeled", precision="coarse_asr_windows"),
+        "switch_on_cut_share": _metric(derived["switch_on_cut_share"], "labeled"),
+        "first_original_at": _metric(
+            None if derived["first_original_at"] is None
+            else {"fraction": derived["first_original_at"]["fraction"]},
+            "labeled"),
+    }
+    methods = []
+    for method in breakdown.get("methods") or []:
+        entry = {key: method[key] for key in (
+            "id", "dimension", "rule", "applies_when", "avoid_when", "applies_to") if key in method}
+        targets = {}
+        for name, target in (method.get("targets") or {}).items():
+            source = target["from"]
+            provenance = ("labeled" if source.startswith("derived.")
+                          else shot_provenance if source.startswith("shots.") else "measured")
+            value = resolve(source, measurements, derived)
+            if source == "derived.first_original_at":   # the absolute `s` stays local, as in the profile
+                value = {"fraction": value["fraction"]}
+            targets[name] = _metric(value, provenance)
+        if targets:
+            entry["targets"] = targets
+        methods.append(entry)
+    subtitles = {k: v for k, v in (labels.get("subtitles") or {}).items() if k != "evidence_t"}
+    settings = measurements.get("settings") or {}
+    cut_detection = {key: settings.get(key) for key in (
+        "detector", "hard_score", "soft_score", "isolation_ratio", "isolation_window_s", "scaled")}
+    return {
+        "schema": PRODUCTION_SCHEMA,
+        "duration_s": measurements["source"]["duration_s"],
+        "canvas": measurements["source"]["canvas"],
+        "cut_detection": {**cut_detection, "agent_added": added, "agent_removed": removed},
+        "profile": {name: metric for name, metric in profile.items() if metric["value"] is not None},
+        "structure": derived["structure"],
+        "subtitles": subtitles,
+        "methods": methods,
+        "skipped_dimensions": dict(breakdown.get("skipped_dimensions") or {}),
+    }