@oh-story/dsh 0.1.12 → 0.1.13

package/lib/video-recap/skills/video-reference/references/reference-schema.md

@@ -0,0 +1,139 @@
+# 制作参考：字段、枚举与示例
+
+本文件只列字段与枚举；剧作与剪辑手法的具体规则以后续写稿阶段自己的手册为准，这里不复述。
+
+## 标注词表
+
+| 字段 | 取值 |
+|---|---|
+| `audio_spans[].owner` | `narration` · `original_dialogue` · `action_sound` · `ambience` · `music` · `silence` |
+| `audio_spans[].narration_job`（可选，仅 narration 段） | `context` · `causal_link` · `foreshadow` · `interpretation` · `transition` |
+| `sections[].function`（可重复出现） | `hook` · `setup` · `turn` · `escalation` · `payoff` |
+| `dimension` | `narrative_structure` · `pacing` · `shots_editing` · `narration_subtitles` · `audio_visual` |
+| `applies_to` | `story_plan` · `visual_audio_board` · `clip_plan` · `narration` · `style_card` |
+
+`audio_spans` 记录**谁占有这段声音**（对白下压着的背景乐不算主导；原片自带的画外音、内心独白记 `original_dialogue`）；`sections` 记录叙事功能。两者都必须按时间排序、
+不重叠、间隙不超过 0.5 秒、覆盖整片。
+
+## `reference_breakdown.json`（Agent 唯一要写的文件）
+
+顶层只允许 `schema`、`labels`、`source_facts`、`methods`、`skipped_dimensions`；每一层的键都是封闭集合。
+
+```json
+{
+  "schema": "video-reference.breakdown.v1",
+  "labels": {
+    "audio_spans": [
+      {"start": 0, "end": 13.6, "owner": "narration", "narration_job": "context"},
+      {"start": 13.6, "end": 30.6, "owner": "original_dialogue"}
+    ],
+    "sections": [{"start": 0, "end": 30.6, "function": "hook"}],
+    "subtitles": {"burned": true, "max_lines": 1, "marks_original": "「」", "evidence_t": [12.0]},
+    "basis": "5s ASR 窗口 + 故事板；切点经 frames --review / --longest 5 复核",
+    "cut_fixes": {"add": [10.8], "remove": []}
+  },
+  "source_facts": [
+    {"id": "f1", "dimension": "narrative_structure", "statement": "开场旁白交代主角身世后切入原声冲突",
+     "t": [0, 13.6], "entities": ["<原片人名>"]},
+    {"id": "f2", "dimension": "pacing", "statement": "原声段沿用原片较密的切点，旁白段切得更少",
+     "measure": ["derived.by_owner.original_dialogue.cuts_per_min", "derived.by_owner.narration.cuts_per_min"],
+     "entities": []}
+  ],
+  "methods": [
+    {"id": "m1", "dimension": "audio_visual",
+     "rule": "原声段保留原片自身的剪辑节奏，旁白段换成较长的镜头承载解说，让注意力留在声音上",
+     "applies_when": "对白冲突强、需旁白补前情的剧集解说", "avoid_when": "主要靠动作声承载的段落",
+     "applies_to": "visual_audio_board", "evidence": ["f2", "measure:derived.switch_on_cut_share"],
+     "targets": {"narration_cuts_per_min": {"from": "derived.by_owner.narration.cuts_per_min"}}}
+  ],
+  "skipped_dimensions": {"narration_subtitles": "ASR 不可用，未测语速"}
+}
+```
+
+- `cut_fixes` 可选，键只有 `add`、`remove`（秒数列表）：`remove` 的每个值必须在某个测得切点 ±0.1 秒内，`add` 的值不得在测得切点
+  ±0.1 秒内。写了（哪怕是 `{}`）就表示看过待复核窗口；有增删时所有 `shots.*` 与切点相关的 `derived.*` 都按复核后的切点重算。
+- `subtitles` 可选：`burned`（布尔）、`max_lines`（≥1 整数）必填，`marks_original`（字符串）、`evidence_t`（秒数列表）可选。
+- `skipped_dimensions` 的值是一句非空的原因；它会原样导出，同样受 R8 泄漏扫描。
+- fact：`id`、`dimension`、`statement`、`entities` 必填，`t` 与 `measure` 二选一。`entities` 写这条事实涉及的人名、地名、
+  组织名，没有就写空列表——它同时是泄漏扫描的词表。
+- method：`id`、`dimension`、`rule`、`applies_to`、`evidence` 必填；`applies_when`、`avoid_when`、`targets` 可选。
+- target：只写 `from`，路径根只能是 `shots`、`loudness` 或 `derived`，不得带列表下标；解析结果必须是数值叶子，或以下派生对象之一：
+  `derived.structure`、`derived.first_original_at`（只导出 `{fraction}`）、`derived.narration_jobs`、`derived.by_owner.<owner>`、
+  `derived.by_section.<function>`。`shots.cuts`、`shots.curve`、`loudness.short_term_1s` 这类逐时刻序列不能做 target。
+- fact 的 `measure` 与 method 的 `measure:` 证据也只认这三个根，且不能落在字符串值上。
+
+## 测量与派生值
+
+`reference_measurements.json` 由 measure 写（`settings` 记切点规则参数，`scdet_scores` 是 ≥2 分的逐帧分数缓存，`mafd_peaks` 是帧差单侧峰，三者都不能被引用），
+路径即 target / evidence 可引用的 `shots.*`、`loudness.*`（有 `cut_fixes` 时按复核后的切点）：
+
+| 路径 | 含义 |
+|---|---|
+| `shots.cuts` · `count` · `mean_s` · `median_s` · `p10_s` · `p90_s` | 切点时间与镜长分布 |
+| `shots.review_windows` | 被压下的疑似切点与不在切点上的帧差单侧峰，合成窗口 `[[开始, 结束], …]`，给 `frames --review` 用 |
+| `shots.share_under_1s` · `share_over_8s` · `cuts_per_min` · `curve` | 短/长镜头占比、切点密度、10 秒窗口切点曲线（每窗按自身长度折算成每分钟） |
+| `loudness.integrated_lufs` · `lra_lu` · `true_peak_dbtp` · `short_term_1s` | 整体响度、动态范围、真峰值、逐秒短期响度（前约 2 秒为预热空值） |
+
+`derived.*` 由 check 在内存里计算，export 写入用到的部分：
+
+| 路径 | 含义 |
+|---|---|
+| `derived.by_owner.<owner>` | `seconds` · `share` · `blocks` · `block_median_s` · `cuts_per_min` · `mean_short_term_lufs` |
+| `derived.narration_chars_per_s` | 只用被旁白覆盖 ≥80% 的 ASR 窗口；ASR 失败或跳过时 `value` 为 null |
+| `derived.switch_on_cut_share` | 音轨归属切换点落在画面切点 ±0.25 秒内的比例 |
+| `derived.by_section.<function>` | `seconds` · `cuts_per_min` · `narration_share` |
+| `derived.structure` | `[{function, at:[开始占比, 结束占比], lead_owner}]` |
+| `derived.first_original_at` | 第一段 `original_dialogue`（含原片自带画外音）的 `{s, fraction}` |
+| `derived.narration_jobs` | 各 job 占旁白时长的比例（标注了 job 时才有） |
+
+## `production_reference.json`（导出物，消费方只读这个）
+
+```json
+{
+  "schema": "video-reference.production.v1",
+  "duration_s": 302.66,
+  "canvas": {"width": 1280, "height": 676},
+  "cut_detection": {"detector": "scdet-isolated-v1", "hard_score": 10.0, "soft_score": 4.0, "isolation_ratio": 2.0,
+                    "isolation_window_s": 0.3, "scaled": true, "agent_added": 3, "agent_removed": 0},
+  "profile": {
+    "shot_median_s": {"value": 2.58, "provenance": "reviewed"},
+    "cuts_per_min": {"value": 16.85, "provenance": "reviewed"},
+    "integrated_lufs": {"value": -14.8, "provenance": "measured"},
+    "narration_share": {"value": 0.65, "provenance": "labeled"},
+    "narration_chars_per_s": {"value": 4.0, "provenance": "labeled", "precision": "coarse_asr_windows"},
+    "switch_on_cut_share": {"value": 0.5, "provenance": "labeled"},
+    "first_original_at": {"value": {"fraction": 0.045}, "provenance": "labeled"}
+  },
+  "structure": [{"function": "hook", "at": [0.0, 0.1], "lead_owner": "narration"}],
+  "subtitles": {"burned": true, "max_lines": 1, "marks_original": "「」"},
+  "methods": [
+    {"id": "m1", "dimension": "audio_visual", "rule": "…", "applies_when": "…", "avoid_when": "…",
+     "applies_to": "visual_audio_board",
+     "targets": {"narration_cuts_per_min": {"value": 14.2, "provenance": "labeled"}}}
+  ],
+  "skipped_dimensions": {}
+}
+```
+
+- `provenance`：路径在 `derived.*` 下为 `labeled`（依赖 Agent 标注）；`shots.*` 在写了 `cut_fixes`（含 `{}`）时为 `reviewed`，
+  否则与 `loudness.*` 一样为 `measured`。值为 null 的 profile 项不导出。
+- `cut_detection` 让读者知道这些切点数怎么来的：规则参数与 Agent 增删的切点数。
+- 导出时丢弃 `source_facts`、`labels`、`evidence`、`entities`、`from`、文件身份和任何路径。
+- 保留键 `written_by`、`template` 给以后的资源库绑定副本使用，本技能不写。
+
+## 好方法与坏方法
+
+方法写"在什么条件下、怎么做、为什么"，数字放进 `targets`。
+
+好：
+
+1. "原声段保留原片自身的剪辑节奏，旁白段换成较长的镜头承载解说" + `applies_when: "对白冲突强、需旁白补前情的剧集解说"`。
+   规则方向必须与 check 打印的派生值一致（这里是 `derived.by_owner.*.cuts_per_min`）；R1–R8 不检查语义是否自相矛盾。
+2. "开场先用一句旁白交代身份与处境，第一次原声冲突尽早接管" + `targets.first_original.from: "derived.first_original_at"`。
+3. "声音归属的切换尽量落在画面硬切上，让观众用画面感知换手" + `evidence: ["measure:derived.switch_on_cut_share"]`。
+
+坏：
+
+1. "范闲进殿后旁白交代他的身世"——原片人名与事件，是事实不是方法（R6）。
+2. "在 1:23 切到原声，旁白语速保持每秒 4 字"——绝对时间码（R6）与手写数字（应写 target）。
+3. "照着这部片的结构做"——没有条件、不可迁移，也无法被后续制作采纳或拒绝。

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

@@ -0,0 +1,85 @@
+"""Self-contained utilities for the video-reference skill (no cross-skill imports)."""
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def log(msg):
+    print(f"[video-reference] {msg}", flush=True)
+
+
+def run_cmd(cmd, **kwargs):
+    """Run a command list and return the CompletedProcess (stdout/stderr captured)."""
+    return subprocess.run(
+        [str(part) for part in cmd], capture_output=True, text=True,
+        encoding="utf-8", errors="replace", **kwargs,
+    )
+
+
+def file_identity(path):
+    """{size, mtime_ns} — the cache identity of an input file (no content read)."""
+    st = os.stat(os.fspath(path))
+    return {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
+
+
+def _fraction(text):
+    try:
+        num, _, den = str(text).partition("/")
+        value = float(num) / float(den or 1)
+    except (ValueError, ZeroDivisionError):
+        return None
+    return round(value, 3) if value > 0 else None
+
+
+def ffprobe(video_path):
+    """Duration, canvas, fps and soft-subtitle stream count of a media file."""
+    result = run_cmd([
+        "ffprobe", "-v", "error", "-show_entries",
+        "format=duration:stream=codec_type,width,height,avg_frame_rate,r_frame_rate",
+        "-of", "json", video_path,
+    ])
+    if result.returncode != 0:
+        raise RuntimeError(f"ffprobe 失败: {result.stderr.strip()[-400:]}")
+    payload = json.loads(result.stdout or "{}")
+    streams = payload.get("streams") or []
+    video = next((s for s in streams if s.get("codec_type") == "video"), None)
+    if video is None:
+        raise RuntimeError(f"没有视频流: {video_path}")
+    duration = float((payload.get("format") or {}).get("duration") or 0.0)
+    if duration <= 0:
+        raise RuntimeError(f"无法读取时长: {video_path}")
+    return {
+        "duration_s": round(duration, 3),
+        "canvas": {"width": int(video.get("width") or 0), "height": int(video.get("height") or 0)},
+        "fps": _fraction(video.get("avg_frame_rate")) or _fraction(video.get("r_frame_rate")),
+        "subtitle_streams": sum(1 for s in streams if s.get("codec_type") == "subtitle"),
+        "audio_streams": sum(1 for s in streams if s.get("codec_type") == "audio"),
+    }
+
+
+def read_json(path, default=None):
+    """Parsed JSON at `path`, or `default` when the file does not exist."""
+    path = Path(path)
+    if not path.is_file():
+        return default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path, payload):
+    """Atomically write `payload` as UTF-8 JSON (temp file + os.replace)."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temporary, path)
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+    return path

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""On-demand production reference from a finished video: measure → (agent looks + labels) → check → export.
+
+    python3 scripts/reference.py measure <video> --work-dir U [--hard-score 10] [--soft-score 4] [--no-scale]
+    python3 scripts/reference.py frames  <video> --work-dir U (--review | --longest N | --span A,B [--step S])
+    python3 scripts/reference.py check   --work-dir U [--json]
+    python3 scripts/reference.py export  --work-dir U --out <dir>/production_reference.json
+
+Exit codes: 0 ok, 1 errors found (nothing exported), 2 bad input or ffmpeg failure.
+"""
+import argparse
+import json
+import sys
+
+from lib import read_json
+from reference_check import run_check, run_export
+from reference_frames import frames, legend
+from reference_measure import DEFAULT_HARD_SCORE, DEFAULT_SOFT_SCORE, MEASUREMENTS_FILE, measure
+
+__all__ = ["main"]
+
+
+def _print_report(report, as_json):
+    if as_json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return
+    if report.get("derived") is not None:
+        print("== derived（只在内存里；target 用 derived.* 路径引用）==")
+        print(json.dumps(report["derived"], ensure_ascii=False, indent=2))
+    for title, key, tag in (("errors", "errors", "ERROR"), ("warnings", "warnings", "WARN")):
+        print(f"== {title} ({len(report[key])}) ==")
+        for line in report[key]:
+            print(f"{tag} {line}")
+    if report.get("written"):
+        print(f"已导出 {report['written']}")
+    print("FAIL" if report["errors"] else "OK")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="把成片拆成可复用的制作参考（按需，不在生产路径上）")
+    sub = parser.add_subparsers(dest="command", required=True)
+    p_measure = sub.add_parser("measure", help="一次 ffmpeg：镜头切点与响度，按文件身份缓存")
+    p_measure.add_argument("video")
+    p_measure.add_argument("--work-dir", required=True)
+    p_measure.add_argument("--hard-score", type=float, default=DEFAULT_HARD_SCORE,
+                           help="scdet 分数达到它就算切点")
+    p_measure.add_argument("--soft-score", type=float, default=DEFAULT_SOFT_SCORE,
+                           help="达到它且是 ±0.3s 内的孤立峰才算切点；被压下的进入待复核窗口")
+    p_measure.add_argument("--no-scale", action="store_true", help="scdet 前不缩放到 320 宽")
+    p_frames = sub.add_parser("frames", help="拼帧图看画面：待复核窗口、最长镜头或任意时间段")
+    p_frames.add_argument("video")
+    p_frames.add_argument("--work-dir", required=True)
+    mode = p_frames.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--review", action="store_true", help="逐帧看 measure 压下的疑似切点")
+    mode.add_argument("--longest", type=int, metavar="N", help="看最长的 N 个镜头里有没有漏掉的切点")
+    mode.add_argument("--span", metavar="A,B", help="A 到 B 秒的接触表（没有理解产物时用它看片）")
+    p_frames.add_argument("--step", type=float, default=2.0, help="--span 的取帧间隔秒数")
+    p_check = sub.add_parser("check", help="R1–R7 校验 reference_breakdown.json 并打印派生值")
+    p_check.add_argument("--work-dir", required=True)
+    p_check.add_argument("--json", action="store_true")
+    p_export = sub.add_parser("export", help="零 error 时写 production_reference.json（R8 复扫）")
+    p_export.add_argument("--work-dir", required=True)
+    p_export.add_argument("--out", required=True)
+    p_export.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "measure":
+            payload = measure(args.video, args.work_dir, hard=args.hard_score, soft=args.soft_score,
+                              scaled=not args.no_scale)
+            shots, loudness = payload["shots"], payload.get("loudness") or {}
+            print(f"镜头 {shots['count']} 个，中位 {shots['median_s']}s，{shots['cuts_per_min']} 切/分钟；"
+                  f"整体响度 {loudness.get('integrated_lufs')} LUFS；待复核窗口 {len(shots['review_windows'])} 个")
+            return 0
+        if args.command == "frames":
+            span = None
+            if args.span:
+                start, _, end = args.span.partition(",")
+                span = (float(start), float(end))
+            if args.longest is not None and args.longest < 1:
+                raise ValueError("--longest 至少为 1")
+            mode = "review" if args.review else "span" if span else "longest"
+            pages = frames(args.video, args.work_dir, read_json(f"{args.work_dir}/{MEASUREMENTS_FILE}"),
+                           mode=mode, longest=args.longest, span=span, step=args.step)
+            print(legend(pages) if pages else "没有要看的帧（没有待复核窗口）")
+            return 0
+        report = run_check(args.work_dir) if args.command == "check" else run_export(args.work_dir, args.out)
+    except (OSError, RuntimeError, ValueError) as exc:
+        print(f"[video-reference] {exc}", file=sys.stderr)
+        return 2
+    _print_report(report, args.json)
+    return 1 if report["errors"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())