videoconverter-worker 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

ffmpeg_runner.py

@@ -21,6 +21,35 @@ def _find_ffprobe() -> str:
     return os.environ.get("FFPROBE_PATH", "ffprobe")
 
 
+def check_ffmpeg_available() -> Optional[str]:
+    """
+    检测 ffmpeg / ffprobe 是否可用。可用则返回 None，不可用则返回错误说明（含安装提示）。
+    """
+    missing = []
+    for name, getter in [("ffmpeg", _find_ffmpeg), ("ffprobe", _find_ffprobe)]:
+        path = getter()
+        try:
+            r = subprocess.run(
+                [path, "-version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if r.returncode != 0:
+                missing.append(name)
+        except (FileNotFoundError, OSError):
+            missing.append(name)
+    if not missing:
+        return None
+    return (
+        "未检测到 {}，请先安装 FFmpeg（本程序不会自动安装系统依赖）。\n"
+        "  macOS:    brew install ffmpeg\n"
+        "  Ubuntu:   sudo apt install ffmpeg\n"
+        "  Windows:  从 https://ffmpeg.org/download.html 下载或将 ffmpeg/ffprobe 加入 PATH\n"
+        "  或设置环境变量: FFMPEG_PATH=... FFPROBE_PATH=..."
+    ).format(" / ".join(missing))
+
+
 def _format_time(seconds: float) -> str:
     if seconds < 0:
         return "0"
@@ -51,6 +80,31 @@ def get_duration(video_path: str) -> float:
     return float(line)
 
 
+def get_video_size(video_path: str) -> Tuple[int, int]:
+    """返回 (width, height)，用于去字幕滤镜。"""
+    cmd = [
+        _find_ffprobe(),
+        "-v", "error",
+        "-select_streams", "v:0",
+        "-show_entries", "stream=width,height",
+        "-of", "csv=p=0",
+        video_path,
+    ]
+    r = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    if r.returncode != 0:
+        return 1920, 1080
+    line = (r.stdout or "").strip()
+    if not line:
+        return 1920, 1080
+    parts = line.split(",")
+    if len(parts) >= 2:
+        try:
+            return int(parts[0]), int(parts[1])
+        except ValueError:
+            pass
+    return 1920, 1080
+
+
 def split_chunk(video_path: str, start_time: float, duration: float, output_path: str) -> None:
     cmd = [
         _find_ffmpeg(),

schema.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""任务队列输入格式说明，供对接方参考。可通过 videoconverter --show-schema 查看。"""
+
+INPUT_SCHEMA = r"""# 任务队列输入格式（如何「喂数据」给 Worker）
+
+## 目录结构
+
+- 数据目录（默认 ~/.videoconverter/data，可用 --data-dir 指定）
+  - queue/                    必选，存放任务
+    - <task_id>.json          每个任务一个文件，文件名=task_id.json
+    - <task_id>.lock          运行时抢占锁，勿手动编辑
+  - queue_config.json         可选，队列暂停等配置
+
+## 单任务文件 queue/<task_id>.json
+
+根级字段:
+  task_id          string   必填，与文件名一致（如 a1b2c3d4-e5f6-7890-abcd-ef1234567890.json）
+  task_type        string   必填，取值: SPLIT | DESUBTITLE | MERGE | ONE_CLICK_COMPOSE
+  parent_task_id   string   可选
+  video_id         string   可选，同一视频/一键合成流程 ID（MERGE 必填）
+  input_file       string   必填（MERGE 可为空串），输入视频或 chunk 的绝对路径
+  output_dir       string   必填，输出目录（绝对路径）
+  config           object   必填，见下
+  status           string   必填，新建任务填 PENDING
+  progress         number   默认 0
+  progress_text    string   可选
+  created_time     number   必填，毫秒时间戳
+  error_message    string   可选
+
+任务类型说明:
+  SPLIT              输入整段视频，按 config.startTime/endTime 切分为 chunk，写入 output_dir 并生成 metadata.json；Worker 会自动创建各 chunk 的 DESUBTITLE 任务。
+  DESUBTITLE         输入单个 chunk 文件，去字幕后写入 output_dir/<video_id>/xxx_desub.mp4，并更新 metadata；全部完成后 Worker 会自动创建 MERGE 任务。
+  MERGE              依赖 output_dir/<video_id>/metadata.json（由 SPLIT 生成、DESUBTITLE 更新），将已处理的 chunk 合成为最终视频。需填 video_id、output_dir，input_file 可空。
+  ONE_CLICK_COMPOSE  与 SPLIT 类似：输入整段视频 + startTime/endTime，切分后自动创建所有 DESUBTITLE 任务（不自动建 SPLIT 子任务名，仅建去字幕任务），后续 MERGE 由 Worker 在全部去字幕后自动创建。
+
+路径: 建议使用本机绝对路径；若队列从别处拷贝而来，启动时用 --path-replace "原前缀=本机前缀" 做替换。
+
+config 对象常用字段:
+  targetWidth/targetHeight  默认 1920/1080
+  cropTop/cropBottom/cropLeft/cropRight  裁剪（如去字幕 208）
+  keepAudio, audioBitrate, videoQuality
+  startTime, endTime  截取时间（秒）
+  inputPath, outputPath  Worker 会按需填充
+
+## queue_config.json（可选）
+
+{ "queue_paused": "true" }  表示暂停，不取新任务；"false" 表示运行。
+
+## 示例：新建一个去字幕任务
+
+在数据目录下创建 queue/<uuid>.json，例如:
+
+{
+  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "task_type": "DESUBTITLE",
+  "video_id": "my-video-id",
+  "input_file": "/path/to/chunk_001.mp4",
+  "output_dir": "/path/to/output",
+  "config": {
+    "targetWidth": 1920,
+    "targetHeight": 1080,
+    "cropBottom": 208,
+    "cropLeft": 293,
+    "cropRight": 293,
+    "keepAudio": true,
+    "videoQuality": 23
+  },
+  "status": "PENDING",
+  "progress": 0,
+  "created_time": 1738828800000
+}
+
+然后启动: videoconverter --data-dir /path/to/data
+
+Worker 会按 created_time 顺序抢占 status=PENDING 的任务并执行。
+
+## 示例：切分+去字幕流程（SPLIT 或 ONE_CLICK_COMPOSE）
+
+新建一个 SPLIT 任务（或 ONE_CLICK_COMPOSE），Worker 会先切分再自动创建各 chunk 的去字幕任务，全部去字幕后自动创建 MERGE 并合成:
+
+{
+  "task_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
+  "task_type": "SPLIT",
+  "input_file": "/path/to/full_video.mp4",
+  "output_dir": "/path/to/output",
+  "config": {
+    "startTime": 0,
+    "endTime": 3600,
+    "targetWidth": 1920,
+    "targetHeight": 1080,
+    "cropBottom": 208,
+    "cropLeft": 293,
+    "cropRight": 293
+  },
+  "status": "PENDING",
+  "progress": 0,
+  "created_time": 1738828800000
+}
+
+注意: MERGE 任务一般由 Worker 在「该 video_id 下所有 DESUBTITLE 完成」后自动创建，无需手写；若需手写 MERGE，则 video_id、output_dir 必填，且 output_dir/<video_id>/metadata.json 已存在且所有 chunk 已标记为已处理。
+"""

task_queue.py

@@ -39,6 +39,7 @@ class QueueStore:
         self.queue_dir = self.data_dir / QUEUE_DIR_NAME
         self.config_file = self.data_dir / CONFIG_FILE_NAME
         self.path_replace = path_replace  # (old, new)
+        self._task_cache: Dict[Path, tuple] = {}  # path -> (mtime, status, created_time)，减少重复读盘
         self._ensure_dirs()
 
     def _ensure_dirs(self) -> None:
@@ -92,17 +93,57 @@ class QueueStore:
             return []
         return sorted(self.queue_dir.glob("*.json"), key=lambda p: p.name)
 
+    def recover_orphaned_processing(self) -> int:
+        """断电/强制关机后：将无 .lock 的 PROCESSING 任务重置为 PENDING，便于重启后继续。返回恢复数量。"""
+        count = 0
+        for p in self._list_task_files():
+            task_id = p.stem
+            lock_path = self._lock_file(task_id)
+            if lock_path.exists():
+                continue
+            try:
+                with open(p, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                if data.get("status") != "PROCESSING":
+                    continue
+                data["status"] = "PENDING"
+                data["progress"] = 0.0
+                data["progress_text"] = "等待重试（已恢复）"
+                if "start_time" in data:
+                    del data["start_time"]
+                tmp = p.with_suffix(p.suffix + ".tmp")
+                with open(tmp, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=2, ensure_ascii=False)
+                tmp.replace(p)
+                self._task_cache.pop(p, None)
+                count += 1
+                logger.info("恢复孤儿任务为 PENDING: %s", task_id)
+            except Exception as e:
+                logger.warning("恢复任务失败 %s: %s", task_id, e)
+        return count
+
     def acquire_pending_task(self) -> Optional[Dict[str, Any]]:
-        """原子抢占一个 PENDING 任务，返回任务 dict 或 None。"""
+        """原子抢占一个 PENDING 任务，返回任务 dict 或 None。用缓存避免每轮读取全部 JSON。"""
         files = self._list_task_files()
         pending_with_time = []
         for p in files:
             try:
+                mtime = p.stat().st_mtime
+                cached = self._task_cache.get(p)
+                if cached is not None and cached[0] == mtime:
+                    _mtime, status, created_time = cached
+                    if status != "PENDING":
+                        continue
+                    pending_with_time.append((created_time, p))
+                    continue
                 with open(p, "r", encoding="utf-8") as f:
                     data = json.load(f)
-                if data.get("status") != "PENDING":
+                status = data.get("status")
+                created_time = data.get("created_time", 0)
+                self._task_cache[p] = (mtime, status, created_time)
+                if status != "PENDING":
                     continue
-                pending_with_time.append((data.get("created_time", 0), p))
+                pending_with_time.append((created_time, p))
             except Exception as e:
                 logger.warning("读取任务文件失败 %s: %s", p.name, e)
         pending_with_time.sort(key=lambda x: x[0])
@@ -133,6 +174,8 @@ class QueueStore:
                 raise
             finally:
                 lock_path.unlink(missing_ok=True)
+        if len(self._task_cache) > 50000:
+            self._task_cache.clear()
         return None
 
     def _apply_paths_to_task(self, task: dict) -> None:
@@ -184,6 +227,18 @@ class QueueStore:
         with open(log_path, "a", encoding="utf-8") as f:
             f.write(line)
 
+    def has_merge_task_for_video_id(self, video_id: str) -> bool:
+        """是否存在该 video_id 的 MERGE 任务，遇第一个即返回，避免全量 get_tasks_by_video_id。"""
+        for p in self._list_task_files():
+            try:
+                with open(p, "r", encoding="utf-8") as f:
+                    d = json.load(f)
+                if d.get("video_id") == video_id and d.get("task_type") == "MERGE":
+                    return True
+            except Exception:
+                pass
+        return False
+
     def get_tasks_by_video_id(self, video_id: str) -> List[Dict[str, Any]]:
         out = []
         for p in self._list_task_files():

{videoconverter_worker-1.0.0.dist-info → videoconverter_worker-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videoconverter-worker
-Version: 1.0.0
+Version: 1.0.2
 Summary: VideoConverter Python Worker：从 queue 目录读取任务并执行切分/去字幕/合成
 License: MIT
 Keywords: videoconverter,ffmpeg,worker,video
@@ -19,21 +19,32 @@ Python Worker 使用说明
 
 0) 安装（任选其一）
    - 从 PyPI 安装（推荐，Windows/Linux/macOS 通用）：
-     pip install videoconverter
-     安装后直接运行： videoconverter [--data-dir DIR] [--path-replace OLD=NEW]
+     pip install videoconverter-worker
+     安装后运行： videoconverter 或 videoconverter-worker [--data-dir DIR] [--path-replace OLD=NEW]
    - 或从本地源码安装： cd src/python && pip install .
 
-1) 作用
+1) 简易模式（当前目录 + 开始/结束时间 + 字幕高度，便于测试）
+   不经过队列，直接在指定目录内对单个文件或批量视频做「切分→去字幕→合成」：
+   - 单文件：
+     videoconverter --simple --dir . --start 0 --end 120 --crop-bottom 208 --file 视频.mp4
+   - 批量（当前目录下所有 .mp4/.mkv/.mov 等）：
+     videoconverter --simple --dir . --start 0 --end 60 --crop-bottom 208 --batch
+   - 参数：--dir 工作目录（默认当前目录），--start/--end 秒（0 表示到结尾），
+     --crop-bottom 字幕高度/裁底像素（默认 208），--crop-left/--crop-right 默认 293，
+     --output 输出目录（默认 <dir>/videoconverter_out）。
+   输出在 <dir>/videoconverter_out 或 --output 指定目录下，合成文件为 <video_id>_merged.mp4。
+
+2) 作用（队列模式）
    与 Java BackendWorker 行为一致：从 queue 目录读取任务（queue/<task_id>.json），
    执行 SPLIT / DESUBTITLE / MERGE / ONE_CLICK_COMPOSE，更新状态与 metadata.json。
    适合在服务器上运行，利用多核与高性能做切分、去字幕、合成。
 
-2) 环境
+3) 环境
    - Python 3.8+
    - 系统已安装 ffmpeg、ffprobe（或在 PATH 中）
    - 可选：环境变量 FFMPEG_PATH、FFPROBE_PATH 指定路径
 
-3) 本机与 Java 共用同一队列（同一台机器）
+4) 本机与 Java 共用同一队列（同一台机器）
    - 数据目录一致即可，例如: ~/.videoconverter/data
    - 先由 Java 前端创建任务（写 queue/*.json），再在本机运行 Python worker 处理：
      cd src/python
@@ -41,7 +52,7 @@ Python Worker 使用说明
    - 或指定数据目录：
      python worker.py --data-dir /path/to/.videoconverter/data
 
-4) 把「前端处理过的文件夹」拷到服务器后运行
+5) 把「前端处理过的文件夹」拷到服务器后运行
    - 将本机用于队列的「数据目录」整个拷到服务器（例如 /server/data），
      其中应包含 queue/ 目录及 queue/*.json 任务文件。
    - 若任务 JSON 里的路径是本机绝对路径（如 /Users/me/videos/a.mp4），
@@ -54,22 +65,28 @@ Python Worker 使用说明
    - 建议：在服务器上把视频放在固定目录（如 /server/videos），
      拷过去的 data 里 queue 的 JSON 中路径统一用本机前缀，用 --path-replace 换成服务器前缀。
 
-5) 多进程并发
+6) 多进程并发
    当前 worker 为单进程单线程循环。要跑满多核，可在同一 data-dir 下启动多个进程：
    - 任务抢占通过 queue/<task_id>.lock 原子创建，多进程不会抢到同一任务。
    - 示例（4 个 worker 进程）：
      for i in 1 2 3 4; do python worker.py --data-dir /server/data & done
      或使用 systemd/supervisor 起多个 worker 实例。
 
-6) 暂停/继续
+7) 暂停/继续
    队列暂停由 queue_config.json 的 queue_paused 控制（"true" 为暂停）。
    Python worker 会定期读该配置，为 true 时不取新任务。可由 Java 前端或手动改该文件控制。
 
-7) 与 Java 的约定
-   - 任务与 config 格式见项目根目录 queue_task_schema.txt。
+8) 对方如何提供数据（喂数据）
+   - 运行以下命令查看完整任务/队列格式说明：
+     videoconverter --show-schema
+   - 按说明在数据目录下创建 queue/<task_id>.json（status=PENDING），
+     Worker 会按 created_time 顺序抢占并执行。
+
+9) 与 Java 的约定
+   - 任务与 config 格式详见 --show-schema 或项目根目录 queue_task_schema.txt。
    - metadata.json 与 Java 生成的格式一致，合成（MERGE）以 metadata 为准。
 
-8) 打包与部署
+10) 打包与部署
    - 打 zip 包（拷贝到服务器解压即用）：
      cd src/python
      ./build_deploy.sh
@@ -78,4 +95,4 @@ Python Worker 使用说明
    - 或安装为命令行（本机/服务器均可）：
      cd src/python
      pip install .
-     然后可直接运行： videoconverter [--data-dir DIR] [--path-replace OLD=NEW]
+     然后可直接运行： videoconverter 或 videoconverter-worker [--data-dir DIR] [--path-replace OLD=NEW]

videoconverter_worker-1.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+ffmpeg_runner.py,sha256=swnOI6cLw9Pe_Vn1XhOnjVzOI7GpUEkqNUgwcpPtlxY,11633
+metadata.py,sha256=PPigPLAZIZ_vI6zeQgY6EQ4uuZskJEXvE-md7nNI7G4,2881
+schema.py,sha256=3ILdGl5qSQOSvKfiKWcnaxdyHwV4rDvGnRZIparVp3o,4361
+task_queue.py,sha256=sYQelPRuTbP9g_sPs69xOR3n5SIxGBFxY4EI5ueQrQs,11822
+worker.py,sha256=NvR_dQQWaHelf7rnX-vGSMUocLkpYr5k37FWyCHhGyA,18002
+videoconverter_worker-1.0.2.dist-info/METADATA,sha256=Dm9e4sYkLd3JDk8J5m1y-kSkx0KKXqe6ZVwsvAg2zwI,5139
+videoconverter_worker-1.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+videoconverter_worker-1.0.2.dist-info/entry_points.txt,sha256=qedJjjix02n9Hz8adBioDIpGHghm8S3fQZdFwM5LV1A,83
+videoconverter_worker-1.0.2.dist-info/top_level.txt,sha256=iamWyiqUZ4X0_2UZx6GEk9gsPmiI9qhse_15HqtzUj8,48
+videoconverter_worker-1.0.2.dist-info/RECORD,,

{videoconverter_worker-1.0.0.dist-info → videoconverter_worker-1.0.2.dist-info}/top_level.txt

@@ -1,4 +1,5 @@
 ffmpeg_runner
 metadata
+schema
 task_queue
 worker

worker.py

@@ -18,6 +18,8 @@ from ffmpeg_runner import (
     run_desubtitle,
     merge_chunks,
     get_duration,
+    get_video_size,
+    check_ffmpeg_available,
 )
 
 logging.basicConfig(
@@ -102,6 +104,30 @@ def process_desubtitle_task(store: QueueStore, task: dict) -> None:
                 logger.warning("更新 metadata 或检查合成失败: videoId=%s, chunkId=%s, %s", video_id, chunk_id, e)
 
 
+def _merge_creation_lock(store: QueueStore, video_id: str):
+    """对同一 video_id 串行化「检查并创建 MERGE」，避免多进程同时建两个 MERGE。"""
+    from contextlib import contextmanager
+    safe_id = (video_id or "").replace("/", "_").replace("\\", "_")[:64]
+    lock_path = store.queue_dir / f".merge_{safe_id}.lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    @contextmanager
+    def _held():
+        try:
+            import fcntl
+            f = open(lock_path, "w")
+            try:
+                fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+                yield
+            finally:
+                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+                f.close()
+        except ImportError:
+            yield  # Windows 无 fcntl，接受可能的重复 MERGE
+
+    return _held()
+
+
 def check_and_create_merge_task(store: QueueStore, video_id: str, output_dir: str, config: dict) -> None:
     metadata_path = Path(output_dir) / video_id / "metadata.json"
     if not metadata_path.exists():
@@ -111,10 +137,11 @@ def check_and_create_merge_task(store: QueueStore, video_id: str, output_dir: st
     total = len(chunks)
     processed = get_processed_chunks(data)
     pending = get_pending_chunks(data)
-    existing = store.get_tasks_by_video_id(video_id)
-    has_merge = any(t.get("task_type") == "MERGE" for t in existing)
-
-    if total > 0 and len(processed) == total and not pending and not has_merge:
+    if total == 0 or len(processed) != total or pending:
+        return
+    with _merge_creation_lock(store, video_id):
+        if store.has_merge_task_for_video_id(video_id):
+            return
         store.create_merge_task(video_id, output_dir, config)
         logger.info("自动创建合成任务: videoId=%s, 已处理 %d/%d 块", video_id, len(processed), total)
 
@@ -218,8 +245,96 @@ def work_loop(store: QueueStore) -> None:
             time.sleep(5)
 
 
+def run_simple_compose(
+    input_file: str,
+    output_dir: str,
+    start_sec: float,
+    end_sec: float,
+    crop_bottom: int = 208,
+    crop_left: int = 293,
+    crop_right: int = 293,
+) -> str:
+    """
+    简易模式：在当前目录/指定目录内，对单个视频做「切分→去字幕→合成」全流程，不经过队列。
+    返回最终合成文件路径；异常时抛出。
+    """
+    input_path = Path(input_file)
+    if not input_path.exists():
+        raise FileNotFoundError(f"文件不存在: {input_file}")
+    if end_sec <= 0:
+        end_sec = get_duration(input_file)
+    start_sec = max(0.0, start_sec)
+    if start_sec >= end_sec:
+        raise ValueError("开始时间必须小于结束时间")
+
+    width, height = get_video_size(input_file)
+    config = {
+        "targetWidth": 1920,
+        "targetHeight": 1080,
+        "cropTop": 0,
+        "cropBottom": crop_bottom,
+        "cropLeft": crop_left,
+        "cropRight": crop_right,
+        "keepAudio": True,
+        "audioBitrate": 192,
+        "videoQuality": 23,
+        "originalWidth": width,
+        "originalHeight": height,
+        "startTime": start_sec,
+        "endTime": end_sec,
+        "useHardwareAccel": False,
+    }
+
+    logger.info("简易模式: 切分 %s (%.0f - %.0f秒), 字幕高度(裁底)=%d", input_path.name, start_sec, end_sec, crop_bottom)
+    metadata, video_id = split_video_to_chunks(input_file, output_dir, 120.0, start_sec, end_sec)
+    chunk_list = [c for c in (metadata.get("chunks") or []) if c.get("originalPath")]
+    logger.info("切分完成: %d 块，开始去字幕", len(chunk_list))
+
+    for ch in chunk_list:
+        rel = ch.get("originalPath", "")
+        if not rel:
+            continue
+        chunk_path = Path(output_dir) / rel
+        if not chunk_path.exists():
+            continue
+        chunk_id = ch.get("chunkId", "")
+        out_dir_v = Path(output_dir) / video_id
+        out_dir_v.mkdir(parents=True, exist_ok=True)
+        output_file = out_dir_v / (Path(chunk_path).stem + "_desub.mp4")
+        cfg = dict(config)
+        cfg["inputPath"] = str(chunk_path)
+        cfg["outputPath"] = str(output_file)
+        cfg["startTime"] = 0
+        cfg["endTime"] = 0
+        cfg["forceKeyframeAtStart"] = True
+        run_desubtitle(cfg, str(chunk_path), str(output_file))
+        meta_path = Path(output_dir) / video_id / "metadata.json"
+        if meta_path.exists():
+            update_chunk_processed(str(meta_path), chunk_id, str(output_file))
+
+    data = load_metadata(str(Path(output_dir) / video_id / "metadata.json"))
+    processed = get_processed_chunks(data)
+    if not processed:
+        raise RuntimeError("没有已处理的 chunk")
+    start_t = processed[0]["startTime"]
+    end_t = processed[-1]["endTime"]
+    out_file = Path(output_dir) / f"{video_id}_merged.mp4"
+    merge_chunks(data, start_t, end_t, str(out_file))
+    logger.info("简易模式完成: %s", out_file)
+    return str(out_file)
+
+
 def main() -> int:
-    parser = argparse.ArgumentParser(description="VideoConverter Python Worker")
+    parser = argparse.ArgumentParser(
+        description="VideoConverter Python Worker：从队列执行任务，或简易模式单文件/批量处理。",
+        epilog="""
+简易模式示例（不经过队列，指定开始/结束时间、字幕高度，便于测试）:
+  单文件:  videoconverter --simple --dir . --start 0 --end 120 --crop-bottom 208 --file 视频.mp4
+  批量:    videoconverter --simple --dir . --start 0 --end 60 --crop-bottom 208 --batch
+  参数:    --dir 工作目录  --start/--end 秒(0=到结尾)  --crop-bottom 字幕高度  --output 输出目录
+""",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     parser.add_argument(
         "--data-dir",
         default=None,
@@ -236,8 +351,117 @@ def main() -> int:
         default=1,
         help="并发 worker 数（默认 1，多进程时由外部起多个 worker 进程）",
     )
+    parser.add_argument(
+        "--show-schema",
+        action="store_true",
+        help="打印任务/队列输入格式说明（对接方如何喂数据）",
+    )
+    parser.add_argument(
+        "--simple",
+        action="store_true",
+        help="简易模式：指定目录内输入开始/结束时间、字幕高度，单文件或批量处理（便于测试）",
+    )
+    parser.add_argument(
+        "--dir",
+        default=".",
+        help="简易模式：工作目录，默认当前目录",
+    )
+    parser.add_argument(
+        "--start",
+        type=float,
+        default=0.0,
+        help="简易模式：开始时间（秒）",
+    )
+    parser.add_argument(
+        "--end",
+        type=float,
+        default=0,
+        help="简易模式：结束时间（秒），0 表示到视频结尾",
+    )
+    parser.add_argument(
+        "--crop-bottom",
+        type=int,
+        default=208,
+        help="简易模式：字幕高度（裁底像素），默认 208",
+    )
+    parser.add_argument(
+        "--crop-left",
+        type=int,
+        default=293,
+        help="简易模式：左侧裁剪像素，默认 293",
+    )
+    parser.add_argument(
+        "--crop-right",
+        type=int,
+        default=293,
+        help="简易模式：右侧裁剪像素，默认 293",
+    )
+    parser.add_argument(
+        "--file",
+        default=None,
+        help="简易模式：指定一个视频文件（否则需用 --batch）",
+    )
+    parser.add_argument(
+        "--batch",
+        action="store_true",
+        help="简易模式：批量处理当前目录下所有视频（.mp4/.mkv/.mov）",
+    )
+    parser.add_argument(
+        "--output",
+        default=None,
+        help="简易模式：输出目录，默认 <dir>/videoconverter_out",
+    )
     args = parser.parse_args()
 
+    if args.show_schema:
+        from schema import INPUT_SCHEMA
+        print(INPUT_SCHEMA)
+        return 0
+
+    err = check_ffmpeg_available()
+    if err:
+        logger.error("%s", err)
+        return 1
+
+    if args.simple:
+        base = Path(args.dir).resolve()
+        if not base.is_dir():
+            logger.error("目录不存在: %s", base)
+            return 1
+        out_dir = Path(args.output).resolve() if args.output else (base / "videoconverter_out")
+        out_dir.mkdir(parents=True, exist_ok=True)
+        if args.file:
+            p = Path(args.file)
+            files = [p.resolve() if p.is_absolute() else (base / p).resolve()]
+            if not files[0].exists():
+                logger.error("文件不存在: %s", files[0])
+                return 1
+        elif args.batch:
+            exts = {".mp4", ".mkv", ".mov", ".avi", ".flv"}
+            files = sorted([p for p in base.iterdir() if p.is_file() and p.suffix.lower() in exts])
+            if not files:
+                logger.error("目录下没有视频文件: %s", base)
+                return 1
+        else:
+            logger.error("简易模式请指定 --file <路径> 或 --batch")
+            return 1
+        failed = 0
+        for f in files:
+            try:
+                run_simple_compose(
+                    str(f),
+                    str(out_dir),
+                    args.start,
+                    args.end,
+                    crop_bottom=args.crop_bottom,
+                    crop_left=args.crop_left,
+                    crop_right=args.crop_right,
+                )
+            except Exception as e:
+                logger.exception("处理失败 %s: %s", f.name, e)
+                failed += 1
+        return 1 if failed else 0
+
     data_dir = args.data_dir or __import__("os").environ.get(
         "VIDEOCONVERTER_DATA_DIR",
         str(Path.home() / ".videoconverter" / "data"),
@@ -258,6 +482,11 @@ def main() -> int:
     if path_replace:
         logger.info("路径替换: %s -> %s", path_replace[0], path_replace[1])
 
+    # 断电/强制关机后：将无主 PROCESSING 任务重置为 PENDING，便于继续处理
+    n = store.recover_orphaned_processing()
+    if n > 0:
+        logger.info("已恢复 %d 个孤儿任务（PROCESSING -> PENDING）", n)
+
     work_loop(store)
     return 0
 

videoconverter_worker-1.0.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-ffmpeg_runner.py,sha256=k7yhCVfAEfY4CcFxKhIdEtlQDdn435JR32Kk_j-krg4,9851
-metadata.py,sha256=PPigPLAZIZ_vI6zeQgY6EQ4uuZskJEXvE-md7nNI7G4,2881
-task_queue.py,sha256=zzcXhE40UFWF5CtJfh8dwv50dzER519hYfo9xPEu_iw,9224
-worker.py,sha256=tuDSrqtoC_4BqlEkbDm_7MNC0qLWjaO5wpmikq-ejB0,9832
-videoconverter_worker-1.0.0.dist-info/METADATA,sha256=yX61rjdqytOHP_Pm3GIvVcuGHI3lrN2ZnMh8PdvO2A4,3926
-videoconverter_worker-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-videoconverter_worker-1.0.0.dist-info/entry_points.txt,sha256=qedJjjix02n9Hz8adBioDIpGHghm8S3fQZdFwM5LV1A,83
-videoconverter_worker-1.0.0.dist-info/top_level.txt,sha256=Dp_FI_KBiJQvfLddduLaKINmGfq3ANDn6No5yUVlu84,41
-videoconverter_worker-1.0.0.dist-info/RECORD,,