# 视频预览字幕功能（本地 + SubtitleCat 在线检索）

- 上线：2026-09-19
- 适用：下载中心 8899 的**所有视频预览**（右侧分栏 / 整页预览 / 转码播放器 / 边转边播）
- 特点：**不需要任何 API Key**，中文（zh-CN/zh-TW）优先

## 一、怎么用

1. 打开任意视频预览 → 视频**右上角出现「字幕」按钮**。
2. 点开按钮：
   - 若同目录已有本地字幕（`视频名.srt` / `视频名.zh-CN.srt` 等）→ **自动挂载**，无需操作；
   - 已下载过的在线字幕也会**自动挂载中文优先**的那条；
   - 否则点 **「搜索」**（检索词已按番号/片名自动填好，如 `ADN-027`）→ 选一条结果 → 选语言（**简体中文排在第一位**）→ 自动下载并播放。
3. 面板底部有「关闭字幕」。

## 二、检索源与匹配规则

| 项 | 说明 |
|---|---|
| 在线源 | **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 覆盖面不错，**大文件命中率较高**；但并非每部都有，且偶尔遇到源损坏（面板会标出）。

## 五、接口（供排查/自动化使用）

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