free-short-video 6.4.0 → 6.4.2

package/README.md

@@ -1,34 +1,23 @@
 ---
 
-# What's New in v6.4.0
+# What's New in v6.4.2
 
 ## What's New
 
 ### Features & Improvements
 
-- **Preview ("dry-run") endpoints for creative and manuscript tasks** — `POST /api/creative/preview-script` and `POST /api/manuscript/preview-split` let you inspect the generated script or manuscript segments before submitting a full task. Synchronous, no task created. Preview calls share the Chat API rate limiter and have a lightweight in-process concurrency cap (429 + Retry-After) to prevent abuse. (Credit: @Khaled97Sho, PR #33)
-- **Arabic tashkeel for TTS narration** — creative and manuscript pipelines now automatically apply Arabic diacritic marks (harakat) to narration text before TTS synthesis, improving pronunciation quality. Tashkeel only affects TTS input; subtitle text and `narration.txt` remain clean. (Credit: @Khaled97Sho, PR #33)
-- **Manuscript reference images** — per-segment reference images for manuscript tasks are now supported via `reference_images` + `reference_images_map` parameters, matching the same feature used in creative pipelines. (Credit: @Khaled97Sho, PR #33)
-- **Language-aware narration budget** — narration length for non-CJK languages now uses a language-specific characters-per-second rate (Arabic: 4.0, CJK: 5.0, others: 12.0), fixing the "narration too short for non-CJK text" issue. (Credit: @Khaled97Sho, PR #33)
-- **Configurable CORS origins** — the `AGNES_CORS_ORIGINS` environment variable (comma-separated) allows any companion tool to call the core API cross-origin. `AGNES_CORS_ENABLED` can force-enable or disable; auto-detects when origins are set.
-- **China domestic API domain** — the `cn` domain in `AGNES_DOMAIN_MAP` now correctly points to `api.agnes-ai.cn` (the official China service endpoint), updated from the incorrect `apihub.agnes-ai.cn` (international-site fallback). The frontend domain picker reflects the correct hostname.
+* **Per-Key domain binding** — each API Key saved in the projects config can now carry its own access domain (`com` / `cn` / `cn_bak`), so keys issued on the global site and keys issued on the domestic site can coexist and be routed to the correct endpoint automatically. Keys can from the environment still use the global domain.
 
-### Refactoring & Optimizations
+* **One-click "Auto-detect domains" button** — in the API Key config panel, trigger a probe that tests each key across the candidate domains and fills in the matching domain automatically, instead of guessing it by hand.
 
-- **`split_manuscript_text()` extracted as a public utility** — the manuscript-splitting algorithm is now available as a standalone function, used by both the manuscript pipeline and the new preview-split endpoint.
+* **Restored China fallback domain** **`apihub.agnes-ai.cn`** — this endpoint accepts both domestic and global keys, giving users a migration path when their key domain changes. It is not listed in the official docs and may be removed later, so we recommend choosing the domain that matches your key.
 
 ### Bug Fixes
 
-- **Fixed rate-limiter live-lock** — a rare synchronous acquire path race condition could stall all pipelines indefinitely. The token bucket's async path is now the primary path, with the sync path hardened to prevent the live-lock. (Credit: @Khaled97Sho, PR #33)
-- **Fixed image save not persisting** — `POST /api/images/generations` now `await`s the image download, ensuring the generated image is actually written to disk before the response.
-- **Fixed GitHub CodeQL alerts #43 and #47** — path-injection and information-disclosure security alerts resolved.
-- **Fixed PBKDF2-HMAC-SHA256 for config key IDs** — config key IDs are now hashed with a proper key-derivation function instead of weaker hashing.
-- **Fixed Docker Hub Cloudflare WAF blocking** — the Docker Hub overview update script now strips `<script>` blocks and escapes `<` in the JSON payload to bypass the WAF XSS rule.
-- **Fixed China domestic site domain** — `AGNES_DOMAIN_MAP["cn"]` corrected to `api.agnes-ai.cn` per the official Agnes model catalog. (Issue #37)
+* **Fixed multi-key authentication failures across domains** — after the Chinese domain migration, global-site keys could fail authentication against the strict domestic endpoint; domain is now resolved per key with the restored fallback, so mixed global/domestic keys authenticate successfully.
 
----
+* **Domain mismatch hints in the config UI** — keys without a bound domain now show a clear "domain not set" hint, prompting users to pick or auto-detect the matching domain on their next visit.
 
-**Compatibility notes**: The `core/audio/tashkeel.py` module adds a new optional dependency (`mishkal`). It is installed by default via `requirements.txt`; if missing, tashkeel silently falls back to the original text. Existing task state files are forward-compatible; no migration needed.
 
 ---
 

package/core/api/agnes_chat.py

@@ -16,7 +16,6 @@ import requests
 
 from core.api.error_collector import collect_error, collect_error_from_exception
 from core.api.rate_limiter import get_rate_limiter, request_with_key_rotation
-from core.config import get_agnes_base_url
 
 logger = logging.getLogger(__name__)
 
@@ -69,13 +68,18 @@ class AgnesChatAPI:
         # 向后兼容：旧调用方可能读取 self.headers
         self.headers = dict(self._base_headers)
 
-    def _auth_headers(self) -> dict:
-        """每次请求前生成带当前 Key 的 headers 副本（从 KeyRing 轮转取 Key）。"""
+    def _auth_headers(self, key: str | None = None) -> dict:
+        """每次请求前生成带当前 Key 的 headers 副本。
+
+        Args:
+            key: 显式指定 Key（供按 Key 绑定域名路由时与 URL 保持一致）。
+                省略时从 KeyRing 轮转取当前 Key。
+        """
         from core.api.key_manager import get_key_ring
 
-        key = get_key_ring().next()
+        k = key or get_key_ring().next()
         h = dict(self._base_headers)
-        h["Authorization"] = f"Bearer {key}"
+        h["Authorization"] = f"Bearer {k}"
         return h
 
     def _image_to_b64_uri(self, path: str) -> str:
@@ -128,7 +132,7 @@ class AgnesChatAPI:
             get_rate_limiter().acquire()
             resp = request_with_key_rotation(
                 requests.post,
-                f"{get_agnes_base_url()}/chat/completions",
+                "/chat/completions",
                 max_retries=_MAX_RETRIES,
                 retry_base_delay=_RETRY_BASE_DELAY,
                 json=payload,

package/core/api/agnes_image.py

@@ -12,7 +12,7 @@ import requests
 from core.api.error_collector import collect_error, collect_error_from_exception
 from core.api.key_manager import get_key_ring
 from core.api.rate_limiter import get_rate_limiter
-from core.config import get_agnes_base_url
+from core.config import get_base_url_for_key
 from utils.image import download_image
 from utils.image_normalizer import normalize_reference_path
 
@@ -77,11 +77,16 @@ class AgnesImageAPI:
         # 向后兼容：旧调用方可能读取 self.headers
         self.headers = dict(self._base_headers)
 
-    def _auth_headers(self) -> dict:
-        """每次请求前生成带当前 Key 的 headers 副本（从 KeyRing 轮转取 Key）。"""
-        key = get_key_ring().next()
+    def _auth_headers(self, key: str | None = None) -> dict:
+        """每次请求前生成带当前 Key 的 headers 副本。
+
+        Args:
+            key: 显式指定 Key（供按 Key 绑定域名路由时与 URL 保持一致）。
+                省略时从 KeyRing 轮转取当前 Key。
+        """
+        k = key or get_key_ring().next()
         h = dict(self._base_headers)
-        h["Authorization"] = f"Bearer {key}"
+        h["Authorization"] = f"Bearer {k}"
         return h
 
     async def _path_to_b64(self, path: str) -> str:
@@ -156,10 +161,11 @@ class AgnesImageAPI:
                 await get_rate_limiter().acquire_async()
                 # 动态超时：第一次 120s，后续逐步增加（图像生成较慢，放宽读超时）
                 read_timeout = _READ_TIMEOUT_BASE_SECONDS * (attempt + 1)
+                key = ring.next()
                 resp = await asyncio.to_thread(
                     requests.post,
-                    f"{get_agnes_base_url()}/images/generations",
-                    headers=self._auth_headers(),
+                    f"{get_base_url_for_key(key)}/images/generations",
+                    headers=self._auth_headers(key),
                     json=payload,
                     timeout=(30, read_timeout),
                 )

package/core/api/agnes_models.py

@@ -12,7 +12,7 @@ from core.config import (
     DEFAULT_IMAGE_MODEL,
     DEFAULT_TEXT_MODEL,
     DEFAULT_VIDEO_MODEL,
-    get_agnes_base_url,
+    get_base_url_for_key,
 )
 
 logger = logging.getLogger(__name__)
@@ -52,7 +52,7 @@ def fetch_available_models(api_key: str) -> dict:
         接口失败（网络/鉴权/非 200）时返回硬编码兜底列表。
     """
     try:
-        endpoint = f"{get_agnes_base_url()}/models?all=true"
+        endpoint = f"{get_base_url_for_key(api_key)}/models?all=true"
         resp = requests.get(
             endpoint,
             headers={"Authorization": f"Bearer {api_key}"},

package/core/api/agnes_video.py

@@ -17,7 +17,7 @@ from core.api.rate_limiter import get_rate_limiter, get_video_submit_limiter
 from core.config import (
     VIDEO_ASPECT_RATIOS,
     get_agnes_api_root,
-    get_agnes_base_url,
+    get_base_url_for_key,
     is_v25_video_model,
 )
 from utils.image_normalizer import normalize_reference_path
@@ -118,11 +118,16 @@ class AgnesVideoAPI:
         # 向后兼容：旧调用方可能读取 self.headers
         self.headers = dict(self._base_headers)
 
-    def _auth_headers(self) -> dict:
-        """每次请求前生成带当前 Key 的 headers 副本（从 KeyRing 轮转取 Key）。"""
-        key = get_key_ring().next()
+    def _auth_headers(self, key: str | None = None) -> dict:
+        """每次请求前生成带当前 Key 的 headers 副本。
+
+        Args:
+            key: 显式指定 Key（供按 Key 绑定域名路由时与 URL 保持一致）。
+                省略时从 KeyRing 轮转取当前 Key。
+        """
+        k = key or get_key_ring().next()
         h = dict(self._base_headers)
-        h["Authorization"] = f"Bearer {key}"
+        h["Authorization"] = f"Bearer {k}"
         return h
 
     def _path_to_b64(self, path: str) -> str:
@@ -202,10 +207,11 @@ class AgnesVideoAPI:
                 }
                 logger.info(f"[AgnesVideo] Uploading image to hosted URL (attempt {attempt + 1}/{retries})...")
                 await get_rate_limiter().acquire_async(self.shutdown_event)
+                key = ring.next()
                 resp = await asyncio.to_thread(
                     requests.post,
-                    f"{get_agnes_base_url()}/images/generations",
-                    headers=self._auth_headers(),
+                    f"{get_base_url_for_key(key)}/images/generations",
+                    headers=self._auth_headers(key),
                     json=payload,
                     timeout=(30, 120),
                 )
@@ -405,11 +411,12 @@ class AgnesVideoAPI:
                 # 2.3 异步原生，停止可打断）
                 await get_video_submit_limiter().acquire_async(self.shutdown_event)
                 # M2: 缩短读超时从 180s 到 60s，使 stop() 更快生效
+                key = ring.next()
                 resp = await asyncio.wait_for(
                     asyncio.to_thread(
                         requests.post,
-                        f"{get_agnes_base_url()}/videos",
-                        headers=self._auth_headers(),
+                        f"{get_base_url_for_key(key)}/videos",
+                        headers=self._auth_headers(key),
                         json=payload,
                         timeout=(15, 60),
                     ),

package/core/api/rate_limiter.py

@@ -269,7 +269,7 @@ def reset_rate_limiter() -> None:
 
 def request_with_key_rotation(
     requester,
-    url: str,
+    endpoint: str,
     *,
     max_retries: int = 3,
     retry_base_delay: float = 20.0,
@@ -279,7 +279,8 @@ def request_with_key_rotation(
     """429 换 Key 立即重试；全 Key 429 或 5xx/超时/连接错误才指数退避。
 
     规则：
-    1. 每请求前 key_ring.next()（round-robin，均匀分摊），生成带当前 Key 的 headers
+    1. 每请求前 key_ring.next()（round-robin，均匀分摊），生成带当前 Key 的 headers，
+       并按该 Key 绑定域名构造 URL（``get_base_url_for_key``，未绑定回退全局域名）
     2. 429 且 has_multiple() -> key_ring.rotate() 立即重试（不 sleep、不计入退避）
        —— Key 级隔离限速，换 Key 后配额是满的
     3. 所有 Key 均 429（rotation 计数达到 len(keys) × 退避上限）-> 指数退避
@@ -287,7 +288,8 @@ def request_with_key_rotation(
 
     Args:
         requester: 可调用 (url, headers, **kw) -> requests.Response。
-        url: 请求 URL。
+        endpoint: API 接口相对路径（如 "/chat/completions"）。完整 URL 依当前 Key
+            绑定域名经 ``get_base_url_for_key`` 动态拼接。
         max_retries: 退避重试上限。
         retry_base_delay: 指数退避基数（秒），delay = 基数 × (retries + 1)。
         key_ring: KeyRing 实例；None 时取全局单例。
@@ -302,6 +304,8 @@ def request_with_key_rotation(
     """
     import requests
 
+    from core.config import get_base_url_for_key
+
     ring = key_ring or get_key_ring()
     base_headers = requester_kwargs.pop("headers", None) or {}
     retries = 0
@@ -309,8 +313,10 @@ def request_with_key_rotation(
     max_rotations = len(ring) * max_retries
     while True:
         # 每请求前轮转 Key：round-robin 均匀分摊；429 换 Key（rotate 推进计数）后
-        # 下次 next() 自然取到下一个 Key
-        headers = {**base_headers, "Authorization": f"Bearer {ring.next()}"}
+        # 下次 next() 自然取到下一个 Key。URL 按该 Key 绑定域名动态拼接。
+        key = ring.next()
+        headers = {**base_headers, "Authorization": f"Bearer {key}"}
+        url = f"{get_base_url_for_key(key)}{endpoint}"
         try:
             resp = requester(url, headers=headers, **requester_kwargs)
         except (requests.ConnectionError, requests.Timeout) as e:

package/core/compositor/concatenator/audio_overlay.py

@@ -13,6 +13,7 @@ from typing import List, Optional, Tuple
 import srt as srt_lib
 from moviepy import AudioFileClip, CompositeVideoClip, VideoFileClip
 
+from core.compositor.ffmpeg_tool import resolve_binary
 from models.task import SubtitleStyle
 
 from .concat import _AUDIO_BITRATE, _AUDIO_CODEC, _AUDIO_FPS, _VIDEO_FPS
@@ -137,7 +138,7 @@ class AudioOverlayMixin:
             tmp_files.append(extend_path)
             pad_dur = final_dur - video_dur
             VideoConcatenator._run_ffmpeg(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-i", silent_path,
                  "-vf", f"tpad=stop_mode=clone:stop_duration={pad_dur:.2f}",
                  "-c:v", "libx264", "-pix_fmt", "yuv420p",
@@ -154,7 +155,7 @@ class AudioOverlayMixin:
             tmp_files.append(apad_path)
             pad_dur = final_dur - audio_dur
             VideoConcatenator._run_ffmpeg(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-i", audio_path,
                  "-af", f"apad=pad_dur={pad_dur:.2f},volume=1.5",
                  "-c:a", "libmp3lame", "-q:a", "2",
@@ -167,7 +168,7 @@ class AudioOverlayMixin:
             vol_path = audio_path.replace(".mp3", "_vol.mp3")
             tmp_files.append(vol_path)
             VideoConcatenator._run_ffmpeg(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-i", audio_path,
                  "-af", "volume=1.5",
                  "-c:a", "libmp3lame", "-q:a", "2",
@@ -290,7 +291,7 @@ class AudioOverlayMixin:
         else:
             v_chain = f"[0:v]tpad=stop_mode=clone:stop_duration={final_dur:.2f}[v]"
         cmd = [
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-i", silent_path,
             "-i", audio_path,
             "-filter_complex",
@@ -315,7 +316,7 @@ class AudioOverlayMixin:
         """ffprobe 获取视频宽高，失败回退 (768, 1152)。"""
         try:
             r = subprocess.run(
-                ["ffprobe", "-v", "error", "-select_streams", "v:0",
+                [resolve_binary("ffprobe"), "-v", "error", "-select_streams", "v:0",
                  "-show_entries", "stream=width,height",
                  "-of", "csv=s=x:p=0", video_path],
                 stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=15,
@@ -706,7 +707,7 @@ class AudioOverlayMixin:
         """
         try:
             n = len(audio_paths)
-            cmd = ["ffmpeg", "-y"]
+            cmd = [resolve_binary("ffmpeg"), "-y"]
             for ap in audio_paths:
                 cmd += ["-i", ap]
             filters = []
@@ -811,7 +812,7 @@ class AudioOverlayMixin:
 
         # Step 1: Get clip duration
         probe = subprocess.run(
-            ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+            [resolve_binary("ffprobe"), "-v", "error", "-show_entries", "format=duration",
              "-of", "csv=p=0", clip_path],
             stdin=subprocess.DEVNULL,
             capture_output=True, text=True, timeout=15,
@@ -836,7 +837,7 @@ class AudioOverlayMixin:
         # Step 4: Concatenate with xfade cross-fade transitions
         try:
             subprocess.run(
-                ["ffmpeg", "-y", "-f", "concat", "-safe", "0",
+                [resolve_binary("ffmpeg"), "-y", "-f", "concat", "-safe", "0",
                  "-i", concat_file,
                  "-c", "copy",
                  "-t", str(needed),
@@ -850,7 +851,7 @@ class AudioOverlayMixin:
             # xfade filter 构建已由上方 trim 循环拼接替代（死代码，3.3 清理）
 
             subprocess.run(
-                ["ffmpeg", "-y",
+                [resolve_binary("ffmpeg"), "-y",
                  "-stream_loop", str(n - 1), "-i", clip_path,
                  "-filter_complex",
                  f"[0:v]trim=duration={needed}[v]",

package/core/compositor/concatenator/concat.py

@@ -11,6 +11,7 @@ from typing import List, Optional
 import srt as srt_lib
 from moviepy import VideoFileClip, concatenate_videoclips
 
+from core.compositor.ffmpeg_tool import resolve_binary
 from models.task import SubtitleStyle
 
 logger = logging.getLogger(__name__)
@@ -114,7 +115,7 @@ class ConcatMixin:
             sigs = set()
             for p in video_paths:
                 r = subprocess.run(
-                    ["ffprobe", "-v", "error", "-select_streams", "v:0",
+                    [resolve_binary("ffprobe"), "-v", "error", "-select_streams", "v:0",
                      "-show_entries", "stream=width,height,avg_frame_rate",
                      "-of", "csv=s=x:p=0", p],
                     stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=15,
@@ -137,7 +138,7 @@ class ConcatMixin:
                     f.write(f"file '{esc}'\n")
             try:
                 r = subprocess.run(
-                    ["ffmpeg", "-y", "-f", "concat", "-safe", "0",
+                    [resolve_binary("ffmpeg"), "-y", "-f", "concat", "-safe", "0",
                      "-i", concat_file, "-c", "copy", output_path],
                     stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=600,
                 )
@@ -383,7 +384,7 @@ class ConcatMixin:
         """用 ffprobe 获取媒体文件时长（秒）。"""
         try:
             r = subprocess.run(
-                ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+                [resolve_binary("ffprobe"), "-v", "error", "-show_entries", "format=duration",
                  "-of", "csv=p=0", path],
                 stdin=subprocess.DEVNULL,
                 capture_output=True, text=True, timeout=15,
@@ -396,6 +397,12 @@ class ConcatMixin:
     def _run_ffmpeg(cmd: list, desc: str = "") -> None:
         """执行 ffmpeg 命令，失败时抛 RuntimeError。"""
         logger.info(f"[Compositor] ffmpeg: {desc}")
+        if not cmd or cmd[0] is None:
+            raise RuntimeError(
+                "ffmpeg not available (no system PATH ffmpeg nor builtin "
+                "imageio-ffmpeg). Please install ffmpeg or verify imageio-ffmpeg "
+                "is installed."
+            )
         try:
             r = subprocess.run(
                 cmd, stdin=subprocess.DEVNULL,

package/core/compositor/ffmpeg_tool.py

@@ -0,0 +1,102 @@
+"""core.compositor.ffmpeg_tool — ffmpeg / ffprobe 可执行文件统一解析。
+
+背景：此前所有 ffmpeg/ffprobe 调用都用裸命令字符串经 ``subprocess.run`` 执行，
+依赖系统 PATH 搜索可执行文件。Windows 未安装 ffmpeg 时 ``CreateProcess`` 抛
+``[WinError 2] The system cannot find the file specified``，且发生在任务运行到
+拼接步骤而非启动时（见 Issue #36 的完整 traceback）。
+
+解析优先级（推荐，但不强制用户安装系统 ffmpeg）：
+  1. 环境变量显式指定：``FFMPEG_BINARY`` / ``FFPROBE_BINARY`` —— 尊重用户意图
+  2. 系统 PATH（``shutil.which``）—— 已安装则用之，绝不覆盖
+  3. ``imageio-ffmpeg`` 内置静态二进制兜底 —— wheel 自带，无需用户操作
+
+结果带进程级缓存；全部不可用时返回 None，由启动检测 / 调用方给出清晰指引
+而非裸的 ``[WinError 2]``。
+"""
+import logging
+import os
+import shutil
+
+logger = logging.getLogger(__name__)
+
+# 二进制名 → 覆盖环境变量名
+_EXE_OVERRIDE = {"ffmpeg": "FFMPEG_BINARY", "ffprobe": "FFPROBE_BINARY"}
+_cache: "dict[str, str | None]" = {}
+
+
+def resolve_binary(name: str) -> "str | None":
+    """按优先级解析 ffmpeg/ffprobe 可执行文件绝对路径，进程内缓存。
+
+    Args:
+        name: ``"ffmpeg"`` 或 ``"ffprobe"``。
+
+    Returns:
+        可用可执行文件绝对路径；全部不可用时返回 None。
+    """
+    if name not in _EXE_OVERRIDE:
+        raise ValueError(f"unknown binary: {name}")
+    if name in _cache:
+        return _cache[name]
+    path = _resolve(name)
+    _cache[name] = path
+    return path
+
+
+def resolve_ffmpeg() -> "str | None":
+    """便捷：解析 ffmpeg。"""
+    return resolve_binary("ffmpeg")
+
+
+def resolve_ffprobe() -> "str | None":
+    """便捷：解析 ffprobe（可能为 None，仅时长/尺寸探测用，调用方自带兜底）。"""
+    return resolve_binary("ffprobe")
+
+
+def _resolve(name: str) -> "str | None":
+    # 1) 显式指定
+    override = os.environ.get(_EXE_OVERRIDE[name])
+    if override and os.path.exists(override):
+        logger.info(f"[Compositor] {name}: explicit {override}")
+        return override
+
+    # 2) 系统 PATH
+    found = shutil.which(name)
+    if found:
+        logger.info(f"[Compositor] {name}: system {found}")
+        return found
+
+    # 3) imageio-ffmpeg 内置（仅自带 ffmpeg；ffprobe 从同目录推导）
+    base = _cache.get("ffmpeg") or _resolve_builtin_ffmpeg()
+    if base:
+        if name == "ffmpeg":
+            return base
+        probe = _sibling(base, "ffprobe")
+        if probe:
+            logger.info(f"[Compositor] {name}: builtin {probe}")
+            return probe
+
+    logger.warning(f"[Compositor] {name}: not found (no system PATH nor builtin)")
+    return None
+
+
+def _resolve_builtin_ffmpeg() -> "str | None":
+    """取 imageio-ffmpeg 内置静态二进制；加载/失败时记录并返回 None。"""
+    try:
+        import imageio_ffmpeg
+
+        exe = imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception as e:  # 加载失败 / 内置缺失 / 首次下载失败
+        logger.warning(f"[Compositor] builtin ffmpeg unavailable: {e}")
+        return None
+    if exe and os.path.exists(exe):
+        logger.info(f"[Compositor] ffmpeg: builtin {exe}")
+        return exe
+    return None
+
+
+def _sibling(exe: str, stem: str) -> "str | None":
+    """由可执行文件路径推导同目录兄弟程序（Windows 补 .exe）。"""
+    candidate = os.path.join(
+        os.path.dirname(exe), stem + (".exe" if os.name == "nt" else "")
+    )
+    return candidate if os.path.exists(candidate) else None

package/core/compositor/processor.py

@@ -6,6 +6,8 @@
 import logging
 import os
 
+from core.compositor.ffmpeg_tool import resolve_binary
+
 logger = logging.getLogger(__name__)
 
 
@@ -20,7 +22,7 @@ class VideoProcessor:
 
         import subprocess
         subprocess.run([
-            "ffmpeg", "-y", "-i", input_path,
+            resolve_binary("ffmpeg"), "-y", "-i", input_path,
             "-vf", f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
                     f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2",
             "-c:v", "libx264", "-preset", "fast",
@@ -37,7 +39,7 @@ class VideoProcessor:
 
         import subprocess
         subprocess.run([
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-sseof", "-1",
             "-i", video_path,
             "-frames:v", "1",
@@ -55,7 +57,7 @@ class VideoProcessor:
 
         import subprocess
         subprocess.run([
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-f", "lavfi",
             "-i", "anullsrc=r=44100:cl=mono",
             "-t", str(duration_sec),
@@ -87,7 +89,7 @@ class VideoProcessor:
         # 注意：勿再用 -t {freeze_duration}，那会把整个输出截断成只剩冻结段。
         try:
             subprocess.run([
-                "ffmpeg", "-y",
+                resolve_binary("ffmpeg"), "-y",
                 "-i", video_path,
                 "-vf", f"tpad=stop_mode=clone:stop_duration={freeze_duration}",
                 "-c:v", "libx264", "-preset", "fast",

package/core/compositor/watermark.py

@@ -11,6 +11,7 @@ import subprocess
 import tempfile
 from typing import NamedTuple, Optional
 
+from core.compositor.ffmpeg_tool import resolve_binary
 from core.config import resolve_font_path
 
 logger = logging.getLogger(__name__)
@@ -194,7 +195,7 @@ def add_watermark(
 
         # ffmpeg overlay: 将水印 PNG 叠加到视频上，无损流式拷贝
         cmd = [
-            "ffmpeg", "-y",
+            resolve_binary("ffmpeg"), "-y",
             "-i", input_path,
             "-i", wm_png_path,
             "-filter_complex", f"[0:v][1:v]overlay={layout.pos_x}:{layout.pos_y}[v]",