视频字幕翻译烧录技能
工作流程（6 步）
📦 原始视频.mp4
→ 🎵 提取音频（ffmpeg，~10s）
→ 📝 Whisper 转录日语（~3-5min，base 模型）
→ 📝 LLM 翻译日→中（~2-3min，QClaw 网关）
→ 📝 SRT 转 ASS（<1s）
→ 🎬 NVENC GPU 烧录（~3-6min）
→ ✅ ffprobe 验证
运行方式
# 默认路径运行
python C:\Users\liket\.agents\skills\video-subtitle\scripts\subtitle_translate.py
# 自定义路径（修改脚本顶部的配置变量）
# VIDEO_DIR 视频目录
# OUTPUT_DIR 输出目录
# FFMPEG_DIR ffmpeg bin 目录
# QCLAW_GATEWAY LLM 网关地址
# QCLAW_TOKEN LLM 网关 Token
环境要求： ffmpeg（已加 PATH）、Python openai-whisper、Python deep-translator（MyMemory 回退用）
踩坑速查
| # | 错误 | 原因 | 解决 |
|---|---|---|---|
| 1 | WinError 2 ffmpeg not found |
Whisper 内部调 ffmpeg 但 PATH 里没有 | 脚本开头 os.environ["PATH"] 加入 ffmpeg 目录 |
| 2 | Unable to parse SRT |
ffmpeg ass 滤镜不支持 SRT | 先转 ASS（Step 4） |
| 3 | Unable to parse original_size |
Windows C: 冒号被当分隔符 |
用相对路径 + cwd=ass_dir（脚本已内置） |
| 4 | Whisper translate 质量差 | ja→zh 用 Whisper 翻译效果差 | 只转录，翻译交给 Step 3 LLM |
| 5 | 烧录后视频无字幕 | ffmpeg 静默失败（路径问题） | 必须用 ffprobe 抽检画面，不能只看文件大小 |
| 6 | LLM 翻译条目数不匹配 | 输出格式不稳定 | 脚本内置兜底补空逻辑 |
| 7 | GBK 解码错误 | Windows 控制台默认 GBK | Python 脚本开头设 sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8') |
关键实现细节
Whisper PATH 修复（脚本内置）：
os.environ["PATH"] = r"E:\ffmpeg\SCP\ffmpeg-master-latest-win64-gpl\bin" + os.pathsep + os.environ["PATH"]
烧录相对路径 + cwd（脚本内置）：
ass_dir = os.path.dirname(os.path.abspath(ass_path))
ass_filename = os.path.basename(ass_path)
subprocess.run(cmd, cwd=ass_dir) # cwd 切到字幕目录，相对路径才有效
ASS 字幕样式： Microsoft YaHei UI，白字黑边（PrimaryColour &H00FFFFFF，Outline=2），底部居中。
NVENC 自动回退 CPU： GPU 编码失败时自动降级到 libx264 -preset ultrafast。
性能参考（RTX 4060）
| 步骤 | 30min 视频 |
|---|---|
| 提取音频 | ~10s |
| Whisper base | ~3-5min |
| LLM 翻译（~700条） | ~2-3min |
| SRT→ASS | <1s |
| NVENC 烧录 | ~3-6min |
| 合计 | ~10-15min/视频 |
验证命令
# 检查时长（必须，但不够）
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "output.mp4"
# 截帧验证字幕真的烧进去了（必须！）
ffmpeg -ss 00:05:00 -i "output.mp4" -vframes 1 -q:v 2 frame.jpg
# 然后用图片查看器确认画面底部有字幕
目录结构
视频目录\
├── 原始视频.mp4
├── output\ ← 脚本输出目录（可自定义）
│ ├── video_xxx_subtitled.mp4 成品
│ ├── xxx_audio.wav 中间音频
│ ├── xxx_subs.srt 日语原文
│ ├── xxx_subs_zh.srt 中文翻译
│ └── xxx_subs_zh.ass 中文 ASS
└── final\ ← 可手动建此目录存放成品
脚本特性
- 断点续传：每步检查文件是否存在，已完成则跳过
- 短 hash 文件名：绕过 Windows 260 字符路径限制
- NVENC/CPU 自动切换
- LLM + MyMemory 双翻译引擎（LLM 失败自动回退）
已知局限
- Whisper base 模型对混合音频（BGM+语音+音效）识别一般
--task translate（ja→zh）翻译质量差，不用- 当前只支持日语→中文，其他语言需修改 Whisper language 参数
- faster-whisper 替代 openai-whisper 可提升速度和内存效率（未来改进方向）
