视频预览字幕功能(本地 + SubtitleCat 在线检索)
- 上线:2026-09-19
- 适用:下载中心 8899 的所有视频预览(右侧分栏 / 整页预览 / 转码播放器 / 边转边播)
- 特点:不需要任何 API Key,中文(zh-CN/zh-TW)优先
一、怎么用
- 打开任意视频预览 → 视频右上角出现「字幕」按钮。
- 点开按钮:
- 若同目录已有本地字幕(
视频名.srt / 视频名.zh-CN.srt 等)→ 自动挂载,无需操作;
- 已下载过的在线字幕也会自动挂载中文优先的那条;
- 否则点 「搜索」(检索词已按番号/片名自动填好,如
ADN-027)→ 选一条结果 → 选语言(简体中文排在第一位)→ 自动下载并播放。
- 面板底部有「关闭字幕」。
二、检索源与匹配规则
| 项 | 说明 |
| 在线源 | subtitlecat.com(搜索页 → 详情页含各语言 .srt 直链,含 zh-CN/zh-TW) |
| 白名单 | 只允许从 subtitlecat.com 下载,且仅 .srt/.ass/.ssa/.vtt/.zip,单文件 ≤4MB |
| 检索词 | 优先提取番号(ADN-027 / ABP-758 / DASS-670);否则用去掉 [...]/(...) 的片名 |
| 语言排序 | zh-CN → zh-TW → zh → en/ja/ko → 其他 |
| 本地字幕 | <视频名>.srt/.ass/.ssa/.vtt/.sub,以及 <视频名>.<语言>.srt(如 xxx.zh-CN.srt) |
三、编码与质量处理(野外字幕的坑)
- 多编码自动识别:依次尝试
UTF-8 → GB18030 → Big5 → CP949(EUC-KR) → Shift_JIS,按「可读字符比例 − 乱码惩罚」打分取最优。野外大量 SRT 是 GBK/Big5/CP949,直接按 UTF-8 读会全是乱码。
- 质量评分:统计 U+FFFD 乱码率与可读字符数,接口回传给前端;乱码超过阈值会在面板上标 「⚠ 疑似乱码」。
- 不可修复的情况:若上游源文件本身已经损坏(例如把 GBK 字节当 UTF-8 解过再存成 UTF-8,产生成片的
锟斤拷/U+FFFD),任何编码都无法还原 —— 只能换一条或换语言。
- 统一转成 WebVTT 交给
<track> 播放;结果缓存在 ~/Downloads/.dl-subs-cache/<视频hash>/<语言>.vtt(含 .json 记录编码与质量)。
四、实测结果(2026-09-19)
| 文件 | 结果 |
abp-758-1.mp4 | ✅ 拿到简体中文字幕:5879 个汉字、0 乱码,样本「2年前 / 来到PRESTIGE的女人 / COOL到不行 不做作」 |
XVSR-790-UNCENSORED-LEAK.mp4 | ✅ 有可用中文字幕(4766 汉字、0 乱码) |
[HD]ADN-027.avi | ❌ SubtitleCat 上该片的所有语言字幕源都已损坏(成片 U+FFFD,不可修复) |
MVSD-467-UNCENSORED-LEAK.mp4 | ⚠ 只有英文字幕 |
DASS-670-UNCENSORED-LEAK.mp4 | ⚠ 搜索无结果 |
结论:对日系/番号类内容,SubtitleCat 覆盖面不错,大文件命中率较高;但并非每部都有,且偶尔遇到源损坏(面板会标出)。
五、接口(供排查/自动化使用)
B=http://127.0.0.1:8899
P=%2F09-%E8%BF%85%E9%9B%B7%E4%B8%8B%E8%BD%BD%2F... # 视频的 URL 路径(encodeURIComponent)
curl -s "$B/api/sub/list?path=$P" # 本地/缓存字幕 + 自动检索词
curl -s "$B/api/sub/search?path=$P&q=ABP-758" # 检索 SubtitleCat
curl -s "$B/api/sub/langs?path=$P&href=subs%2F453%2F...html" # 该条目的各语言直链
curl -s "$B/api/sub/fetch?path=$P&lang=zh-CN&url=<srt直链>" # 下载+转VTT+缓存
curl -s "$B/api/sub/vtt?path=$P&lang=zh-CN" # 取 WebVTT(可给 <track> 用)
六、已知限制与可扩展
- 只接了 SubtitleCat 一个源。OpenSubtitles REST API 也可达(探测为 200),但它需要免费注册的 Api-Key(搜索接口强制
Api-Key 头)——你提供 Key 后我可以作为第二源接上(覆盖欧美片更好)。
- 未做「打开预览即自动联网搜索」(避免每次预览都发外网请求),目前是点按钮才检索;需要的话可改成自动。
- 未做字幕样式/字号/位置的自定义(浏览器默认渲染)。
- 未支持多字幕同时挂载与切换记忆(切文件后按规则重新自动选)。