mkmkv-smart 1.1.1

智能视频字幕合并工具

mkmkv-smart

智能视频字幕合并工具 - 基于先进的模糊匹配算法,自动匹配视频和字幕文件并合并为 MKV 容器。

✨ 特性

• 🎯 智能匹配: 使用 rapidfuzz 多算法混合策略,准确匹配视频和字幕
• 🌐 多语言支持: 自动识别和处理多语言字幕,支持语言优先级
  • 支持标准语言代码 (zh-hans, zh-hant, en, ja, ko 等)
  • 兼容常见别名 (CHS/CHT, GB/Big5 等)
• 🔍 语言自动检测: 智能检测字幕语言,支持简繁体中文区分
  • 支持 SRT、ASS、VTT 字幕格式
  • 自动处理多种文件编码 (UTF-8, GBK, Big5 等)
  • 可选自动重命名功能
• 🎵 音频语言检测 (可选): 使用 AI 模型检测音轨语言
  • 基于 Faster-Whisper 高精度模型
  • 支持 99+ 种语言
  • 需要单独安装：pip install mkmkv-smart[audio]
• ⚙️ 灵活配置: 支持 YAML 配置文件和命令行参数
• 🎨 美观输出: 使用 Rich 库提供彩色表格和进度显示
• 🔍 干运行模式: 预览匹配结果,无需实际执行
• 📦 批量处理: 一次处理整个目录的视频和字幕

📋 需求

Python 版本

• 基础功能: Python 3.8+ (包括 3.14) ✅
  • 智能匹配、字幕检测、批量处理等核心功能
• 音频检测功能: Python 3.8 - 3.13 ⚠️
  • Python 3.14 暂不支持: 依赖 onnxruntime 尚未发布 Python 3.14 支持
  • 推荐版本: Python 3.11 或 3.12（ML 生态系统支持最好）

系统依赖

• mkvtoolnix (提供 mkvmerge 命令)

安装 mkvtoolnix

macOS:

brew install mkvtoolnix

Ubuntu/Debian:

sudo apt install mkvtoolnix

Windows: 从 MKVToolNix 官网 下载安装

🚀 安装

方法 1: 从源码安装

# 克隆仓库
git clone https://github.com/cnsunyour/mkmkv-smart.git
cd mkmkv-smart

# 安装基础功能（支持所有 Python 版本 3.8+）
pip install -e .

# 或安装开发依赖
pip install -e ".[dev]"

# 可选：安装音频检测功能（需要 ~500MB，包括 PyTorch）
# ⚠️ 注意：Python 3.14 暂不支持，建议使用 Python 3.11-3.13
pip install -e ".[audio]"

方法 2: 使用 pip (发布后)

# 基础安装（支持所有 Python 版本）
pip install mkmkv-smart

# 包含音频检测功能（Python 3.8-3.13）
pip install mkmkv-smart[audio]

📖 使用方法

基本用法

# 预览匹配结果(干运行)
mkmkv-smart --dry-run ~/Downloads

# 执行合并(输出到源目录)
mkmkv-smart ~/Downloads

# 指定输出目录
mkmkv-smart ~/Downloads ~/Movies

高级用法

# 自定义相似度阈值
mkmkv-smart --threshold 40 ~/Downloads

# 指定匹配方法
mkmkv-smart --method token_set ~/Downloads

# 使用配置文件
mkmkv-smart --config config.yaml ~/Downloads

# 检测视频音轨语言（需要安装 audio 功能）
mkmkv-smart --detect-audio-language ~/Downloads

# 指定音频检测模型
mkmkv-smart --detect-audio-language --audio-model medium ~/Downloads

# 组合使用
mkmkv-smart --dry-run --threshold 35 --config config.yaml ~/Downloads ~/Movies

命令行参数

位置参数:
  source                源目录(包含视频和字幕文件)
  output                输出目录(可选,默认为源目录)

可选参数:
  -h, --help            显示帮助信息
  -n, --dry-run         干运行模式:只显示匹配结果,不实际执行
  -t, --threshold       相似度阈值(0-100,默认: 30)
  -m, --method          匹配方法(默认: hybrid)
                        可选: token_set, token_sort, partial, hybrid
  -c, --config          配置文件路径
  --detect-audio-language
                        自动检测视频音轨语言(需要安装: pip install mkmkv-smart[audio])
  --audio-model {tiny,base,small,medium,large}
                        音频检测模型大小(默认从配置文件读取，配置默认: small)
  --set-audio-language  将检测到的音轨语言信息写入 MKV 文件
  --keep-embedded-subtitles
                        合并外部字幕时保留视频中的嵌入字幕
  --track-order         指定轨道顺序(格式: 0:0,0:1,1:0)
                        0 = 视频文件, 1+ = 字幕文件
                        示例: 0:0,0:1,1:0,2:0 (视频轨0, 音轨1, 字幕1, 字幕2)
  -v, --version         显示版本信息

⚙️ 配置文件

创建 config.yaml:

# 匹配配置
match:
  threshold: 30.0        # 相似度阈值
  method: hybrid         # 匹配方法
  keep_year: true        # 保留年份
  keep_episode: true     # 保留剧集编号

# 语言配置
language:
  priority:              # 语言优先级
    - zh-hans            # 简体中文
    - zh-hant            # 繁体中文
    - zh                 # 中文
    - en                 # 英文
    - ja                 # 日文
    - ko                 # 韩文

# 输出配置
output:
  default_charset: UTF-8 # 默认字幕编码

# 语言检测配置
language_detection:
  enabled: true          # 是否启用自动语言检测（默认启用）
  min_confidence: 0.8    # 最小置信度阈值
  min_chars: 100         # 最小文本长度（字符数）

# 音频检测配置（可选功能）
audio_detection:
  enabled: false         # 是否启用音频检测
  model_size: small      # 模型大小: tiny, base, small, medium, large
  device: cpu            # 设备: cpu, cuda
  compute_type: int8     # 计算类型: int8, float16, float32
  min_confidence: 0.7    # 最小置信度阈值
  max_duration: 30       # 提取音频的最大长度（秒）
  smart_sampling: true   # 智能多点采样
  max_attempts: 3        # 非智能模式下的最大重试次数

生成默认配置:

python -m mkmkv_smart.config

📝 使用示例

示例 1: 电影匹配

文件结构:

Downloads/
├── The.Matrix.1999.1080p.BluRay.x264.mp4
├── The.Matrix.1999.zh-hans.srt
├── The.Matrix.1999.zh-hant.srt
└── The.Matrix.1999.en.srt

命令:

mkmkv-smart --dry-run ~/Downloads

输出:

智能匹配模式
[ 干运行 - 不会实际执行 ]
源目录: /Users/xxx/Downloads
找到 1 个视频文件
找到 3 个字幕文件

匹配结果:
======================================================================

视频: The.Matrix.1999.1080p.BluRay.x264.mp4
  规范化: the matrix 1999

语言     字幕文件                              相似度
───────────────────────────────────────────────────────
zh-hans  The.Matrix.1999.zh-hans.srt          100.0%
zh-hant  The.Matrix.1999.zh-hant.srt          100.0%
en       The.Matrix.1999.en.srt               100.0%

======================================================================
总计: 1 个文件
可处理: 1 个文件

示例 2: 剧集匹配

文件结构:

Series/
├── Breaking.Bad.S01E01.720p.WEB-DL.mp4
├── Breaking.Bad.S01E02.720p.WEB-DL.mp4
├── Breaking.Bad.S01E01.zh.srt
├── Breaking.Bad.S01E01.en.srt
├── Breaking.Bad.S01E02.zh.srt
└── Breaking.Bad.S01E02.en.srt

命令:

mkmkv-smart ~/Series ~/Series/Output

结果: 每集视频会自动匹配对应的字幕,输出到指定目录。

示例 3: 不同发布组匹配

即使视频和字幕来自不同发布组,也能正确匹配:

Movie.2024.1080p.BluRay.x264-GROUP1.mp4
Movie.2024.1080p.WEB-DL.H264-GROUP2.zh.srt

因为规范化会去除发布组标签,所以可以成功匹配。

示例 4: CHS/CHT 语言代码支持

支持常见的中文字幕命名方式:

Movie.2024.1080p.mp4
Movie.2024.CHS.srt       # 简体中文 (自动识别为 zh-hans)
Movie.2024.CHT.srt       # 繁体中文 (自动识别为 zh-hant)
Movie.2024.GB.srt        # 国标简体 (自动识别为 zh-hans)
Movie.2024.Big5.srt      # Big5 繁体 (自动识别为 zh-hant)

命令:

mkmkv-smart --dry-run ~/Downloads

输出:

视频: Movie.2024.1080p.mp4

语言     字幕文件                   相似度
─────────────────────────────────────────
zh-hans  Movie.2024.CHS.srt        100.0%
zh-hant  Movie.2024.CHT.srt        100.0%

所有这些别名会自动映射到标准的语言代码:

• CHS, GB → zh-hans (简体中文)
• CHT, Big5 → zh-hant (繁体中文)

查看完整示例:

python examples/chs_cht_example.py

示例 5: 自动语言检测

当字幕文件名中没有语言代码时，程序会自动检测并重命名字幕文件（通过配置文件中的 language_detection.enabled 控制，默认启用）：

文件结构:

Downloads/
├── Movie.2024.1080p.mp4
├── Movie.2024.subtitle1.srt     # 无语言标识
├── Movie.2024.subtitle2.srt     # 无语言标识
└── Movie.2024.en.srt             # 已有语言标识

命令 (干运行预览):

mkmkv-smart --dry-run ~/Downloads

输出:

将重命名: Movie.2024.subtitle1.srt → Movie.2024.subtitle1.zh-hans.srt (zh-hans, 99.21%)
将重命名: Movie.2024.subtitle2.srt → Movie.2024.subtitle2.zh-hant.srt (zh-hant, 98.75%)
将自动识别并重命名 2 个字幕文件

自动重命名并合并:

mkmkv-smart ~/Downloads

结果:

✓ Movie.2024.subtitle1.srt → Movie.2024.subtitle1.zh-hans.srt (zh-hans, 99.21%)
✓ Movie.2024.subtitle2.srt → Movie.2024.subtitle2.zh-hant.srt (zh-hant, 98.75%)

已自动识别并重命名 2 个字幕文件

重命名后的字幕会自动匹配到视频文件进行合并。

支持的语言检测:

• ✅ 简体中文 (zh-hans)
• ✅ 繁体中文 (zh-hant) - 包含简繁体区分
• ✅ 英文 (en)
• ✅ 日文 (ja)
• ✅ 韩文 (ko)
• ✅ 等 50+ 种语言

支持的字幕格式:

• ✅ SRT (.srt)
• ✅ ASS (.ass)
• ✅ VTT (.vtt)

支持的文件编码:

• UTF-8, GBK, Big5, UTF-16 等

示例 6: 音频语言检测

当视频文件的音轨没有语言标签时，可以使用音频语言检测功能：

前置条件:

# 安装音频检测功能
pip install mkmkv-smart[audio]

文件结构:

Downloads/
├── Movie.2024.1080p.mkv      # 音轨无语言标签
└── Movie.2024.zh-hans.srt

命令:

mkmkv-smart --detect-audio-language ~/Downloads

输出:

音频语言检测模式
使用模型: small
注意: 首次使用会自动下载模型，可能需要几分钟

检测: Movie.2024.1080p.mkv
  音轨 0: ja (置信度: 98.75%)

成功检测 1 个视频的音轨语言

支持的模型:

模型	大小	准确率	速度（CPU）	推荐场景
tiny	39MB	⭐⭐⭐	快速	快速检测
base	142MB	⭐⭐⭐⭐	中等	平衡选择
small	466MB	⭐⭐⭐⭐⭐	中等	默认推荐
medium	1.5GB	⭐⭐⭐⭐⭐	较慢	高精度需求
large	2.9GB	⭐⭐⭐⭐⭐	慢	最高精度

支持的语言:

• ✅ 中文、英文、日文、韩文
• ✅ 等 99+ 种语言

性能说明:

• CPU: 30秒音频约需 3-5 秒处理（small 模型）
• GPU: 30秒音频约需 2-3 秒处理（需要 CUDA）
• 只提取前 30 秒音频进行检测

🧪 匹配算法

mkmkv-smart 使用多种模糊匹配算法:

1. Token Set Ratio

最适合处理包含不同标签的文件名:

Video: "Movie 2024 1080p BluRay x264"
Sub:   "Movie 2024 zh-hans"
→ 提取共同词: {Movie, 2024}
→ 相似度: 100%

2. Token Sort Ratio

适合词序不同的情况:

Video: "2024 Movie Name"
Sub:   "Movie Name 2024"
→ 排序后比较
→ 相似度: 100%

3. Partial Ratio

适合部分匹配:

Video: "Movie Complete Edition 2024"
Sub:   "Movie 2024"
→ 部分字符串匹配
→ 相似度: 90%

4. Ratio

标准编辑距离算法:

Video: "Movie 2024 BluRay"
Sub:   "Movie 2024 WEB-DL"
→ Levenshtein 距离计算
→ 适合相似但不完全相同的文件名

5. WRatio

加权比率算法（自动选择最优策略）:

综合考虑多种因素：
- 字符串长度差异
- 词序重要性
- 部分匹配权重
→ 自适应选择最佳算法

6. Hybrid (默认)

综合以上算法,取最高分:

score = max([
    token_set_ratio(v, s),
    token_sort_ratio(v, s),
    partial_ratio(v, s) * 0.9
])

7. 全局最优分配算法

mkmkv-smart 使用**匈牙利算法（Hungarian Algorithm）**实现全局最优字幕分配:

问题: 当多个视频和多个字幕匹配时，如何确保总体匹配质量最高？

传统贪心算法的问题:

视频A ←→ 字幕1: 90%
视频A ←→ 字幕2: 85%
视频B ←→ 字幕1: 88%
视频B ←→ 字幕2: 70%

贪心: A→字幕1 (90%), B 无匹配
总分: 90%

全局最优分配:

使用匈牙利算法求解:
A→字幕2 (85%) + B→字幕1 (88%)
总分: 173% ✅ 更优

算法特点:

• ✅ 确保总体相似度最大化，避免局部次优
• ✅ 每个字幕最多分配一次，避免冲突
• ✅ 按语言分组独立求解，提高匹配精度
• ✅ 低于阈值的匹配自动过滤

🔧 开发

设置开发环境

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

# 安装开发依赖
pip install -e ".[dev]"

运行测试

# 运行所有测试
pytest

# 运行并显示覆盖率
pytest --cov=src/mkmkv_smart --cov-report=term-missing

# 生成 HTML 覆盖率报告
pytest --cov=src/mkmkv_smart --cov-report=html
open htmlcov/index.html

# 或使用脚本
./run_tests.sh

代码格式化

# 格式化代码
black src/ tests/

# 类型检查
mypy src/

📊 性能对比

与原 Bash 版本对比:

特性	Bash 版本	Python 版本
匹配算法	Jaccard 相似度	Hybrid (多算法)
匹配准确度	~50%	~95%
多语言支持	❌	✅
配置文件	❌	✅
干运行模式	❌	✅
进度显示	简单	Rich 美化
批量处理	✅	✅

🆚 与 Bash 脚本对比

本项目是原 Bash 脚本工具集的 Python 重写版本，专注于外部字幕文件匹配功能。

功能覆盖情况

功能类型	Bash 脚本	Python 实现	说明
外部字幕匹配	mkmkv.sh, mkmkv_smart.sh	✅ 已实现	Python 版本功能更强
内部字幕重排	mkmkv_繁简英.sh 等 4 个脚本	✅ 已实现	使用 --track-order 参数重排内部轨道
音轨调整	mkmkv_调整音轨.sh	✅ 已实现	使用 --track-order 参数重排音轨顺序

使用场景区分

使用 Python 版本 (mkmkv-smart) 当：

• ✅ 你有独立的 .srt / .ass 字幕文件需要合并
• ✅ 文件名不规范，需要智能匹配
• ✅ 需要批量处理多个视频
• ✅ 需要配置文件管理复杂规则
• ✅ 需要自定义轨道顺序（--track-order 参数）
• ✅ 需要自动语言检测和优先级排序

继续使用 Bash 脚本 当：

• ✅ 需要快速的一次性操作
• ✅ 不想安装 Python 依赖

详细功能对比请查看：FEATURE_COMPARISON.md

---

🤝 贡献

欢迎提交 Issue 和 Pull Request!

开发流程

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

代码规范

• 使用 Black 格式化代码
• 添加类型注解
• 编写单元测试
• 更新文档

📄 许可证

MIT License

🙏 致谢

• rapidfuzz - 高性能模糊匹配库
• SciPy - 科学计算库（匈牙利算法实现）
• Rich - 美化终端输出
• MKVToolNix - MKV 容器工具
• langdetect - 语言检测库
• Faster-Whisper - 高性能音频语言检测

📮 联系

项目链接: https://github.com/cnsunyour/mkmkv-smart

---

注意: 此工具仅用于合法拥有的视频和字幕文件。请遵守版权法律。