youtube-subtitle-burner

name	youtube-subtitle-burner
slug	youtube-subtitle-burner
displayName	YouTube 视频字幕烧录器
version	1.1.0
summary	下载 YouTube 视频，转录中文字幕并烧录到视频画面，支持抗锯齿渲染
license	MIT
description	下载 YouTube 视频到本地，提取 word-level 时间轴，翻译为中文，用 PIL 逐帧烧录字幕到视频画面。支持 2x 超采样抗锯齿消除文字锯齿。适用于横屏和竖屏视频。最终输出带中文字幕的 H.264 MP4 文件，可直接上传到国内平台。
allowed-tools	Bash(uv:*), Bash(yt-dlp:*), Bash(ffmpeg:*), Bash(ffprobe:*)

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 逐帧绘制。

字幕参数（已验证）：

参数	横屏 (1920x1080)	竖屏 (1080x1920)
字体	STHeiti Medium	STHeiti Medium
字号	56px	58px
文字颜色	黑色	黑色
背景色	黄色半透明 (255,220,0,180)	同左
每行最大字数	15	15
底部边距	60px	200px
圆角半径	8px	8px
超采样倍数	2x	2x

字体路径： /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），不写临时文件。