Python Worker 使用说明

0) 安装（任选其一）
   - 从 PyPI 安装（推荐，Windows/Linux/macOS 通用）：
     pip install videoconverter-worker
     安装后运行： videoconverter 或 videoconverter-worker [--data-dir DIR] [--path-replace OLD=NEW]
   - 或从本地源码安装： cd src/python && pip install .

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。
   适合在服务器上运行，利用多核与高性能做切分、去字幕、合成。

3) 环境
   - Python 3.8+
   - 系统已安装 ffmpeg、ffprobe（或在 PATH 中）
   - 可选：环境变量 FFMPEG_PATH、FFPROBE_PATH 指定路径

4) 本机与 Java 共用同一队列（同一台机器）
   - 数据目录一致即可，例如: ~/.videoconverter/data
   - 先由 Java 前端创建任务（写 queue/*.json），再在本机运行 Python worker 处理：
     cd src/python
     python worker.py
   - 或指定数据目录：
     python worker.py --data-dir /path/to/.videoconverter/data

5) 把「前端处理过的文件夹」拷到服务器后运行
   - 将本机用于队列的「数据目录」整个拷到服务器（例如 /server/data），
     其中应包含 queue/ 目录及 queue/*.json 任务文件。
   - 若任务 JSON 里的路径是本机绝对路径（如 /Users/me/videos/a.mp4），
     需要在服务器上做路径替换，否则找不到文件：
     python worker.py --data-dir /server/data --path-replace "/Users/me/videos=/server/videos"
   - 环境变量方式（便于脚本/ systemd）：
     export VIDEOCONVERTER_DATA_DIR=/server/data
     export VIDEOCONVERTER_PATH_REPLACE="/Users/me/videos=/server/videos"
     python worker.py
   - 建议：在服务器上把视频放在固定目录（如 /server/videos），
     拷过去的 data 里 queue 的 JSON 中路径统一用本机前缀，用 --path-replace 换成服务器前缀。

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 实例。

7) 暂停/继续
   队列暂停由 queue_config.json 的 queue_paused 控制（"true" 为暂停）。
   Python worker 会定期读该配置，为 true 时不取新任务。可由 Java 前端或手动改该文件控制。

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 为准。

10) 打包与部署
   - 打 zip 包（拷贝到服务器解压即用）：
     cd src/python
     ./build_deploy.sh
     会生成 videoconverter.zip，解压后在该目录执行：
     python3 worker.py [--data-dir DIR] [--path-replace OLD=NEW]
   - 或安装为命令行（本机/服务器均可）：
     cd src/python
     pip install .
     然后可直接运行： videoconverter 或 videoconverter-worker [--data-dir DIR] [--path-replace OLD=NEW]
