@oh-story/dsh 0.1.12 → 0.1.13

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

@@ -0,0 +1,189 @@
+"""The sentence-boundary gate: may a clip edge cut the source audio here?
+
+Every audible clip edge must rest on the source start/end, a sentence or quiet pause, a
+lossless same-source join, or outside detected speech. A blocked edge names the nearest
+safe edge times on either side.
+"""
+
+
+def _unverified_window(row):
+    return row.get("boundary_use") == "unverified"
+
+
+def _same_source(left, right):
+    # Single-source normalized plans omit source identity; both sides then read as None.
+    return left.get("source_id") == right.get("source_id") and left.get(
+        "source_path"
+    ) == right.get("source_path")
+
+
+def _continuous_source_join(left, right, tolerance=0.05):
+    """`right` plays straight on from `left` with no media removed between them.
+
+    Plan neighbours only: a per-source sub-plan (multi-source snapping) packs clips that
+    another source's clip separates in the real plan, so consecutive clip_ids are required.
+    """
+    return (
+        right.get("clip_id", 1) - left.get("clip_id", 0) == 1
+        and _same_source(left, right)
+        and abs(left["source_end"] - right["source_start"]) <= tolerance
+        and abs(left["output_end"] - right["output_start"]) <= tolerance
+    )
+
+
+def _edge_joined(clips, idx, edge, tolerance=0.05):
+    """Whether clips[idx]'s `edge` is a continuous same-source join with its plan neighbour."""
+    if edge == "start":
+        return idx > 0 and _continuous_source_join(clips[idx - 1], clips[idx], tolerance)
+    return idx + 1 < len(clips) and _continuous_source_join(clips[idx], clips[idx + 1], tolerance)
+
+
+# How far either side of a blocked edge the gate looks for a safe edge to suggest.
+_SAFE_EDGE_SEARCH_SECONDS = 5.0
+# How close to a pause window or speech span an edge counts as on it.
+_GATE_TOLERANCE = 0.05
+# The longest first-video-frame delay still waived as the source start. Typical mp4 offsets
+# are a few ms; a capture whose picture begins later than this has real audio before it.
+_VIDEO_START_WAIVER_SECONDS = 0.2
+
+
+def _edge_classifier(boundary_windows, speech_spans, video_duration, tolerance,
+                     video_start=0.0):
+    """classify(edge, ts, contiguous) -> (status, reason) under the sentence-boundary gate.
+
+    `video_start` is the source's first video frame (seconds after the file start): a clip
+    cannot start any earlier on the picture, so a start up to it is the source start. Only
+    up to `_VIDEO_START_WAIVER_SECONDS`: a later first frame (a TS capture whose picture
+    starts 1.5 s into the audio) gets the normal speech rules, so a start moved onto it
+    that lands mid-sentence still blocks.
+    """
+    verified_windows = [row for row in boundary_windows if not _unverified_window(row)]
+    unverified_windows = [row for row in boundary_windows if _unverified_window(row)]
+    source_start = video_start if video_start <= _VIDEO_START_WAIVER_SECONDS else 0.0
+
+    def inside(rows, ts):
+        return any(row["start"] - tolerance <= ts <= row["end"] + tolerance for row in rows)
+
+    def classify(edge, ts, contiguous=False):
+        if edge == "start" and ts <= source_start + tolerance:
+            return "safe", "source_start"
+        if edge == "end" and ts >= video_duration - tolerance:
+            return "safe", "source_end"
+        if contiguous:
+            return "safe", "continuous_source_join"
+        if inside(verified_windows, ts):
+            return "safe", "sentence_or_quiet_boundary"
+        if inside(unverified_windows, ts) and (not speech_spans or inside(speech_spans, ts)):
+            # Word-safe pause, but the sentence end is only a coarse-ASR estimate.
+            return "safe", "unverified_sentence_boundary"
+        if not speech_spans:
+            return "unchecked", "speech_timing_unavailable"
+        if not inside(speech_spans, ts):
+            return "safe", "outside_detected_speech"
+        return "blocking", "inside_detected_speech"
+
+    return classify
+
+
+def _nearest_safe_edges(classify, edge, clip, boundary_windows, speech_spans, video_duration,
+                        tolerance, frame_snap=None):
+    """The closest safe edge times before and after a blocked edge, within the search span.
+
+    Candidates are pause-window bounds, the first instants clear of a speech span (past the
+    gate tolerance), and the source start/end; each is re-checked with the gate itself and
+    must leave the clip a positive length. With `frame_snap(edge, clip, ts)` (where the
+    frame-grid pass would move that edge) each candidate is reported where it lands on the
+    source frame grid, and only when that landing is safe too: a candidate between two frames
+    (a speech start minus the 60 ms clearance is half a frame at 25 fps) is never handed back
+    for the frame pass to re-decide, so sending the suggestion back cannot be blocked again or
+    moved onto the other side of a source hard cut.
+    """
+    ts = clip["source_start"] if edge == "start" else clip["source_end"]
+
+    def usable(when):
+        if not 0.0 <= when <= video_duration or abs(when - ts) > _SAFE_EDGE_SEARCH_SECONDS:
+            return False
+        return when < clip["source_end"] if edge == "start" else when > clip["source_start"]
+
+    margin = tolerance + 0.01
+    candidates = {0.0, round(video_duration, 3)}
+    for row in boundary_windows:
+        candidates.update((row["start"], row["end"]))
+    for row in speech_spans:
+        candidates.update((row["start"] - margin, row["end"] + margin))
+    safe = {}
+    for when in sorted(round(c, 3) for c in candidates):
+        if not usable(when) or classify(edge, when)[0] != "safe":
+            continue
+        if frame_snap is not None:
+            when = round(frame_snap(edge, clip, when), 3)
+        status, reason = classify(edge, when)
+        if status == "safe" and usable(when):
+            safe.setdefault(when, reason)
+    before = [when for when in safe if when < ts]
+    after = [when for when in safe if when > ts]
+
+    def suggestion(when):
+        return {"time": when, "reason": safe[when], "delta": round(when - ts, 3)}
+
+    return {"before": suggestion(max(before)) if before else None,
+            "after": suggestion(min(after)) if after else None}
+
+
+def enforce_clip_sentence_boundaries(
+    plan, boundary_windows, speech_spans, video_duration, tolerance=_GATE_TOLERANCE,
+    video_start=0.0, frame_snap=None,
+):
+    """Block any audible clip edge that falls inside detected source speech.
+
+    Safe edges are: source start (up to a prompt first video frame, `video_start`) and end, a
+    sentence/quiet pause (`unverified_sentence_boundary` when only a coarse-ASR sentence
+    estimate covers it), or a truly contiguous same-source join (no media is removed).
+    Missing ASR timing degrades to `unchecked` rather than inventing speech. Once ASR says
+    an edge is speech-owned, failure to snap is blocking, and the check names the nearest
+    safe edge times on either side (`nearest_safe`, frame-checked through `frame_snap`).
+    """
+    clips = plan["clips"]
+    checks, new_blockers = [], []
+    classify = _edge_classifier(boundary_windows, speech_spans, video_duration, tolerance,
+                                video_start)
+
+    for idx, clip in enumerate(clips):
+        for edge, ts in (("start", clip["source_start"]), ("end", clip["source_end"])):
+            status, reason = classify(edge, ts, _edge_joined(clips, idx, edge, tolerance))
+            check = {
+                "clip_id": clip["clip_id"],
+                "source_id": clip.get("source_id"),
+                "edge": edge,
+                "time": round(ts, 3),
+                "status": status,
+                "reason": reason,
+            }
+            if status == "blocking":
+                check["nearest_safe"] = _nearest_safe_edges(
+                    classify, edge, clip, boundary_windows, speech_spans, video_duration,
+                    tolerance, frame_snap,
+                )
+            checks.append(check)
+            if status == "blocking":
+                new_blockers.append(
+                    {
+                        "code": "unsafe_clip_sentence_boundary",
+                        **check,
+                        "message": "剪辑边界仍落在原声讲话区间内，必须移动到句末锚点，不能截断原声句子。"
+                        "nearest_safe 给出前后最近的安全边界时间。",
+                    }
+                )
+
+    qc = plan.setdefault("qc", {})
+    qc.setdefault("boundary_status", {})["sentence_checks"] = checks
+    existing = [
+        row
+        for row in qc.get("blocking", [])
+        if row["code"] != "unsafe_clip_sentence_boundary"
+    ]
+    if existing or new_blockers:
+        qc["blocking"] = existing + new_blockers
+    else:
+        qc.pop("blocking", None)
+    return plan

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

@@ -341,14 +341,10 @@ def main():
     parser.add_argument("--threshold", type=float, default=0.35)
     parser.add_argument("--roi", nargs=4, type=int, metavar=("X", "Y", "WIDTH", "HEIGHT"))
     parser.add_argument("--max-short-frames", type=int, default=None,
-                        help="explicit frame cap; default derives round(fps * max_short_seconds)")
-    parser.add_argument("--max-short-seconds", type=float, default=1.0)
-    parser.add_argument("--dense-window-seconds", type=float, default=2.0)
-    parser.add_argument("--min-dense-cuts", type=int, default=4)
+                        help="explicit frame cap; default derives round(fps * 1s) from the measured clock")
     args = parser.parse_args()
     report = write_scan(args.video, args.output, threshold=args.threshold, plan_path=args.plan, roi=args.roi,
-                        max_short_frames=args.max_short_frames, max_short_seconds=args.max_short_seconds,
-                        dense_window_seconds=args.dense_window_seconds, min_dense_cuts=args.min_dense_cuts)
+                        max_short_frames=args.max_short_frames)
     print(json.dumps({"status": report["status"], "short_spans": len(report["short_spans"]),
                       "dense_windows": len(report["dense_windows"]), "report": args.output}))
 

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

@@ -15,8 +15,13 @@ description: >
 video-understanding ─▶ Agent 按 video-script 制定方案并写稿 ─▶ [video-cut] ─▶ video-voiceover ─▶ video-assemble
 ```
 
+把成片拆成制作参考不是生产路径。用户要求时：对成片跑 video-understanding（建议 `ASR_SEGMENT_SECONDS=5`），
+再用 video-reference 做 measure、标注、check、export，把导出的 `production_reference.json` 复制进下一次运行的
+`work_dir`，或登记成资源库的 `production_reference` 模板、采纳后经 `--project` 绑定。recap 不会自动运行它，也不拿新成片与参考做比对。
+
 流程支持断点续跑：写好 `narration.json` 后重复同一条命令即可继续。第二阶段会比对
 `recap_run_manifest.json` 记录的源视频路径、文件大小/修改时间与运行参数，拒绝复用来自其他源视频或其他参数的旧工作目录；视频理解产物也只在来源一致时复用。
+暂停时打印的续跑命令就是原命令：保留原来的写法，视频与路径参数转成绝对路径，补上 `--work-dir` 和来自环境变量的设置，从任何目录都能直接运行；同一份参数写在 manifest 的 `argv`。
 
 画面流程 `--edit-mode full|cut|dub` 与声音策略 `--audio-mode` 是两个独立开关；
 `narration` 保留上述解说流程，`source-mix` 不做配音，`adopted-packet-copy` 冻结当前输入的已采用 AAC 音轨。
@@ -46,7 +51,7 @@ python3 scripts/recap.py picture.mp4 --edit-mode full --work-dir NEW_WORK \
 ```
 
 三个 JSON 参数必须同时出现。该入口只接受单视频、full、narration、音轨 0、新工作目录和未存在的
-交付文件；不运行理解、写稿、解说评审、TTS、cut、MiMo QC 或剪映导出。语义与媒体形状仍由
+交付文件；不运行理解、写稿、解说评审、TTS、cut 或剪映导出。语义与媒体形状仍由
 video-assemble 严格验证，recap 只核对子技能绑定记录引用的是同一批采用文件与母版路径，不把调用方
 采用的声音或混音声明成自动创作或发布批准。详见 `references/audio-routing.md`。
 
@@ -85,9 +90,8 @@ TTS 供应商由 `--tts-provider mimo-tts|fish-audio|index-tts`（或 `TTS_PROVI
 可选能力：
 
 - `--mimo-video-overview`：按场景块补充 MiMo 视频理解。
-- `--mimo-qc pre-assemble|post-render|both`：在合成前、成片后或两个阶段给出建议型复核。
 
-MiMo QC 默认关闭；每个选定阶段最多请求一次，写入 `mimo_qc.json`。任何凭证缺失、限流、超时、格式错误或采样失败都只记录状态，不阻断流程。可覆盖配置见 `references/config-playbook.md`，QC 报告的最小契约见 `references/shift-left-qc-schema.md`。
+可覆盖配置见 `references/config-playbook.md`，`final_qc.json` 的字段见 `references/data-schema.md`。
 
 下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本启动后会自行定位兄弟技能和资源。
 
@@ -97,6 +101,7 @@ MiMo QC 默认关闭；每个选定阶段最多请求一次，写入 `mimo_qc.js
 
 若能识别影片、剧集或主题，先按 video-understanding 技能的调研指南 `research-guide.md` 调研并写入
 `work_dir/background_research.json`。视频理解会把人物名和剧情背景折入 VLM 上下文，避免只得到“黑衣男子”一类模糊描述。无法识别来源时可跳过。
+多视频运行同样写在项目 `work_dir` 下：recap 在每个来源理解前把它复制到 `sources/<source_id>/`（来源目录里没有、或比项目文件旧时才复制，所以某一集需要单独的调研时，在项目文件之后写入该来源目录即可）。
 
 ### 4.2 分析并暂停创作
 
@@ -116,7 +121,8 @@ python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
 时间线有两条不可降级的硬约束：原声只能在可靠句末/静音边界被切入、切出或恢复；旁白必须使用
 完整逐段音频，任何 clip 映射裁段、TTS 裁尾或剪映引用更长的加速前素材都阻断。Agent 收到
 `interrupts_source_sentence` / `unsafe_clip_sentence_boundary` / `no_safe_fit` /
-`timeline_audio_mismatch` 时，应移动边界、缩短整句或删除该块，而不是增加抢断 override。
+`timeline_audio_mismatch` 时，应移动边界、缩短整句或删除该块，而不是增加抢断 override；
+`unsafe_clip_sentence_boundary` 附带的 `nearest_safe` 给出前后最近的安全边界时间。
 
 ### 4.3 多视频与素材库
 
@@ -126,6 +132,8 @@ python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
 python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep
 ```
 
+第二阶段与单视频一样生成剪后故事板 `storyboard/edited_storyboard.*`，取自各来源 `sources/<source_id>/frames/`，brief 顶部列出 `S1`/`S2`… 对应的 `source_id`；素材库恢复的来源没有抽帧，这些片段不出现在故事板里，用 `inspect clip-map` 核对。
+
 可选文件系统素材库：
 
 ```bash
@@ -135,8 +143,8 @@ python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --material-library-dir
 
 素材检索只是对 JSON / MD / JSONL 做 grep，例如 `grep -R "keyword" .video-materials`。当前版本不复制原始媒体，也不提供数据库、向量或语义搜索。
 
-同一根目录还可以登记可复用的资源（BGM、音效、音色、字体、图片）、带版本与采用记录的模板（字幕样式、包装图层）和样片。
-格式与 `scripts/library.py check|list|show` 只读工具见 `references/resource-library.md`。用 `--project recap_project.json` 把已采用的字幕样式、音色与 BGM 绑定到这次运行；
+同一根目录还可以登记可复用的资源（BGM、音效、音色、字体、图片）、带版本与采用记录的模板（字幕样式、包装图层、制作参考）和样片。
+格式与 `scripts/library.py check|list|show` 只读工具见 `references/resource-library.md`。用 `--project recap_project.json` 把已采用的字幕样式、包装、制作参考、音色与 BGM 绑定到这次运行；
 每次 full / cut 合成后 `work_dir/resource_lock.json` 记下实际用到的资源与授权状态。
 
 ### 4.4 继续生成成片
@@ -149,15 +157,7 @@ python3 scripts/recap.py <video> --work-dir <work_dir>  # 可追加 --edit-mode
 
 流程会校验当前阶段的硬输入（`clip_plan.json` / `narration.json`）；两份创作计划仍是 Agent 与建议型评审使用的工作记录，不是渲染门禁。cut 模式随后生成 `edited_source.mp4`，再合成旁白并输出 `recap_<name>.mp4`。
 
-若需要建议型 MiMo 复核：
-
-```bash
-python3 scripts/recap.py <video> --work-dir <work_dir> --mimo-qc both
-```
-
-合成前复核会读取脚本、计划和 TTS 元数据；成片后还会读取最多六张临时 JPEG。输入文件的大小/修改时间、模型与提示都未变时直接复用上次报告，`--mimo-qc-refresh` 可强制刷新。帧的 base64 与凭证不会写入磁盘。
-
-已有批准解说稿时加 `--preserve-approved-text`：校验与 TTS 原样保留批准稿（只更新 `overlaps_speech`），装不下时间窗即失败，不缩稿、不降级为部分成功。
+校验从不改写解说稿（只更新实测的 `overlaps_speech`）；full 模式下文本装不下时间窗会以 `over_budget` error 退回给 Agent。已有批准解说稿时加 `--preserve-approved-text`，TTS 也原样保留批准稿，装不下时间窗即失败，不缩稿、不降级为部分成功。
 
 ### 4.5 字幕与克隆旁白
 
@@ -184,11 +184,16 @@ python3 tools/measure_subtitle.py <video>
 scene score、亮度统计、contact sheet 与自动 QC 只负责定位候选问题；最终判断以真实播放为准。密集切点的来源判断与处理规则按剪辑技能执行。修复失败时回到剪点、声音或文案层，不用更多包装掩盖。
 
 full/cut 交付如需让确定性的最终检查影响命令退出状态，显式传
-`--require-final-qc`。只有 `final_qc.json` 与 `golden_eval.json` 的摘要均为
-`ok: true` 且整数 `blocker_count: 0` 才打印完成并返回成功；缺失、畸形或 blocker
+`--require-final-qc`。只有 `final_qc.json` 的摘要为 `ok: true` 且整数
+`blocker_count: 0` 才打印完成并返回成功；缺失、畸形或 blocker
 会保留报告和已渲染诊断媒体，但命令非零退出且不打印完成。默认仍是仅报告、不阻断。
 该参数不支持 `--edit-mode dub`；dub 未传该参数时的准备和渲染行为不变。
 
+交付时读 `final_qc.json` 的 `metadata.warnings`，有内容就原样告诉用户，不能只报“完成”。`subtitle_burn_degraded`
+表示 ffmpeg 缺 libass、默认烧录被降级：成片里没有字幕，字幕在成片旁的同名 `.srt`。用户要烧录字幕，就请他装带 libass 的
+ffmpeg 后重跑；显式传 `--burn-subtitles` 时缺 libass 会在开跑前报错。旁白里写了 `visual_overlays` 而 ffmpeg 缺
+drawtext 时，流程在配音前停下，按报错删掉叠加或换 ffmpeg 后续跑。
+
 ### 4.7 不需要解说的片子
 
 ```bash
@@ -211,19 +216,13 @@ python3 scripts/recap.py adopted.mp4 --work-dir packaging_work --audio-mode adop
 python3 scripts/recap.py <video> --edit-mode dub --work-dir <work_dir>
 ```
 
-准备阶段会转写英文、提取一段参考音频，并写出 `dub_brief.md` 与 `dub_transcript.json`。Agent 随后写：
+准备阶段会转写英文、提取一段参考音频，并写出 `dub_brief.md` 与 `dub_transcript.json`。Agent 按 `dub_brief.md` 里的翻译要求（逐句忠实、时间窗、语速）写 `dub_script.json`：
 
 ```json
 [{"start": 0.0, "end": 2.0, "zh": "中文译文"}]
 ```
 
-要求：
-
-- 逐句忠实翻译，不删钩子、不合并、不擅自压缩；原文重复，译文也按时间重复。
-- 每句沿用原声 `[start, end]`，相邻句不重叠。
-- 译文尽量控制在约 5 字/秒，使其能在原时间窗内说完。
-
-重复同一命令后输出 `dub_<name>.mp4`。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。
+重复同一命令后先做确定性 lint（`dub_lint.json`，空行、重叠、越界即中止），再输出 `dub_<name>.mp4`。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。
 
 ## 6. 自检与只读 dashboard
 
@@ -249,12 +248,10 @@ python3 scripts/dashboard_server.py --root <目录> [--port 0] [--open]
 - `subtitles.srt` / `subtitles.ass`：字幕。
 - `work_dir/`：全部中间产物，契约见 `references/data-schema.md`。
 - `work_dir/recap_story_plan.json` / `visual_audio_board.json`：Agent 创作意图与剪辑决定。
-- `work_dir/mimo_qc.json`：可选的建议型复核，不作为发布门禁。
 
 完整参数列表以 `python3 scripts/recap.py --help` 为准。`--style` 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。
 
 ## 8. 能力边界
 
 - 语义评审默认建议型、失败开放；只有调用方显式启用严格解说评审时，事实矛盾、残句或评审不可用才会在 TTS 前阻断。确定性校验阶段始终负责硬校验。
-- MiMo QC 不能阻断、自动修复或改变退出状态，只提供定位建议。
 - 宣发标题、花字或外部文案回填见 `video-script` 的 references/promotional-copy.md。

package/lib/video-recap/skills/video-recap/references/audio-routing.md

@@ -26,9 +26,9 @@ exactly this all-or-none bundle:
 It requires narration mode, stream 0, a new explicit `--work-dir`, and a delivery path
 that does not already exist. `--output-dir` is optional; when omitted, delivery uses the
 new work directory's parent. The route calls only the video-assemble CLI; it does
-not run understanding, script validation, narration review, voiceover, MiMo QC, cut,
+not run understanding, script validation, narration review, voiceover, cut,
 continuation, editor export, or material-cache reuse. Ambient TTS provider and voice
-configuration are inert. Explicit TTS/voice/review/MiMo/editor flags are rejected rather
+configuration are inert. Explicit TTS/voice/review/editor flags are rejected rather
 than silently ignored.
 
 `recap_run_manifest.json` records the resolved path of all three local artifacts under
@@ -54,8 +54,10 @@ episodes. Use two existing stages rather than sending an old mix binding into a
      --sources-manifest SOURCES_JSON
    ```
 
-   A single-source cut omits `--sources-manifest`. For already locked frame decisions,
-   use the picture-plan path instead. Read `clip_plan_validated.json` (or the locked path's
+   `SOURCES_JSON` must be `{"sources": [{"source_id": ..., "source_path": ...}]}`
+   (optional per-source `duration` and `source_work_dir`); recap's
+   `multi_source_manifest.json` already has this shape. A single-source cut omits
+   `--sources-manifest`. For already locked frame decisions, use the picture-plan path instead. Read `clip_plan_validated.json` (or the locked path's
    `picture_map.json`) before placing sound.
 2. Keep the selected WAVs, `tts_meta.json`, and `narration_adoption.json` when the words,
    WAV bytes, and selected voice are unchanged. Do not run voiceover just to move a line.
@@ -97,7 +99,6 @@ narration review files are not read as evidence for the current run.
   not run, and continuation commands do not promote it into explicit flags.
 - Cut audio modes support selected stream 0 only. Full mode may pass
   another stream to assemble, subject to assemble/export support.
-- Source modes do not support advisory MiMo QC; use `off`.
 - Local adopted full-sound assembly consumes a prebuilt picture in `full` mode; use the
   two-stage workflow above for single- or multi-source cuts. That assembly invocation
   does not resume an old work directory or export an editor draft.
@@ -105,7 +106,8 @@ narration review files are not read as evidence for the current run.
   because the precise-track contract only binds adopted packet audio.
 
 `--preserve-approved-text` remains opt-in and is forwarded unchanged to
-voiceover and continuation only in narration mode.
+voiceover and continuation only in narration mode. The narration validator no longer takes
+it: validation never rewrites narration in any mode.
 
 Narration may explicitly select `--tts-provider index-tts`; `auto` does not
 select Index TTS. Index TTS cannot be combined with MiMo voice selection,

package/lib/video-recap/skills/video-recap/references/config-playbook.md

@@ -26,23 +26,20 @@ Defaults below are bundle-level defaults unless a note scopes them to a specific
 | Fish Audio endpoint | `FISH_TTS_API_URL` | `https://api.fish.audio/v1/tts` | returns WAV directly to the existing voiceover pipeline |
 | Self-hosted TTS | `INDEX_TTS_ENDPOINT` / `INDEX_TTS_VOICE` | — | explicit `--tts-provider index-tts` only; the endpoint is never written to disk, and segment `emotion`/style is rejected |
 | TTS transport | `TTS_TIMEOUT` / `TTS_WORKERS` / `TTS_RETRIES` | `300` / `4` / `3` | request timeout, parallel segments, and per-segment retries for all providers |
-| Advisory MiMo QC | `MIMO_QC` / `--mimo-qc {off,pre-assemble,post-render,both}` | `off` | optional subjective review at the selected stage(s), one request per stage. Always fail-open: results only point the agent/user to `mimo_qc.json`, never block or auto-repair |
-| MiMo QC refresh/model | `MIMO_QC_REFRESH` / `--mimo-qc-refresh`; `MIMO_QC_MODEL` | cache on / VLM fallback | the reuse check compares evidence file sizes/mtimes, model and prompt, never absolute paths. Post-render temporarily samples at most 6 JPEGs (≤768px); base64 is never persisted. The standalone adapter requires explicit `mimo_qc.py --live` for network access |
-| Narration block coverage | `NARRATION_COVERAGE_TARGET` / `NARRATION_BLOCK_SECONDS` | `0.7` / `9.0` | current block-recap density controls |
+| TTS hallucination bound | `TTS_MIN_SPEECH_RATE` | `2.5` | chars/s (each digit counts 1, `%` counts 3, a Latin word 1.5); a narration segment or dub line longer than reading its text at this rate plus pause and edge allowances is treated as invented speech: retried, never cached, failed after `TTS_RETRIES` with the last take kept as `*.rejected.wav`; `0` disables |
 | Narration speed | `NARRATION_SPEED` | `1.15` | global atempo on the voiceover; set `1.0` for long-form/documentary |
-| Narration authored start | `NARRATION_DELAY_SECONDS` | `0` | the renderer uses the Agent-authored `start` exactly. Set a non-zero value only for legacy drafts; hidden delay can move a validated sentence-boundary entry back into source speech |
 | Source sentence boundary detector | `SOURCE_BOUNDARY_NOISE_THRESHOLD` / `SOURCE_BOUNDARY_MIN_PAUSE` / `SOURCE_BOUNDARY_MAX_ALIGNMENT_ERROR` | `-18dB` / `0.12` / `2.1` | aligns ASR terminal punctuation to short acoustic pauses and writes `speech_boundary_anchors.json`; unsafe narration entries and cut in/out points are blocked. There is no intentional-interrupt override |
-| Cut sentence snapping | `SNAP_CLIP_LINE_END` / `CLIP_START_SNAP_MAX_PREPEND` / `CLIP_START_SNAP_MAX_TRIM` / `CLIP_SNAP_MAX_EXTEND` | on / `1.8` / `0.35` / `2.0` | scene-cut cleanup runs first; reliable sentence/quiet snapping runs last. An ASR-owned edge still inside speech produces `unsafe_clip_sentence_boundary` instead of a half sentence |
-| Mask source subs | `MASK_SOURCE_SUBTITLES` / `SOURCE_SUBTITLE_MASK_POLICY` / `SOURCE_SUBTITLE_MASK_RATIO` | off / `off` / `0.14` | masking requires an explicit policy (`opt_in`, `safe`, or `forced`) and burned recap subtitles. Passing measured `--subtitle-y-top/--subtitle-y-bot` opts in automatically. With `--no-burn-subtitles`, the MP4 stays unmasked |
-| Measured subtitle band | `SUBTITLE_Y_TOP` / `SUBTITLE_Y_BOT`; `--subtitle-y-top/--subtitle-y-bot` | off | half-open `[top, bot)` ffmpeg auto-rotated display-frame pixel coordinates; square-pixel video and bottom ASS alignment (1/2/3) only; use `tools/measure_subtitle.py` to generate source-identified previews and suggestions |
+| Cut sentence snapping | `SNAP_CLIP_LINE_END` / `CLIP_START_SNAP_MAX_PREPEND` / `CLIP_START_SNAP_MAX_TRIM` / `CLIP_SNAP_MAX_EXTEND` | on / `1.8` / `0.35` / `2.0` | scene-cut cleanup runs first, then reliable sentence/quiet snapping, then a sub-frame frame-grid alignment that keeps the edge in its pause. An ASR-owned edge still inside speech produces `unsafe_clip_sentence_boundary` instead of a half sentence, with `nearest_safe` before/after times within 5 s, already on the source frame grid |
+| Mask source subs | `MASK_SOURCE_SUBTITLES` / `SOURCE_SUBTITLE_MASK_POLICY` / `SOURCE_SUBTITLE_MASK_RATIO` | off / `off` / `0.14` | masking requires an explicit policy (`opt_in`, `safe`, or `forced`) and burned recap subtitles. Passing measured `--subtitle-y-top/--subtitle-y-bot` opts in automatically. With `--no-burn-subtitles`, or when a default burn degrades because ffmpeg lacks libass, the MP4 stays unmasked |
+| Measured subtitle band | `SUBTITLE_Y_TOP` / `SUBTITLE_Y_BOT`; `--subtitle-y-top/--subtitle-y-bot` | off | half-open `[top, bot)` rows of the auto-rotated display canvas (the stored width is scaled by the SAR; a rotated non-square stream's rows are scaled by it too, and the mask converts them back to decoded-frame rows); square or near-square pixels (SAR within 2% of 1:1; unspecified `0:1` counts as square) and bottom ASS alignment (1/2/3) only; use `tools/measure_subtitle.py` to generate source-identified previews and suggestions |
 | Subtitle mask look | `SUBTITLE_MASK_OPACITY` / `SOURCE_SUBTITLE_MASK_TIMING` / `SUBTITLE_MASK_PADDING` | `0.6` / `narration` / `4` | generic ratio masks stay translucent by default; an explicitly measured `--subtitle-y-top/--subtitle-y-bot` band defaults to opaque so source glyphs cannot show through. Set `SUBTITLE_MASK_OPACITY` to override; timing `all` restores full-time masking |
-| Original ducking | `IDLE_ORIG_VOLUME` / `SPEECH_DUCKING_VOLUME` | `1.0` / `0.2` | the original returns to full-volume `IDLE` in deliberate gaps/original blocks, and ducks to `SPEECH` under narration. Inter-beat gaps shorter than `DUCK_BRIDGE_SECONDS` stay ducked so a single narration block does not swell between sentences. `DUCKING_ORIG_VOLUME` (`0.3`) is only the fallback when beats carry no placement info |
+| Original ducking | `IDLE_ORIG_VOLUME` / `SPEECH_DUCKING_VOLUME` | `1.0` / `0.2` | the original returns to full-volume `IDLE` in deliberate gaps/original blocks, and ducks to `SPEECH` under narration. Inter-beat gaps shorter than `DUCK_BRIDGE_SECONDS` stay ducked so a single narration block does not swell between sentences. A fixed `0.3` is only the fallback when beats carry no placement info |
 | Foreign source audio | `FOREIGN_SOURCE_AUDIO` | off | set when the original audio is in a language the narration is **not** (e.g. a Japanese drama recapped in Chinese). The under-narration original (`SPEECH_DUCKING_VOLUME` / `ZONE_DUCKING_VOLUME`) drops from `0.2`/`0.12` to `0.05` so the foreign speech doesn't bleed under the narration as 怪音; original-audio gap blocks still play full-volume (`IDLE_ORIG_VOLUME`). Explicit `SPEECH_DUCKING_VOLUME`/`ZONE_DUCKING_VOLUME` still override. Pairs with bring-your-own `user_subtitles.*` for the foreign dialogue |
 | Duck fade | `DUCK_FADE_SECONDS` | `0.3` | attack ramp target. Sentence-safe source restore is shortened to fit wholly inside the measured acoustic pause (`pause_start`→anchor), so it never reveals the previous source sentence tail |
 | Duck bridge | `DUCK_BRIDGE_SECONDS` | `1.5` | inter-beat gaps shorter than this stay ducked inside one narration block; gaps >= this are treated as intentional original-audio blocks and return to `IDLE_ORIG_VOLUME` |
 | Background music | `BGM_PATH` / `BGM_VOLUME` / `BGM_DUCKING_VOLUME` | off / `0.18` / `0.10` | optional looped music bed mixed as its own track; point `BGM_PATH` at any audio file. It ducks to `BGM_DUCKING_VOLUME` under narration |
-| Final loudness | `FINAL_LOUDNORM` / `TARGET_LUFS` | `true` / `-14` | end-of-pipeline normalize |
-| Output compression | `OUTPUT_CRF` / `OUTPUT_PRESET` / `OUTPUT_MAX_HEIGHT` | `18` / `veryfast` / `0` | x264 re-encode controls, applied whenever the final mux re-encodes (burning subtitles / masking / scaling / `FORCE_VIDEO_REENCODE`). Higher `OUTPUT_CRF` = smaller file/lower quality (18≈visually lossless, 23–26 much smaller); `slow`/`slower` preset shrinks more at the same CRF; `OUTPUT_MAX_HEIGHT>0` downscales the final height (keeps aspect, even width), e.g. `720` to halve 1080p pixels. Subtitles/mask render at native res then downscale, so they stay crisp |
+| Final loudness | `FINAL_LOUDNORM` / `TARGET_LUFS` / `LOUDNESS_LIMITER_MAX_DB` | `true` / `-14` / `6` | end-of-pipeline two-pass normalize with one constant gain, never dynamically compressed; when the mix's true peak has no room for that gain an oversampled true-peak limiter takes up to `LOUDNESS_LIMITER_MAX_DB` of peak first, and only the gain beyond that lowers the target (`0` disables the limiter). The -1 dBTP ceiling holds for the delivered AAC file: the first render aims 0.5 dB under it, the encoded file is decoded and measured, and an overshoot re-encodes only the audio lower (at most twice; still over blocks with `delivered_true_peak_over_target`). `assembly_qc.json` records the mode ffmpeg actually ran (`loudness_mode`, `loudnorm_final_pass` incl. `peak_limiter` and the measured `delivered` file) |
+| Output compression | `OUTPUT_CRF` / `OUTPUT_PRESET` / `OUTPUT_MAX_HEIGHT` | `18` / `veryfast` / `0` | x264 re-encode controls, applied whenever the final mux re-encodes (burning subtitles / masking / scaling / `FORCE_VIDEO_REENCODE`, or a source picture that is not H.264 8-bit 4:2:0 with even dimensions; the delivery is always H.264 8-bit 4:2:0 with `+faststart`: `yuv420p`, or a full-range `yuvj420p` H.264 source copied unchanged; tagged BT.709 when the source is untagged or BT.709, keeping any other declared colour tags, and an RGB source (colour space `gbr` or an RGB/paletted pixel format) is converted to BT.709 limited range; multi-source cuts whose sources disagree convert every clip's matrix and range to BT.709 limited. Dub mode (`--edit-mode dub`) copies the source picture as is). Higher `OUTPUT_CRF` = smaller file/lower quality (18≈visually lossless, 23–26 much smaller); `slow`/`slower` preset shrinks more at the same CRF; `OUTPUT_MAX_HEIGHT>0` downscales the final height (keeps aspect, even width), e.g. `720` to halve 1080p pixels. Subtitles/mask render at native res then downscale, so they stay crisp |
 | Style | `--style` | `纪录片` | freeform verbatim guidance passed into the agent brief. The agent synthesizes voice/pacing from this exact text plus evidence; it is not a fixed option list, preset, switch, or finite style taxonomy |
 | Edit mode | `EDIT_MODE` / `--edit-mode` | `full` | `full`, `cut`, or `dub`; multi-source input supports `cut` only |
 | Cut target | `TARGET_DURATION` / `--target-duration` | — | e.g. `10m` (cut mode) |
@@ -56,7 +53,7 @@ Defaults below are bundle-level defaults unless a note scopes them to a specific
 | 剪映 export (optional) | `--export-jianying` / `EXPORT_JIANYING` | off | after rendering, also write a 剪映/JianYing draft from `timeline.json`. Decoupled — the core render never needs it |
 | 剪映 draft dir | `JIANYING_DRAFT_DIR` | work_dir | parent folder for the exported draft (point it at 剪映's drafts root to open in-app) |
 | 剪映 bundle media | `JIANYING_BUNDLE_MEDIA` / `--jianying-no-bundle-media` | **on** | copies video/audio/photo into `Resources/local/*`, uses draft-placeholder paths, and writes the type-0 material index in `draft_meta_info.json`. This makes a cloned/moved draft self-contained and is required on sandboxed macOS. Use `--jianying-no-bundle-media` only if 剪映 can reach the original paths |
-| Source video | `--source-video` | — | original video (cut mode) so `timeline.json` / 剪映 export reference the real source clips instead of the concatenated `edited_source.mp4`; direct `video-assemble` runs intentionally ignore ambient `SOURCE_VIDEO` unless `--source-video` is passed |
+| Source video | `--source-video` | — | original video (cut mode) so `timeline.json` / 剪映 export reference the real source clips instead of the concatenated `edited_source.mp4` |
 
 `video-assemble` always writes `timeline.json` — a backend-neutral multi-track model
 (video / original-audio / narration / BGM / subtitle, with ducking automation). The