@oh-story/dsh 0.1.12 → 0.1.13

package/lib/video-recap/skills/video-voiceover/scripts/dub.py

@@ -21,6 +21,7 @@ brittle and case-by-case. Two stages around an agent-authored pause:
 import argparse
 import base64
 import json
+import os
 import re
 import unicodedata
 import wave
@@ -35,13 +36,15 @@ from lib import (
     mimo_tts_api_call,
     run_cmd,
 )
+from tts_audio import implausible_tts_duration, rejected_take_hint, rejected_take_path
 
 CLONE_MODEL = "mimo-v2.5-tts-voiceclone"
 CLONE_SR = 24000  # mimo voiceclone returns 24kHz mono PCM16 wav
 DUB_DELIVERY_SR = 48000  # explicit delivery rate; loudnorm otherwise exposes its 96kHz internal rate
 ASR_MIME = "audio/wav"
 ATEMPO_CAP = 2.0  # max compression before we trim instead (atempo>2 also sounds rushed)
-DUB_FAST_SPEECH_CPS = 7.0
+DUB_TARGET_CPS = 5.0  # what the brief asks the translator for
+DUB_FAST_SPEECH_CPS = 7.0  # lint warns at or above this density
 DUB_TRIM_RISK_CPS = 7.0
 DUB_MIN_ASR_WINDOW_SECONDS = 0.5
 DUB_TTS_STYLE_PROMPT = "自然、清晰，保持原说话人的音色与节奏，语气平稳。"
@@ -50,41 +53,6 @@ DUB_SCHEMA_VERSION = 1
 # Tolerate ~1-frame rounding in agent-estimated timings so the gate blocks only GENUINE
 # errors, not rounding noise (the old render clamped such cases via min(slot_end, nxt)).
 DUB_TIMING_EPS = 0.05
-DUB_LINT_SCHEMA = {
-    "schema_version": DUB_SCHEMA_VERSION,
-    "artifact": "dub_lint.json",
-    "fields": {
-        "verdict": "PASS|FAIL",
-        "issues": "[{severity, code, line, message, start, end}]",
-        "summary": "{lines, errors, warnings, max_chars_per_second, trim_risk_lines}",
-    },
-}
-DUB_REVIEW_SCHEMA = {
-    "schema_version": DUB_SCHEMA_VERSION,
-    "artifact": "dub_review.json",
-    "fields": {
-        "verdict": "PASS|REVISE|FAIL",
-        "checks": "{faithful_to_source, spoken_chinese, speaker_tone, timing_fit, platform_fit}",
-        "highest_return_edits": "[{line, start, issue, suggestion}]",
-        "notes": "human/agent review notes; script-level output is deterministic pre-review guidance",
-    },
-}
-DUB_ARTIFACT_SCHEMAS = {
-    "dub_transcript.json": {
-        "schema_version": DUB_SCHEMA_VERSION,
-        "shape": {"video": "path", "duration": "seconds", "windows": [{"start": 0.0, "end": 6.0, "text": "English ASR"}]},
-    },
-    "dub_script.json": {
-        "schema_version": DUB_SCHEMA_VERSION,
-        "shape": [{"start": 0.0, "end": 2.4, "zh": "中文台词"}],
-    },
-    "dub_manifest.json": {
-        "schema_version": DUB_SCHEMA_VERSION,
-        "shape": {"video": "path", "duration": "seconds", "lines": [{"start": 0.0, "end": 2.4, "zh": "中文台词", "tts_cache": "hit|miss", "fitted_wav": "path", "fitted_dur": 1.8, "room": 2.4}]},
-    },
-    "dub_lint.json": DUB_LINT_SCHEMA,
-    "dub_review.json": DUB_REVIEW_SCHEMA,
-}
 
 
 def _chars_per_second(text, room):
@@ -205,37 +173,6 @@ def lint_dub_script(script, duration, work_dir=None):
     return report
 
 
-def build_dub_review(script, transcript, lint=None):
-    """Script-level review scaffold: deterministic timing/naturalness signals for agent review."""
-    duration = float(transcript["duration"])
-    lint = lint or lint_dub_script(script, duration)
-    lines = _normalize_dub_script(script) if isinstance(script, list) else []
-    edits = []
-    for issue in lint["issues"]:
-        if issue["severity"] in {"error", "warning"}:
-            edits.append({
-                "line": issue["line"],
-                "start": issue.get("start"),  # _issue only records start when the line had one
-                "issue": f"{issue['code']}: {issue['message']}",
-                "suggestion": "缩短译文、调整 start/end，或回到 transcript 核对原句边界。",
-            })
-    verdict = "FAIL" if lint["verdict"] == "FAIL" else ("REVISE" if edits else "PASS")
-    return {
-        "schema_version": DUB_SCHEMA_VERSION,
-        "verdict": verdict,
-        "checks": {
-            "faithful_to_source": "needs_agent_review",
-            "spoken_chinese": "REVISE" if any(i["code"] == "fast_speech" for i in lint["issues"]) else "PASS",
-            "speaker_tone": "needs_agent_review",
-            "timing_fit": verdict,
-            "platform_fit": "needs_agent_review",
-        },
-        "highest_return_edits": edits[:8],
-        "notes": "Deterministic script-level review; an agent/human should fill semantic fidelity and tone judgments against dub_transcript.json.",
-        "coverage": {"transcript_windows": len(transcript["windows"]), "script_lines": len(lines)},
-    }
-
-
 def _write_json(path, payload):
     Path(path).write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
     return path
@@ -362,6 +299,11 @@ def _clone_cache_meta_path(raw_wav):
     return raw_wav.with_name(f"{raw_wav.name}.meta.json")
 
 
+def _wav_seconds(path):
+    with wave.open(str(path), "rb") as w:
+        return w.getnframes() / w.getframerate()
+
+
 def _usable_clone_wav(path):
     try:
         sample_rate, channels, frames = _wav_frames(path)
@@ -376,6 +318,11 @@ def _write_clone_cache_meta(raw_wav, text, ref_identity):
 
 
 def _ensure_clone_tts(text, ref_b64, ref_identity, raw_wav):
+    """Reuse or synthesize one line's raw clone WAV; returns True on a cache hit.
+
+    A take far longer than reading `text` (the line plus invented speech) is the same failure
+    voiceover rejects: retried up to TTS_RETRIES times and never cached or time-fitted; the
+    latest such take is kept as `<name>.rejected.wav` for listening."""
     raw_wav = Path(raw_wav)
     expected = _clone_cache_inputs(text, ref_identity)
     meta_path = _clone_cache_meta_path(raw_wav)
@@ -385,13 +332,32 @@ def _ensure_clone_tts(text, ref_b64, ref_identity, raw_wav):
         meta = json.loads(meta_path.read_text(encoding="utf-8"))
         # A meta from the content-hash schema has no "inputs" and is simply a miss.
         if meta.get("inputs") == expected and _usable_clone_wav(raw_wav):
-            return True
-
-    _clone_tts(text, ref_b64, raw_wav)
-    if not _usable_clone_wav(raw_wav):
-        raise RuntimeError(f"MiMo voiceclone returned an invalid WAV: {raw_wav}")
-    _write_clone_cache_meta(raw_wav, text, ref_identity)
-    return False
+            implausible = implausible_tts_duration(text, _wav_seconds(raw_wav))
+            if not implausible:
+                return True
+            # Cached before this bound existed: re-synthesize instead of fitting it every rerun.
+            log(f"  {raw_wav.name}: 不复用缓存，重新合成：{implausible}")
+
+    rejected = rejected_take_path(raw_wav)
+    rejected.unlink(missing_ok=True)
+    retries = CONFIG["tts_retries"]
+    implausible = None
+    for attempt in range(1, retries + 1):
+        meta_path.unlink(missing_ok=True)  # never leave a sidecar vouching for an unchecked take
+        _clone_tts(text, ref_b64, raw_wav)
+        if not _usable_clone_wav(raw_wav):
+            raise RuntimeError(f"MiMo voiceclone returned an invalid WAV: {raw_wav}")
+        implausible = implausible_tts_duration(text, _wav_seconds(raw_wav))
+        if not implausible:
+            rejected.unlink(missing_ok=True)
+            _write_clone_cache_meta(raw_wav, text, ref_identity)
+            return False
+        os.replace(raw_wav, rejected)
+        if attempt < retries:
+            log(f"  {raw_wav.name}: voiceclone 重试 {attempt + 1}/{retries}: {implausible}")
+    raise RuntimeError(
+        f"MiMo voiceclone 合成失败（«{text[:18]}»）: {implausible}{rejected_take_hint(rejected)}"
+    )
 
 
 def _time_fit(raw_wav, fitted_wav, room_seconds):
@@ -432,11 +398,15 @@ def _build_dub_track(lines, duration, out_wav):
 
 
 def _mux(video, dub_wav, out_video):
+    # The picture is stream-copied as the source has it (no yuv420p / colour-tag
+    # normalisation in dub mode); +faststart is copy-safe and lets web players start early.
+    # The source's container/stream tags (a scraper's title, comment or URL, the original
+    # audio language) and chapters are not carried into the dubbed deliverable.
     _ffmpeg(["-i", str(video), "-i", str(dub_wav),
              "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy",
              "-af", "loudnorm=I=-16:TP=-1.5:LRA=11", "-c:a", "aac", "-b:a", "192k",
-             "-ar", str(DUB_DELIVERY_SR),
-             "-shortest", str(out_video)])
+             "-ar", str(DUB_DELIVERY_SR), "-map_metadata", "-1", "-map_chapters", "-1",
+             "-shortest", "-movflags", "+faststart", str(out_video)])
 
 
 # ── stages ───────────────────────────────────────────────────────────
@@ -446,7 +416,7 @@ def _ref_window(duration, ref_start, ref_dur):
     return start, max(2.0, min(ref_dur, duration - start))
 
 
-def stage_prepare(video, work, asr_window, ref_start, ref_dur):
+def stage_prepare(video, work, asr_window=6.0, ref_start=2.0, ref_dur=10.0):
     work.mkdir(parents=True, exist_ok=True)
     segs_dir = work / "dub_asr"
     segs_dir.mkdir(exist_ok=True)
@@ -484,7 +454,8 @@ def _brief_md(windows, duration):
         "原声重复，配音也跟着重复。",
         "2. 每句放在它在原声里被说出的时间，`start`/`end` 取那句话的起止——这样配音才跟着原声节奏走"
         "（该停顿处自然留白）。",
-        "3. 译文忠实精简，能在自己的 `start`→`end` 区间内用正常语速说完（约 5 字/秒）。",
+        f"3. 译文忠实精简，能在自己的 `start`→`end` 区间内用正常语速说完（目标约 {DUB_TARGET_CPS:g} 字/秒；"
+        f"达到 {DUB_FAST_SPEECH_CPS:g} 字/秒 lint 会警告，渲染时可能被大幅加速或截断）。",
         "4. 只有完全被截断、没法说完整的残句，才取其中说得完整的部分。",
         "",
         "输出 `dub_script.json` = `[{\"start\": 起秒, \"end\": 止秒, \"zh\": \"中文台词\"}, ...]`，按 start "
@@ -500,16 +471,13 @@ def _brief_md(windows, duration):
     return "\n".join(lines) + "\n"
 
 
-def stage_render(video, work, ref_start, ref_dur):
+def stage_render(video, work, ref_start=2.0, ref_dur=10.0):
     transcript = json.loads((work / "dub_transcript.json").read_text(encoding="utf-8"))
     duration = transcript["duration"]
     script = json.loads((work / "dub_script.json").read_text(encoding="utf-8"))
     # Mechanical hard gate BEFORE any voiceclone spend: empty/overlapping/out-of-range lines
     # cannot produce a publishable dub, so fail fast instead of paying for a broken render.
-    lint = lint_dub_script(script, duration)
-    _write_json(work / "dub_lint.json", lint)
-    review = build_dub_review(script, transcript, lint)
-    _write_json(work / "dub_review.json", review)
+    lint = lint_dub_script(script, duration, work_dir=work)
     if lint["verdict"] != "PASS":
         raise SystemExit(f"[dub] dub_script.json failed lint; see {work / 'dub_lint.json'}")
     lines = [{"start": ln["start"], "end": ln["end"], "zh": ln["zh"]}
@@ -556,67 +524,24 @@ def stage_render(video, work, ref_start, ref_dur):
                      ensure_ascii=False))
 
 
-def stage_lint(work):
-    transcript = json.loads((work / "dub_transcript.json").read_text(encoding="utf-8"))
-    script = json.loads((work / "dub_script.json").read_text(encoding="utf-8"))
-    lint = lint_dub_script(script, transcript["duration"])
-    path = _write_json(work / "dub_lint.json", lint)
-    print(json.dumps({"status": "dub_linted", "verdict": lint["verdict"], "issues": len(lint["issues"]), "dub_lint": str(path)}, ensure_ascii=False))
-    return lint
-
-
-def stage_review(work):
-    transcript = json.loads((work / "dub_transcript.json").read_text(encoding="utf-8"))
-    script = json.loads((work / "dub_script.json").read_text(encoding="utf-8"))
-    lint = lint_dub_script(script, transcript["duration"])
-    _write_json(work / "dub_lint.json", lint)
-    review = build_dub_review(script, transcript, lint)
-    path = _write_json(work / "dub_review.json", review)
-    print(json.dumps({"status": "dub_reviewed", "verdict": review["verdict"], "edits": len(review["highest_return_edits"]), "dub_review": str(path)}, ensure_ascii=False))
-    return review
-
-
-def print_schemas():
-    print(json.dumps(DUB_ARTIFACT_SCHEMAS, ensure_ascii=False, indent=2))
-
-
 def main():
     ap = argparse.ArgumentParser(
         description=(
-            "English→Chinese dub workflow. Artifacts: dub_transcript.json, "
-            "agent-authored dub_script.json, dub_lint.json, dub_review.json, dub_manifest.json. "
+            "English→Chinese dub workflow, run by recap.py --edit-mode dub. Artifacts: "
+            "dub_transcript.json, agent-authored dub_script.json, dub_lint.json, dub_manifest.json. "
             "Uses MiMo ASR plus mimo-v2.5-tts-voiceclone; ordinary narration TTS config is separate."
         )
     )
-    ap.add_argument("--stage", choices=["prepare", "lint", "review", "render"], required=False,
-                    help="prepare ASR brief; lint/review dub_script.json; render writes lint/review before voiceclone")
-    ap.add_argument("--video", required=False, help="source video (required for prepare/render)")
-    ap.add_argument("--work-dir", required=False, help="work directory containing dub artifacts")
-    ap.add_argument("--asr-window", type=float, default=6.0)
-    ap.add_argument("--ref-start", type=float, default=2.0)
-    ap.add_argument("--ref-dur", type=float, default=10.0)
-    ap.add_argument("--print-schema", action="store_true",
-                    help="print JSON schemas for dub_transcript/script/lint/review/manifest and exit")
+    ap.add_argument("--stage", choices=["prepare", "render"], required=True,
+                    help="prepare writes the ASR brief; render lints dub_script.json before voiceclone")
+    ap.add_argument("--video", required=True, help="source video")
+    ap.add_argument("--work-dir", required=True, help="work directory containing dub artifacts")
     args = ap.parse_args()
-    if args.print_schema:
-        print_schemas()
-        return
-    if not args.stage:
-        ap.error("--stage is required unless --print-schema is used")
-    if not args.work_dir:
-        ap.error("--work-dir is required")
-    work = Path(args.work_dir)
-    if args.stage in {"prepare", "render"} and not args.video:
-        ap.error("--video is required for prepare/render")
-    video = Path(args.video) if args.video else None
+    video, work = Path(args.video), Path(args.work_dir)
     if args.stage == "prepare":
-        stage_prepare(video, work, args.asr_window, args.ref_start, args.ref_dur)
-    elif args.stage == "lint":
-        stage_lint(work)
-    elif args.stage == "review":
-        stage_review(work)
+        stage_prepare(video, work)
     else:
-        stage_render(video, work, args.ref_start, args.ref_dur)
+        stage_render(video, work)
 
 
 if __name__ == "__main__":

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

@@ -120,10 +120,7 @@ CONFIG = {
     "mimo_tts_model": os.environ.get("MIMO_TTS_MODEL", DEFAULT_MIMO_TTS_MODEL),
     "mimo_tts_voice": os.environ.get("MIMO_TTS_VOICE", "冰糖"),
     "voice_ref": os.environ.get("VOICE_REF", "").strip(),  # optional arbitrary reference audio for narration voice clone
-    "mimo_tts_style": os.environ.get(
-        "MIMO_TTS_STYLE",
-        "自然、清晰、有感染力，像在给观众讲故事；随剧情起伏，该紧张时紧张、该动情时动情，不平铺直叙。",
-    ),
+    "mimo_tts_style": "自然、清晰、有感染力，像在给观众讲故事；随剧情起伏，该紧张时紧张、该动情时动情，不平铺直叙。",
     "tts_provider": os.environ.get("TTS_PROVIDER", "auto").strip().lower(),
     "tts_timeout": env_int("TTS_TIMEOUT", 300, minimum=1),
     "fish_api_key": os.environ.get("FISH_API_KEY", ""),
@@ -135,16 +132,17 @@ CONFIG = {
     "mimo_disable_thinking": env_bool("MIMO_DISABLE_THINKING", True),
     "breath_ms": 250,  # 段间呼吸空间(ms)；block recap 块内连贯、块间留原声呼吸
     "narration_speed": env_float("NARRATION_SPEED", 1.15, minimum=0.5),  # 解说整体提速(atempo)，默认回到可懂区间；长片可设 1.0
-    "narration_cumulative_tempo_max": env_float("NARRATION_CUMULATIVE_TEMPO_MAX", 1.35, minimum=1.0),  # TTS rate × 全局 atempo × 段内 atempo 的累计上限
-    "narration_cumulative_tempo_hard_max": env_float("NARRATION_CUMULATIVE_TEMPO_HARD_MAX", 1.40, minimum=1.0),  # QC/阻断硬上限
-    "tts_segment_tempo_max": env_float("TTS_SEGMENT_TEMPO_MAX", 1.20, minimum=1.0),  # 兼容旧段内 atempo 上限；实际会被累计预算收紧
-    "tts_dynamic_params": True,  # 启用动态语速调节
+    "narration_cumulative_tempo_max": 1.35,  # TTS rate × 全局 atempo × 段内 atempo 的累计上限
+    "narration_cumulative_tempo_hard_max": 1.40,  # QC/阻断硬上限
+    "tts_segment_tempo_max": 1.20,  # 兼容旧段内 atempo 上限；实际会被累计预算收紧
     "tts_workers": env_int("TTS_WORKERS", 4, minimum=1),  # TTS 并行合成线程数
     "tts_retries": env_int("TTS_RETRIES", 3, minimum=1),  # 单段 TTS 失败重试次数
+    # 段音频时长合理性下限语速（字/秒，拉丁词按 1.5）：比它还慢说明 TTS 多读了内容，按失败重试；0 关闭
+    "tts_min_speech_rate": env_float("TTS_MIN_SPEECH_RATE", 2.5, minimum=0.0),
     "allow_partial_tts": env_bool("ALLOW_PARTIAL_TTS", False),
-    "tts_segment_normalize": env_bool("TTS_SEGMENT_NORMALIZE", True),  # 单段 TTS RMS 归一，降低段间忽大忽小
-    "tts_segment_target_rms_dbfs": env_float("TTS_SEGMENT_TARGET_RMS_DBFS", -20.0),
-    "tts_segment_peak_limit": env_float("TTS_SEGMENT_PEAK_LIMIT", 0.98, minimum=0.1),
+    "tts_segment_normalize": True,  # 单段 TTS RMS 归一，降低段间忽大忽小
+    "tts_segment_target_rms_dbfs": -20.0,
+    "tts_segment_peak_limit": 0.98,
 }
 
 
@@ -327,26 +325,3 @@ def api_call(payload, *, api_url, api_key, api_env_var, max_retries=8):
                 raise RuntimeError(f"API 调用失败 {max_retries} 次: {safe_error}")
 
 
-def _text_char_count(text):
-    """计算文本的有效字数（去除标点和空白，这些不占 TTS 朗读时间）。"""
-    return len(re.sub(r'[，。！？、；：…“”‘’《》〈〉\s"\'「」『』（）()【】\[\]—～·,.!?;:\\-]', '', text))
-
-
-def _truncate_at_sentence(text, max_chars):
-    """在句子边界截断，不产生残句。max_chars 按有效字符计（不含标点空白）。"""
-    if _text_char_count(text) <= max_chars:
-        return text
-    eff = 0
-    cutoff = len(text)
-    for i, ch in enumerate(text):
-        eff += 1 if _text_char_count(ch) else 0
-        if eff > max_chars:
-            cutoff = i + 1
-            break
-    idx = max(text[:cutoff].rfind(sep) for sep in ['。', '！', '？', '!', '?'])
-    if idx > 0:
-        return text[:idx + 1]
-    idx = max(text[:cutoff].rfind(sep) for sep in ['，', '、', '；', ','])
-    if idx > 3:
-        return text[:idx] + '。'
-    return ""

package/lib/video-recap/skills/video-voiceover/scripts/providers/fish_audio.py

@@ -13,13 +13,18 @@ from pathlib import Path
 from lib import CONFIG, _sanitize_api_error
 
 
+def fish_speed(rate):
+    """The numeric prosody speed Fish Audio receives for a '+5%'-style rate."""
+    return 1.0 + float(rate.rstrip("%")) / 100.0
+
+
 def _fish_payload(text, rate):
     payload = {
         "text": text,
         "format": "wav",
         "normalize": True,
         "prosody": {
-            "speed": 1.0 + float(rate.rstrip("%")) / 100.0,
+            "speed": fish_speed(rate),
             "volume": 0,
             "normalize_loudness": True,
         },

package/lib/video-recap/skills/video-voiceover/scripts/tts_audio.py

@@ -1,4 +1,4 @@
-"""Loudness normalization for synthesized TTS blocks.
+"""Loudness normalization and a duration sanity bound for synthesized TTS blocks.
 
 Split out of voiceover.py to keep that module within the bundle's per-module line
 budget. Dependency-free on purpose (stdlib `wave` + `array` only) so QC and assembly
@@ -7,6 +7,7 @@ can reuse the returned metadata without pulling in the synthesis path.
 import array
 import math
 import os
+import re
 import sys
 import wave
 from pathlib import Path
@@ -100,3 +101,65 @@ def _maybe_normalize_tts_wav(output_wav):
     )
     os.replace(tmp, output_wav)
     return meta
+
+
+# Speech units for the duration bound: a CJK character or a digit (half or full width, read
+# one by one as in 二〇二六) is one syllable, "%" is three (百分之), a Latin word about one and
+# a half. Pause marks get a fixed allowance each; "……" is a long pause.
+_CJK_OR_DIGIT = re.compile(r"[\u3007\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff0-9\uff10-\uff19]")
+_PERCENT = re.compile(r"[%\uff05]")
+_PERCENT_UNITS = 3
+_LATIN_WORD = re.compile(r"[A-Za-z]+(?:'[A-Za-z]+)?")
+_LONG_PAUSE = re.compile(r"……|\.\.\.|——")
+_PAUSE_MARK = re.compile(r"[，。！？；：、,.!?;:]")
+TTS_EDGE_SILENCE_SECONDS = 1.5
+TTS_PAUSE_SECONDS = 0.4
+TTS_LONG_PAUSE_SECONDS = 0.8
+
+
+def speech_units(text):
+    """Syllable-like units a faithful reading of `text` speaks (pauses not included)."""
+    rest = _LONG_PAUSE.sub("", text)
+    return (len(_CJK_OR_DIGIT.findall(rest)) + _PERCENT_UNITS * len(_PERCENT.findall(rest))
+            + 1.5 * len(_LATIN_WORD.findall(rest)))
+
+
+def max_plausible_tts_seconds(text):
+    """Longest a faithful reading of `text` can last, or None when the bound is disabled.
+
+    Reading every unit at TTS_MIN_SPEECH_RATE (default 2.5 units/s; MiMo's median is ~3.5
+    CJK chars/s) plus generous pause and edge-silence allowances. Audio past this is the
+    provider reading more than the text: MiMo TTS has returned a sentence followed by
+    invented speech at 1.17x this bound, while the slowest of ~100 faithful MiMo segments
+    from real runs reached 0.86x."""
+    min_rate = CONFIG["tts_min_speech_rate"]
+    if min_rate <= 0:
+        return None
+    long_pauses = len(_LONG_PAUSE.findall(text))
+    rest = _LONG_PAUSE.sub("", text)
+    return (TTS_EDGE_SILENCE_SECONDS + speech_units(text) / min_rate
+            + TTS_PAUSE_SECONDS * len(_PAUSE_MARK.findall(rest))
+            + TTS_LONG_PAUSE_SECONDS * long_pauses)
+
+
+def implausible_tts_duration(text, duration):
+    """A user-facing reason when `duration` is too long to be a reading of `text`, else None."""
+    limit = max_plausible_tts_seconds(text)
+    if limit is None or duration <= limit:
+        return None
+    return (f"音频 {duration:.1f}s 超过这段文字（{len(text)} 字）的合理上限 {limit:.1f}s，"
+            "疑似 TTS 多读了原稿以外的内容（幻读），这段音频不会被缓存或交付")
+
+
+def rejected_take_path(output_wav):
+    """Where the latest take rejected by the bound is kept for listening."""
+    output_wav = Path(output_wav)
+    return output_wav.with_name(f"{output_wav.stem}.rejected{output_wav.suffix}")
+
+
+def rejected_take_hint(rejected):
+    """Where the last rejected take is, and how to accept such takes; empty when none was kept."""
+    if not Path(rejected).is_file():
+        return ""
+    return (f"；最后一次被拒的音频保留在 {rejected}，试听确认确实只读了原稿时，"
+            "可调低 TTS_MIN_SPEECH_RATE（0 关闭检查）后重跑")

package/lib/video-recap/skills/video-voiceover/scripts/tts_cache.py

@@ -0,0 +1,99 @@
+"""Content-addressed store for synthesized narration blocks.
+
+A block's audio depends on its text and synthesis settings, never on where the block sits in
+narration.json. Entries live in `tts_segments/cache/<digest>.wav` next to a `<digest>.json`
+sidecar recording the exact inputs, the stored WAV's `{size, mtime_ns}` and the facts the
+rerun needs (spoken text, duration, normalization, provider receipt). The index-named
+`narr_NNN.wav` files that tts_meta.json and assemble read are views of an entry: a hard link,
+or a copy where the filesystem has no links. Deleting or inserting a block therefore only
+re-synthesizes the blocks whose own inputs changed.
+"""
+import hashlib
+import json
+import os
+import shutil
+import threading
+from pathlib import Path
+
+from approved_text_policy import write_json_atomically
+from lib import file_identity
+
+CACHE_DIR_NAME = "cache"
+_RECORD_KEYS = ("spoken_text", "audio_duration", "normalization", "provider_receipt")
+
+
+def cache_entry(tts_dir, cache_inputs):
+    """(stored WAV, sidecar) paths for one set of synthesis inputs."""
+    blob = json.dumps(cache_inputs, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+    digest = hashlib.sha256(blob.encode("utf-8")).hexdigest()[:32]
+    base = Path(tts_dir) / CACHE_DIR_NAME
+    return base / f"{digest}.wav", base / f"{digest}.json"
+
+
+def legacy_sidecar_path(output_wav):
+    """The per-index sidecar earlier versions wrote; never read (its keys differ), only removed."""
+    return Path(str(output_wav) + ".cache.json")
+
+
+def load(tts_dir, cache_inputs):
+    """The stored record for these inputs, or None when absent or its WAV changed since."""
+    stored_wav, sidecar = cache_entry(tts_dir, cache_inputs)
+    if not sidecar.exists():
+        return None
+    # This skill wrote the sidecar: one it cannot parse is a bug to surface, not a silent miss
+    # that re-bills the provider.
+    try:
+        data = json.loads(sidecar.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        raise RuntimeError(f"TTS 缓存 sidecar 损坏: {sidecar}") from exc
+    if not isinstance(data, dict) or data.get("settings") != cache_inputs:
+        return None
+    if not stored_wav.is_file() or stored_wav.stat().st_size == 0:
+        return None
+    return data if data.get("audio") == file_identity(stored_wav) else None
+
+
+def store(output_wav, cache_inputs, record):
+    """Publish a finished block WAV under its inputs; returns the sidecar payload."""
+    stored_wav, sidecar = cache_entry(Path(output_wav).parent, cache_inputs)
+    stored_wav.parent.mkdir(exist_ok=True)
+    tmp = _tmp_path(stored_wav)
+    _link_or_copy(output_wav, tmp)
+    # Identity of exactly the bytes being published: if a concurrent worker replaces the entry
+    # with another take of the same inputs, the sidecars disagree with the WAV and miss safely.
+    identity = file_identity(tmp)
+    os.replace(tmp, stored_wav)
+    data = {"settings": cache_inputs, "audio": identity,
+            **{key: record.get(key) for key in _RECORD_KEYS}}
+    write_json_atomically(sidecar, data)
+    return data
+
+
+def materialize(tts_dir, cache_inputs, output_wav):
+    """Point the index-named `output_wav` at the stored WAV for these inputs."""
+    stored_wav, _sidecar = cache_entry(tts_dir, cache_inputs)
+    output_wav = Path(output_wav)
+    if output_wav.exists():
+        try:
+            if os.path.samefile(stored_wav, output_wav):
+                return
+        except OSError:
+            pass
+    # Anything else is re-linked (or re-copied): {size, mtime_ns} cannot tell two takes of the
+    # same length apart when they were written within one timestamp tick, and a stale slot
+    # would silently play the wrong block.
+    tmp = _tmp_path(output_wav)
+    _link_or_copy(stored_wav, tmp)
+    os.replace(tmp, output_wav)
+
+
+def _tmp_path(path):
+    return path.with_name(f".{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+
+
+def _link_or_copy(source, destination):
+    destination.unlink(missing_ok=True)
+    try:
+        os.link(source, destination)
+    except OSError:
+        shutil.copy2(source, destination)