YouTube 视频字幕烧录器

下载 YouTube 视频 → 提取字幕时间轴 → 翻译为中文 → 烧录到视频画面（含抗锯齿）。

环境准备

必需依赖

# macOS
brew install ffmpeg yt-dlp

# uv（Python 环境管理，自动处理依赖）
curl -LsSf https://astral.sh/uv/install.sh | sh

Python 脚本使用 PEP 723 内联依赖声明（# /// script），uv run 会自动创建虚拟环境并安装依赖（如 Pillow），用户无需手动管理 Python 环境。

代理设置（中国大陆）

Clash Verge fake-ip 模式下 yt-dlp 必须显式设置代理：

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

代理不通时用 Clash unix socket 切换节点：

curl -s --unix-socket /tmp/verge/verge-mihomo.sock \
  -X PUT 'http://localhost/proxies/%F0%9F%93%B9%20YouTube' \
  -H "Content-Type: application/json" \
  -d '{"name":"⚡ 最快线路"}'

工作流程

第一步：下载视频

# 设代理（中国大陆必需）
export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890

# 下载最高画质，转为 H.264（国内平台兼容）
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/bestvideo+bestaudio/best" \
  --recode-video h264 \
  -o "%(id)s_h264.mp4" \
  "YOUTUBE_URL"

⚠️ 不要用 -f best，会拿到 360p。必须用 bestvideo+bestaudio 分流下载。

第二步：提取字幕时间轴（关键步骤）

⚠️ 必须用 json3 格式，不能用 VTT。VTT 格式有 rolling cues（滚动字幕重复），直接解析会丢失开头字幕段，导致字幕延迟 2 秒以上。

# 下载 json3 格式自动字幕（word-level 精确时间轴）
yt-dlp --skip-download \
  --write-auto-subs \
  --sub-langs en \
  --sub-format json3 \
  -o "VIDEO_ID_json3.%(ext)s" \
  "YOUTUBE_URL"

然后运行解析脚本，将 json3 的 word-level 时间轴提取为句子段落：

uv run SKILL_DIR/scripts/parse_json3_subs.py \
  INPUT.json3 \
  OUTPUT_segments.json

输出格式：[{"start": 0.00, "end": 3.26, "text_zh_src": "English sentence"}, ...]

参数说明：
- 字幕按句号/问号/感叹号或 5 秒间隔分组
- 每段起始时间精确到该段第一个词的出现时间
- 首段从 0 秒开始（不会丢失开头内容）

第三步：翻译字幕

使用 LLM 将英文翻译为中文。批量处理（每批 20 条），规则：

• 译文简洁，适合视频字幕（≤20 中文字/段）
• 去除 [music] 等标签
• 专有名词保持原文（Claude, YouTube, Reddit 等）
• 输出在每段添加 text_zh 字段

uv run SKILL_DIR/scripts/translate_subs.py \
  INPUT_segments.json \
  OUTPUT_translated.json

> 注意：translate_subs.py 是批量调用 LLM 的辅助脚本。也可以直接用 agent/LLM 内联翻译，将 text_zh_src 翻译为 text_zh。

第四步：烧录字幕到视频（含抗锯齿）

这是核心步骤。ffmpeg 8.x 的 subtitles/ass filter 在某些平台不渲染，改用 Python PIL 逐帧绘制。

字幕参数（已验证）：

字体路径： /System/Library/Fonts/STHeiti Medium.ttc
（PingFang.ttc 在 PIL 中不可用，用 STHeiti Medium 替代）

抗锯齿原理（2x 超采样）：
1. 将每帧放大到 2 倍分辨率（如 1920x1080 → 3840x2160）
2. 在 2x 画布上用 2x 字号（112px）渲染字幕
3. 用 LANCZOS 算法缩回原始分辨率
4. 效果：文字边缘平滑，无锯齿

# 烧录字幕（含音频，流式管道不写临时文件）
uv run SKILL_DIR/scripts/burn_subtitles.py \
  --video INPUT_h264.mp4 \
  --subs INPUT_translated.json \
  --output OUTPUT_burned.mp4 \
  --font-size 56 \
  --supersample 2

处理流程（流式管道）：

ffmpeg 解码 → Python PIL 逐帧渲染字幕 → ffmpeg 编码
         （rawvideo pipe，不写临时文件）

⚠️ 不要写临时 raw 文件，1080p × 30fps × 7分钟 ≈ 85GB，磁盘会满。

第五步（可选）：生成预览

烧录完整视频前，先做 10-15 秒预览让用户确认字幕效果：

uv run SKILL_DIR/scripts/burn_subtitles.py \
  --video INPUT_h264.mp4 \
  --subs INPUT_translated.json \
  --output /tmp/preview.mp4 \
  --font-size 56 \
  --supersample 2 \
  --preview 15

完整示例

# 1. 下载视频
export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best" \
  --recode-video h264 -o "VIDEO_h264.mp4" "URL"

# 2. 下载 json3 字幕
yt-dlp --skip-download --write-auto-subs --sub-langs en \
  --sub-format json3 -o "VIDEO_json3.%(ext)s" "URL"

# 3. 解析时间轴
uv run SKILL_DIR/scripts/parse_json3_subs.py VIDEO_json3.en.json3 VIDEO_segments.json

# 4. 翻译（用 LLM 翻译 text_zh_src → text_zh）
# ... agent 内联翻译或用 translate_subs.py ...

# 5. 预览（15秒）
uv run SKILL_DIR/scripts/burn_subtitles.py \
  --video VIDEO_h264.mp4 --subs VIDEO_translated.json \
  --output /tmp/preview.mp4 --font-size 56 --supersample 2 --preview 15

# 6. 烧录完整视频
uv run SKILL_DIR/scripts/burn_subtitles.py \
  --video VIDEO_h264.mp4 --subs VIDEO_translated.json \
  --output VIDEO_burned.mp4 --font-size 56 --supersample 2

常见问题

字幕延迟 / 不同步

原因：使用了 VTT 格式字幕。YouTube VTT 有 rolling cues（每段重复前一段内容），解析时会丢失开头段落。
解决：必须用 json3 格式（--sub-format json3），它包含 word-level 的 tOffsetMs 时间戳。

字幕有锯齿

原因：PIL 直接在原分辨率画布渲染文字，边缘有像素锯齿。
解决：启用 --supersample 2，在 2x 分辨率渲染后用 LANCZOS 缩回。

字幕太小看不清

横屏 1080p 用 56px（之前 22px 太小已废弃）。竖屏用 58px。

ffmpeg subtitles filter 不工作

ffmpeg 8.x 的 subtitles/ass filter 在某些平台（macOS）不渲染。
解决：用 PIL 逐帧绘制（本方案已内置）。

磁盘空间不足

1080p 视频逐帧写 raw 临时文件约 85GB。
解决：burn_subtitles.py 使用流式管道（decode pipe → PIL → encode pipe），不写临时文件。