@oh-story/dsh 0.1.4 → 0.1.6

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

@@ -0,0 +1,109 @@
+"""Fish Audio TTS transport for the video-voiceover skill.
+
+The provider returns audio bytes rather than JSON. Keep the request, response validation,
+and secret-safe error handling isolated here so voiceover.py only selects an engine.
+"""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from lib import (
+    CONFIG,
+    DEFAULT_FISH_TTS_API_URL,
+    DEFAULT_FISH_TTS_MODEL,
+    _sanitize_api_error,
+)
+
+
+def _fish_payload(text, rate="+0%"):
+    try:
+        speed = 1.0 + float(str(rate).rstrip("%")) / 100.0
+    except (TypeError, ValueError):
+        speed = 1.0
+    payload = {
+        "text": text,
+        "format": "wav",
+        "normalize": True,
+        "prosody": {
+            "speed": max(0.5, min(2.0, speed)),
+            "volume": 0,
+            "normalize_loudness": True,
+        },
+    }
+    reference_id = str(CONFIG.get("fish_tts_reference_id") or "").strip()
+    if reference_id:
+        payload["reference_id"] = reference_id
+    return payload
+
+
+def synthesize_fish_audio(text, output_path, rate="+0%", **_ignored):
+    """Synthesize one narration block and atomically write the WAV response."""
+    api_key = str(CONFIG.get("fish_api_key") or "").strip()
+    if not api_key:
+        raise RuntimeError("请设置 FISH_API_KEY 用于 Fish Audio TTS")
+
+    endpoint = str(CONFIG.get("fish_tts_api_url") or DEFAULT_FISH_TTS_API_URL)
+    model = str(CONFIG.get("fish_tts_model") or DEFAULT_FISH_TTS_MODEL)
+    body = json.dumps(_fish_payload(text, rate), ensure_ascii=False).encode("utf-8")
+    request = urllib.request.Request(
+        endpoint,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "audio/wav",
+            "model": model,
+            "User-Agent": "video-recap/1.0",
+        },
+        method="POST",
+    )
+
+    timeout = max(1, int(CONFIG.get("tts_timeout", 300) or 300))
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            audio = response.read()
+            content_type = str(response.headers.get("Content-Type") or "").lower()
+    except urllib.error.HTTPError as exc:
+        detail = _sanitize_api_error(
+            exc.read().decode("utf-8", errors="replace"),
+            extra_secrets=(api_key,),
+        )
+        if exc.code == 401:
+            raise RuntimeError("Fish Audio 认证失败 (401)，请检查 FISH_API_KEY") from exc
+        if exc.code == 402:
+            raise RuntimeError("Fish Audio 请求被拒绝 (402)，请检查模型额度或计费状态") from exc
+        raise RuntimeError(f"Fish Audio TTS 请求失败 (HTTP {exc.code}): {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(
+            "Fish Audio TTS 网络错误: "
+            f"{_sanitize_api_error(exc.reason, extra_secrets=(api_key,))}"
+        ) from exc
+
+    if "json" in content_type:
+        detail = _sanitize_api_error(
+            audio.decode("utf-8", errors="replace"),
+            extra_secrets=(api_key,),
+        )
+        raise RuntimeError(
+            f"Fish Audio TTS 返回了 JSON 而不是音频: {detail}"
+        )
+    if (
+        len(audio) <= 44
+        or audio[:4] != b"RIFF"
+        or audio[8:12] != b"WAVE"
+    ):
+        raise RuntimeError("Fish Audio TTS 返回的内容不是有效 WAV")
+
+    output = Path(output_path)
+    partial = Path(str(output) + ".part")
+    try:
+        partial.write_bytes(audio)
+        os.replace(partial, output)
+    finally:
+        try:
+            partial.unlink(missing_ok=True)
+        except OSError:
+            pass

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

@@ -0,0 +1,421 @@
+"""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 os
+import re
+import subprocess
+import time
+import urllib.request
+import urllib.error
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+
+
+# ── 配置 ──────────────────────────────────────────────────────────────
+_EXISTING_CONFIG_REF = globals().get("CONFIG")
+
+DEFAULT_MIMO_API_URL = "https://api.xiaomimimo.com/v1"
+DEFAULT_MIMO_TOKEN_PLAN_CLUSTER = "cn"
+MIMO_TOKEN_PLAN_API_URLS = {
+    "cn": "https://token-plan-cn.xiaomimimo.com/v1",
+    "sgp": "https://token-plan-sgp.xiaomimimo.com/v1",
+    "ams": "https://token-plan-ams.xiaomimimo.com/v1",
+}
+DEFAULT_MIMO_MODEL = "mimo-v2.5"          # VLM / chat (vision understanding)
+DEFAULT_MIMO_ASR_MODEL = "mimo-v2.5-asr"  # speech-to-text
+DEFAULT_MIMO_TTS_MODEL = "mimo-v2.5-tts"  # text-to-speech
+DEFAULT_FISH_TTS_API_URL = "https://api.fish.audio/v1/tts"
+DEFAULT_FISH_TTS_MODEL = "s2.1-pro-free"
+DEFAULT_FISH_TTS_REFERENCE_ID = "5653cea4ac83480aaf2bf45406556185"
+
+
+def normalize_api_url(raw_url):
+    """Normalize a MiMo (OpenAI-compatible) base URL or chat/completions endpoint."""
+    url = (raw_url or DEFAULT_MIMO_API_URL).rstrip("/")
+    if url.endswith("/chat/completions"):
+        return url
+    return f"{url}/chat/completions"
+
+
+def is_mimo_token_plan_key(api_key):
+    """Return True for Xiaomi MiMo Token Plan keys, which use token-plan base URLs."""
+    return str(api_key or "").strip().startswith("tp-")
+
+
+def default_mimo_api_url(api_key="", cluster=None):
+    """Pick the correct MiMo base URL for pay-as-you-go vs Token Plan keys.
+
+    MiMo uses independent credentials for pay-as-you-go (`sk-*`) and Token Plan
+    (`tp-*`). Token Plan keys must be sent to the Token Plan cluster base URL,
+    not the pay-as-you-go `api.xiaomimimo.com` endpoint.
+    """
+    if is_mimo_token_plan_key(api_key):
+        cluster_name = (cluster or os.environ.get("MIMO_TOKEN_PLAN_CLUSTER") or DEFAULT_MIMO_TOKEN_PLAN_CLUSTER)
+        cluster_name = str(cluster_name).strip().lower()
+        return MIMO_TOKEN_PLAN_API_URLS.get(cluster_name, MIMO_TOKEN_PLAN_API_URLS[DEFAULT_MIMO_TOKEN_PLAN_CLUSTER])
+    return DEFAULT_MIMO_API_URL
+
+
+def env_int(name, default, *, minimum=None):
+    """Read an integer env var; ignore malformed values instead of crashing import."""
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return default
+    if minimum is not None:
+        value = max(minimum, value)
+    return value
+
+
+def env_bool(name, default=False):
+    """Read common boolean env var forms."""
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+def env_float(name, default, *, minimum=None):
+    """Read a float env var; ignore malformed values instead of crashing import."""
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return default
+    if minimum is not None:
+        value = max(minimum, value)
+    return value
+
+
+# Single MiMo credential powers ASR + VLM + TTS. Per-capability overrides
+# (MIMO_VIDEO_API_KEY / MIMO_TTS_API_KEY / MIMO_ASR_API_KEY and their *_API_URL forms)
+# are optional and fall back to MIMO_API_KEY / MIMO_API_URL. Token-Plan keys (tp-*) auto-
+# route to the Token-Plan cluster base URL; pay-as-you-go keys use api.xiaomimimo.com.
+_mimo_api_key = os.environ.get("MIMO_API_KEY", "")
+_mimo_tts_api_key = os.environ.get("MIMO_TTS_API_KEY", "") or _mimo_api_key
+_raw_api_url = os.environ.get("MIMO_API_URL") or default_mimo_api_url(_mimo_api_key)
+_raw_mimo_tts_api_url = (
+    os.environ.get("MIMO_TTS_API_URL")
+    or os.environ.get("MIMO_API_URL")
+    or default_mimo_api_url(_mimo_tts_api_key)
+)
+
+CONFIG = {
+    "api_url": normalize_api_url(_raw_api_url),
+    "api_key": _mimo_api_key,
+    "api_key_source": "MIMO_API_KEY",
+    "mimo_api_url": normalize_api_url(_raw_api_url),
+    "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_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", "冰糖"),
+    "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",
+        "自然、清晰、有感染力，像在给观众讲故事；随剧情起伏，该紧张时紧张、该动情时动情，不平铺直叙。",
+    ),
+    "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", ""),
+    "fish_tts_api_url": os.environ.get("FISH_TTS_API_URL", DEFAULT_FISH_TTS_API_URL),
+    "fish_tts_model": os.environ.get("FISH_TTS_MODEL", DEFAULT_FISH_TTS_MODEL),
+    "fish_tts_reference_id": os.environ.get(
+        "FISH_TTS_REFERENCE_ID", DEFAULT_FISH_TTS_REFERENCE_ID
+    ).strip(),
+    "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,  # 启用动态语速调节
+    "tts_workers": env_int("TTS_WORKERS", 4, minimum=1),  # TTS 并行合成线程数
+    "tts_retries": env_int("TTS_RETRIES", 3, minimum=1),  # 单段 TTS 失败重试次数
+    "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),
+}
+if isinstance(_EXISTING_CONFIG_REF, dict):
+    _EXISTING_CONFIG_REF.clear()
+    _EXISTING_CONFIG_REF.update(CONFIG)
+    CONFIG = _EXISTING_CONFIG_REF
+
+def narration_tempo_budget(tts_rate_offset=0.0, *, config=None):
+    """Return the canonical tempo budget shared by voiceover and assemble."""
+    cfg = config or CONFIG
+    global_speed = max(0.01, float(cfg.get("narration_speed", 1.0) or 1.0))
+    rate_factor = max(0.01, 1.0 + float(tts_rate_offset or 0.0))
+    cumulative_max = max(1.0, float(cfg.get("narration_cumulative_tempo_max", 1.35) or 1.35))
+    hard_max = max(cumulative_max, float(cfg.get("narration_cumulative_tempo_hard_max", 1.40) or 1.40))
+    legacy_segment_cap = max(1.0, float(cfg.get("tts_segment_tempo_max", 1.20) or 1.20))
+    segment_tempo_max = max(1.0, min(legacy_segment_cap, cumulative_max / (global_speed * rate_factor)))
+    return {
+        "global_narration_speed": global_speed,
+        "tts_rate_factor": rate_factor,
+        "cumulative_tempo_max": cumulative_max,
+        "cumulative_tempo_hard_max": hard_max,
+        "segment_tempo_max": segment_tempo_max,
+        "max_raw_duration_factor": global_speed * segment_tempo_max,
+    }
+
+def log(msg):
+    print(f"[video-recap] {msg}", flush=True)
+
+def run_cmd(cmd, **kwargs):
+    """运行命令，返回 CompletedProcess"""
+    if isinstance(cmd, list):
+        display_parts = []
+        for part in cmd:
+            text = str(part)
+            display_parts.append(text if len(text) <= 240 else text[:237] + "...")
+        display = " ".join(display_parts)
+    else:
+        display = str(cmd)
+        if len(display) > 2000:
+            display = display[:1997] + "..."
+    log(f"运行: {display}")
+    return subprocess.run(cmd, capture_output=True, text=True, **kwargs)
+
+def get_video_duration(video_path):
+    """获取视频时长（秒）"""
+    cmd = ["ffprobe", "-v", "quiet", "-show_entries", "format=duration",
+           "-of", "csv=p=0", str(video_path)]
+    result = run_cmd(cmd)
+    if result.returncode != 0:
+        return 0.0
+    try:
+        return float(result.stdout.strip())
+    except (TypeError, ValueError):
+        return 0.0
+
+def stable_json_dumps(value):
+    """Serialize values deterministically for non-secret cache fingerprints."""
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
+
+def stable_hash(value):
+    """Return an md5 digest for deterministic JSON-serializable values."""
+    return hashlib.md5(stable_json_dumps(value).encode("utf-8")).hexdigest()
+
+_FILE_FINGERPRINT_MEMO = {}
+
+
+def _file_identity(path):
+    """(device, inode, size, mtime_ns) — changes whenever the bytes could have changed."""
+    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
+def _retry_after_seconds(value, fallback):
+    """Parse Retry-After seconds or HTTP-date; return fallback on malformed input."""
+    if not value:
+        return fallback
+    try:
+        return max(fallback, max(0, int(value)))
+    except (TypeError, ValueError):
+        pass
+    try:
+        retry_at = parsedate_to_datetime(value)
+        if retry_at.tzinfo is None:
+            retry_at = retry_at.replace(tzinfo=timezone.utc)
+        return max(fallback, max(0, int((retry_at - datetime.now(timezone.utc)).total_seconds())))
+    except (TypeError, ValueError, IndexError, OverflowError):
+        return fallback
+
+
+_ERROR_DATA_URL_RE = re.compile(
+    r"data:(?:audio|video|image)/[^;,\s\"'<>]+;base64,[A-Za-z0-9+/=]+",
+    re.IGNORECASE,
+)
+_ERROR_KEY_RE = re.compile(r"\b(?:tp|sk)-[A-Za-z0-9_-]{8,}\b")
+
+
+def _sanitize_api_error(value, limit=500, *, extra_secrets=()):
+    """Bound transport diagnostics without echoing request media or credentials."""
+    text = _ERROR_DATA_URL_RE.sub("<redacted-data-url>", str(value or ""))
+    text = _ERROR_KEY_RE.sub("<redacted-key>", text)
+    for secret in extra_secrets:
+        if secret:
+            text = text.replace(str(secret), "<redacted-key>")
+    return text[:limit]
+
+def _api_headers(api_provider=None, api_url=None, api_key=None):
+    """Build MiMo auth headers (OpenAI-compatible chat/completions with an api-key header)."""
+    del api_provider, api_url  # MiMo is the only provider; signature kept for call sites
+    key = CONFIG.get("api_key", "") if api_key is None else api_key
+    return {
+        "Content-Type": "application/json",
+        "User-Agent": "video-recap/1.0",
+        "api-key": key,
+    }
+
+def _prepare_api_payload(payload, api_provider=None, api_url=None):
+    """Normalize payload fields for MiMo's OpenAI-compatible chat/completions API."""
+    del api_provider, api_url
+    normalized = dict(payload)
+    if "max_tokens" in normalized and "max_completion_tokens" not in normalized:
+        normalized["max_completion_tokens"] = normalized.pop("max_tokens")
+    model = str(normalized.get("model") or "")
+    if (
+        CONFIG.get("mimo_disable_thinking", True)
+        and not model.endswith(("-tts", "-asr"))
+        and "thinking" not in normalized
+    ):
+        # MiMo V2.5 may spend small max_completion_tokens budgets on reasoning_content.
+        # The recap pipeline needs visible text, so disable thinking unless set explicitly.
+        normalized["thinking"] = {"type": "disabled"}
+    return normalized
+
+def _mimo_endpoint(kind):
+    """Return per-capability MiMo endpoint settings (video understanding / TTS / ASR)."""
+    by_kind = {
+        "video": ("mimo_video_api_url", "mimo_video_api_key", "mimo_video_api_key_source"),
+        "tts": ("mimo_tts_api_url", "mimo_tts_api_key", "mimo_tts_api_key_source"),
+        "asr": ("mimo_asr_api_url", "mimo_asr_api_key", "mimo_asr_api_key_source"),
+    }
+    if kind not in by_kind:
+        raise ValueError(f"Unsupported MiMo endpoint kind: {kind}")
+    url_key, key_key, src_key = by_kind[kind]
+    return {
+        "api_url": CONFIG.get(url_key) or CONFIG.get("mimo_api_url"),
+        "api_key": CONFIG.get(key_key) or CONFIG.get("mimo_api_key"),
+        "api_key_source": CONFIG.get(src_key, "MIMO_API_KEY"),
+    }
+
+def _call_mimo_endpoint(kind, payload, max_retries=10):
+    settings = _mimo_endpoint(kind)
+    return api_call(
+        payload,
+        max_retries=max_retries,
+        api_provider="mimo",
+        api_url=settings["api_url"],
+        api_key=settings["api_key"],
+        api_key_source=settings["api_key_source"],
+    )
+
+def mimo_tts_api_call(payload, max_retries=10):
+    """Call the MiMo TTS endpoint."""
+    return _call_mimo_endpoint("tts", payload, max_retries=max_retries)
+
+def mimo_asr_api_call(payload, max_retries=10):
+    """Call the MiMo speech-recognition (ASR) endpoint."""
+    return _call_mimo_endpoint("asr", payload, max_retries=max_retries)
+
+def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key=None, api_key_source=None):
+    """调用 OpenAI-compatible API，带重试。
+
+    集群的 429 限流是常态而非错误，所以重试更耐心（更多次数 + 退避封顶 60s + 遵从 Retry-After），
+    避免一次瞬时限流就中止整个阶段。配额窗口常以分钟计，所以 429 在没有 Retry-After 时也至少等 10s。
+    """
+    endpoint = normalize_api_url(api_url if api_url is not None else CONFIG["api_url"])
+    headers = _api_headers(api_provider=api_provider, api_url=endpoint, api_key=api_key)
+    data = json.dumps(_prepare_api_payload(payload, api_provider=api_provider, api_url=endpoint)).encode("utf-8")
+
+    for attempt in range(max_retries):
+        try:
+            req = urllib.request.Request(endpoint, data=data, headers=headers)
+            with urllib.request.urlopen(req, timeout=300) as resp:
+                result = json.loads(resp.read().decode("utf-8"))
+                return result
+        except urllib.error.HTTPError as e:
+            body = _sanitize_api_error(e.read().decode("utf-8", errors="replace"))
+            wait = min(2 ** attempt, 60)
+            if e.code == 429:
+                retry_after = e.headers.get("Retry-After")
+                wait = _retry_after_seconds(retry_after, max(wait, 10))
+                log(f"API 速率限制 (尝试 {attempt+1}/{max_retries}), 等待 {wait}s")
+            elif e.code == 401:
+                key_name = api_key_source or CONFIG.get("api_key_source", "MIMO_API_KEY")
+                raise RuntimeError(f"API 认证失败 (401)。请检查 {key_name} 和 API URL 是否匹配。")
+            elif e.code == 403:
+                hint = "API 访问被拒绝 (403)。"
+                if "1010" in body or "cloudflare" in body.lower():
+                    hint += "IP 被 Cloudflare 限流，请等待几分钟后重试。"
+                    raise RuntimeError(hint)
+                hint += "请检查 API key 权限和 API URL 设置。"
+                raise RuntimeError(hint)
+            elif e.code == 405:
+                raise RuntimeError("API 端点不可用 (405)，可能被 WAF 拦截。请检查 MIMO_API_URL 或稍后重试。")
+            elif e.code == 503:
+                log(f"API 服务暂不可用 (503)，等待 {wait}s (尝试 {attempt+1}/{max_retries})")
+            elif e.code == 524:
+                # Cloudflare 超时：服务端处理超时，需要更长退避
+                wait = max(wait, 4 * (attempt + 1))
+                log(f"API 超时 (524)，等待 {wait}s (尝试 {attempt+1}/{max_retries})")
+            else:
+                log(f"API 调用失败 (尝试 {attempt+1}/{max_retries}): HTTP {e.code} — {body}")
+            if attempt < max_retries - 1:
+                time.sleep(wait)
+            else:
+                raise RuntimeError(f"API 调用失败 {max_retries} 次: HTTP {e.code} — {body}")
+        except Exception as e:  # noqa: BLE001 - transport/decode faults are all retryable here
+            # (Deliberately broad, but no longer written as `(URLError, Exception)`, which
+            # read as a tuple while `Exception` already subsumed the first member.)
+            wait = min(2 ** attempt, 60)
+            safe_error = _sanitize_api_error(e)
+            log(f"API 调用失败 (尝试 {attempt+1}/{max_retries}): {safe_error}")
+            if attempt < max_retries - 1:
+                log(f"等待 {wait}s 后重试...")
+                time.sleep(wait)
+            else:
+                raise RuntimeError(f"API 调用失败 {max_retries} 次: {safe_error}")
+    # Unreachable for max_retries >= 1; guards against a silent `None` return (and the
+    # TypeError it would cause at the caller's resp["choices"]) if a caller passes 0.
+    raise ValueError(f"max_retries must be >= 1, got {max_retries}")
+
+def _text_char_count(text):
+    """计算文本的有效字数（去除标点和空白，这些不占 TTS 朗读时间）。"""
+    return len(re.sub(r'[，。！？、；：…“”‘’《》〈〉\s"\'「」『』（）()【】\[\]—～·,.!?;:\\-]', '', text or ""))
+
+
+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/tts_audio.py

@@ -0,0 +1,113 @@
+"""Loudness normalization 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
+can reuse the returned metadata without pulling in the synthesis path.
+"""
+import array
+import math
+import os
+import sys
+import wave
+from pathlib import Path
+
+from lib import CONFIG, log
+
+
+def _normalize_tts_wav_rms(input_wav, output_wav, *, target_rms_dbfs=-20.0, peak_limit=0.98):
+    """Normalize a mono/stereo 16-bit WAV to a target RMS with peak guard.
+
+    This helper is intentionally dependency-free so QC/assembly can reuse the
+    returned metadata even when normalization is applied in a later lane.
+    """
+    input_wav = Path(input_wav)
+    output_wav = Path(output_wav)
+    with wave.open(str(input_wav), "rb") as wf:
+        channels = wf.getnchannels()
+        sampwidth = wf.getsampwidth()
+        framerate = wf.getframerate()
+        frames = wf.getnframes()
+        data = wf.readframes(frames)
+    if sampwidth != 2:
+        raise ValueError(f"仅支持 16-bit PCM WAV: {input_wav}")
+
+    # array('h') decodes the whole block in C. The previous per-sample int.from_bytes
+    # comprehension ran three times over the audio (decode, normalize, re-decode the
+    # OUTPUT just to measure it) — about 420ms for a 12s block, times every narration
+    # segment. Same arithmetic, same rounding, one decode.
+    samples = array.array("h")
+    samples.frombytes(data[: len(data) - (len(data) % 2)])
+    if sys.byteorder != "little":  # wave data is little-endian regardless of host
+        samples.byteswap()
+    if not samples:
+        output_wav.write_bytes(input_wav.read_bytes())
+        return {
+            "rms_dbfs_before": None,
+            "rms_dbfs_after": None,
+            "peak_after": 0.0,
+            "gain_db": 0.0,
+        }
+    count = len(samples)
+    rms = math.sqrt(sum(s * s for s in samples) / count)
+    peak = max(max(samples), -min(samples)) / 32768.0
+    rms_dbfs_before = 20 * math.log10(max(rms, 1e-9) / 32768.0)
+    target_linear = 10 ** (float(target_rms_dbfs) / 20.0) * 32768.0
+    gain = target_linear / max(rms, 1e-9)
+    if peak > 0:
+        gain = min(gain, float(peak_limit) / peak)
+
+    # Accumulate the output statistics while normalizing instead of decoding the result back.
+    normalized = array.array("h", bytes(2 * count))
+    out_square_sum = 0
+    out_peak_raw = 0
+    for i in range(count):
+        value = max(-32768, min(32767, int(round(samples[i] * gain))))
+        normalized[i] = value
+        out_square_sum += value * value
+        if abs(value) > out_peak_raw:
+            out_peak_raw = abs(value)
+    out_bytes = normalized
+    if sys.byteorder != "little":
+        out_bytes = array.array("h", normalized)
+        out_bytes.byteswap()
+    with wave.open(str(output_wav), "wb") as wf:
+        wf.setnchannels(channels)
+        wf.setsampwidth(sampwidth)
+        wf.setframerate(framerate)
+        wf.writeframes(out_bytes.tobytes())
+
+    out_rms = math.sqrt(out_square_sum / count)
+    return {
+        "rms_dbfs_before": rms_dbfs_before,
+        "rms_dbfs_after": 20 * math.log10(max(out_rms, 1e-9) / 32768.0),
+        "peak_after": out_peak_raw / 32768.0,
+        "gain_db": 20 * math.log10(max(gain, 1e-9)),
+    }
+
+
+def _maybe_normalize_tts_wav(output_wav):
+    """Normalize a synthesized TTS block in-place when possible.
+
+    Unit tests often stub TTS with text bytes rather than real WAV. In that case
+    normalization is skipped safely; real MiMo WAV output gets RMS/peak metadata.
+    """
+    if not CONFIG.get("tts_segment_normalize", True):
+        return None
+    output_wav = Path(output_wav)
+    tmp = output_wav.with_name(f"{output_wav.stem}_norm{output_wav.suffix}")
+    try:
+        meta = _normalize_tts_wav_rms(
+            output_wav,
+            tmp,
+            target_rms_dbfs=float(CONFIG.get("tts_segment_target_rms_dbfs", -20.0) or -20.0),
+            peak_limit=float(CONFIG.get("tts_segment_peak_limit", 0.98) or 0.98),
+        )
+        os.replace(tmp, output_wav)
+        return meta
+    except Exception as exc:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+        log(f"  TTS RMS 归一跳过: {exc}")
+        return None