@oh-story/dsh 0.1.12 → 0.1.13

package/lib/video-recap/skills/video-assemble/scripts/timeline.py

@@ -10,8 +10,8 @@ set of tracks — exactly like a cut-tool project:
   - one **narration** audio track: the placed TTS beats;
   - an optional **bgm** audio track: a looped music bed with its own ducking;
   - one **subtitle** (text) track: the narration lines.
-  - optional **image** tracks: local photo overlays with normalized center-origin,
-    Y-up transforms for editable JianYing export.
+  - optional **image** tracks: local photo overlays with a normalized center-origin,
+    Y-up scale/position for editable JianYing export.
 
 The canonical ducking semantics live in `audio_automation.py`; ffmpeg
 (`assemble.py`) and this timeline model both derive their automation from that
@@ -44,8 +44,7 @@ def _floor_time(value, digits=4):
 
 def build_timeline(canvas, duration_s, video_clips, narration_segments,
                    bgm=None, ducking=None, subtitle_segments=None,
-                   image_segments=(), resource_packages=None,
-                   style_presets=None, extra_tracks=()):
+                   image_segments=()):
     """Assemble a Timeline dict from resolved placement data.
 
     canvas: {"width", "height", "fps"}
@@ -63,8 +62,8 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
     ducking: {"idle", "speech", "quiet", "fade", "bridge"} for the original-audio
              automation; None disables original ducking (flat original). `bridge` holds
              the duck across inter-beat gaps shorter than it.
-    image_segments: optional v2 local image overlays [{"source_path", "timeline_start",
-                 "timeline_end", ...authoring extensions}], passed through as authored.
+    image_segments: optional local image overlays [{"source_path", "timeline_start",
+                 "timeline_end", optional "scale"/"position"}], passed through as authored.
     """
     placed = [
         s for s in narration_segments
@@ -94,22 +93,14 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
             audio["base_gain"] = round(float(ducking["idle"]), 4)
         else:
             audio["base_gain"] = 1.0
-        video_clip = {
+        video_clip_objs.append({
             "source_path": c["source_path"],
             "source_start": round(float(c["source_start"]), 4),
             "source_end": round(float(c["source_end"]), 4),
             "timeline_start": round(ts, 4),
             "timeline_end": round(te, 4),
             "audio": audio,
-        }
-        for key in (
-            "chroma", "compound", "flip", "green_background", "lut", "mask",
-            "opacity", "position", "reverse", "reverse_path", "rotation_degrees",
-            "scale", "speed", "transition",
-        ):
-            if key in c:
-                video_clip[key] = deepcopy(c[key])
-        video_clip_objs.append(video_clip)
+        })
 
     tracks = [{"kind": "video", "name": "video", "clips": video_clip_objs}]
 
@@ -127,8 +118,6 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
         for key in ("source_duck_end", "source_restore_at", "source_handoff_status", "source_entry_status"):
             if key in s:
                 narration[key] = deepcopy(s[key])
-        if "speed" in s:
-            narration["speed"] = float(s["speed"])
         narr_segs.append(narration)
     if narr_segs:
         tracks.append({"kind": "audio", "name": "narration", "role": "narration",
@@ -161,20 +150,16 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
         ts, te = float(s["timeline_start"]), float(s["timeline_end"])
         if te <= ts:
             continue
-        text_segment = {
+        text_segs.append({
             "text": s["text"],
             "timeline_start": round(ts, 4),
             "timeline_end": round(te, 4),
-        }
-        for key in ("flip", "opacity", "position", "rotation_degrees", "scale", "style", "style_id", "words"):
-            if key in s:
-                text_segment[key] = deepcopy(s[key])
-        text_segs.append(text_segment)
+        })
     if text_segs:
         tracks.append({"kind": "text", "name": "subtitle", "segments": text_segs})
 
-    # --- local image overlays (optional, timeline schema v2). Transform fields are
-    # optional authoring extensions; the JianYing exporter validates and defaults them.
+    # --- local image overlays (optional). scale/position are optional; the JianYing
+    # exporter validates and defaults them.
     images = []
     for segment in image_segments:
         image = {
@@ -182,16 +167,13 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
             "timeline_start": round(float(segment["timeline_start"]), 4),
             "timeline_end": round(float(segment["timeline_end"]), 4),
         }
-        for key in ("flip", "lut", "mask", "opacity", "position", "rotation_degrees",
-                    "scale", "speed", "transition"):
+        for key in ("position", "scale"):
             if key in segment:
                 image[key] = deepcopy(segment[key])
         images.append(image)
     if images:
         tracks.append({"kind": "image", "name": "image", "segments": images})
 
-    tracks.extend(deepcopy(track) for track in extra_tracks)
-
     timeline = {
         "schema_version": SCHEMA_VERSION,
         "canvas": {"width": int(canvas["width"]), "height": int(canvas["height"]),
@@ -199,10 +181,6 @@ def build_timeline(canvas, duration_s, video_clips, narration_segments,
         "duration": round(float(duration_s), 4),
         "tracks": tracks,
     }
-    if resource_packages:
-        timeline["resource_packages"] = deepcopy(resource_packages)
-    if style_presets:
-        timeline["style_presets"] = deepcopy(style_presets)
     return timeline
 
 

package/lib/video-recap/skills/video-assemble/scripts/timeline_emit.py

@@ -81,11 +81,10 @@ def _emit_timeline(input_video, tts_segments, work_dir, duration_s, canvas, has_
                "volume": CONFIG["bgm_volume"],
                "ducking_volume": CONFIG["bgm_ducking_volume"],
                "fade": fade}
-    # carry ducking automation whenever ducking is on at all; even under sidechain
-    # mode the draft gets editable volume keyframes (ffmpeg stays the canonical mix)
+    # narration mode always ducks; the draft carries the same envelope as editable
+    # volume keyframes (ffmpeg stays the canonical mix)
     ducking = None
-    if audio_mode == "narration" and explicit_audio_mix is None \
-            and CONFIG["ducking_mode"] != "none":
+    if audio_mode == "narration" and explicit_audio_mix is None:
         ducking = {"idle": CONFIG["idle_orig_volume"],
                    "speech": CONFIG["speech_ducking_volume"],
                    "quiet": CONFIG["zone_ducking_volume"],

package/lib/video-recap/skills/video-assemble/scripts/visual_render.py

@@ -19,6 +19,7 @@ from source_subtitles import (
     _source_subtitle_mask_policy,
 )
 from subtitles.core import (
+    _frame_row,
     _measured_subtitle_band,
     _measured_subtitle_safe_area,
     _normalize_subtitle_text,
@@ -107,6 +108,7 @@ def _subtitle_layout_qc(entries, style, safe_area=None):
     return {
         "enabled": CONFIG["burn_subtitles"],
         "renderer": "ass" if CONFIG["burn_subtitles"] else "sidecar_srt",
+        "burn_degraded_reason": CONFIG["burn_subtitles_degraded"],
         "style": {
             "font_size": int(font_size),
             "max_chars": int(style["max_chars"]),
@@ -267,6 +269,28 @@ def _visual_overlay_filters(work_dir, canvas, video_duration):
     return filters, qc
 
 
+def _subtitle_delivery_warnings(mask, *, has_subtitles):
+    """Non-blocking, machine-readable record of a default burn that degraded to the sidecar.
+
+    A run with no subtitle entries loses nothing to the missing libass (a burned empty ASS
+    shows nothing either), so it ships no sidecar and records no warning.
+    """
+    reason = CONFIG["burn_subtitles_degraded"]
+    if not reason or not has_subtitles:
+        return []
+    return [{
+        "code": "subtitle_burn_degraded",
+        "reason": reason,
+        "delivered": "sidecar_srt",
+        "mask_dropped": mask["trigger"] == "burn_subtitles_degraded",
+        "message": (
+            "ffmpeg lacks the libass subtitles filter: subtitles are not burned into the "
+            "video and ship as a .srt sidecar next to it"
+        ),
+        "next_action": "install an ffmpeg build with libass and rerun to burn, or deliver the .srt sidecar",
+    }]
+
+
 def _build_visual_qc(tts_segments, work_dir, video_duration, canvas, *, overlay_qc=None, mask_filter=None):
     entries = _combined_subtitle_entries(tts_segments, work_dir, video_duration)
     style = _style_for_measured_subtitle_band(_subtitle_style_config(canvas), canvas)
@@ -284,6 +308,7 @@ def _build_visual_qc(tts_segments, work_dir, video_duration, canvas, *, overlay_
     })
     if overlay_qc is None:
         overlay_qc = _visual_overlay_filters(work_dir, canvas, video_duration)[1]
+    warnings = _subtitle_delivery_warnings(mask, has_subtitles=bool(entries))
     blocking_codes = []
     if mask["blocking"]:
         blocking_codes.append("mask_policy_not_explicit")
@@ -299,6 +324,7 @@ def _build_visual_qc(tts_segments, work_dir, video_duration, canvas, *, overlay_
         "verdict": "FAIL" if blocking_codes else "PASS",
         "blocking": bool(blocking_codes),
         "blocking_codes": blocking_codes,
+        "warnings": warnings,
         "geometry": {
             "canvas": {
                 "width": canvas["width"],
@@ -400,8 +426,8 @@ def _source_subtitle_mask_filter(canvas, work_dir, tts_segments, video_duration)
     if band is not None:
         y_top, y_bot = band
         padding = CONFIG["subtitle_mask_padding"]
-        mask_top = max(0, y_top - padding)
-        mask_bot = min(canvas["height"], y_bot + padding)
+        mask_top = _frame_row(canvas, max(0, y_top - padding))
+        mask_bot = _frame_row(canvas, min(canvas["height"], y_bot + padding))
         geometry = f"x=0:y={mask_top}:w=iw:h={mask_bot - mask_top}"
     else:
         # Our subtitle cues are one line. Keep the mask large enough for that line and its

package/lib/video-recap/skills/video-cut/SKILL.md

@@ -13,9 +13,10 @@ description: >
 本技能只执行 Agent 已经做出的剪辑决定：
 
 1. 校验并补全 `clip_plan.json`，写出带 `clip_id`、原片/输出时间与时长的 `clip_plan_validated.json`。
-2. 先避开原片硬切附近的闪帧风险，最后把边界吸附到可靠句末/自然停顿；声音完整性拥有最终优先级。
-3. 拼接选定区间，输出 `edited_source.mp4`。
-4. 到此停止，由 Agent 按真实输出时间线写 `narration.json`；本工具不读取旁白，也不做原片→输出映射。
+2. 先避开原片硬切附近的闪帧风险，再把边界吸附到可靠句末/自然停顿；声音完整性拥有最终优先级。
+3. 把每个入点对齐到源视频帧网格、每段时长对齐到整数个输出帧（不足一帧的移动，优先选句界门禁仍判为安全、仍在停顿内的一侧；两侧同样安全时选不跨过原片硬切的一侧，避免闪一帧），句界门禁检查的是对齐后的边界。
+4. 拼接选定区间，输出恒定帧率的 `edited_source.mp4`，帧数与 `clip_plan_validated.json` 记录的一致。
+5. 到此停止，由 Agent 按真实输出时间线写 `narration.json`；本工具不读取旁白，也不做原片→输出映射。
 
 相同输入会得到相同输出。`edited_source.mp4.meta.json` 记录标准化 clips、渲染设置和每个源文件的 `size`/`mtime_ns`；三者与当前一致且 `edited_source.mp4` 存在非空才复用，任一不同即重渲染。只有 sidecar 而没有媒体文件不复用。
 
@@ -29,8 +30,16 @@ description: >
 
 - `start` / `end` 是原片秒数；也接受 `source_start` / `source_end` 或 `in` / `out`。
 - 顶层可选 `target_duration`，例如 `"10m"`。
-- 多视频项目的每个片段还必须填写 `source_id`。
-- `speech_boundary_anchors.json` 与 ASR 时间段由理解阶段提供；Agent 先写大致区间，工具会尝试吸附并把仍在讲话区间内的入/出点作为 blocker 返回。
+- 多视频项目的每个片段还必须填写 `source_id`（不接受 `id` 代替），并用 `--sources-manifest` 传入来源清单（形状见下）。
+- `speech_boundary_anchors.json` 与 ASR 时间段由理解阶段提供；Agent 先写大致区间，工具会尝试吸附并把仍在讲话区间内的入/出点作为 blocker 返回。只含语气词或 ASR 杂音的窗口（"啊！"、"Hi."）不算讲话区间，只在紧挨真实对白的一侧保留 1 秒保护。只有标点的窗口（"……"）仍算讲话。
+
+多视频来源清单只接受一种形状，其他形状直接报错并写明期望形状：
+
+```json
+{"sources": [{"source_id": "ep1", "source_path": "/media/ep1.mp4", "duration": 1520.0, "source_work_dir": "sources/ep1"}]}
+```
+
+`duration` 可省略（省略时用 ffprobe 读取）；`source_work_dir` 可省略，填写时相对 `--work-dir`，用于读取该来源的静音、句末锚点与 ASR。其他键忽略。
 
 ## 3. 剪辑意图契约
 
@@ -68,24 +77,41 @@ beat_id | function | change | POV | preferred moment | 入点 reason | 出点 re
 ## 4. 运行命令
 
 ```bash
-python3 scripts/cut.py <video> --work-dir <work_dir> \
-  [--target-duration 10m] [--clip-padding 0] [--allow-overlap]
+python3 scripts/cut.py <video> --work-dir <work_dir> [--clip-plan <clip_plan.json>] \
+  [--sources-manifest <sources.json>] [--target-duration 10m] [--allow-overlap] \
+  [--allow-duration-drift] [--normalize-only] \
+  [--review-shots [--shot-scene-threshold 0.35] [--shot-roi X Y W H]]
 ```
 
+- `--clip-plan`：剪辑计划路径，默认 `<work_dir>/clip_plan.json`。
+
+- `--sources-manifest`：多源剪辑的来源清单 `{"sources": [{"source_id", "source_path"[, "duration", "source_work_dir"]}]}`；片段用 `source_id` 指明来源，并按自己的来源吸附句界与画面切点。
+- `--target-duration`：目标时长。实际时长与目标之比在 0.85–1.15 之外记 warning，在 0.60–1.40 之外阻断。
+- `--allow-duration-drift`：只放行时长偏差阻断（记为 `allowed: true` 的 warning），不放行句界或必保证据阻断。
+- `--normalize-only`：只标准化、吸附并检查计划，写出 `clip_plan_validated.json` 后退出，不渲染。
+- `--review-shots`：在渲染或复用的 `edited_source.mp4` 上召回短镜与密集切点候选，只报告、不修复；`--shot-scene-threshold` 是召回阈值（默认 0.35，不是验收标准），`--shot-roi` 只扫描该像素矩形（有黑边或包装时用），不裁画面。
+
+cut 阻断时以非零状态退出，并把原因写入 `clip_plan_validated.json` 的 `qc.blocking`，每项带 `code`：
+
+- `unsafe_clip_sentence_boundary`：片段边界仍在原声讲话内；逐边界判定见 `qc.boundary_status.sentence_checks`。被阻断的边界带 `nearest_safe: {"before", "after"}`：前后 5 秒内最近的安全边界 `{time, reason, delta}`（原片秒；`delta` 为相对当前边界的秒数，没有则为 `null`；已是原片帧网格上的落点并复核过；重跑时切镜头避让若把它拉回讲话内，这次避让会被撤回，`qc.boundary_status.shot_snaps` 记 `reverted_unsafe`，所以原样写回不会再因句界被阻断），按它改 `clip_plan.json` 的 `start`/`end` 后重跑。入点往前（`before`）是多保留、往后（`after`）是裁掉，出点相反；先确认改动不会切掉必保内容或与相邻片段重叠。两侧都是 `null` 说明附近没有停顿，要换区间而不是微调。
+- `target_duration_drift`：时长偏差超出阻断阈值；明细见 `qc.target_duration`。
+- `REQUIRED_EVIDENCE_INVALID` / `REQUIRED_EVIDENCE_MISSING` / `REQUIRED_EVIDENCE_ORDER` / `REQUIRED_EVIDENCE_AUDIO_UNAVAILABLE`：必保证据声明无效、缺段、错序或源无音轨；明细见 `qc.required_evidence`。
+
 ## 5. 输出契约
 
-- `clip_plan_validated.json`：标准化片段，包含 `clip_id`、`source_start/end`、`output_start/end` 与 `duration`。
-- `edited_source.mp4`：按计划拼接后的短视频。
+- `clip_plan_validated.json`：标准化片段，包含 `clip_id`、`source_start/end`、`output_start/end`、`duration` 与 `frame_count`（该片段渲染的帧数）。`qc.frame_grid` 记录输出帧率 `output_frame_rate`（单源沿用源帧率，多源用画布帧率，NTSC 写成 `30000/1001`）、总帧数与各源帧率；每次帧对齐的前后时间写在 `qc.boundary_status.frame_snaps`。
+- `edited_source.mp4`：按计划拼接后的恒定帧率短视频，帧数等于 `qc.frame_grid.frame_count`。
 - `shot_review.json`：仅 `--review-shots` 开启后生成的实际视频短镜/密集切镜候选；不会更改计划。
 
 下游把 `edited_source.mp4` 当作视频，把 Agent 按输出时间写的 `narration.json` 当作旁白。
 
 ## 6. 边界与时间线规则
 
-- `clip_plan.json` 使用原片时间；`narration.json` 直接使用剪后输出时间，不存在原片 → 输出的旁白映射。
+- `clip_plan.json` 使用原片时间；`narration.json` 直接使用剪后输出时间，不存在原片 → 输出的旁白映射。输出时间以 `clip_plan_validated.json` 为准：帧对齐会把边界移动不到一帧（25fps 下不超过 40 ms），写旁白前读 validated 计划，不要用自己写的原始区间推算。
+- 边界不在帧网格上时，concat 会在每个接点丢掉一个帧位（25fps 下画面停顿 80 ms，成片变成可变帧率），所以帧对齐无法关闭。源帧率未知（`r_frame_rate` 为 `0/0` 或大于 120）时入点不动，时长仍对齐到整数输出帧。
 - 默认禁止重叠或重复原片区间；`--allow-overlap` 开启后才允许。
 - 片段起点只能位于源头、可靠句末/静音窗，或与上一片段构成无损同源连续连接；片段终点同理。ASR 判定仍在讲话且无法吸附时写入 `unsafe_clip_sentence_boundary` 并阻断。
-- `SCENE_CUT_SNAP` 默认开启：先按画面把 source start 向后、source end 向前吸附到附近硬切，随后句末吸附再做最终修正，避免视觉修正重新制造半句原声。默认范围为 `SCENE_CUT_SNAP_MARGIN=0.5` 秒，检测阈值为 `SCENE_CUT_DETECT_THRESHOLD=0.4`。
+- `SCENE_CUT_SNAP` 默认开启：先按画面把 source start 向后、source end 向前吸附到附近硬切，随后句末吸附再做最终修正，避免视觉修正重新制造半句原声；附近没有停顿、句末吸附修不回来时，把边界移进讲话的那次避让会被撤回（原位置能过门禁时）。默认范围为 `SCENE_CUT_SNAP_MARGIN=0.5` 秒，检测阈值为 `SCENE_CUT_DETECT_THRESHOLD=0.4`。
 - scene-change score 只提供接点候选，不证明接点自然。先检查短时间窗内是否出现密集候选，再区分来源：原片自带的无关短镜头整段删除；相关但短到像闪帧的镜头通过扩展 IN/OUT 保留完整动作、反应或台词，不用定格/慢放伪造时长；由本次拼接制造的切点则优先移动边界、恢复同源连续运动、合并相邻片段或改用更自然的连接，尽量消除。成片后仍要逐个播放接点前后约 0.5–1 秒；白闪或曝光叠化再结合逐帧亮度定位，不能为了通过视觉检测切断完整台词，也不能用转场遮掩坏接点。
 - 修短残镜时不得仅为压低 scene 分数而对接点附近施加与所属镜头不连续的极端放大或位移；取景复核与修复验证流程见 `references/shot-review.md`。
 - 连续同源片段的无损连接不做句中双侧音频淡出；非连续片段仍在安全停顿内做防爆音淡入淡出。

package/lib/video-recap/skills/video-cut/references/shot-review.md

@@ -30,7 +30,7 @@ python3 scripts/cut.py source.mp4 --work-dir work --review-shots
 
 - `ffprobe` 完整解码收集真实帧 PTS；scene filter 使用整数 PTS 与过滤器 timebase，不用 seek 后的浮点 `pts_time` 反推帧号。
 - 帧号从 0 开始，区间半开 `[start_frame,end_frame)`；首镜、末镜也检查。VFR 同时记录真实 rational PTS 时长，不能用平均 fps 乘秒数。
-- 默认候选规则：镜头不超过 **1 秒**，或 **2 秒内至少 4 个切点**。帧数上限缺省由实测帧钟换算（`round(fps × max_short_seconds)`），不写死某个帧率；需要固定帧数时用 `--max-short-frames` 显式覆盖。参数只控制召回，不是统一剪辑标准。
+- 默认候选规则：镜头不超过 **1 秒**，或 **2 秒内至少 4 个切点**。帧数上限缺省由实测帧钟换算（`round(fps × 1 秒)`），不写死某个帧率；需要固定帧数时用 `--max-short-frames` 显式覆盖。参数只控制召回，不是统一剪辑标准。
 - `0.35` 是默认 scene 起始阈值。加黑边、包装占比大、低反差的画面会系统性少报。**某个阈值下零候选不是没有闪帧的证据。** 用一段已知有坏短镜的窗口校准阈值，保留每一轮的报告，不静默换阈值只报告“通过”。降低阈值也可能增加曝光、运动和动效误报。
 - 未提供计划时来源为 `UNKNOWN`。提供计划时先核对计划 clips、渲染设置与 `edited_source.mp4.meta.json` 一致、源文件 `size`/`mtime_ns` 未变、输出存在非空；失配直接失败，不猜“最新版本”。报告 `plan_binding.path` 只记录所用计划路径。
 - 靠近量化后 EDL 拼接点一帧以内仅标 `EDIT_JOIN_CANDIDATE`。内部候选可以标所在已绑定 clip、估计原片秒数，但仍为 `UNKNOWN`；没有独立源片证据，不能认定是原片自带切镜。

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

@@ -1,41 +1,9 @@
 #!/usr/bin/env python3
-"""Public API and CLI entrypoint for the self-contained video-cut skill."""
+"""CLI entrypoint for the self-contained video-cut skill."""
 
 from cut_cli import main
-from cut_contract import (
-    edited_source_render_cache_payload,
-    normalize_clip_plan,
-    normalize_multi_source_clip_plan,
-    parse_duration_seconds,
-    should_reuse_edited_source,
-)
-from cut_render import build_edited_source_video
-from media_geometry import VideoGeometry
-from narration_mapping import update_cut_qc
-from sentence_boundaries import (
-    enforce_clip_sentence_boundaries,
-    snap_clip_ends_to_lines,
-    snap_clip_starts_to_lines,
-    snap_clips_off_shot_changes,
-    snap_multi_source_clips,
-)
 
-__all__ = [
-    "VideoGeometry",
-    "build_edited_source_video",
-    "edited_source_render_cache_payload",
-    "enforce_clip_sentence_boundaries",
-    "main",
-    "normalize_clip_plan",
-    "normalize_multi_source_clip_plan",
-    "parse_duration_seconds",
-    "should_reuse_edited_source",
-    "snap_clip_ends_to_lines",
-    "snap_clip_starts_to_lines",
-    "snap_clips_off_shot_changes",
-    "snap_multi_source_clips",
-    "update_cut_qc",
-]
+__all__ = ["main"]
 
 if __name__ == "__main__":
     main()