video-voiceover

1. 概要

このスキルは、タイムスタンプ付きのナレーション原稿を読み込み、各セグメントの音声を個別に生成して、対応する時間枠に合わせたうえで、後続の合成に必要な配置メタデータを記録します。 デフォルトのエンジンは MiMo TTS（mimo-v2.5-tts）です。Fish Audio（デフォルトモデル s2.1-pro-free）を明示的に選択することもできます。

2. リモートサービスとデータの外部送信

このスキルは、選択した TTS または dub の経路に応じてネットワークに接続します。表の「実読テキスト」とは、narration.json のセグメントから書式と演出指示を取り除いたテキストを指します。

経路	サービスと認証情報	送信内容
デフォルトのナレーション TTS（--tts-provider auto|mimo-tts）	MiMo chat インターフェース <MIMO_TTS_API_URL または MIMO_API_URL>/chat/completions、MIMO_TTS_API_KEY または MIMO_API_KEY、モデル mimo-v2.5-tts	各セグメントの実読テキスト、自然な口調／速度を指定する一文の指示（セグメントの emotion と時間枠から算出）、組み込み音声名（デフォルトは 冰糖）。auto の場合、MiMo key がなく FISH_API_KEY が設定されていれば、Fish Audio の行に切り替えます
ナレーションの音声クローン（--voice-ref <audio> / VOICE_REF）	同上、モデル mimo-v2.5-tts-voiceclone	上記の内容に加え、参照音声（24 kHz のモノラル WAV に変換、最長 30 秒）の base64。各セグメントのリクエストに含まれます
Fish Audio（--tts-provider fish-audio）	FISH_TTS_API_URL（デフォルトは https://api.fish.audio/v1/tts）、FISH_API_KEY	各セグメントの実読テキスト、数値で指定する読み上げ速度、音声 ID FISH_TTS_REFERENCE_ID。ローカル音声は送信しません
セルフホスト IndexTTS（--tts-provider index-tts）	ユーザー自身がデプロイし、INDEX_TTS_ENDPOINT で指定する HTTP(S) サービス	{"voice": INDEX_TTS_VOICE, "text": 実読テキスト}。ローカル音声は送信しません
実験的な dub（§8 を参照）	MiMo ASR（MIMO_API_URL、MIMO_API_KEY、mimo-v2.5-asr）および MiMo voiceclone（TTS インターフェースと認証情報、mimo-v2.5-tts-voiceclone）	元動画の音声トラック全体を 6 秒ごとに分割して ASR に送信します。中国語の各訳文と、元音声から切り出した約 10 秒の元話者の音声（クローン用の参照音声）を voiceclone に送信します

--voice-ref と dub は、実在する人物の音声を MiMo に送信してクローンを作成します。その音声を使用する権利があり、かつ本人がクローン作成に同意している場合にのみ使用してください。

3. 環境要件

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/... は、すべてこのスキルのディレクトリを基準とします。実行環境からリポジトリのルートディレクトリで起動する場合は、スクリプトのパスにこのスキルの絶対ディレクトリを付けてください。

4. 入力仕様

デフォルトの入力は work_dir/narration.json です。各セグメントには start、end、narration が必須です。pause_after_ms と overlaps_speech は任意のフィールドです。時間はすべて、音声を最終的に配置する出力タイムライン上の秒数で表します。

cut の処理は、先にカットしてから音声を合わせます。narration.json はカット後の完成映像の出力時間に基づいて記述するため、別の対応表はありません。

5. 実行コマンド

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] [--allow-partial-tts]

単独で実行し、--narration を省略した場合は、デフォルトで work_dir/narration.json を読み込みます。--narration は、別のパスにある同じ形式の原稿を指定する場合にのみ使用します。

6. 出力仕様

• tts_segments/*.wav：ナレーションの各セグメントに対応する音声ファイルです。
• tts_meta.json：segments、engine、voice（実際に使用したプロバイダー、モデル、音声または参照音声）と 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 が付与されます。[停顿] などの除去マーカーのみを含み、除去後に実読テキストが残らない原稿セグメントも、必須セグメントのエラーとなります。

7. 运行规则

• 分段音频按内容缓存在 tts_segments/cache/：键是实读文本、实际发给供应商的语气请求（MiMo 是那句自然语言指令，语速只在 ≥+6% 或 ≤-3% 时改变措辞；Fish Audio 是数值 speed；index-tts 没有段级控制）与 TTS 设置，不含段序号和时间窗；因此段位变化让名义语速从 +5% 变成 -2% 时，MiMo 不重新合成； 缓存 WAV 的 size/mtime_ns 变了即失效。narr_NNN.wav 是指向缓存的硬链接（不支持时为副本），tts_meta.json 照旧引用它。删掉、插入或挪动某段后，只重生成文本或发给供应商的请求变了的段（名义语速随首段、末两段的位置变化）； 旧版的 narr_NNN.wav.cache.json 不再读取。
• 批准稿保护策略属于缓存设置：严格模式往缓存键里加入策略与原稿，与默认策略（report-over-budget-v2，不进键）互不命中；旧版逐段缓存（含自动缩稿音频）不再读取；只有同一严格策略下、 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、归一化设置或按内容计算出的语速变化时会重新生成缓存（Fish 不接收音高和情绪，它们变了不重新生成）。当前免费模型无 SLA，受 Fair Use 和官方免费期限约束。
• --voice-ref 仅用于 full/cut 解说克隆，切换到 mimo-v2.5-tts-voiceclone。仅在确需新合成时惰性规范化一次； 参考音频的路径、size/mtime_ns 或预处理版本变化会使旧缓存失效。仅在获得授权后使用，参考音频会发送到 MiMo。
• dub voiceclone 原始 WAV 也会按模型、提示、台词和参考音频的 size/mtime_ns 缓存；匹配重跑不再重复请求或计费， dub_manifest.json 逐行记录 tts_cache=hit|miss。
• 合成出的段音频比按 TTS_MIN_SPEECH_RATE（默认 2.5 字/秒，英文按每词 1.5 字）读完全文、再加停顿与首尾静音的上限还长时， 视为 TTS 幻读（读完原稿后又编出一段话），按失败重试，不缓存也不交给 assemble；重试用尽则该段失败，报错写明时长与上限， 最后一次被拒的音频留在 tts_segments/narr_NNN.rejected.wav 供试听。数字（半角/全角）逐个计 1 字，% 计 3 字（百分之）。 dub 的 voiceclone 台词走同一道检查与重试（被拒的留在 dub_tts/line_NNN_raw.rejected.wav）。 旧版本缓存下的这类 WAV 在重跑时不再复用，会重新合成。设为 0 关闭这道检查。
• TTS_WORKERS、TTS_TIMEOUT、TTS_RETRIES、ALLOW_PARTIAL_TTS 用于调整并发、超时、重试与部分成功策略。

8. 实验性 dub 配音（英译中、克隆原声）

dub.py 是实验功能：把英文原声翻译成中文，并用原说话人的克隆音色整轨替换人声。它与解说配音分别执行，voiceover.py 不调用它。

• 触发：只在用户明确要求英译中配音时，由编排入口以 --edit-mode dub --confirm-voice-rights 运行；编排入口把确认参数原样转给 dub.py 的准备和渲染两个阶段。没有单独的手动阶段。
• 确认门禁：dub.py 的两个阶段都必须带 --confirm-voice-rights，缺少时在抽取音频和发出任何请求之前退出，并说明会外发什么。编排入口在 dub 模式下同样拒绝缺少该参数的运行，在其他模式下拒绝该参数。
• 外发内容：准备阶段把源视频音轨按 6 秒分窗发给 MiMo ASR（mimo-v2.5-asr）转写英文；渲染阶段把每句中文译文和从源音频第 2 秒起截取的约 10 秒原说话人声音（dub_reference.wav）一起发给 MiMo voiceclone（mimo-v2.5-tts-voiceclone）。
• 权利与同意：只能用于用户有权使用的视频与音频，且被克隆声音的说话人已同意。Agent 必须先向用户确认这两点，用户确认后才能加 --confirm-voice-rights；无法确认时不要运行 dub，也不要用它冒充他人发言。
• 确定性门禁：渲染阶段在语音克隆前写 dub_lint.json，空行、重叠或越界译文即中止，不发 voiceclone 请求。
• 本地产物：dub_source.wav、dub_transcript.json、dub_brief.md、dub_reference.wav、Agent 写的 dub_script.json、dub_lint.json、dub_tts/、dub_manifest.json 与 dub_<name>.mp4，都只写在 work_dir。

9. 能力边界

• 超窗时保留原稿并记录日志；assemble 有界提速放不下则在渲染前以 no_safe_fit 阻断。批准稿加 --preserve-approved-text，超窗即在 TTS 阶段失败。
• 不混流、不压低原声、不渲染字幕。
• 不分析视频，也不选择时间点；只为输入稿件中的既定分段配音。
• Fish Audio 与 IndexTTS 路径都不接受本地 --voice-ref；前者用已创建的 FISH_TTS_REFERENCE_ID 选择音色。