Subtitle Generator / 字幕生成器

基于可插拔 ASR 引擎的多语言字幕生成技能，支持 Faster-Whisper（优先）和 OpenAI Whisper（兜底），自动检测 GPU 加速，支持 99+ 语言。

⚠️ 执行规则（强制，AI 必须遵守）

1. 必须后台直接执行，禁止委托子代理

字幕生成是纯执行任务，禁止使用 sessions_spawn 或子代理来执行命令，原因：

• - 子代理消耗额外 tokens，纯属浪费
• 直接 exec background:true 效率最高

2. 执行模板

bash
exec background:true command:python3 ~/.openclaw/workspace/skills/subtitle-generator/scripts/main.py <视频文件> [srt|vtt] [语言] --notify

⚠️ 必须使用 background:true，禁止前台执行阻塞主窗口。

3. 执行流程（强制顺序）

步骤 0（首次自动）： engines/init.py 在首次导入时自动检测 ~/.whisper-venv 是否存在，不存在时自动创建 venv 并安装依赖（faster-whisper 优先，openai-whisper 兜底），GPU 可用时自动启用 CUDA 加速。AI 无需手动干预。

1. 1. 收到任务后立即回复用户：「🎬 字幕生成已启动（后台），完成后我会通知你。」
2. 使用 exec background:true 启动任务
3. 任务完成后（进程退出码为 0 或出错）必须 kill 相关进程
4. 通过 openclaw system event --mode now 唤醒 AI，再由 AI 使用 message 工具发送完成通知给用户

- ⚠️ openclaw system event 只唤醒 AI，不发送 Telegram/Discord 等消息 - ✅ 必须用 message 工具才能触达用户

1. 5. 将字幕文件复制到视频同目录
2. 清理 /tmp 中的临时文件

4. 禁止行为

• - ❌ sessions_spawn / 子代理执行此任务
• ❌ 前台执行 exec command:...（无 background:true）
• ❌ 不发送通知就结束会话
• ❌ 任务完成后不 kill 相关进程

5. AI 回复模板

任务启动时：

🎬 字幕生成已启动（后台），完成后我会通知你。
文件：xxx.mp4 | 格式：SRT | 语言：中文

Python 脚本输出 【字幕生成完成】 或 【字幕生成失败】 标记后，AI 被唤醒时使用 message 工具发送：

python
message(
action=send,
# 不传 channel 参数，自动路由到用户当前所在的聊天平台
message=✅ 字幕生成完成\n文件：xxx.srt | 条数：356\n路径：C:\\Users\\xxx\\Videos\\temp\\xxx.srt
)

⚠️ 必须省略 channel 参数，这样才能兼容所有 OpenClaw 支持的聊天工具（Telegram / Discord / WhatsApp / Slack 等）。

使用方法 / Usage

bash
python ~/.openclaw/workspace/skills/subtitle-generator/scripts/main.py

示例 / Examples

bash

英文视频，SRT 字幕

python ~/.openclaw/workspace/skills/subtitle-generator/scripts/main.py video.mp4 srt en --notify

日文视频，VTT 字幕

python ~/.openclaw/workspace/skills/subtitle-generator/scripts/main.py video.mp4 vtt ja --notify

中文视频，自动语言检测

python ~/.openclaw/workspace/skills/subtitle-generator/scripts/main.py video.mp4 srt zh --notify

自动检测任意 Whisper 支持的语言

python ~/.openclaw/workspace/skills/subtitle-generator/scripts/main.py video.mp4 srt --notify

支持语言 / Supported Languages

Whisper 支持 99+ 语言。常用语言代码：

代码	语言
en	英语
zh

中文 |
| ja | 日语 |
| ko | 韩语 |
| fr | 法语 |
| de | 德语 |
| es | 西班牙语 |
| ru | 俄语 |

不传语言参数 = 自动检测。

GPU 加速 / GPU Acceleration

faster-whisper 使用 CTranslate2 作为推理引擎，运行时自动检测并启用 GPU：

系统	GPU	加速方式	说明
Windows + NVIDIA	CUDA	cuDNN + CUDA	CTranslate2 自动加载
macOS M1/M2/M3/M4

Metal | Apple GPU | 需安装 Metal 版 CTranslate2（见下） |
| macOS Intel | CPU | — | 慢但可用 |
| Linux + NVIDIA | CUDA | cuDNN + CUDA | CTranslate2 自动加载 |
| 仅 CPU | — | 降级运行 | 所有平台均支持 |

Apple Silicon (M系列) 安装 Metal 加速版

faster-whisper 默认不包含 Metal 加速，手动安装 Metal 版可获得显著提速：

bash

先激活 venv，再安装 Metal 版 CTranslate2

~/.whisper-venv/bin/pip install \
--extra-index-url https://download.pytorch.org/whl/metal \
faster-whisper

安装后运行时日志会显示 Using device Metal，表示 Metal 加速已启用。

引擎优先级 / Engine Priority

优先级	引擎	说明
1（首选）	faster-whisper	CTranslate2，快 2-4 倍，内存占用更低
2（兜底）

openai-whisper | PyTorch，兼容性更好 |

引擎自动选择，无需手动配置。

输出 / Output

字幕文件生成在视频同目录：

video.mp4
video.srt ← 自动生成

依赖项 / Dependencies

• - faster-whisper 或 openai-whisper（自动选择，自动安装）
• ffmpeg（系统级，必须提前安装）
• ffmpeg-python（Python 绑定，自动安装）

ffmpeg 安装 / ffmpeg Installation

系统	安装命令
Windows	winget install ffmpeg 或 https://ffmpeg.org/download.html
macOS

brew install ffmpeg | | Linux | sudo apt install ffmpeg 或 sudo yum install ffmpeg |

⚠️ ffmpeg 缺失时脚本会报错并给出对应系统的安装提示。