SubZH · 影库中文字幕助手

Automatic Chinese subtitle finder for local movie libraries, matching across Shooter/Xunlei/Assrt/OpenSubtitles.

给本地电影库（NAS / 移动硬盘）自动补全中文字幕的小工具。带一个 macOS 窗口壳。

扫描影库 → 找出缺中文字幕的电影 → 多来源逐个尝试下载 → 按视频名存成外挂字幕， 全程零验证码、零手动。

字幕来源（多源链，命中即止）

按 provider_order 顺序逐个尝试，第一个命中就用它：

来源	匹配方式	是否要 key	备注
shooter（射手网）	视频文件哈希	否	按内容匹配，绝不串片，但收录有限
xunlei（迅雷影音）	片名 + 年份/相关性过滤	否	国内库大，覆盖广
assrt（伪射手）	片名 + 过滤	需免费 token	限速 5 次/分钟，内置限速器
opensubtitles	IMDB ID 精确查	需 Api-Key	境外片强，但有每日额度，放最后省额度

加新来源很简单：在 subzh/providers/ 写一个 Provider 子类，注册进 __init__.py， 加进 provider_order 即可。SubHD/字幕库这类需登录+验证码的站不在自动来源里（见路线图）。

为什么 OpenSubtitles 要按 IMDB ID 查

OpenSubtitles 主要按原名/IMDB ID 索引。用中文片名做文本搜索，冷门外语片几乎都搜不到； 改用 NFO 里的 tt... ID 精确查，命中率天差地别。

国内来源（迅雷/射手/Assrt）按片名搜，靠片名相关性 + 年份一致性过滤防串片； 默认直连不走代理（cn_proxy_bypass），境外的 OpenSubtitles 才用代理。

影库需是 Kodi/Plex 常见的刮削结构：每部电影一个目录，内含视频 + movie.nfo （NFO 里有 <id>tt...</id>）。

安装（普通用户，推荐）

下载 SubZH.dmg → 双击打开 → 把 SubZH 拖进 Applications → 从启动台/应用程序里打开。

首次打开若提示「来自身份不明的开发者」（未做苹果签名/公证）， 右键点 App → 打开 → 再点"打开" 即可，只需一次。

开箱即用、无需任何 key：迅雷 / 射手两个来源不需要登录或密钥，装好直接能用。 想多覆盖一些片，再在窗口里选填 OpenSubtitles / Assrt 的 key（见下）。

安装与运行（开发期）

⚠️ GUI 需要带较新 Tk（8.6/9.0）的 Python。macOS 自带的 /usr/bin/python3 用的是老 Tk 8.5，在部分 macOS 版本上启动窗口会直接崩（SIGABRT）。 请用 python.org 的 Python 或 brew install python-tk，并用虚拟环境：

git clone https://github.com/xmcter/SubZH.git && cd SubZH
python3.11 -m venv .venv          # 用带新 Tk 的解释器建虚拟环境
source .venv/bin/activate
pip install -r requirements.txt
python run_gui.py                 # 启动窗口

纯命令行（CLI 不依赖 Tk，系统 python3 也能跑）：

python -m subzh.cli config   # 看配置文件位置/内容
python -m subzh.cli scan     # 离线统计有多少缺中文字幕
python -m subzh.cli probe    # 联网探测有多少能下到（不下载、不耗额度）
python -m subzh.cli run      # 真正下载并落地

配置

首次运行会在 ~/.subzh/config.json 生成配置，照 config.example.json 填：

字段	说明
api_key	OpenSubtitles，在 https://www.opensubtitles.com/consumers 免费申请；不填则跳过该来源
assrt_token	Assrt，在 https://assrt.net/api/doc 免费申请；不填则跳过该来源
provider_order	来源尝试顺序，默认 ["shooter","xunlei","assrt","opensubtitles"]
proxy	境外来源（OpenSubtitles）用；留空直连
cn_proxy_bypass	国内来源是否绕过代理直连，默认 true
languages	OpenSubtitles 的语言优先级，默认 ["zh-cn","zh-tw"]
libraries	影库根目录列表，每个根下一层是各电影目录

⚠️ api_key / assrt_token 是私密信息，config.json 已在 .gitignore 里，不会上传。

关于 OpenSubtitles 额度

• /download 免费额度约 100 次 / 24 小时，UTC 0 点重置；
• 额度绑 Api-Key（不绑 IP，换代理无效）；
• 用尽后工具会自动暂停并提示，次日继续跑即可（已下好的会自动跳过）。

打包 DMG（开发者）

PYTHON=.venv/bin/python ./build_dmg.sh
# 产物：dist/SubZH.app 和 dist/SubZH.dmg

用 PyInstaller 打包（对 Python 3.11+ 比 py2app 稳）。未做代码签名/公证， 分发后普通用户首次打开需「右键 → 打开」。如需免此提示，要 Apple 开发者证书做签名+公证。

路线图

• v1：扫库 + 多来源全自动下载（射手/迅雷/Assrt/OpenSubtitles）
• 硬字幕 OCR 检测（识别已内嵌中文字幕的片，避免重复下）
• SubHD/字幕库 等 native 站的半自动接入（需登录/验证码）
• 英文字幕 + 机翻兜底（可选）

协议

MIT，见 LICENSE。