@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-assemble/scripts/{jianying_builders.py → jianying/builders.py}

@@ -4,9 +4,9 @@ import json
 import os
 from copy import deepcopy
 
-from jianying_schema import scrub_platform_identity, us, validate_material_category
-from jianying_templates import template
-from jianying_tracks import SEGMENT_RENDER_INDEX
+from jianying.schema import scrub_platform_identity, us
+from jianying.templates import template
+from jianying.tracks import SEGMENT_RENDER_INDEX
 
 
 def timerange(start_us, dur_us):
@@ -83,9 +83,10 @@ def windowed_volume_keyframes(keyframes, seg_start_s, seg_end_s, default_gain, n
 
 
 def clip_from_segment(segment):
-    scale = segment.get("scale") if isinstance(segment.get("scale"), dict) else {}
-    position = segment.get("position") if isinstance(segment.get("position"), dict) else {}
-    flip = segment.get("flip") if isinstance(segment.get("flip"), dict) else {}
+    """Map optional authoring transforms (validated as objects by the timeline contract)."""
+    scale = segment.get("scale", {})
+    position = segment.get("position", {})
+    flip = segment.get("flip", {})
     return {
         "alpha": round(float(segment.get("opacity", 1.0)), 4),
         "flip": {
@@ -220,13 +221,6 @@ def rich_text_content(text, base_style=None, words=None, style_presets=None):
     return content
 
 
-def unsupported_track_note(kind):
-    info = validate_material_category(kind)
-    if info["supported"]:
-        return None
-    return info.get("note")
-
-
 RESOURCE_TRACKS = {
     "sound": "audios",
     "sticker": "stickers",
@@ -237,17 +231,12 @@ RESOURCE_TRACKS = {
 
 
 def _resource_material(segment, kind, new_id):
-    raw = segment.get("material")
+    """The contract guarantees exactly one of material / resource_config (resolved package)."""
     config = segment.get("resource_config")
-    if raw is not None and config is not None:
-        raise ValueError(f"{kind} segment must use either material or resource_config, not both")
-    if config is not None:
-        if not isinstance(config, dict):
-            raise ValueError(f"{kind} resource_config must be an object")
-        raw = config.get("main_config")
-        if not isinstance(raw, dict):
-            raise ValueError(f"{kind} resource_config.main_config must be an object")
-        raw = deepcopy(raw)
+    if config is None:
+        raw = deepcopy(segment["material"])
+    else:
+        raw = deepcopy(config["main_config"])
         resource_id = config.get("resource_id")
         if resource_id is not None:
             raw.setdefault("resource_id", resource_id)
@@ -257,10 +246,6 @@ def _resource_material(segment, kind, new_id):
         if kind == "sticker" and cover_img:
             raw["icon_url"] = cover_img
             raw["preview_cover_url"] = cover_img
-    elif not isinstance(raw, dict):
-        raise ValueError(f"{kind} segment requires material or resource_config")
-    else:
-        raw = deepcopy(raw)
     raw["id"] = new_id()
     return raw
 
@@ -269,7 +254,7 @@ def build_resource_track(ctx, timeline_track):
     kind = timeline_track["kind"]
     materials_key = RESOURCE_TRACKS[kind]
     track_name = timeline_track.get("name", kind)
-    for item in timeline_track.get("segments", []):
+    for item in timeline_track["segments"]:
         ts, te = float(item["timeline_start"]), float(item["timeline_end"])
         duration_us = us(te - ts)
         authored_item = item
@@ -295,8 +280,6 @@ def build_resource_track(ctx, timeline_track):
             ctx.materials["effects"].extend(subordinate_effects)
         seg = base_segment(material["id"], us(ts), duration_us, 1.0, [], ctx.new_id)
         speed_value = float(item.get("speed", 1.0))
-        if speed_value <= 0:
-            raise ValueError(f"{kind} segment speed must be greater than 0")
         seg["source_timerange"] = timerange(0, round(duration_us * speed_value))
         seg["track_render_index"] = 0
         seg["extra_material_refs"] = []
@@ -310,8 +293,6 @@ def build_resource_track(ctx, timeline_track):
 
 
 def _attachment_material(spec, kind, new_id):
-    if not isinstance(spec, dict):
-        raise ValueError(f"video {kind} must be an object")
     material = deepcopy(spec)
     config = material.pop("main_config", None)
     resources = material.pop("resources", None)
@@ -400,18 +381,14 @@ def _track_object(ctx, name, track_type, segments, flag):
 
 def build_compound_video(ctx, clip, material, foreground_segment, track_name, ts, te):
     """Build duo-video's nested green-screen/compound draft structure."""
-    background_spec = clip.get("green_background")
-    chroma_spec = _resolve_attachment_spec(ctx, clip.get("chroma"), "chroma")
-    if not isinstance(background_spec, dict) or not isinstance(chroma_spec, dict):
-        raise ValueError("compound green-screen clips require green_background and chroma objects")
+    background_spec = clip["green_background"]
+    chroma_spec = _resolve_attachment_spec(ctx, clip["chroma"], "chroma")
 
     duration_us = us(te - ts)
-    full_material_duration_us = int(material.get("duration") or duration_us)
+    full_material_duration_us = material["duration"]
     outer_source_timerange = deepcopy(foreground_segment["source_timerange"])
     outer_target_timerange = deepcopy(foreground_segment["target_timerange"])
-    background_path = background_spec.get("source_path")
-    if not isinstance(background_path, str) or not background_path:
-        raise ValueError("green_background.source_path must be a non-empty string")
+    background_path = background_spec["source_path"]
 
     background_id = ctx.new_id()
     background = template("video")
@@ -495,20 +472,21 @@ def build_compound_video(ctx, clip, material, foreground_segment, track_name, ts
 
 def build_video_track(ctx, timeline_track):
     track_name = timeline_track.get("name", "video")
-    for clip in timeline_track.get("clips", []):
+    for clip in timeline_track["clips"]:
         ts, te = float(clip["timeline_start"]), float(clip["timeline_end"])
         ss, se = float(clip["source_start"]), float(clip["source_end"])
         path = clip["source_path"]
         speed_value = float(clip.get("speed", 1.0))
-        if speed_value <= 0:
-            raise ValueError("video clip speed must be greater than 0")
         reverse = bool(clip.get("reverse", False))
         if reverse:
-            reverse_path = clip.get("reverse_path")
-            if not isinstance(reverse_path, str) or not reverse_path:
+            # The contract allows omitting reverse_path so export_timeline_to_jianying
+            # can generate it; building directly from such a clip is an authoring error.
+            if "reverse_path" not in clip:
                 raise ValueError("reverse video clips require a local reverse_path")
-            path = reverse_path
-        src_dur_us, width, height = ctx.media_duration(path, us(se))
+            path = clip["reverse_path"]
+        src_dur_us, width, height = ctx.probe(path)
+        if src_dur_us <= 0:
+            raise ValueError(f"JianYing video source has no probed duration: {path}")
         mat_id = ctx.new_id()
         material = template("video")
         material.update({
@@ -546,17 +524,17 @@ def build_video_track(ctx, timeline_track):
 def build_audio_track(ctx, timeline_track):
     role = timeline_track.get("role", timeline_track.get("name", "audio"))
     track_name = timeline_track.get("name", role)
-    for segment in timeline_track.get("segments", []):
+    for segment in timeline_track["segments"]:
         ts, te = float(segment["timeline_start"]), float(segment["timeline_end"])
         path = segment["source_path"]
-        mat_dur_us, _width, _height = ctx.media_duration(path, us(te - ts))
+        mat_dur_us, _width, _height = ctx.probe(path)
+        if mat_dur_us <= 0:
+            raise ValueError(f"JianYing audio source has no probed duration: {path}")
         want_us = us(te - ts)
         speed_value = float(segment.get("speed", 1.0))
-        if speed_value <= 0:
-            raise ValueError("audio segment speed must be greater than 0")
         place_us = want_us
         required_source_us = int(round(want_us * speed_value))
-        if mat_dur_us and required_source_us > mat_dur_us:
+        if required_source_us > mat_dur_us:
             if role == "bgm" and timeline_track.get("loop"):
                 place_us = want_us
             else:
@@ -569,14 +547,14 @@ def build_audio_track(ctx, timeline_track):
         mat_id = ctx.new_id()
         material = template("audio")
         material.update({
-            "duration": int(mat_dur_us or want_us),
+            "duration": int(mat_dur_us),
             "id": mat_id,
             "path": path,
         })
         ctx.materials["audios"].append(material)
         keyframes = volume_keyframes(segment.get("volume_keyframes"), ts, ctx.new_id)
         volume = segment.get("gain", 1.0) if not keyframes else 1.0
-        if role == "bgm" and timeline_track.get("loop") and mat_dur_us and required_source_us > mat_dur_us:
+        if role == "bgm" and timeline_track.get("loop") and required_source_us > mat_dur_us:
             cursor = 0
             while cursor < want_us:
                 piece = min(int(mat_dur_us / speed_value), want_us - cursor)
@@ -613,9 +591,9 @@ def build_audio_track(ctx, timeline_track):
 def build_text_track(ctx, timeline_track):
     track_name = timeline_track.get("name", "text")
     track_kind = "subtitle" if track_name == "subtitle" else "text"
-    for segment in timeline_track.get("segments", []):
+    for segment in timeline_track["segments"]:
         ts, te = float(segment["timeline_start"]), float(segment["timeline_end"])
-        text = segment.get("text", "")
+        text = segment["text"]
         mat_id = ctx.new_id()
         authored_style = dict(ctx.style_presets.get(str(segment.get("style_id")), {}))
         authored_style.update(segment.get("style") or {})
@@ -691,11 +669,11 @@ def build_text_track(ctx, timeline_track):
 def build_image_track(ctx, timeline_track):
     """Build local image overlays as JianYing photo materials on video tracks."""
     track_name = timeline_track.get("name", "image")
-    for segment in timeline_track.get("segments", []):
+    for segment in timeline_track["segments"]:
         ts, te = float(segment["timeline_start"]), float(segment["timeline_end"])
         duration_us = us(te - ts)
         path = segment["source_path"]
-        _ignored_duration, width, height = ctx.media_duration(path, duration_us)
+        _still_image_duration, width, height = ctx.probe(path)
         mat_id = ctx.new_id()
         material = template("video")
         material.update({
@@ -710,8 +688,6 @@ def build_image_track(ctx, timeline_track):
         ctx.materials["videos"].append(material)
         seg = base_segment(mat_id, us(ts), duration_us, 1.0, [], ctx.new_id)
         speed_value = float(segment.get("speed", 1.0))
-        if speed_value <= 0:
-            raise ValueError("image segment speed must be greater than 0")
         seg["source_timerange"] = timerange(0, round(duration_us * speed_value))
         seg["clip"] = clip_from_segment(segment)
         seg["speed"] = speed_value
@@ -727,8 +703,8 @@ def build_image_track(ctx, timeline_track):
 
 
 def build_timeline_track(ctx, timeline_track):
-    kind = timeline_track.get("kind")
-    if kind in ("audio", "text") and not timeline_track.get("segments"):
+    kind = timeline_track["kind"]
+    if kind in ("audio", "text") and not timeline_track["segments"]:
         return
     if kind == "video":
         build_video_track(ctx, timeline_track)
@@ -738,9 +714,5 @@ def build_timeline_track(ctx, timeline_track):
         build_text_track(ctx, timeline_track)
     elif kind == "image":
         build_image_track(ctx, timeline_track)
-    elif kind in RESOURCE_TRACKS:
+    else:  # normalize_timeline admits only RESOURCE_TRACKS kinds past this point
         build_resource_track(ctx, timeline_track)
-    else:
-        note = unsupported_track_note(kind)
-        if note:
-            ctx.note(note)

package/lib/video-recap/skills/video-assemble/scripts/{jianying_model.py → jianying/model.py}

@@ -1,11 +1,10 @@
 """Thin internal model used at the JianYing adapter boundary."""
 
-import os
 from dataclasses import dataclass, field
 from collections.abc import Callable
 
-from jianying_schema import us
-from jianying_tracks import TrackAllocator
+from jianying.schema import us
+from jianying.tracks import TrackAllocator
 
 
 ProbeFn = Callable[[str], tuple[int, int, int]]
@@ -50,7 +49,7 @@ class DraftBuildContext:
 
     @classmethod
     def from_timeline(cls, timeline, new_id, probe):
-        """Build from a timeline already validated by jianying_timeline_contract."""
+        """Build from a timeline already validated by jianying.timeline_contract."""
         canvas = timeline["canvas"]
         return cls(
             width=canvas["width"],
@@ -63,13 +62,6 @@ class DraftBuildContext:
             style_presets=timeline.get("style_presets", {}),
         )
 
-    def media_duration(self, path, fallback_us):
-        """(duration_us, width, height) probed from the file; images and missing files fall back."""
-        if os.path.exists(path):
-            duration_us, width, height = self.probe(path)
-            return duration_us or fallback_us, width, height
-        return fallback_us, 0, 0
-
     def add_segment(self, kind, base_name, start_us, duration_us, segment):
         allocated = self.track_allocator.allocate(kind, base_name, start_us, duration_us)
         track = next(

package/lib/video-recap/skills/video-assemble/scripts/{jianying_optional.py → jianying/optional.py}

@@ -4,7 +4,7 @@ from pathlib import Path
 
 from lib import CONFIG, log
 
-def _maybe_export_jianying(work_dir, out_dir, stem):
+def maybe_export_jianying(work_dir, out_dir, stem):
     """Lazy-import the optional 剪映 exporter and write a draft from timeline.json.
 
     The export is a documented fail-open sidecar: any failure is logged and never

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

@@ -0,0 +1,53 @@
+"""Schema constants and skeleton factories for JianYing export.
+
+This module is intentionally data-oriented: it owns draft version metadata and
+the full `materials` parallel-array shape.
+"""
+
+from jianying.templates import template
+
+# The full 剪映 materials object: ~45 parallel arrays. Only arrays backed by a
+# production builder are populated; retaining the full shape preserves compatibility.
+MATERIAL_KEYS = ["ai_translates", "audio_balances", "audio_effects", "audio_fades", "audio_track_indexes", "audios", "beats", "canvases", "chromas", "color_curves", "digital_humans", "drafts", "effects", "flowers", "green_screens", "handwrites", "hsl", "images", "log_color_wheels", "loudnesses", "manual_deformations", "masks", "common_mask", "material_animations", "material_colors", "multi_language_refs", "placeholders", "plugin_effects", "primary_color_wheels", "realtime_denoises", "shapes", "smart_crops", "smart_relights", "sound_channel_mappings", "speeds", "stickers", "tail_leaders", "text_templates", "texts", "time_marks", "transitions", "video_effects", "video_trackings", "videos", "vocal_beautifys", "vocal_separations"]
+
+
+def us(seconds):
+    """Seconds (float) -> integer microseconds. The single seconds->µs boundary."""
+    return int(round(float(seconds) * 1_000_000))
+
+
+def full_materials(filled):
+    """Return a complete JianYing `materials` object with all known arrays."""
+    out = {k: [] for k in MATERIAL_KEYS}
+    out.update(filled)
+    return out
+
+
+def scrub_platform_identity(project):
+    """Remove hardware fingerprints carried by the pinned upstream templates."""
+    for platform_key in ("last_modified_platform", "platform"):
+        for identity_key in ("device_id", "hard_disk_id", "mac_address"):
+            project[platform_key][identity_key] = ""
+    return project
+
+
+def draft_content_skeleton(draft_id, width, height, fps, total_us, materials, tracks):
+    """Build the root `draft_content.json` / `draft_info.json` skeleton."""
+    content = template("project")
+    scrub_platform_identity(content)
+    content["canvas_config"] = {"width": width, "height": height, "ratio": "original"}
+    content["duration"] = int(total_us)
+    content["fps"] = float(fps)
+    content["id"] = draft_id
+    content["materials"] = full_materials(materials)
+    content["tracks"] = tracks
+    return content
+
+
+def meta_info(draft_id, total_us):
+    """Build the companion `draft_meta_info.json` skeleton."""
+    meta = template("meta")
+    meta["draft_id"] = draft_id
+    meta["draft_timeline_materials_size_"] = 0
+    meta["tm_duration"] = int(total_us)
+    return meta

package/lib/video-recap/skills/video-assemble/scripts/{jianying_templates.py → jianying/templates.py}

@@ -6,7 +6,7 @@ from functools import lru_cache
 from pathlib import Path
 
 
-_TEMPLATE_DIR = Path(__file__).resolve().parent.parent / "references" / "jianying"
+_TEMPLATE_DIR = Path(__file__).resolve().parent.parent.parent / "references" / "jianying"
 _TEMPLATE_FILES = {
     "project": "empty_jy_project_info.json",
     "video": "empty_jy_material_video.json",

package/lib/video-recap/skills/video-assemble/scripts/{jianying_timeline_contract.py → jianying/timeline_contract.py}

@@ -45,6 +45,19 @@ def _validate_span(item, path, start_key="timeline_start", end_key="timeline_end
         _error(f"{path}.{end_key}", f"must be greater than {start_key}")
 
 
+def _validate_transform(item, path):
+    for field in ("scale", "position", "flip"):
+        if field in item and not isinstance(item[field], dict):
+            _error(f"{path}.{field}", "must be an object")
+
+
+def _validate_resources(resources, path):
+    if not isinstance(resources, list) or any(not isinstance(item, dict) for item in resources):
+        _error(path, "must contain source_path objects")
+    for index, item in enumerate(resources):
+        _require_string(item, "source_path", f"{path}[{index}]")
+
+
 def _validate_video_clip(clip, path):
     if not isinstance(clip, dict):
         _error(path, "must be an object")
@@ -68,18 +81,30 @@ def _validate_video_clip(clip, path):
             )
     if "reverse" in clip and not isinstance(clip["reverse"], bool):
         _error(f"{path}.reverse", "must be a boolean")
-    if clip.get("reverse"):
+    # A reversed clip may omit reverse_path: export_timeline_to_jianying generates it.
+    if "reverse_path" in clip:
         _require_string(clip, "reverse_path", path)
-    for field in ("scale", "position", "flip"):
-        if field in clip and not isinstance(clip[field], dict):
-            _error(f"{path}.{field}", "must be an object")
+    _validate_transform(clip, path)
     for field in ("transition", "mask", "lut", "chroma"):
-        if field in clip and not isinstance(clip[field], (dict, str)):
+        if field not in clip:
+            continue
+        spec = clip[field]
+        if isinstance(spec, dict):
+            if "resources" in spec:
+                _validate_resources(spec["resources"], f"{path}.{field}.resources")
+        elif not isinstance(spec, str):
             _error(f"{path}.{field}", "must be an object or resource-package name")
-    if "green_background" in clip and not isinstance(clip["green_background"], dict):
-        _error(f"{path}.green_background", "must be a local media object")
     if "compound" in clip and not isinstance(clip["compound"], bool):
         _error(f"{path}.compound", "must be a boolean")
+    if clip.get("compound") or "green_background" in clip or "chroma" in clip:
+        # Any one of these makes the clip a green-screen compound, which needs both.
+        background = clip.get("green_background")
+        if not isinstance(background, dict):
+            _error(f"{path}.green_background", "must be a local media object")
+        _require_string(background, "source_path", f"{path}.green_background")
+        _validate_transform(background, f"{path}.green_background")
+        if "chroma" not in clip:
+            _error(f"{path}.chroma", "compound green-screen clips require a chroma object")
 
 
 def _validate_resource_config(config, path):
@@ -87,18 +112,14 @@ def _validate_resource_config(config, path):
         _error(path, "must be an object")
     if not isinstance(config.get("main_config"), dict):
         _error(f"{path}.main_config", "must be an object")
-    resources = config.get("resources", [])
-    if not isinstance(resources, list) or any(
-        not isinstance(item, dict) or not isinstance(item.get("source_path"), str)
-        for item in resources
-    ):
-        _error(f"{path}.resources", "must contain source_path objects")
+    _validate_resources(config.get("resources", []), f"{path}.resources")
 
 
 def _validate_segment(segment, path, kind):
     if not isinstance(segment, dict):
         _error(path, "must be an object")
     _validate_span(segment, path)
+    _validate_transform(segment, path)
     if "speed" in segment:
         speed = _require_number(segment, "speed", path)
         if speed <= 0:

package/lib/video-recap/skills/video-assemble/scripts/{jianying_writer.py → jianying/writer.py}

@@ -9,7 +9,7 @@ import time
 import uuid
 import zipfile
 
-from jianying_templates import template
+from jianying.templates import template
 
 
 DRAFT_PATH_PLACEHOLDER = "##_draftpath_placeholder_0E685133-18CE-45ED-8CB8-2904A212EC80_##"
@@ -98,14 +98,10 @@ def _meta_value(material, relative_path, metetype, copied_path, timestamp_ms):
 
 def _material_sets(content):
     """Yield root and nested compound-draft material dictionaries."""
-    materials = content.get("materials")
-    if not isinstance(materials, dict):
-        return
+    materials = content["materials"]
     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)
+    for draft in materials["drafts"]:
+        yield from _material_sets(draft["draft"])
 
 
 def _replace_value(value, old, new):
@@ -184,13 +180,10 @@ def _is_packaged_path(value):
 
 
 def _descriptor(raw, default_kind, *, required):
-    if not isinstance(raw, dict):
-        raise ValueError("JianYing resources entries must be objects")
-    source = raw.get("source_path")
+    """`raw` is a contract-validated resource entry: an object with a non-empty source_path."""
+    source = raw["source_path"]
     resource_kind = raw.get("resource_kind", default_kind)
     target_path = raw.get("target_path")
-    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",
@@ -321,11 +314,8 @@ def bundle_media(content, meta, draft_dir):
 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)
+                material.pop("_bundle_resources", None)
 
 
 def draft_dir_has_user_content(draft_dir):

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

@@ -1,8 +1,10 @@
 """Self-contained config + utilities for this skill (no cross-skill imports)."""
+import functools
 import math
 import os
+import shutil
 import subprocess
-from pathlib import Path
+import tempfile
 
 
 # ── 配置 ──────────────────────────────────────────────────────────────
@@ -53,7 +55,6 @@ _foreign_under_narration_volume = 0.05  # original volume under narration when s
 
 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,
@@ -73,6 +74,7 @@ CONFIG = {
     "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(),  # 剪辑模式下的原始视频(可选)，用于时间线/剪映导出引用原片片段
+    "source_video_explicit": False,  # 仅 assemble.py --source-video 显式传入时为 True；环境变量 SOURCE_VIDEO 不算显式
     "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 剪映沙箱读不到外部路径，须把素材拷进草稿目录
@@ -117,6 +119,8 @@ CONFIG = {
     "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"),
+    # 可选字体文件：ASS 烧录经 fontsdir 加载，画面文字经 drawtext fontfile 使用；family 名仍由 SUBTITLE_FONT_NAME 指定
+    "subtitle_font_file": os.environ.get("SUBTITLE_FONT_FILE", "").strip(),
     "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"),
@@ -136,8 +140,6 @@ if isinstance(_EXISTING_CONFIG_REF, dict):
     _EXISTING_CONFIG_REF.update(CONFIG)
     CONFIG = _EXISTING_CONFIG_REF
 
-SCRIPT_DIR = Path(__file__).parent
-
 def narration_tempo_budget(tts_rate_offset=0.0):
     """Return the canonical tempo budget shared by voiceover and assemble.
 
@@ -175,6 +177,37 @@ def run_cmd(cmd, **kwargs):
     log(f"运行: {display}")
     return subprocess.run(cmd, capture_output=True, text=True, **kwargs)
 
+
+# ffmpeg 7 added `-/option path` to read any option's value from a file; ffmpeg 9 removed the
+# older `-filter_complex_script` / `-filter_script` spellings, which are all ffmpeg <= 6 knows.
+_LEGACY_FILTER_FILE_OPTIONS = {
+    "filter_complex": "-filter_complex_script",
+    "filter:v:0": "-filter_script:v:0",
+}
+
+
+@functools.lru_cache(maxsize=None)
+def _ffmpeg_reads_option_files():
+    """Whether the ffmpeg on PATH accepts `-/option path` (asked once per process)."""
+    if shutil.which("ffmpeg") is None:
+        return False
+    with tempfile.TemporaryDirectory() as tmp:
+        graph = os.path.join(tmp, "probe_filter.txt")
+        with open(graph, "w", encoding="utf-8") as fh:
+            fh.write("null")
+        result = subprocess.run(["ffmpeg", "-hide_banner", "-/filter_complex", graph],
+                                stdin=subprocess.DEVNULL, capture_output=True, text=True,
+                                timeout=20)
+    return "Unrecognized option" not in result.stderr
+
+
+def filter_file_args(option, path):
+    """ffmpeg arguments that load `option`'s filtergraph from `path`, spelled for this ffmpeg."""
+    if _ffmpeg_reads_option_files():
+        return [f"-/{option}", str(path)]
+    return [_LEGACY_FILTER_FILE_OPTIONS[option], str(path)]
+
+
 def get_video_duration(video_path):
     """获取视频时长（秒）"""
     cmd = ["ffprobe", "-v", "quiet", "-show_entries", "format=duration",