视频字幕翻译烧录技能

工作流程（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 可提升速度和内存效率（未来改进方向）