视频预览字幕功能（本地 + 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 后我可以作为第二源接上（覆盖欧美片更好）。
- 未做「打开预览即自动联网搜索」（避免每次预览都发外网请求），目前是点按钮才检索；需要的话可改成自动。
- 未做字幕样式/字号/位置的自定义（浏览器默认渲染）。
- 未支持多字幕同时挂载与切换记忆（切文件后按规则重新自动选）。