@oh-story/dsh 0.1.4 → 0.1.6

package/lib/video-recap/skills/video-assemble/scripts/jianying_writer.py

@@ -0,0 +1,394 @@
+"""Safe writer and portable media bundler for JianYing draft folders."""
+
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+import time
+import uuid
+import zipfile
+
+from jianying_templates import template
+
+
+DRAFT_PATH_PLACEHOLDER = "##_draftpath_placeholder_0E685133-18CE-45ED-8CB8-2904A212EC80_##"
+
+
+def validate_draft_name(draft_name):
+    """Reject draft names that could escape or alias the requested parent dir."""
+    if not isinstance(draft_name, str):
+        raise TypeError("draft_name must be a string")
+    if not draft_name or not draft_name.strip():
+        raise ValueError("draft_name must not be empty")
+    if os.path.isabs(draft_name):
+        raise ValueError("draft_name must be a plain folder name, not an absolute path")
+    if "/" in draft_name or "\\" in draft_name:
+        raise ValueError("draft_name must not contain path separators")
+    if draft_name in {".", ".."}:
+        raise ValueError("draft_name must not be '.' or '..'")
+
+
+def _resource_kind(material, materials_key):
+    if materials_key == "audios":
+        return "audio", "music"
+    if material.get("type") == "photo":
+        return "image", "photo"
+    return "video", "video"
+
+
+RESOURCE_DIRECTORY_BY_MATERIALS_KEY = {
+    "chromas": "effect",
+    "common_mask": "mask",
+    "effects": "effect",
+    "masks": "mask",
+    "stickers": "sticker",
+    "texts": "text",
+    "text_templates": "text_template",
+    "transitions": "transition",
+    "video_effects": "effect",
+}
+
+
+def _unused_name(directory, basename, used):
+    """Return a collision-free filename within one resource directory."""
+    name = basename
+    stem, ext = os.path.splitext(basename)
+    suffix = 1
+    while name in used or os.path.exists(os.path.join(directory, name)):
+        name = f"{stem}_{suffix}{ext}"
+        suffix += 1
+    used.add(name)
+    return name
+
+
+def _md5(path):
+    digest = hashlib.md5(usedforsecurity=False)
+    with open(path, "rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _meta_value(material, relative_path, metetype, copied_path, timestamp_ms):
+    duration = int(material.get("duration") or 0)
+    timestamp_s = timestamp_ms // 1000
+    value = template("meta_material")
+    value.update({
+        "duration": duration,
+        "height": int(material.get("height") or 0),
+        # duo-video indexes imported local resources independently from the
+        # draft-content material IDs.
+        "id": str(uuid.uuid4()).upper(),
+        "md5": _md5(copied_path),
+        "metetype": metetype,
+        "type": 0,
+        "width": int(material.get("width") or 0),
+        "create_time": timestamp_s,
+        "extra_info": os.path.basename(relative_path),
+        "file_Path": f"./{relative_path}",
+        "import_time": timestamp_s,
+        "import_time_ms": timestamp_ms,
+        "item_source": 1,
+        "roughcut_time_range": {"duration": duration, "start": 0},
+        "sub_time_range": {"duration": -1, "start": -1},
+    })
+    return value
+
+
+def _material_sets(content):
+    """Yield root and nested compound-draft material dictionaries."""
+    materials = content.get("materials")
+    if not isinstance(materials, dict):
+        return
+    yield materials
+    for draft in materials.get("drafts", []):
+        nested = draft.get("draft") if isinstance(draft, dict) else None
+        if isinstance(nested, dict):
+            yield from _material_sets(nested)
+
+
+def _replace_value(value, old, new):
+    if isinstance(value, dict):
+        for key, item in value.items():
+            value[key] = _replace_value(item, old, new)
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            value[index] = _replace_value(item, old, new)
+    elif isinstance(value, str):
+        if value == old:
+            return new
+        stripped = value.lstrip()
+        if stripped.startswith(("{", "[")):
+            try:
+                parsed = json.loads(value)
+            except json.JSONDecodeError:
+                return value
+            replaced = _replace_value(parsed, old, new)
+            return json.dumps(replaced, ensure_ascii=False, separators=(",", ":"))
+    return value
+
+
+def _safe_resource_target(target_path):
+    normalized = os.path.normpath(str(target_path).replace("\\", "/"))
+    if normalized in {"", "."} or os.path.isabs(normalized):
+        raise ValueError(f"invalid JianYing resource target_path: {target_path}")
+    if normalized == ".." or normalized.startswith("../"):
+        raise ValueError(f"JianYing resource target_path escapes package: {target_path}")
+    return normalized
+
+
+def _extract_zip(source, destination):
+    os.makedirs(destination, exist_ok=False)
+    destination_real = os.path.realpath(destination)
+    with zipfile.ZipFile(source) as archive:
+        for member in archive.infolist():
+            member_path = os.path.realpath(os.path.join(destination, member.filename))
+            if os.path.commonpath((destination_real, member_path)) != destination_real:
+                raise ValueError(f"unsafe path in JianYing resource archive: {member.filename}")
+        archive.extractall(destination)
+
+
+def _copy_resource(source, resource_kind, resources_root, used, target_path=None):
+    resource_dir = os.path.join(resources_root, resource_kind)
+    os.makedirs(resource_dir, exist_ok=True)
+    is_zip = os.path.isfile(source) and zipfile.is_zipfile(source)
+    if target_path is None:
+        basename = os.path.basename(source.rstrip(os.sep))
+        if is_zip:
+            basename = os.path.splitext(basename)[0]
+        relative_target = _unused_name(resource_dir, basename, used[resource_kind])
+    else:
+        relative_target = _safe_resource_target(target_path)
+    copied_path = os.path.join(resource_dir, relative_target)
+    copied_real = os.path.realpath(copied_path)
+    if os.path.commonpath((os.path.realpath(resource_dir), copied_real)) != os.path.realpath(resource_dir):
+        raise ValueError(f"JianYing resource target escapes package: {target_path}")
+    os.makedirs(os.path.dirname(copied_path), exist_ok=True)
+    if os.path.exists(copied_path):
+        raise FileExistsError(f"duplicate JianYing resource target: {relative_target}")
+    if is_zip:
+        _extract_zip(source, copied_path)
+    elif os.path.isdir(source):
+        shutil.copytree(source, copied_path)
+    else:
+        shutil.copy2(source, copied_path)
+    relative_path = f"Resources/local/{resource_kind}/{relative_target.replace(os.sep, '/')}"
+    return copied_path, relative_path, f"{DRAFT_PATH_PLACEHOLDER}/{relative_path}"
+
+
+def _is_packaged_path(value):
+    return str(value).startswith((DRAFT_PATH_PLACEHOLDER, "Resources/", "./Resources/"))
+
+
+def _descriptor(raw, default_kind, *, required):
+    if isinstance(raw, str):
+        source = raw
+        resource_kind = default_kind
+        target_path = None
+    elif isinstance(raw, dict):
+        source = raw.get("source_path") or raw.get("source")
+        resource_kind = raw.get("resource_kind") or raw.get("kind") or default_kind
+        target_path = raw.get("target_path")
+    else:
+        raise ValueError("JianYing resources entries must be paths or objects")
+    if not isinstance(source, str) or not source:
+        raise ValueError("JianYing resource source_path must be a non-empty string")
+    if not isinstance(resource_kind, str) or resource_kind not in {
+        "audio", "effect", "fonts", "image", "lut", "mask", "sticker",
+        "text", "text_template", "transition", "video",
+    }:
+        raise ValueError(f"invalid JianYing resource kind: {resource_kind}")
+    suffix = os.path.splitext(source)[1].lower()
+    if suffix == ".cube":
+        resource_kind = "lut"
+    elif suffix in {".ttf", ".otf"}:
+        resource_kind = "fonts"
+    return {
+        "source_path": source,
+        "resource_kind": resource_kind,
+        "target_path": target_path,
+        "required": required,
+    }
+
+
+def _material_resource_descriptors(material, default_kind):
+    descriptors = [
+        _descriptor(raw, default_kind, required=True)
+        for raw in material.get("_bundle_resources", [])
+    ]
+    path = material.get("path")
+    if isinstance(path, str) and path and not _is_packaged_path(path):
+        if not any(item["source_path"] == path for item in descriptors):
+            descriptors.append(_descriptor(path, default_kind, required=False))
+    return descriptors
+
+
+def bundle_media(content, meta, draft_dir):
+    """Copy media into duo-video's Resources/local contract and index it.
+
+    Materials that reference the same source file and resource kind share one
+    copied file and one meta entry. Missing sources remain untouched and are
+    reported to the caller so a non-portable reference is never disguised as a
+    successfully bundled one.
+    """
+    resources_root = os.path.join(draft_dir, "Resources", "local")
+    copied = {}
+    resource_kinds = {
+        "audio", "effect", "fonts", "image", "lut", "mask", "sticker",
+        "text", "text_template", "transition", "video",
+    }
+    used = {kind: set() for kind in resource_kinds}
+    meta_values = []
+    notes = []
+    timestamp_ms = int(time.time() * 1000)
+
+    material_sets = list(_material_sets(content))
+    for materials in material_sets:
+        for materials_key in ("videos", "audios"):
+            for material in materials.get(materials_key, []):
+                src = material.get("path")
+                if not src:
+                    continue
+                resource_kind, metetype = _resource_kind(material, materials_key)
+                source_key = (resource_kind, os.path.realpath(src))
+                existing = copied.get(source_key)
+                if existing is not None:
+                    material["path"] = existing["draft_path"]
+                    continue
+                if not os.path.isfile(src):
+                    if not _is_packaged_path(src):
+                        notes.append(f"素材缺失，未打包: {src}")
+                    continue
+
+                copied_path, relative_path, draft_path = _copy_resource(
+                    src, resource_kind, resources_root, used
+                )
+                material["path"] = draft_path
+                copied[source_key] = {"draft_path": draft_path}
+                meta_values.append(
+                    _meta_value(material, relative_path, metetype, copied_path, timestamp_ms)
+                )
+
+        for materials_key, resource_kind in RESOURCE_DIRECTORY_BY_MATERIALS_KEY.items():
+            for material in materials.get(materials_key, []):
+                descriptors = _material_resource_descriptors(
+                    material, resource_kind
+                )
+                seen_descriptors = set()
+                for descriptor in descriptors:
+                    src = descriptor["source_path"]
+                    if _is_packaged_path(src):
+                        continue
+                    descriptor_key = (
+                        descriptor["resource_kind"],
+                        os.path.realpath(src),
+                        descriptor["target_path"],
+                    )
+                    if descriptor_key in seen_descriptors:
+                        continue
+                    seen_descriptors.add(descriptor_key)
+                    if not os.path.exists(src):
+                        message = f"声明的剪映资源缺失: {src}"
+                        if descriptor["required"]:
+                            raise ValueError(message)
+                        notes.append(message)
+                        continue
+                    kind = descriptor["resource_kind"]
+                    source_key = (kind, os.path.realpath(src), descriptor["target_path"])
+                    existing = copied.get(source_key)
+                    if existing is None:
+                        _copied_path, _relative_path, draft_path = _copy_resource(
+                            src,
+                            kind,
+                            resources_root,
+                            used,
+                            target_path=descriptor["target_path"],
+                        )
+                        copied[source_key] = {"draft_path": draft_path}
+                    else:
+                        draft_path = existing["draft_path"]
+                    _replace_value(material, src, draft_path)
+
+    material_group = next(group for group in meta["draft_materials"] if group["type"] == 0)
+    material_group["value"] = meta_values
+    meta["draft_timeline_materials_size_"] = sum(
+        os.path.getsize(os.path.join(draft_dir, value["file_Path"][2:]))
+        for value in meta_values
+    )
+    return notes
+
+
+def strip_internal_resource_fields(content):
+    for materials in _material_sets(content):
+        for entries in materials.values():
+            if not isinstance(entries, list):
+                continue
+            for material in entries:
+                if isinstance(material, dict):
+                    material.pop("_bundle_resources", None)
+
+
+def draft_dir_has_user_content(draft_dir):
+    """Return True when writing here could overwrite an existing draft/material."""
+    if not os.path.exists(draft_dir):
+        return False
+    try:
+        return any(os.scandir(draft_dir))
+    except OSError:
+        return True
+
+
+def collision_safe_draft_dir(out_dir, draft_name):
+    """Pick a fresh draft folder instead of overwriting an existing non-empty one."""
+    validate_draft_name(draft_name)
+    base = os.path.join(out_dir, draft_name)
+    if not draft_dir_has_user_content(base):
+        return base, draft_name
+    idx = 2
+    while True:
+        candidate_name = f"{draft_name}_{idx}"
+        candidate = os.path.join(out_dir, candidate_name)
+        if not draft_dir_has_user_content(candidate):
+            return candidate, candidate_name
+        idx += 1
+
+
+def write_draft(content, meta, notes, out_dir, draft_name, bundle_media_enabled=False):
+    """Atomically write the three JianYing draft JSON files and optional bundle."""
+    validate_draft_name(draft_name)
+    out_dir = os.path.abspath(out_dir)
+    os.makedirs(out_dir, exist_ok=True)
+    draft_dir, actual_name = collision_safe_draft_dir(out_dir, draft_name)
+    notes = list(notes)
+    if actual_name != draft_name:
+        notes.append(f"草稿目录已存在，改写为 {actual_name} 以避免覆盖")
+
+    tmp_parent = tempfile.mkdtemp(prefix=f".{actual_name}.", dir=out_dir)
+    tmp_dir = os.path.join(tmp_parent, actual_name)
+    try:
+        os.makedirs(tmp_dir, exist_ok=False)
+        if bundle_media_enabled:
+            notes.extend(bundle_media(content, meta, tmp_dir))
+        strip_internal_resource_fields(content)
+        timestamp_ms = int(time.time() * 1000)
+        meta["draft_name"] = actual_name
+        meta["draft_fold_path"] = draft_dir
+        meta["tm_draft_create"] = timestamp_ms
+        meta["tm_draft_modified"] = timestamp_ms
+        content["name"] = actual_name
+        for fname in ("draft_content.json", "draft_info.json"):
+            with open(os.path.join(tmp_dir, fname), "w", encoding="utf-8") as f:
+                json.dump(content, f, ensure_ascii=False, indent=2)
+        with open(os.path.join(tmp_dir, "draft_meta_info.json"), "w", encoding="utf-8") as f:
+            json.dump(meta, f, ensure_ascii=False, indent=2)
+        if os.path.isdir(draft_dir) and not draft_dir_has_user_content(draft_dir):
+            os.rmdir(draft_dir)
+        os.replace(tmp_dir, draft_dir)
+    except Exception:
+        shutil.rmtree(tmp_parent, ignore_errors=True)
+        raise
+    finally:
+        if os.path.exists(tmp_parent):
+            shutil.rmtree(tmp_parent, ignore_errors=True)
+    return draft_dir, notes

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

@@ -0,0 +1,239 @@
+"""Self-contained config + utilities for this skill (no cross-skill imports)."""
+import os
+import subprocess
+from pathlib import Path
+
+
+# ── 配置 ──────────────────────────────────────────────────────────────
+_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
+
+
+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.
+
+# Cross-language source: when the original audio is in a language the narration is NOT in
+# (e.g. a Japanese drama recapped in Chinese), the original speech bleeding under the narration
+# is just noise the viewer can't parse — it reads as 怪音. In that mode the original is ducked to
+# near-silent UNDER narration; it still plays full-volume in the original-audio gap blocks, where
+# a single language is fine. Explicit SPEECH_DUCKING_VOLUME / ZONE_DUCKING_VOLUME still override.
+_foreign_source_audio = env_bool("FOREIGN_SOURCE_AUDIO", False)
+_foreign_under_narration_volume = 0.05  # original volume under narration when source audio is foreign
+
+CONFIG = {
+    "fade_ms": env_int("FADE_MS", 120, minimum=0),  # 每段 TTS 淡入淡出(ms)；过大会让紧凑的句子一顿一顿，120ms 防爆音又不发闷
+    "breath_ms": 250,  # 段间呼吸空间(ms)；block recap 块内连贯、块间留原声呼吸
+    "ducking_mode": "fixed",  # fixed | sidechaincompress | none
+    "ducking_threshold": 0.15,
+    "ducking_ratio": 3,
+    "ducking_attack": 10,
+    "ducking_release": 300,
+    "ducking_level_sc": 2.0,
+    "ducking_makeup": 1.2,
+    "ducking_narr_weight": 1.5,
+    "ducking_orig_volume": env_float("DUCKING_ORIG_VOLUME", 0.3, minimum=0.0),  # 解说时原声基准音量
+    # Derived report of the FOREIGN_SOURCE_AUDIO knob this skill implements: it selects the
+    # ducking volumes below. Declared so callers can see which policy is in effect.
+    "foreign_source_audio": _foreign_source_audio,
+    "zone_ducking_volume": env_float("ZONE_DUCKING_VOLUME",
+        _foreign_under_narration_volume if _foreign_source_audio else 0.12, minimum=0.0),  # 解说时原声压低到的音量
+    "idle_orig_volume": env_float("IDLE_ORIG_VOLUME", 1.0, minimum=0.0),  # 解说块之间的"原声块"音量：默认满音量(1.0)，让精彩原声整段放出来，不被压低（用户要求解说成块、原声也成块）
+    "duck_fade_seconds": env_float("DUCK_FADE_SECONDS", 0.3, minimum=0.0),  # 解说块/原声块切换的淡入淡出(秒)，略放宽到 0.3 让满音量↔压低的过渡更顺
+    "duck_bridge_seconds": env_float("DUCK_BRIDGE_SECONDS", 1.5, minimum=0.0),  # 仅把间隔小于此值的相邻解说窗口并成一段压低；超过则视为作者特意留的"原声块"，原声放回满音量。默认 1.5s：解说块内部连续压低，块与块之间的留白放出满音量原声。该值只控制短间隔合并，不设定旁白/原声配额。调大→更连续铺底、原声块更少；调小→更碎
+    "bgm_path": os.environ.get("BGM_PATH", "").strip(),  # 背景音乐文件(可选)，留空则不加 BGM
+    "source_video": os.environ.get("SOURCE_VIDEO", "").strip(),  # 剪辑模式下的原始视频(可选)，用于时间线/剪映导出引用原片片段
+    "export_jianying": env_bool("EXPORT_JIANYING", False),  # 渲染后可选导出剪映草稿(默认关；与核心解耦)
+    "jianying_draft_dir": os.environ.get("JIANYING_DRAFT_DIR", "").strip(),  # 剪映草稿输出父目录(留空=work_dir)
+    "jianying_bundle_media": env_bool("JIANYING_BUNDLE_MEDIA", True),  # 默认开：macOS 剪映沙箱读不到外部路径，须把素材拷进草稿目录
+    "bgm_volume": env_float("BGM_VOLUME", 0.18, minimum=0.0),  # BGM 铺底音量
+    "bgm_ducking_volume": env_float("BGM_DUCKING_VOLUME", 0.10, minimum=0.0),  # 旁白时 BGM 压低到的音量
+    "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 上限；实际会被累计预算收紧
+    "mask_source_subtitles": env_bool("MASK_SOURCE_SUBTITLES", False),  # 遮挡原片烧录字幕；必须配合显式 SOURCE_SUBTITLE_MASK_POLICY
+    "source_subtitle_mask_policy_declared": bool(os.environ.get("SOURCE_SUBTITLE_MASK_POLICY", "").strip()),
+    "source_subtitle_mask_policy": (
+        os.environ.get("SOURCE_SUBTITLE_MASK_POLICY", "").strip().lower()
+        or "off"
+    ),  # off | opt_in | safe | forced；MASK_SOURCE_SUBTITLES alone is legacy implicit and QC-blocking
+    "source_subtitle_mask_ratio": env_float("SOURCE_SUBTITLE_MASK_RATIO", 0.14, minimum=0.0),  # 底部遮挡比例
+    "source_subtitle_mask_timing": os.environ.get("SOURCE_SUBTITLE_MASK_TIMING", "narration").strip().lower(),  # all | narration；增强版默认仅解说时遮罩
+    "subtitle_mask_opacity": min(1.0, env_float("SUBTITLE_MASK_OPACITY", 0.6, minimum=0.0)),  # 0=透明，1=全黑；增强版默认半透明
+    "subtitle_mask_padding": env_int("SUBTITLE_MASK_PADDING", 4, minimum=0),
+    "subtitle_y_top": env_int("SUBTITLE_Y_TOP", -1, minimum=-1),  # 自动旋转后的显示画布坐标；top/bot 同时有效时贴合原字幕带
+    "subtitle_y_bot": env_int("SUBTITLE_Y_BOT", -1, minimum=-1),
+    "narration_delay_seconds": env_float("NARRATION_DELAY_SECONDS", 0.0, minimum=0.0),  # 默认严格采用 Agent 写入的 start；旧项目可显式恢复延迟
+    "narration_tighten": env_bool("NARRATION_TIGHTEN", True),  # 段落内把句子紧贴上一句实际收尾播放，句间间隔稳定≤tight_pause，杜绝"一句解说一段空白"的卡顿
+    "narration_run_gap_seconds": env_float("NARRATION_RUN_GAP_SECONDS", 1.6, minimum=0.0),  # 作者留白超过此值=新段落（让精彩原声透出）；小于则视为同一连续段落
+    "narration_tight_pause_seconds": env_float("NARRATION_TIGHT_PAUSE_SECONDS", 0.35, minimum=0.0),  # 段落内句间固定间隔(秒)
+    "narration_max_pull_seconds": env_float("NARRATION_MAX_PULL_SECONDS", 1.2, minimum=0.0),  # 收紧时一句最多比作者标注提前的秒数（漂移上限，越小越贴画面）
+    "narration_tail_pad_seconds": 0.1,  # 解说尾部最少留白；短 slot 会自动压低 delay 避免截断
+    "quiet_overlap_min_ratio": 0.8,  # 解说段至少多少比例落在安静窗口内才标记为非对白重叠
+    "speech_ducking_volume": env_float("SPEECH_DUCKING_VOLUME",
+        _foreign_under_narration_volume if _foreign_source_audio else 0.2, minimum=0.0),    # 解说与对白重叠时原声音量
+    "burn_subtitles": env_bool("BURN_SUBTITLES", True),  # 烧录解说字幕（默认开；遮挡原字幕后需自带字幕，否则字幕区空白）
+    "subtitle_original_in_gaps": env_bool("SUBTITLE_ORIGINAL_IN_GAPS", True),  # 原声留白处补烧原声台词字幕（来自 ASR）
+    "force_video_reencode": env_bool("FORCE_VIDEO_REENCODE", False),  # 组装时重编码视频，修复部分容器时间戳问题
+    # 成片压制（仅在重编码时生效：烧字幕/遮罩/缩放/FORCE_VIDEO_REENCODE 任一触发重编码）。
+    "output_crf": env_int("OUTPUT_CRF", 18, minimum=0),          # x264 CRF；越大文件越小、画质越低（18≈视觉无损，23~26 体积更小）
+    "output_preset": os.environ.get("OUTPUT_PRESET", "veryfast"),  # x264 preset；slow/slower 同 CRF 下体积更小但更慢
+    "output_max_height": env_int("OUTPUT_MAX_HEIGHT", 0, minimum=0),  # >0 时把成片高度上限缩到该值(保持宽高比、偶数宽)；0=不缩放
+    # 成片末端整体响度归一（默认混音偏轻，归一后更接近常见短视频响度；样片约 -11.9，默认取更安全的 -14）
+    "final_loudnorm": env_bool("FINAL_LOUDNORM", True),  # 组装末端做一次整体响度归一
+    "target_lufs": env_float("TARGET_LUFS", -14.0),       # 目标综合响度 (LUFS)
+    "target_true_peak": env_float("TARGET_TRUE_PEAK", -1.0),  # 目标真峰值 (dBTP)
+    "target_lra": env_float("TARGET_LRA", 11.0),          # 目标响度范围 (LU)
+    "final_limiter_peak": env_float("FINAL_LIMITER_PEAK", 0.98, minimum=0.1),  # loudnorm 后峰值保护 limiter
+    "subtitle_font_name": os.environ.get("SUBTITLE_FONT_NAME", "Arial"),
+    "subtitle_font_size": env_int("SUBTITLE_FONT_SIZE", 42, minimum=8),
+    "subtitle_primary_color": os.environ.get("SUBTITLE_PRIMARY_COLOR", "&H00FFFFFF"),
+    "subtitle_outline_color": os.environ.get("SUBTITLE_OUTLINE_COLOR", "&H00000000"),
+    "subtitle_outline": env_float("SUBTITLE_OUTLINE", 2.0, minimum=0.0),
+    "subtitle_shadow": env_float("SUBTITLE_SHADOW", 1.0, minimum=0.0),
+    "subtitle_margin_v": env_int("SUBTITLE_MARGIN_V", 48, minimum=0),
+    "subtitle_margin_l": env_int("SUBTITLE_MARGIN_L", 40, minimum=0),
+    "subtitle_margin_r": env_int("SUBTITLE_MARGIN_R", 40, minimum=0),
+    "subtitle_alignment": env_int("SUBTITLE_ALIGNMENT", 2, minimum=1),
+    "subtitle_max_chars": env_int("SUBTITLE_MAX_CHARS", 20, minimum=6),
+    "subtitle_max_lines": env_int("SUBTITLE_MAX_LINES", 2, minimum=1),
+    "subtitle_play_res_x": env_int("SUBTITLE_PLAY_RES_X", 1280, minimum=1),
+    "subtitle_play_res_y": env_int("SUBTITLE_PLAY_RES_Y", 720, minimum=1),
+}
+if isinstance(_EXISTING_CONFIG_REF, dict):
+    _EXISTING_CONFIG_REF.clear()
+    _EXISTING_CONFIG_REF.update(CONFIG)
+    CONFIG = _EXISTING_CONFIG_REF
+
+SCRIPT_DIR = Path(__file__).parent
+PROMPTS_DIR = SCRIPT_DIR.parent / "references"
+
+def narration_tempo_budget(tts_rate_offset=0.0, *, config=None):
+    """Return the canonical tempo budget shared by voiceover and assemble.
+
+    `effective_tempo` is the user-perceived cumulative compression:
+    TTS rate × global narration atempo × per-segment atempo.  The segment atempo
+    cap is therefore tightened by the configured global speed and TTS rate
+    offset; callers must fail/shorten instead of time-trimming speech when the
+    needed ratio exceeds `segment_tempo_max`.
+    """
+    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