@oh-story/dsh 0.1.10 → 0.1.12

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

@@ -3,33 +3,40 @@ import base64
 import json
 import os
 import re
-import shutil
 import tempfile
 import time
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from threading import Lock
 
-from fish_audio import synthesize_fish_audio
+from approved_text_policy import (
+    PRESERVE_APPROVED_TEXT_POLICY,
+    ApprovedTextDurationError,
+    archive_current_meta,
+    enforce_duration,
+    policy_name,
+    validate_required_texts,
+    write_json_atomically as _write_tts_meta_atomically,
+)
+from providers.fish_audio import synthesize_fish_audio
+import providers.index_tts as index_provider
 from lib import (
     CONFIG,
     _text_char_count,
     _truncate_at_sentence,
-    file_fingerprint,
+    file_identity,
     get_video_duration,
     log,
     mimo_tts_api_call,
     narration_tempo_budget,
     run_cmd,
-    stable_hash,
 )
 
 # Re-exported: tests and callers reach these through voiceover, the module owns the flow.
 from tts_audio import _maybe_normalize_tts_wav, _normalize_tts_wav_rms  # noqa: F401
 
-SUPPORTED_TTS_ENGINES = {"mimo-tts", "fish-audio"}
+SUPPORTED_TTS_ENGINES = {"mimo-tts", "fish-audio", "index-tts"}
 SEGMENT_AUDIO_SCHEMA_VERSION = 1
-TTS_CACHE_VERSION = 2
 VOICE_REFERENCE_PREP_VERSION = 1
 _VOICE_REFERENCE_LOCK = Lock()
 # Process-wide voice-reference state; prepared bytes are invocation-scoped.
@@ -37,12 +44,24 @@ _VOICE_REFERENCE_STATE_KEYS = (
     "voice_ref_b64",
     "voice_ref_snapshot_path",
     "voice_ref_snapshot_signature",
-    "voice_ref_source_signature",
-    "voice_ref_fingerprint",
     "voice_ref_snapshot_locked",
 )
 
 
+def authored_text_policy():
+    """Return the explicit cacheable policy governing creative text mutation."""
+    return policy_name(CONFIG.get("preserve_approved_text", False))
+
+
+def enforce_approved_text_policy(index, seg, authored_text, spoken_text, audio_duration,
+                                  available_duration, max_raw_duration):
+    """Fail closed when immutable approved text cannot fit its authored window."""
+    enforce_duration(
+        index, seg, authored_text, spoken_text, audio_duration, available_duration,
+        max_raw_duration, CONFIG.get("preserve_approved_text", False), CONFIG["breath_ms"],
+    )
+
+
 def _parse_rate_offset(rate_str):
     """'+5%' -> 0.05, '-3%' -> -0.03, '+0%' -> 0.0"""
     return float(rate_str.rstrip("%")) / 100.0
@@ -103,17 +122,23 @@ def _clean_narration_text(text):
     return re.sub(r'\s+', ' ', text).strip()
 
 
-def _synthesize_segment(i, seg, narration, tts_dir, engine):
-    """合成单个 TTS 段（线程安全），支持 resume 跳过已有文件"""
-    prepared = _prepare_tts_segment(i, seg, narration, tts_dir, engine)
-    if prepared is None:
-        return None
-    text, output_wav, rate, pitch, cache_key = prepared
-    cached = _reuse_tts_segment_cache(i, seg, output_wav, cache_key)
-    if cached:
-        return cached
+def _synthesize_segment(i, seg, narration, tts_dir, engine, prepared=None):
+    """合成单个 TTS 段（线程安全），支持 resume 跳过已有文件。
 
-    _run_tts_engine(engine, text, output_wav, rate=rate, pitch=pitch, emotion=seg.get("emotion"))
+    `prepared` is the `_prepare_tts_segment` tuple of a segment synthesize_tts already probed
+    as a cache miss; passing it skips a second sidecar read + settings resolution."""
+    if prepared is None:
+        prepared = _prepare_tts_segment(i, seg, narration, tts_dir, engine)
+        if prepared is None:
+            return None
+        cached = _reuse_tts_segment_cache(i, seg, prepared[1], prepared[4], engine)
+        if cached:
+            return cached
+    text, output_wav, rate, pitch, cache_inputs = prepared
+
+    provider_receipt = _run_tts_engine(
+        engine, text, output_wav, rate=rate, pitch=pitch, emotion=seg.get("emotion")
+    )
 
     dur = get_video_duration(output_wav)
     seg_slot = seg["end"] - seg["start"]
@@ -124,6 +149,11 @@ def _synthesize_segment(i, seg, narration, tts_dir, engine):
     raw_budget = available * budget["max_raw_duration_factor"]
     truncated = False
     truncate_reason = "none"
+    try:
+        enforce_approved_text_policy(i, seg, seg["narration"], text, dur, available, raw_budget)
+    except ApprovedTextDurationError:
+        _cleanup_partial_tts_outputs(output_wav)
+        raise
     if dur > raw_budget and len(text) > 5:
         chars_per_sec = _text_char_count(text) / dur
         target_chars = max(5, int(raw_budget * chars_per_sec) - 1)
@@ -133,20 +163,24 @@ def _synthesize_segment(i, seg, narration, tts_dir, engine):
             text = shortened
             truncated = True
             truncate_reason = "sentence_boundary"
-            _run_tts_engine(engine, text, output_wav, rate=rate, pitch=pitch, emotion=seg.get("emotion"))
+            provider_receipt = _run_tts_engine(
+                engine, text, output_wav, rate=rate, pitch=pitch, emotion=seg.get("emotion")
+            )
             dur = get_video_duration(output_wav)
 
     norm_meta = _maybe_normalize_tts_wav(output_wav)
     if norm_meta:
         dur = get_video_duration(output_wav)
-    _write_tts_segment_cache(output_wav, cache_key, text, dur, rate_offset,
-                             truncated, truncate_reason, norm_meta)
+    _write_tts_segment_cache(output_wav, cache_inputs, text, dur, rate_offset,
+                             truncated, truncate_reason, norm_meta, provider_receipt)
     return _build_tts_segment_result(
-        i, seg, text, output_wav, dur, rate_offset, truncated, truncate_reason, norm_meta)
+        i, seg, text, output_wav, dur, rate_offset, truncated, truncate_reason, norm_meta,
+        provider_receipt)
 
 
 def _build_tts_segment_result(index, seg, text, output_wav, duration, rate_offset,
-                              truncated=False, truncate_reason="none", norm_meta=None):
+                              truncated=False, truncate_reason="none", norm_meta=None,
+                              provider_receipt=None):
     budget = narration_tempo_budget(rate_offset)
     authored_text = _clean_narration_text(seg["narration"])
     resolved_truncated = truncated or text != authored_text
@@ -156,6 +190,7 @@ def _build_tts_segment_result(index, seg, text, output_wav, duration, rate_offse
         "start": seg["start"],
         "end": seg["end"],
         "narration": authored_text,
+        "authored_text": seg["narration"],
         "spoken_text": text,
         "truncated": resolved_truncated,
         "truncate_reason": (truncate_reason if truncate_reason != "none" else "sentence_boundary") if resolved_truncated else "none",
@@ -174,6 +209,8 @@ def _build_tts_segment_result(index, seg, text, output_wav, duration, rate_offse
         "tts_rate_offset": rate_offset,
         "pause_after_ms": seg.get("pause_after_ms", CONFIG["breath_ms"]),
         "overlaps_speech": seg.get("overlaps_speech", True),
+        "authored_text_policy": authored_text_policy(),
+        "provider_receipt": provider_receipt,
     }
     for optional_key in ("source_start", "source_end", "source_clip_id", "emotion"):
         if optional_key in seg:
@@ -183,13 +220,33 @@ def _build_tts_segment_result(index, seg, text, output_wav, duration, rate_offse
 
 def _tts_failure_record(index, seg, error):
     """Build a user-visible failure record for partial TTS output."""
-    return {
+    record = {
         "index": index,
         "start": seg["start"],
         "end": seg["end"],
         "text": _clean_narration_text(seg["narration"]),
         "error": str(error),
     }
+    if authored_text_policy() == PRESERVE_APPROVED_TEXT_POLICY:
+        record.update({"required": True, "policy": PRESERVE_APPROVED_TEXT_POLICY})
+    if isinstance(error, ApprovedTextDurationError):
+        record.update({"required": True, **error.evidence})
+    return record
+
+
+def _voice_record(engine):
+    """Which voice this run actually used: provider, model, voice id or reference audio."""
+    settings = tts_settings_payload(engine)
+    if engine == "fish-audio":
+        return {"provider": engine, "model": settings["fish_tts_model"],
+                "voice_id": settings["fish_tts_reference_id"], "reference": None}
+    if engine == "index-tts":
+        return {"provider": engine, "model": None,
+                "voice_id": settings["index_tts_voice"], "reference": None}
+    reference = settings.get("voice_ref_identity")
+    return {"provider": engine, "model": settings["mimo_tts_model"],
+            "voice_id": None if reference else settings["mimo_tts_voice"],
+            "reference": reference}
 
 
 def _build_tts_meta(segments, engine, narration_name, failures):
@@ -197,6 +254,7 @@ def _build_tts_meta(segments, engine, narration_name, failures):
     return {
         "segments": segments,
         "engine": engine,
+        "voice": _voice_record(engine),
         "narration": narration_name,
         "partial": bool(failures),
         "failures": failures,
@@ -218,32 +276,34 @@ def synthesize_tts(narration, work_dir):
 
     if not narration:
         raise RuntimeError("narration.json 没有可配音的解说段，已中止以避免生成无解说视频")
+    validate_required_texts(
+        narration, _clean_narration_text, CONFIG.get("preserve_approved_text", False)
+    )
 
     cache_engine = _configured_tts_engine_for_cache()
-    if cache_engine == "fish-audio" and voice_ref:
-        raise RuntimeError(
-            "Fish Audio 不接受本地 VOICE_REF/--voice-ref；请改用 FISH_TTS_REFERENCE_ID"
-        )
-    # A fully cached narration needs no credential: probe every segment's sidecar first.
-    cached_segments = []
-    needs_fresh = False
-    prepared_count = 0
+    if cache_engine in {"fish-audio", "index-tts"} and voice_ref:
+        if cache_engine == "fish-audio":
+            raise RuntimeError("Fish Audio 不接受本地 VOICE_REF/--voice-ref；请改用 FISH_TTS_REFERENCE_ID")
+        raise RuntimeError("index-tts 不支持本地 VOICE_REF/--voice-ref 克隆")
+    # A fully cached narration needs no credential: probe every segment's sidecar once here;
+    # hits are final and only misses reach the workers (with their prepared inputs).
+    segments = []
+    misses = []
     for i, seg in enumerate(narration):
         prepared = _prepare_tts_segment(i, seg, narration, tts_dir, cache_engine)
         if prepared is None:
             continue
-        prepared_count += 1
-        cached = _reuse_tts_segment_cache(i, seg, prepared[1], prepared[4])
-        if not cached:
-            needs_fresh = True
-            break
-        cached_segments.append(cached)
-    if prepared_count == 0:
+        cached = _reuse_tts_segment_cache(i, seg, prepared[1], prepared[4], cache_engine)
+        if cached:
+            segments.append(cached)
+        else:
+            misses.append((i, seg, prepared))
+    if not segments and not misses:
         raise RuntimeError("narration.json 没有可配音的有效文本，已中止以避免生成无解说视频")
-    if not needs_fresh:
-        cached_segments.sort(key=lambda x: x["index"])
+    if not misses:
+        segments.sort(key=lambda x: x["index"])
         log(f"TTS 引擎: {cache_engine} (cache)")
-        return cached_segments, cache_engine, []
+        return segments, cache_engine, []
 
     engine = resolve_tts_engine()
 
@@ -253,15 +313,14 @@ def synthesize_tts(narration, work_dir):
 
     log(f"TTS 引擎: {engine}")
 
-    segments = []
     failures = []
-    max_workers = min(len(narration), CONFIG["tts_workers"])
+    max_workers = min(len(misses), CONFIG["tts_workers"])
 
     try:
         with ThreadPoolExecutor(max_workers=max_workers) as executor:
             futures = {
-                executor.submit(_synthesize_segment, i, seg, narration, tts_dir, engine): i
-                for i, seg in enumerate(narration)
+                executor.submit(_synthesize_segment, i, seg, narration, tts_dir, engine, prepared): i
+                for i, seg, prepared in misses
             }
             for future in as_completed(futures):
                 try:
@@ -278,6 +337,25 @@ def synthesize_tts(narration, work_dir):
         CONFIG.pop("voice_ref_snapshot_locked", None)
 
     segments.sort(key=lambda x: x["index"])
+    approved_text_failures = [
+        failure for failure in failures
+        if failure.get("failure_kind") == "approved_text_duration_conflict"
+    ]
+    if approved_text_failures:
+        first = approved_text_failures[0]
+        evidence = {
+            key: value for key, value in first.items()
+            if key not in {"text", "error", "required"}
+        }
+        if len(approved_text_failures) > 1:
+            evidence["conflict_count"] = len(approved_text_failures)
+        raise ApprovedTextDurationError(evidence)
+    if failures and authored_text_policy() == PRESERVE_APPROVED_TEXT_POLICY:
+        sample = json.dumps(failures[:3], ensure_ascii=False, sort_keys=True)
+        raise RuntimeError(
+            f"批准稿严格模式有 {len(failures)}/{len(narration)} 个必需 TTS 段失败，"
+            f"不能按部分成功交付: {sample}"
+        )
     if failures and not CONFIG["allow_partial_tts"]:
         sample = "; ".join(f"段 {f['index']+1}: {f['error']}" for f in failures[:3])
         raise RuntimeError(
@@ -297,22 +375,26 @@ def synthesize_tts(narration, work_dir):
 
 
 def _run_tts_engine(engine, text, output_wav, rate="+0%", pitch="+0Hz", emotion=None):
-    """Run one TTS engine with retry and remove partial files after failures."""
-    if engine not in SUPPORTED_TTS_ENGINES:
-        raise RuntimeError(f"不支持的 TTS 引擎: {engine}。当前支持 mimo-tts、fish-audio。")
+    """Run one TTS engine with retry and remove partial files after failures.
+
+    `engine` comes from resolve_tts_engine; index-tts controls were already forced to the
+    provider defaults by _prepare_tts_segment."""
     retries = CONFIG["tts_retries"]
     last_error = None
 
     for attempt in range(1, retries + 1):
         try:
             _cleanup_partial_tts_outputs(output_wav)
+            receipt = None
             if engine == "mimo-tts":
                 _tts_mimo(text, output_wav, rate=rate, pitch=pitch, emotion=emotion)
-            else:
+            elif engine == "fish-audio":
                 synthesize_fish_audio(text, output_wav, rate=rate)
+            else:
+                receipt = index_provider.synthesize_configured(text, output_wav, CONFIG)
             if get_video_duration(output_wav) <= 0:
                 raise RuntimeError(f"{engine} 输出音频时长无效")
-            return
+            return receipt
         except Exception as exc:
             last_error = exc
             _cleanup_partial_tts_outputs(output_wav)
@@ -345,19 +427,23 @@ def _prepare_tts_segment(index, seg, narration, tts_dir, engine):
     if not text:
         return None
     output_wav = tts_dir / f"narr_{index:03d}.wav"
-    if CONFIG["tts_dynamic_params"]:
+    if engine == "index-tts":
+        rate, pitch = index_provider.default_controls(seg)
+    elif CONFIG["tts_dynamic_params"]:
         rate, pitch = _compute_tts_params(text, narration, index)
     else:
         rate, pitch = "+0%", "+0Hz"
-    cache_key = _tts_segment_cache_key(engine, index, seg, text, rate, pitch)
-    return text, output_wav, rate, pitch, cache_key
+    cache_inputs = _tts_segment_cache_inputs(engine, index, seg, text, rate, pitch)
+    return text, output_wav, rate, pitch, cache_inputs
 
 
-def _reuse_tts_segment_cache(index, seg, output_wav, cache_key):
-    cached = _load_tts_segment_cache(output_wav, cache_key)
+def _reuse_tts_segment_cache(index, seg, output_wav, cache_inputs, engine):
+    cached = _load_tts_segment_cache(output_wav, cache_inputs)
     if cached is None:
         return None
-    # The sidecar's audio_fingerprint already proved these exact bytes are what produced
+    if engine == "index-tts" and not index_provider.valid_cached_receipt(cached, CONFIG):
+        return None
+    # The sidecar's audio identity (size, mtime_ns) still matches the WAV that produced
     # `audio_duration`; re-probing would be one ffprobe process per segment on every rerun.
     log(f"  段 {index+1}: 复用已有 ({cached['audio_duration']:.1f}s)")
     return _build_tts_segment_result(
@@ -370,13 +456,13 @@ def _reuse_tts_segment_cache(index, seg, output_wav, cache_key):
         cached["truncated"],
         cached["truncate_reason"],
         cached["normalization"],
+        cached.get("provider_receipt"),
     )
 
 
-def _tts_segment_cache_key(engine, index, seg, source_text, rate, pitch):
-    """Fingerprint the exact inputs that make a cached segment safe to reuse."""
+def _tts_segment_cache_inputs(engine, index, seg, source_text, rate, pitch):
+    """The exact inputs that make a cached segment safe to reuse (compared by equality)."""
     payload = {
-        "version": TTS_CACHE_VERSION,
         "engine": engine,
         "source_text": source_text,
         "segment_index": index,
@@ -386,49 +472,50 @@ def _tts_segment_cache_key(engine, index, seg, source_text, rate, pitch):
         "rate": rate,
         "pitch": pitch,
         "emotion": seg.get("emotion", ""),
-        "settings": tts_settings_fingerprint(engine),
+        "settings": tts_settings_payload(engine),
     }
-    return stable_hash(payload)
+    if authored_text_policy() == PRESERVE_APPROVED_TEXT_POLICY:
+        payload.update({
+            "authored_text_policy": PRESERVE_APPROVED_TEXT_POLICY,
+            "authored_text": seg["narration"],
+            "provider_text_cleanup": "clean-narration-text-v1",
+        })
+    return payload
 
 
-def _load_tts_segment_cache(output_wav, cache_key):
-    """Return cache metadata only when the sidecar proves the WAV matches narration."""
+def _load_tts_segment_cache(output_wav, cache_inputs):
+    """Return cache metadata only when the sidecar's inputs and WAV identity still match."""
     cache_path = _tts_segment_cache_path(output_wav)
-    if not output_wav.exists() or not cache_path.exists():
+    if not output_wav.exists() or output_wav.stat().st_size == 0 or not cache_path.exists():
         return None
+    # This skill wrote the sidecar (_write_tts_segment_cache): one it cannot parse is a bug
+    # to surface. One from the earlier content-hash schema (cache_key/audio_fingerprint,
+    # no settings/audio) is a plain miss: the segment is re-synthesized once.
     try:
         data = json.loads(cache_path.read_text(encoding="utf-8"))
-    except (OSError, ValueError):
+    except ValueError as exc:
+        raise RuntimeError(f"TTS 缓存 sidecar 损坏: {cache_path}") from exc
+    if not isinstance(data, dict) or "settings" not in data or "audio" not in data:
         return None
-    required = {
-        "cache_key", "audio_fingerprint", "spoken_text", "audio_duration",
-        "tts_rate_offset", "truncated", "truncate_reason", "normalization",
-    }
-    if not isinstance(data, dict) or not required <= data.keys():
-        return None
-    try:
-        audio_fingerprint = file_fingerprint(output_wav)
-    except OSError:
-        return None
-    if data["cache_key"] != cache_key or data["audio_fingerprint"] != audio_fingerprint:
-        return None
-    return data
+    stale = data["settings"] != cache_inputs or data["audio"] != file_identity(output_wav)
+    return None if stale else data
 
 
-def _write_tts_segment_cache(output_wav, cache_key, spoken_text, duration, rate_offset,
-                             truncated=False, truncate_reason="none", norm_meta=None):
-    """Persist non-secret provenance for safe per-segment TTS reuse."""
+def _write_tts_segment_cache(output_wav, cache_inputs, spoken_text, duration, rate_offset,
+                             truncated=False, truncate_reason="none", norm_meta=None,
+                             provider_receipt=None):
+    """Persist non-secret inputs and the WAV identity for safe per-segment TTS reuse."""
     _tts_segment_cache_path(output_wav).write_text(
         json.dumps({
-            "version": TTS_CACHE_VERSION,
-            "cache_key": cache_key,
-            "audio_fingerprint": file_fingerprint(output_wav),
+            "settings": cache_inputs,
+            "audio": file_identity(output_wav),
             "spoken_text": spoken_text,
             "audio_duration": duration,
             "tts_rate_offset": rate_offset,
             "truncated": truncated,
             "truncate_reason": truncate_reason if truncated else "none",
             "normalization": norm_meta or None,
+            "provider_receipt": provider_receipt,
         }, ensure_ascii=False, indent=2),
         encoding="utf-8",
     )
@@ -443,7 +530,7 @@ def _configured_tts_engine_for_cache():
         return "fish-audio"
     if provider not in SUPPORTED_TTS_ENGINES:
         raise RuntimeError(
-            "TTS_PROVIDER/--tts-provider 必须是 auto、mimo-tts 或 fish-audio"
+            "TTS_PROVIDER/--tts-provider 必须是 auto、mimo-tts、fish-audio 或 index-tts"
         )
     return provider
 
@@ -451,6 +538,8 @@ def _configured_tts_engine_for_cache():
 def resolve_tts_engine():
     """Resolve the selected MiMo or Fish Audio TTS engine and require its credential."""
     engine = _configured_tts_engine_for_cache()
+    if engine == "index-tts":
+        return engine
     if engine == "fish-audio":
         if CONFIG["fish_api_key"]:
             return engine
@@ -458,11 +547,11 @@ def resolve_tts_engine():
     if CONFIG["mimo_tts_api_key"]:
         return engine
     raise RuntimeError(
-        f"没有可用的 TTS 引擎：请设置 {CONFIG['mimo_tts_api_key_source']}（MiMo TTS 需要）。"
+        f"没有可用的 TTS 引擎：请设置 {CONFIG['mimo_tts_env_var']}（MiMo TTS 需要）。"
     )
 
 
-def tts_settings_fingerprint(engine):
+def tts_settings_payload(engine):
     """Return non-secret TTS settings that materially affect generated audio."""
     settings = {
         "engine": engine,
@@ -475,7 +564,9 @@ def tts_settings_fingerprint(engine):
         "tts_segment_target_rms_dbfs": CONFIG["tts_segment_target_rms_dbfs"],
         "tts_segment_peak_limit": CONFIG["tts_segment_peak_limit"],
     }
-    if engine == "fish-audio":
+    if engine == "index-tts":
+        settings.update(index_provider.cache_settings(CONFIG))
+    elif engine == "fish-audio":
         settings.update(
             {
                 "fish_tts_api_url": CONFIG["fish_tts_api_url"],
@@ -496,7 +587,7 @@ def tts_settings_fingerprint(engine):
     if voice_ref and engine == "mimo-tts":
         ref_path = Path(voice_ref).expanduser()
         settings.pop("mimo_tts_voice", None)  # ignored by the voiceclone API
-        settings["voice_ref_fingerprint"] = _voice_reference_fingerprint(ref_path)
+        settings["voice_ref_identity"] = _voice_reference_identity(ref_path)
         settings["voice_ref_preparation"] = (
             f"pcm_s16le:24000hz:mono:30s:v{VOICE_REFERENCE_PREP_VERSION}"
         )
@@ -538,32 +629,22 @@ def _prepare_voice_reference(ref_path):
 
 
 def _voice_reference_signature(ref_path):
-    """Cheaply identify the prepared source so a reused process cannot serve stale audio."""
+    """Identity of the reference source: resolved path plus size and mtime_ns."""
     ref = Path(ref_path).expanduser().resolve()
-    stat = ref.stat()
-    return f"{ref}:{stat.st_size}:{stat.st_mtime_ns}"
+    return {"path": str(ref), **file_identity(ref)}
 
 
-def _voice_reference_fingerprint(ref_path):
-    ref = Path(ref_path).expanduser()
-    resolved = str(ref.resolve())
+def _voice_reference_identity(ref_path):
+    """Identity for cache settings: the locked snapshot's while a run is in flight, else live."""
+    resolved = str(Path(ref_path).expanduser().resolve())
     if (
         CONFIG.get("voice_ref_snapshot_locked")
         and CONFIG.get("voice_ref_b64")
         and CONFIG.get("voice_ref_snapshot_path") == resolved
-        and CONFIG.get("voice_ref_fingerprint")
-    ):
-        return CONFIG["voice_ref_fingerprint"]
-    signature = _voice_reference_signature(ref)
-    if (
-        CONFIG.get("voice_ref_source_signature") == signature
-        and CONFIG.get("voice_ref_fingerprint")
+        and CONFIG.get("voice_ref_snapshot_signature")
     ):
-        return CONFIG["voice_ref_fingerprint"]
-    fingerprint = file_fingerprint(ref)
-    CONFIG["voice_ref_source_signature"] = signature
-    CONFIG["voice_ref_fingerprint"] = fingerprint
-    return fingerprint
+        return CONFIG["voice_ref_snapshot_signature"]
+    return _voice_reference_signature(ref_path)
 
 
 def _cache_prepared_voice_reference(ref_path):
@@ -576,30 +657,19 @@ def _cache_prepared_voice_reference(ref_path):
             and CONFIG.get("voice_ref_snapshot_path") == resolved
         ):
             return CONFIG["voice_ref_b64"]
+        if not ref.is_file():
+            raise FileNotFoundError(f"参考音频不存在或不是文件: {ref}")
         signature = _voice_reference_signature(ref)
-        snapshot_path = CONFIG.get("voice_ref_snapshot_path")
-        snapshot_signature = CONFIG.get("voice_ref_snapshot_signature")
         if (
             CONFIG.get("voice_ref_b64")
-            and snapshot_path == resolved
-            and snapshot_signature == signature
+            and CONFIG.get("voice_ref_snapshot_path") == resolved
+            and CONFIG.get("voice_ref_snapshot_signature") == signature
         ):
             return CONFIG["voice_ref_b64"]
-        if not ref.is_file():
-            raise FileNotFoundError(f"参考音频不存在或不是文件: {ref}")
-        # ffmpeg and the cache fingerprint must consume the same immutable bytes. Copy first,
-        # then derive both the normalized WAV and identity from that snapshot rather than reading
-        # a caller-mutable source twice.
-        with tempfile.TemporaryDirectory(prefix="video-recap-voice-ref-snapshot-") as temp_dir:
-            snapshot = Path(temp_dir) / f"source{ref.suffix or '.audio'}"
-            shutil.copyfile(ref, snapshot)
-            fingerprint = file_fingerprint(snapshot)
-            encoded = _prepare_voice_reference(snapshot)
+        encoded = _prepare_voice_reference(ref)
         CONFIG["voice_ref_b64"] = encoded
-        CONFIG["voice_ref_snapshot_path"] = str(ref)
+        CONFIG["voice_ref_snapshot_path"] = resolved
         CONFIG["voice_ref_snapshot_signature"] = signature
-        CONFIG["voice_ref_source_signature"] = signature
-        CONFIG["voice_ref_fingerprint"] = fingerprint
         return encoded
 
 
@@ -640,21 +710,28 @@ def main():
         description="video-voiceover: synthesize narration audio segments from narration.json.")
     ap.add_argument("--work-dir", required=True)
     ap.add_argument("--narration", default=None,
-                    help="narration json (default: <work-dir>/narration.json; pass narration_mapped.json explicitly for legacy cut runs)")
+                    help="narration json (default: <work-dir>/narration.json)")
     ap.add_argument("--mimo-voice", default=None, help="MiMo TTS voice name")
     ap.add_argument(
         "--tts-provider",
         default=os.environ.get("TTS_PROVIDER", "auto"),
-        choices=["auto", "mimo-tts", "fish-audio"],
+        choices=["auto", "mimo-tts", "fish-audio", "index-tts"],
         help="TTS provider (default: MiMo when configured, otherwise Fish Audio)",
     )
     ap.add_argument("--voice-ref", default=None,
                     help="reference audio (wav/mp3/etc.) for mimo-v2.5-tts-voiceclone")
     ap.add_argument("--allow-partial-tts", action="store_true",
                     help="allow output when some narration segments fail TTS")
+    ap.add_argument(
+        "--preserve-approved-text",
+        action="store_true",
+        help="fail closed when approved narration exceeds its window; never auto-truncate/resynthesize",
+    )
     args = ap.parse_args()
     work_dir = Path(args.work_dir)
     CONFIG["tts_provider"] = args.tts_provider
+    index_provider.load_private_config(CONFIG, os.environ)
+    CONFIG["preserve_approved_text"] = args.preserve_approved_text
     CONFIG["voice_ref"] = (
         args.voice_ref if args.voice_ref is not None else os.environ.get("VOICE_REF", "").strip()
     )
@@ -662,8 +739,9 @@ def main():
         CONFIG["mimo_tts_voice"] = args.mimo_voice
     if args.mimo_voice and CONFIG["voice_ref"]:
         ap.error("--mimo-voice and --voice-ref are mutually exclusive")
-    if args.tts_provider == "fish-audio" and (args.mimo_voice or CONFIG["voice_ref"]):
-        ap.error("--mimo-voice/--voice-ref are only supported by the MiMo TTS provider")
+    if args.mimo_voice and args.tts_provider in {"fish-audio", "index-tts"}:
+        ap.error("--mimo-voice is only supported by the MiMo TTS provider")
+    # A local --voice-ref with fish-audio/index-tts is rejected by synthesize_tts.
     # Voice-reference normalization is intentionally lazy: a fully cached rerun should not
     # invoke ffmpeg. _tts_mimo uses a process-wide lock so a fresh parallel run still converts
     # the reference exactly once.
@@ -672,15 +750,15 @@ def main():
     if args.narration:
         narration_path = Path(args.narration)
     else:
-        # Canonical cut mode is cut-first/narrate-second: narration.json is already on the
-        # output timeline. A stale legacy narration_mapped.json in the same work_dir must not
-        # silently override it; legacy direct-cut callers can still pass --narration explicitly.
+        # Cut mode is cut-first/narrate-second: narration.json is already on the output
+        # timeline, so the default needs no remapping.
         narration_path = work_dir / "narration.json"
+    if CONFIG["preserve_approved_text"]:
+        archive_current_meta(work_dir / "tts_meta.json")
     narration = json.loads(narration_path.read_text(encoding="utf-8"))
     tts_segments, engine_used, failures = synthesize_tts(narration, work_dir)
     meta = _build_tts_meta(tts_segments, engine_used, narration_path.name, failures)
-    (work_dir / "tts_meta.json").write_text(
-        json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
+    _write_tts_meta_atomically(work_dir / "tts_meta.json", meta)
     if failures:
         log(f"配音完成但缺 {len(failures)} 段：成片可预览但不建议直接发布")
     log(f"配音完成: {len(tts_segments)} 段, 引擎 {engine_used}")