@lemoncat7/dsh-partner 2.8.1 → 2.8.2

package/resources/skills/video-recap-production/upstream/skills/video-voiceover/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: video-voiceover
+user-invocable: false
+description: >
+ 把带时间戳的 narration.json 合成为中文解说音频。使用 MiMo TTS（mimo-v2.5-tts）或
+ Fish Audio（s2.1-pro-free）或显式配置的通用 IndexTTS HTTP 服务逐段生成语音，
+ 按时间窗动态适配语速并处理响度；输入输出时间线上的旁白，产出 tts_segments 与 tts_meta.json。
+ 触发词：配音、语音合成、TTS、解说配音、
+ voiceover、text to speech、旁白配音。
+---
+
+## 1. 定位
+
+本技能读取带时间戳的旁白稿，为每一段生成独立音频，并把语音适配到对应时间窗，随后记录下游合成所需的放置元数据。
+默认引擎是 MiMo TTS（`mimo-v2.5-tts`）；也可显式选择 Fish Audio（默认模型 `s2.1-pro-free`）。
+
+## 2. 环境要求
+
+```bash
+export MIMO_API_KEY=***  # 也可使用仅供 TTS 的 MIMO_TTS_API_KEY
+
+# 或改用 Fish Audio TTS
+export TTS_PROVIDER=fish-audio
+export FISH_API_KEY=***
+export FISH_TTS_REFERENCE_ID=<voice-model-id>  # 可选；覆盖内置“娱乐扒妹”音色
+
+# 或显式选择自托管 index-tts 端点，配置见 references/index-tts.md
+export TTS_PROVIDER=index-tts
+```
+
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
+
+## 3. 输入契约
+
+默认输入为 `work_dir/narration.json`。每段必须包含 `start`、`end` 与 `narration`，可选字段包括
+`pause_after_ms` 和 `overlaps_speech`。时间统一表示音频最终放置的**输出时间线秒数**。
+
+cut 流程先剪后配：`narration.json` 本身就是按剪后成片的输出时间写的，不存在另一份映射稿。
+
+## 4. 运行命令
+
+```bash
+python3 scripts/voiceover.py --work-dir <work_dir> --narration <narration.json> \
+  [--tts-provider auto|mimo-tts|fish-audio|index-tts] \
+  [--mimo-voice 冰糖 | --voice-ref <reference-audio>] \
+  [--preserve-approved-text]
+```
+
+单独运行且省略 `--narration` 时，默认读取 `work_dir/narration.json`；`--narration` 只用于指定其他路径的同格式稿件。
+
+## 5. 输出契约
+
+- `tts_segments/*.wav`：每段旁白对应一个音频文件。
+- `tts_meta.json`：包含 `segments`、`engine`、`voice`（实际使用的 provider、模型、音色或参考音频）与 `narration`。每段记录 `audio_path`、时间、
+  `pause_after_ms` 和放置字段。
+- 干净运行写入 `partial: false` 与 `failures: []`。
+- 使用 `--allow-partial-tts` 跳过失败段时，写入 `partial: true` 和
+  `failures: [{index,start,end,text,error}]`，让缺失语音保持可见。
+- `--preserve-approved-text` 是显式的批准稿保护策略。每段保留原始 `authored_text`
+  证据；TTS 实际读取的 `spoken_text` 只经过既有的格式/舞台提示清理。若完整语音超过时间窗及
+  累计语速预算，命令失败并报告段序号、原稿、实读文本、语音时长和窗口证据，不写成功的
+  `tts_meta.json`。严格模式下任何必需段失败（包括供应商失败）都不能被
+  `--allow-partial-tts` 降级为可交付的部分成功；异常记录标为 `required: true` 并带策略 ID。
+  仅含 `[停顿]` 等清理标记、清理后无实读文本的作者段也属于必需段错误。
+
+## 6. 运行规则
+
+- 重跑只复用分段 sidecar 中记录的文本、TTS 设置与该 WAV 的 `size`/`mtime_ns` 均与当前相等的分段音频；
+  修改旁白或合成参数后，只重生成受影响的 WAV。
+- 批准稿保护策略属于缓存设置：严格模式不会命中旧的自动缩稿缓存；只有同一严格策略下、
+  `spoken_text` 完整匹配且 WAV 存在非空的缓存才可离线复用。
+- 严格 CLI 在本轮合成前把旧 `tts_meta.json` 按时间戳归档至 `tts_meta.history/`，因此失败时
+  当前路径不会继续冒充本轮成功；成功元数据通过同目录临时文件原子替换。
+- `auto` 优先使用已配置的 MiMo，MiMo key 缺失且设置了 `FISH_API_KEY` 时使用 Fish Audio；需要可复现的 provider 选择时显式传 `--tts-provider`。
+- 自托管 index-tts 端点只能由 `--tts-provider index-tts` 或 `TTS_PROVIDER=index-tts` 显式选择，`auto`
+  永不兜底选择它。协议、请求体、receipt 语义与缓存失效规则见 `references/index-tts.md`。
+- Fish Audio 直接请求 WAV；默认使用“娱乐扒妹”音色（`5653cea4ac83480aaf2bf45406556185`），`FISH_TTS_REFERENCE_ID` 可覆盖。模型、音色 ID、API URL、动态语速或归一化设置变化时会重新生成缓存。当前免费模型无 SLA，受 Fair Use 和官方免费期限约束。
+- `--voice-ref` 仅用于 full/cut 解说克隆，切换到 `mimo-v2.5-tts-voiceclone`。仅在确需新合成时惰性规范化一次；
+- dub voiceclone 原始 WAV 也会按模型、提示、台词和参考音频的 `size`/`mtime_ns` 缓存；匹配重跑不再重复请求或计费，`dub_manifest.json` 逐行记录 `tts_cache=hit|miss`；
+  参考音频文件变化会使旧缓存失效。仅在获得授权后使用，参考音频会发送到 MiMo。
+- `TTS_WORKERS`、`TTS_TIMEOUT`、`TTS_RETRIES`、`ALLOW_PARTIAL_TTS` 用于调整并发、超时、重试与部分成功策略。
+- dub 模式有独立的确定性门禁：`dub_lint.json` 会在语音克隆前阻止空行、重叠或越界译文；
+  `dub_review.json` 用于记录忠实度、语气、时长和平台适配复核。可通过
+  `dub.py --stage lint|review` 或 `dub.py --print-schema` 单独调用。
+
+## 7. 能力边界
+
+- 超窗时默认在句界自动缩稿并在 `spoken_text/truncated` 留痕；批准稿加 `--preserve-approved-text`。
+- 不混流、不压低原声、不渲染字幕。
+- 不分析视频，也不选择时间点；只为输入稿件中的既定分段配音。
+- Fish Audio 与 IndexTTS 路径都不接受本地 `--voice-ref`；前者用已创建的 `FISH_TTS_REFERENCE_ID` 选择音色。

package/resources/skills/video-recap-production/upstream/skills/video-voiceover/references/index-tts.md

@@ -0,0 +1,31 @@
+# 自托管 IndexTTS 端点
+
+`--tts-provider index-tts` 或 `TTS_PROVIDER=index-tts` 显式选择自托管的 index-tts 协议服务（JSON→WAV）。
+`auto` 永不兜底选择它。
+
+## 配置
+
+```bash
+export TTS_PROVIDER=index-tts
+export INDEX_TTS_ENDPOINT=http://127.0.0.1:<port>/tts
+export INDEX_TTS_VOICE=<authorized-voice-name>
+```
+
+- 缺 `INDEX_TTS_ENDPOINT` 或 `INDEX_TTS_VOICE` 时在缓存/请求前失败。
+- endpoint 只接受无 userinfo/query/fragment 的 HTTP(S) URL，且请求禁止重定向，避免把批准文本转发至其他主机。
+- 不接受 `--voice-ref` / `--mimo-voice`。
+
+## 请求契约
+
+请求体固定为 `{"voice": voice, "text": spoken_text}`。当前段 schema 的可选 `emotion`
+以及额外 style、非默认 rate/pitch 控制会显式失败，不会静默忽略。原始合成使用 provider 默认速度，
+不按标点、长度或位置自动计算 rate；这不等于下游放置阶段的端到端 tempo 锁。
+
+## Receipt 与缓存
+
+每段的 `provider_receipt` 只记录 `provider` 与“请求的 voice”（`requested_voice`）。它说明请求参数，
+不是该声线的声学验证，也不代表已做人耳听审或音色身份验证。endpoint 不写入任何文件。
+
+缓存复用条件：sidecar 中的文本与设置（含 `index_tts_voice`）与当前相等、WAV 的 `size`/`mtime_ns` 未变，
+且 sidecar 的 receipt 对应当前 voice；缓存命中复用 sidecar 中的 receipt，不能现场补造。
+服务端模型或部署变化不会被自动察觉；更换声线实现后请删除 `tts_segments/*.cache.json` 强制重合成。

package/resources/skills/video-recap-production/upstream/skills/video-voiceover/scripts/approved_text_policy.py

@@ -0,0 +1,123 @@
+"""Fail-closed approved narration policy and current-metadata lifecycle helpers."""
+
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+LEGACY_TEXT_POLICY = "legacy-auto-truncate-v1"
+PRESERVE_APPROVED_TEXT_POLICY = "preserve-approved-text-v1"
+
+
+class ApprovedTextPolicyError(RuntimeError):
+    def __init__(self, message, evidence):
+        self.evidence = evidence
+        super().__init__(
+            f"{message}: " + json.dumps(evidence, ensure_ascii=False, sort_keys=True)
+        )
+
+
+class ApprovedTextDurationError(ApprovedTextPolicyError):
+    """Approved narration cannot fit its authored window without changing text."""
+
+    def __init__(self, evidence):
+        super().__init__(
+            "批准旁白无法在不删改文本的前提下安全放入时间窗；请扩大窗口或由作者修订文本",
+            evidence,
+        )
+
+
+def policy_name(preserve_approved_text):
+    if preserve_approved_text:
+        return PRESERVE_APPROVED_TEXT_POLICY
+    return LEGACY_TEXT_POLICY
+
+
+def validate_required_texts(narration, clean_text, preserve_approved_text):
+    """Reject authored segments whose provider-cleaned spoken text is empty."""
+    if not preserve_approved_text:
+        return
+    for index, segment in enumerate(narration):
+        spoken_text = clean_text(segment["narration"])
+        if spoken_text:
+            continue
+        evidence = {
+            "failure_kind": "approved_text_empty_after_cleanup",
+            "policy": PRESERVE_APPROVED_TEXT_POLICY,
+            "required": True,
+            "index": index,
+            "segment": index + 1,
+            "authored_text": segment["narration"],
+            "spoken_text": spoken_text,
+            "window_start": segment["start"],
+            "window_end": segment["end"],
+        }
+        raise ApprovedTextPolicyError(
+            "批准稿必需段经显式格式/舞台提示清理后没有可合成文本；请修订或删除该作者段",
+            evidence,
+        )
+
+
+def enforce_duration(index, segment, authored_text, spoken_text, audio_duration,
+                     available_duration, max_raw_duration, preserve_approved_text,
+                     default_pause_ms):
+    if not preserve_approved_text or audio_duration <= max_raw_duration:
+        return
+    evidence = {
+        "failure_kind": "approved_text_duration_conflict",
+        "policy": PRESERVE_APPROVED_TEXT_POLICY,
+        "index": index,
+        "segment": index + 1,
+        "authored_text": authored_text,
+        "spoken_text": spoken_text,
+        "audio_duration": round(audio_duration, 6),
+        "window_start": segment["start"],
+        "window_end": segment["end"],
+        "window_duration": round(segment["end"] - segment["start"], 6),
+        "pause_after_ms": segment.get("pause_after_ms", default_pause_ms),
+        "available_duration": round(available_duration, 6),
+        "max_raw_duration": round(max_raw_duration, 6),
+    }
+    raise ApprovedTextDurationError(evidence)
+
+
+def archive_current_meta(meta_path):
+    """Atomically move a current meta file into timestamp-named history."""
+    path = Path(meta_path)
+    if not path.is_file():
+        return None
+    history_dir = path.parent / "tts_meta.history"
+    history_dir.mkdir(exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ")
+    archived = history_dir / f"{stamp}.json"
+    counter = 0
+    while archived.exists():
+        counter += 1
+        archived = history_dir / f"{stamp}-{counter}.json"
+    os.replace(path, archived)
+    return archived
+
+
+def write_json_atomically(path, payload):
+    """Replace JSON only after a complete same-directory write and fsync."""
+    destination = Path(path)
+    temp_path = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=destination.parent,
+            prefix=f".{destination.stem}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_path = Path(handle.name)
+            json.dump(payload, handle, ensure_ascii=False, indent=2)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_path, destination)
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)