MKV Bilingual Subtitle Merger#

从 MKV 视频中提取中文和英文字幕，合并为双语字幕（英文在上，中文在下），再嵌入回 MKV。

Requirements#

• mkvmerge + mkvextract (MKVToolNix) — 必需，用于提取和嵌入字幕
• 安装： brew install mkvtoolnix
• 仅支持文本字幕（SRT / ASS / SSA），不支持图像字幕（PGS / VobSub）

Quick Start#

bash

# 单个文件
python3 scripts/merge_subs.py /path/to/video.mkv

# 批量处理（文件夹内所有 mkv）
python3 scripts/merge_subs.py /path/to/videos/

# 递归处理子文件夹
python3 scripts/merge_subs.py /path/to/videos/ --recursive

# 预览模式（不执行，只显示哪些文件可以处理）
python3 scripts/merge_subs.py /path/to/videos/ --dry-run

脚本路径： scripts/merge_subs.py

How It Works#

1. 扫描字幕轨道 — mkvmerge -i 识别所有字幕轨道，按语言匹配中文（chi/zho/zh/cn）和英文（eng/en）

2. 提取字幕 — mkvextract tracks 将中英文字幕提取为独立文件

3. 合并字幕 — 基于时间戳重叠匹配，合并为中英双语条目：

   • 完全匹配：直接合并，取时间并集
   • 部分重叠（>30%）：合并，取时间并集
   • 无匹配：保留原文条目

4. 嵌入回 MKV — mkvmerge -o 将双语字幕作为新轨道嵌入，设为默认字幕轨道

5. 替换源文件 — 用新文件替换原始 MKV（文件名不变），整个过程原子性操作

Output Format#

• SRT：英文行 + 换行 + 中文行
• ASS：英文文本 + \N + 中文文本

Options#

选项说明-o, --output指定输出文件路径（不指定则直接替换源文件）-r, --recursive递归搜索子目录--keep-temp保留提取的临时字幕文件--dry-run预览模式，不实际执行

Error Handling#

• 无字幕轨道 → 提示并跳过
• 无中文或英文字幕 → 提示并跳过
• 图像字幕（PGS/VobSub）→ 提示不支持并跳过
• mkvmerge/mkvextract 未安装 → 提示安装命令

Batch Processing Rules#

当用户给出文件夹路径或涉及多个文件时，必须先列出目录内容让用户确认后再执行。

流程：

1. 扫描目录，列出所有 MKV 文件（文件名 + 大小 + 字幕状态）
2. 标记已处理和待处理文件（已有「中英双语」字幕轨 = 已处理）
3. 等待用户确认后再执行批量处理
4. 用户可以指定范围（如「只处理 E03-E10」）

示例输出格式：

text

| # | 文件 | 大小 | 状态 |
|---|------|------|------|
| 1 | S01E01 ... | 1.0G | ⬜ 待处理 |
| 2 | S01E02 ... | 989M | ✅ 已处理 |

Notes#

• 默认 直接替换源文件（文件名不变），如需保留源文件请用 -o 指定输出路径
• 合并后的双语字幕轨道语言标记为 chi，轨道名为 中英双语
• 批量处理时自动统计成功/跳过/失败数量
• 单文件处理时无需确认，直接执行