free-short-video 6.4.0 → 6.4.1

package/README.md

@@ -1,34 +1,13 @@
 ---
 
-# What's New in v6.4.0
+# What's New in v6.4.1
 
 ## 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.
-
-### Refactoring & Optimizations
-
-- **`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.
-
 ### 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 "ffmpeg not found" failure (`FileNotFoundError`) during video composition** — on Windows or systems where `ffmpeg` is not on the `PATH`, creative / manuscript / anchor / poetry composition (concatenation, audio overlay, watermark) could fail at the composition step with `[WinError 2]`. The server now automatically falls back to the static ffmpeg binary bundled with `imageio-ffmpeg`, so no manual ffmpeg installation is required. A non-blocking startup check logs which ffmpeg source is being used. (Issues #35, #36)
 
-**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/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]",

package/core/config.py

@@ -18,7 +18,7 @@ CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")
 # ═══════════════════════════════════════════════════
 # 应用版本号（v6.1 新增：发版时同步更新，见 docs/dev/release_process.md）
 # ═══════════════════════════════════════════════════
-APP_VERSION = "6.4.0"
+APP_VERSION = "6.4.1"
 
 # 未配置 API Key 时的统一报错文案（含免费获取与在线体验兜底，全站路由共用）
 API_KEY_MISSING_MSG = (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-short-video",
-  "version": "6.4.0",
+  "version": "6.4.1",
   "description": "Free AI short-video generator — run the full free-short-video service locally with one command. Text-to-video, image generation, Edge-TTS narration, subtitles, and compositing, all free. Official site: https://video.lichuanyang.top",
   "bin": {
     "free-short-video": "bin/cli.js",

package/server.py

@@ -105,6 +105,21 @@ async def lifespan(app: FastAPI):
         except Exception as e:
             logger.warning(f"[Startup] Stale task sweep failed ({e})")
 
+    # ffmpeg 启动检测（非阻断）：解析一次并打印来源；缺失仅告警、不阻止启动。
+    try:
+        from core.compositor.ffmpeg_tool import resolve_binary
+        ffmpeg_bin = resolve_binary("ffmpeg")
+        if ffmpeg_bin:
+            logger.info(f"[Compositor] ffmpeg resolved: {ffmpeg_bin}")
+        else:
+            logger.warning(
+                "[Compositor] ffmpeg NOT found (no system PATH nor builtin "
+                "imageio-ffmpeg). Video/audio composition will fail later; "
+                "install ffmpeg or verify imageio-ffmpeg dependency."
+            )
+    except Exception as e:
+        logger.warning(f"[Compositor] ffmpeg detection failed: {e}")
+
     yield