@oh-story/dsh 0.1.10 → 0.1.12

package/lib/video-recap/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)

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

@@ -20,7 +20,6 @@ brittle and case-by-case. Two stages around an agent-authored pause:
 """
 import argparse
 import base64
-import hashlib
 import json
 import re
 import unicodedata
@@ -28,6 +27,7 @@ import wave
 from pathlib import Path
 
 from lib import (
+    file_identity,
     CONFIG,
     get_video_duration,
     log,
@@ -44,7 +44,6 @@ ATEMPO_CAP = 2.0  # max compression before we trim instead (atempo>2 also sounds
 DUB_FAST_SPEECH_CPS = 7.0
 DUB_TRIM_RISK_CPS = 7.0
 DUB_MIN_ASR_WINDOW_SECONDS = 0.5
-DUB_TTS_CACHE_VERSION = 1
 DUB_TTS_STYLE_PROMPT = "自然、清晰，保持原说话人的音色与节奏，语气平稳。"
 
 DUB_SCHEMA_VERSION = 1
@@ -208,32 +207,32 @@ def lint_dub_script(script, duration, work_dir=None):
 
 def build_dub_review(script, transcript, lint=None):
     """Script-level review scaffold: deterministic timing/naturalness signals for agent review."""
-    duration = float(transcript.get("duration", 0.0))
+    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.get("issues", []):
+    for issue in lint["issues"]:
         if issue["severity"] in {"error", "warning"}:
             edits.append({
-                "line": issue.get("line"),
-                "start": issue.get("start"),
+                "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.get("verdict") == "FAIL" else ("REVISE" if edits else "PASS")
+    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.get("code") == "fast_speech" for i in lint.get("issues", [])) else "PASS",
+            "spoken_chinese": "REVISE" if any(i["code"] == "fast_speech" for i in lint["issues"]) else "PASS",
             "speaker_tone": "needs_agent_review",
-            "timing_fit": "FAIL" if lint.get("verdict") == "FAIL" else ("REVISE" if edits else "PASS"),
+            "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.get("windows", [])), "script_lines": len(lines)},
+        "coverage": {"transcript_windows": len(transcript["windows"]), "script_lines": len(lines)},
     }
 
 
@@ -244,12 +243,19 @@ def _write_json(path, payload):
 
 # ── ffmpeg / wav helpers ─────────────────────────────────────────────
 
+def _ffmpeg(args):
+    """Run one ffmpeg command; a non-zero exit raises instead of leaving a silent gap."""
+    result = run_cmd(["ffmpeg", "-y", *args])
+    if result.returncode != 0:
+        raise RuntimeError(f"ffmpeg 失败 ({args[-1]}): {result.stderr.strip()[-2000:]}")
+
+
 def _ffmpeg_extract_wav(video, out_wav, sr=16000):
-    run_cmd(["ffmpeg", "-y", "-i", str(video), "-vn", "-ar", str(sr), "-ac", "1", str(out_wav)])
+    _ffmpeg(["-i", str(video), "-vn", "-ar", str(sr), "-ac", "1", str(out_wav)])
 
 
 def _cut_wav(src_wav, out_wav, start, dur, sr=16000):
-    run_cmd(["ffmpeg", "-y", "-i", str(src_wav), "-ss", str(start), "-t", str(dur),
+    _ffmpeg(["-i", str(src_wav), "-ss", str(start), "-t", str(dur),
              "-ar", str(sr), "-ac", "1", str(out_wav)])
 
 
@@ -285,18 +291,14 @@ def _strip_reasoning_residue(text):
 
 
 def _run_asr(wav_path, lang="en"):
-    try:
-        with wave.open(str(wav_path), "rb") as source:
-            if source.getnframes() <= 0:
-                return ""
-    except (OSError, EOFError, wave.Error):
-        return ""
-    raw = Path(wav_path).read_bytes()
-    if not raw:
-        return ""
-    b64 = base64.b64encode(raw).decode("ascii")
+    # The WAV was just cut by ffmpeg (which raised on failure); an unreadable file is a bug,
+    # not "no speech". A zero-frame window (audio shorter than the picture) is skipped.
+    with wave.open(str(wav_path), "rb") as source:
+        if source.getnframes() <= 0:
+            return ""
+    b64 = base64.b64encode(Path(wav_path).read_bytes()).decode("ascii")
     payload = {
-        "model": CONFIG.get("mimo_asr_model", "mimo-v2.5-asr"),
+        "model": CONFIG["mimo_asr_model"],
         "messages": [{"role": "user", "content": [
             {"type": "input_audio", "input_audio": {"data": f"data:{ASR_MIME};base64,{b64}"}},
         ]}],
@@ -305,8 +307,8 @@ def _run_asr(wav_path, lang="en"):
     resp = mimo_asr_api_call(payload)
     try:
         text = str(resp["choices"][0]["message"]["content"] or "").strip()
-    except (KeyError, IndexError, TypeError):
-        return ""
+    except (KeyError, IndexError, TypeError) as exc:
+        raise RuntimeError("MiMo-ASR 响应缺少 choices[0].message.content") from exc
     return re.sub(r"<[^>]{1,20}>", "", _strip_reasoning_residue(text)).strip()  # strip reasoning + ASR markers like "<chinese>"
 
 
@@ -346,16 +348,13 @@ def _clone_tts(text, ref_b64, out_wav):
     Path(out_wav).write_bytes(base64.b64decode(data))
 
 
-def _clone_cache_fingerprint(text, ref_bytes):
-    payload = {
-        "cache_version": DUB_TTS_CACHE_VERSION,
+def _clone_cache_inputs(text, ref_identity):
+    return {
         "model": CLONE_MODEL,
         "style_prompt": DUB_TTS_STYLE_PROMPT,
         "text": str(text),
-        "reference_sha256": hashlib.sha256(ref_bytes).hexdigest(),
+        "reference": ref_identity,
     }
-    encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
-    return hashlib.sha256(encoded).hexdigest()
 
 
 def _clone_cache_meta_path(raw_wav):
@@ -371,30 +370,27 @@ def _usable_clone_wav(path):
     return sample_rate > 0 and channels > 0 and bool(frames)
 
 
-def _write_clone_cache_meta(raw_wav, text, ref_bytes):
-    meta = {
-        "schema_version": DUB_TTS_CACHE_VERSION,
-        "fingerprint": _clone_cache_fingerprint(text, ref_bytes),
-        "model": CLONE_MODEL,
-    }
+def _write_clone_cache_meta(raw_wav, text, ref_identity):
+    meta = {"inputs": _clone_cache_inputs(text, ref_identity)}
     return _write_json(_clone_cache_meta_path(raw_wav), meta)
 
 
-def _ensure_clone_tts(text, ref_b64, ref_bytes, raw_wav):
+def _ensure_clone_tts(text, ref_b64, ref_identity, raw_wav):
     raw_wav = Path(raw_wav)
-    expected = _clone_cache_fingerprint(text, ref_bytes)
+    expected = _clone_cache_inputs(text, ref_identity)
     meta_path = _clone_cache_meta_path(raw_wav)
-    try:
+    # Missing sidecar = never synthesized; a sidecar this skill wrote but cannot parse is a
+    # bug, not a reason to silently pay for re-synthesis.
+    if meta_path.exists():
         meta = json.loads(meta_path.read_text(encoding="utf-8"))
-    except (FileNotFoundError, OSError, ValueError, TypeError):
-        meta = {}
-    if meta.get("fingerprint") == expected and _usable_clone_wav(raw_wav):
-        return True
+        # 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_bytes)
+    _write_clone_cache_meta(raw_wav, text, ref_identity)
     return False
 
 
@@ -403,17 +399,15 @@ def _time_fit(raw_wav, fitted_wav, room_seconds):
     the next line). Never globally speed up; a short dub keeps the natural pause. Returns the
     fitted duration."""
     dur = get_video_duration(raw_wav)
-    if dur <= 0:
-        return 0.0
     if dur <= room_seconds + 0.05:
-        run_cmd(["ffmpeg", "-y", "-i", str(raw_wav), "-ar", str(CLONE_SR), "-ac", "1", str(fitted_wav)])
+        _ffmpeg(["-i", str(raw_wav), "-ar", str(CLONE_SR), "-ac", "1", str(fitted_wav)])
         return dur
     factor = dur / room_seconds
     if factor <= ATEMPO_CAP:
-        run_cmd(["ffmpeg", "-y", "-i", str(raw_wav), "-filter:a", _atempo_chain(factor),
+        _ffmpeg(["-i", str(raw_wav), "-filter:a", _atempo_chain(factor),
                  "-ar", str(CLONE_SR), "-ac", "1", str(fitted_wav)])
         return get_video_duration(fitted_wav)
-    run_cmd(["ffmpeg", "-y", "-i", str(raw_wav),
+    _ffmpeg(["-i", str(raw_wav),
              "-filter:a", f"{_atempo_chain(ATEMPO_CAP)},atrim=0:{room_seconds:.3f},"
                           f"afade=t=out:st={max(0, room_seconds - 0.15):.3f}:d=0.15",
              "-ar", str(CLONE_SR), "-ac", "1", str(fitted_wav)])
@@ -423,12 +417,10 @@ def _time_fit(raw_wav, fitted_wav, room_seconds):
 def _build_dub_track(lines, duration, out_wav):
     canvas = bytearray(int(duration * CLONE_SR) * 2)  # 16-bit mono silence
     for ln in lines:
-        fw = ln.get("fitted_wav")
-        if not fw or not Path(fw).exists():
-            continue
-        sr, ch, frames = _wav_frames(fw)
+        # _time_fit always writes fitted_wav at CLONE_SR mono (and raised if ffmpeg failed).
+        sr, ch, frames = _wav_frames(ln["fitted_wav"])
         if sr != CLONE_SR or ch != 1:
-            continue
+            raise RuntimeError(f"fitted WAV {ln['fitted_wav']} is {sr}Hz/{ch}ch, expected {CLONE_SR}Hz mono")
         off = int(ln["start"] * CLONE_SR) * 2
         end = min(off + len(frames), len(canvas))
         canvas[off:end] = frames[: end - off]
@@ -440,7 +432,7 @@ def _build_dub_track(lines, duration, out_wav):
 
 
 def _mux(video, dub_wav, out_video):
-    run_cmd(["ffmpeg", "-y", "-i", str(video), "-i", str(dub_wav),
+    _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),
@@ -529,8 +521,8 @@ def stage_render(video, work, ref_start, ref_dur):
     if not ref_wav.exists():
         rs, rd = _ref_window(duration, ref_start, ref_dur)
         _cut_wav(work / "dub_source.wav", ref_wav, rs, rd)
-    ref_bytes = ref_wav.read_bytes()
-    ref_b64 = base64.b64encode(ref_bytes).decode("ascii")
+    ref_identity = file_identity(ref_wav)
+    ref_b64 = base64.b64encode(ref_wav.read_bytes()).decode("ascii")
 
     tts_dir = work / "dub_tts"
     tts_dir.mkdir(exist_ok=True)
@@ -542,7 +534,7 @@ def stage_render(video, work, ref_start, ref_dur):
         room = max(0.4, min(slot_end, nxt) - ln["start"])
         raw = tts_dir / f"line_{i:03d}_raw.wav"
         fitted = tts_dir / f"line_{i:03d}.wav"
-        cache_hit = _ensure_clone_tts(ln["zh"], ref_b64, ref_bytes, raw)
+        cache_hit = _ensure_clone_tts(ln["zh"], ref_b64, ref_identity, raw)
         ln["tts_cache"] = "hit" if cache_hit else "miss"
         ln["fitted_wav"] = str(fitted)
         ln["fitted_dur"] = round(_time_fit(raw, fitted, room), 2)

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

@@ -1,7 +1,6 @@
 """Self-contained config + utilities for this skill (no cross-skill imports).
 Merged from the shared core; reads the same env vars as the rest of the bundle."""
 import json
-import hashlib
 import math
 import os
 import re
@@ -116,7 +115,7 @@ CONFIG = {
     "mimo_api_key": _mimo_api_key,
     "mimo_tts_api_url": normalize_api_url(_raw_mimo_tts_api_url),
     "mimo_tts_api_key": _mimo_tts_api_key,
-    "mimo_tts_api_key_source": "MIMO_TTS_API_KEY" if os.environ.get("MIMO_TTS_API_KEY") else "MIMO_API_KEY",
+    "mimo_tts_env_var": "MIMO_TTS_API_KEY" if os.environ.get("MIMO_TTS_API_KEY") else "MIMO_API_KEY",
     "mimo_asr_model": os.environ.get("MIMO_ASR_MODEL", DEFAULT_MIMO_ASR_MODEL),
     "mimo_tts_model": os.environ.get("MIMO_TTS_MODEL", DEFAULT_MIMO_TTS_MODEL),
     "mimo_tts_voice": os.environ.get("MIMO_TTS_VOICE", "冰糖"),
@@ -190,45 +189,10 @@ def get_video_duration(video_path):
     return float(result.stdout.strip())
 
 
-def stable_hash(value):
-    """Return an md5 digest of a deterministic JSON serialization (non-secret cache fingerprints)."""
-    encoded = json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
-    return hashlib.md5(encoded.encode("utf-8")).hexdigest()
-
-
-_FILE_FINGERPRINT_MEMO = {}
-
-
-def _file_identity(path):
-    """(device, inode, size, mtime_ns) — changes whenever the bytes could have changed."""
+def file_identity(path):
+    """{size, mtime_ns} — the cache identity of an input file (no content read)."""
     st = os.stat(os.fspath(path))
-    return (st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns)
-
-
-def file_fingerprint(path, chunk_size=1024 * 1024):
-    """Return a full-content fingerprint for cache-correct identity checks.
-
-    The digest covers CONTENT only — never the path or mtime — so a copied video or
-    artifact is still recognised as the same asset, while any byte change invalidates
-    the cache even if timestamps, size, head, or tail bytes are misleading.
-
-    Identity metadata is used ONLY to memoize within a single process. One understanding
-    run fingerprints the same source video 8-10 times and the whole extracted frame set
-    2-3 times; on a 40-minute video at fps=1 that is gigabytes of redundant reads before
-    any real work starts. A file rewritten in place gets a new (size, mtime_ns) and is
-    re-hashed, so the memo can never serve a stale digest.
-    """
-    key = _file_identity(path)
-    memoized = _FILE_FINGERPRINT_MEMO.get(key)
-    if memoized is not None:
-        return memoized
-    h = hashlib.sha256()
-    with open(os.fspath(path), "rb") as f:
-        for chunk in iter(lambda: f.read(chunk_size), b""):
-            h.update(chunk)
-    digest = h.hexdigest()
-    _FILE_FINGERPRINT_MEMO[key] = digest
-    return digest
+    return {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
 
 
 def _retry_after_seconds(value, fallback):
@@ -288,7 +252,7 @@ def mimo_tts_api_call(payload):
         max_retries=10,
         api_url=CONFIG["mimo_tts_api_url"],
         api_key=CONFIG["mimo_tts_api_key"],
-        api_key_source=CONFIG["mimo_tts_api_key_source"],
+        api_env_var=CONFIG["mimo_tts_env_var"],
     )
 
 
@@ -299,11 +263,11 @@ def mimo_asr_api_call(payload):
         max_retries=10,
         api_url=CONFIG["mimo_api_url"],
         api_key=CONFIG["mimo_api_key"],
-        api_key_source="MIMO_API_KEY",
+        api_env_var="MIMO_API_KEY",
     )
 
 
-def api_call(payload, *, api_url, api_key, api_key_source, max_retries=8):
+def api_call(payload, *, api_url, api_key, api_env_var, max_retries=8):
     """调用 OpenAI-compatible API，带重试。
 
     集群的 429 限流是常态而非错误，所以重试更耐心（更多次数 + 退避封顶 60s + 遵从 Retry-After），
@@ -330,7 +294,7 @@ def api_call(payload, *, api_url, api_key, api_key_source, max_retries=8):
                 wait = _retry_after_seconds(retry_after, max(wait, 10))
                 log(f"API 速率限制 (尝试 {attempt+1}/{max_retries}), 等待 {wait}s")
             elif e.code == 401:
-                raise RuntimeError(f"API 认证失败 (401)。请检查 {api_key_source} 和 API URL 是否匹配。")
+                raise RuntimeError(f"API 认证失败 (401)。请检查 {api_env_var} 和 API URL 是否匹配。")
             elif e.code == 403:
                 hint = "API 访问被拒绝 (403)。"
                 if "1010" in body or "cloudflare" in body.lower():

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

@@ -0,0 +1 @@
+"""TTS provider transports (fish-audio, index-tts) for the video-voiceover skill."""

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

@@ -0,0 +1,184 @@
+"""Self-hosted index-tts JSON-to-WAV transport with no redirect forwarding."""
+
+import contextlib
+import io
+import json
+import os
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+import wave
+from pathlib import Path
+
+
+MAX_WAV_BYTES = 64 * 1024 * 1024
+MAX_ERROR_BYTES = 512
+SPEED_POLICY = "provider-default-no-rate-control"
+
+
+class _SafeResponseError(RuntimeError):
+    pass
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def _open_without_redirects(request, timeout):
+    return urllib.request.build_opener(_NoRedirectHandler()).open(request, timeout=timeout)
+
+
+def validate_index_tts_config(endpoint, voice):
+    """Validate explicit private settings without returning a credential-bearing URL."""
+    endpoint = str(endpoint or "")
+    voice = str(voice or "").strip()
+    if not endpoint:
+        raise ValueError("INDEX_TTS_ENDPOINT 必须显式配置")
+    if any(ord(char) < 32 or ord(char) == 127 for char in endpoint):
+        raise ValueError("INDEX_TTS_ENDPOINT 配置无效或包含禁止字符")
+    try:
+        parsed = urllib.parse.urlsplit(endpoint)
+        port = parsed.port
+    except ValueError:
+        raise ValueError("INDEX_TTS_ENDPOINT 配置无效") from None
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("INDEX_TTS_ENDPOINT 必须是带主机名的 http/https URL")
+    if "@" in parsed.netloc or "?" in endpoint or "#" in endpoint:
+        raise ValueError("INDEX_TTS_ENDPOINT 禁止 userinfo、query 或 fragment 携带凭证")
+    if port is not None and not 1 <= port <= 65535:
+        raise ValueError("INDEX_TTS_ENDPOINT 配置无效")
+    if not voice:
+        raise ValueError("INDEX_TTS_VOICE 必须显式配置")
+    return endpoint, voice
+
+
+def load_private_config(config, environ):
+    """Read the private index-tts settings; validate them once, only when that provider is selected."""
+    endpoint = environ.get("INDEX_TTS_ENDPOINT", "").strip()
+    voice = environ.get("INDEX_TTS_VOICE", "").strip()
+    if config["tts_provider"] == "index-tts":
+        endpoint, voice = validate_index_tts_config(endpoint, voice)
+    config["index_tts_endpoint"] = endpoint
+    config["index_tts_voice"] = voice
+
+
+def cache_settings(config):
+    """Non-secret settings that decide reuse; the endpoint is never written to disk."""
+    return {
+        "index_tts_voice": config["index_tts_voice"],
+        "index_tts_speed_policy": SPEED_POLICY,
+    }
+
+
+def default_controls(segment):
+    unsupported = []
+    for key, default in (("emotion", None), ("style", None), ("rate", "+0%"), ("pitch", "+0Hz")):
+        if segment.get(key) not in (None, "", default):
+            unsupported.append(key)
+    if unsupported:
+        raise RuntimeError(f"已配置的端点不接受段级控制字段: {', '.join(unsupported)}")
+    return "+0%", "+0Hz"
+
+
+def synthesize_configured(text, output_path, config):
+    return synthesize_index_tts(
+        text, output_path, endpoint=config["index_tts_endpoint"],
+        voice=config["index_tts_voice"], timeout=config["tts_timeout"],
+    )
+
+
+def valid_cached_receipt(cache_data, config):
+    """A cached index-tts segment must carry the receipt of a request for the current voice."""
+    receipt = cache_data.get("provider_receipt")
+    return isinstance(receipt, dict) and receipt == {
+        "provider": "index-tts",
+        "requested_voice": config["index_tts_voice"],
+    }
+
+
+def _discard_http_error_body(error):
+    """Drain a bounded slice and close; the body is never surfaced (it may echo private URLs)."""
+    with contextlib.suppress(Exception):
+        try:
+            error.read(MAX_ERROR_BYTES)
+        finally:
+            error.close()
+
+
+def _validate_wav(audio):
+    if len(audio) <= 44 or audio[:4] != b"RIFF" or audio[8:12] != b"WAVE":
+        raise RuntimeError("IndexTTS 返回的内容不是有效 WAV")
+    if int.from_bytes(audio[4:8], "little") + 8 > len(audio):
+        raise RuntimeError("IndexTTS 返回的 RIFF 声明长度超过响应，音频被截断")
+    try:
+        with wave.open(io.BytesIO(audio), "rb") as wav:
+            channels = wav.getnchannels()
+            sample_width = wav.getsampwidth()
+            sample_rate = wav.getframerate()
+            frames = wav.getnframes()
+            decoded = wav.readframes(frames)
+    except (EOFError, wave.Error) as exc:
+        raise RuntimeError("IndexTTS 返回的 WAV 结构损坏或不受支持") from exc
+    if not (1 <= channels <= 8 and 1 <= sample_width <= 4 and 8000 <= sample_rate <= 192000):
+        raise RuntimeError("IndexTTS 返回的 WAV 音频参数越界")
+    if frames <= 0:
+        raise RuntimeError("IndexTTS 返回的 WAV 没有音频帧")
+    if len(decoded) != frames * channels * sample_width:
+        raise RuntimeError("IndexTTS 返回的 WAV 音频数据被截断")
+
+
+def synthesize_index_tts(text, output_path, *, endpoint, voice, timeout):
+    """POST the exact {voice,text} contract and atomically persist an authentic WAV.
+
+    endpoint/voice were validated by load_private_config; timeout by lib's env_int."""
+    body = json.dumps({"voice": voice, "text": text}, ensure_ascii=False).encode("utf-8")
+    request = urllib.request.Request(
+        endpoint,
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "audio/wav",
+            "User-Agent": "video-recap/1.0",
+        },
+        method="POST",
+    )
+    try:
+        with _open_without_redirects(request, timeout) as response:
+            content_type = response.headers.get("Content-Type", "").lower()
+            content_length = response.headers.get("Content-Length")
+            if content_length and int(content_length) > MAX_WAV_BYTES:
+                raise _SafeResponseError("IndexTTS 返回 WAV 过大，已拒绝读取")
+            audio = response.read(MAX_WAV_BYTES + 1)
+    except urllib.error.HTTPError as exc:
+        _discard_http_error_body(exc)
+        if 300 <= exc.code < 400:
+            raise RuntimeError("IndexTTS 禁止 HTTP 重定向，未向其他主机转发批准文本") from None
+        raise RuntimeError(f"IndexTTS 请求失败 (HTTP {exc.code})，远端返回错误状态") from None
+    except urllib.error.URLError as exc:
+        kind = "超时" if isinstance(exc.reason, (TimeoutError, socket.timeout)) else "网络"
+        raise RuntimeError(f"IndexTTS {kind}错误，未返回音频") from None
+    except (TimeoutError, socket.timeout):
+        raise RuntimeError("IndexTTS 超时错误，未返回音频") from None
+    except ValueError:
+        raise RuntimeError("IndexTTS 返回了无效的 Content-Length") from None
+    except _SafeResponseError as exc:
+        raise RuntimeError(str(exc)) from None
+    except Exception:
+        raise RuntimeError("IndexTTS 响应读取或关闭失败，未保存音频") from None
+
+    if len(audio) > MAX_WAV_BYTES:
+        raise RuntimeError("IndexTTS 返回 WAV 过大，已拒绝保存")
+    if "json" in content_type:
+        raise RuntimeError("IndexTTS 返回了 JSON 错误响应而不是音频；正文已隐藏")
+    _validate_wav(audio)
+
+    output = Path(output_path)
+    partial = Path(str(output) + ".part")
+    try:
+        partial.write_bytes(audio)
+        os.replace(partial, output)
+    finally:
+        partial.unlink(missing_ok=True)
+    return {"provider": "index-tts", "requested_voice": voice}