SubFlow

基于 WXT + React + TypeScript 的 Chromium 浏览器扩展，一个通用视频字幕增强器，核心能力：

扫描页面中所有 <video>，检测通过浏览器原生 TextTrack / VTTCue 渲染的字幕轨道，将其中的繁体 / 简体中文 VTTCue.text 在本地按所选方向互相转换，并直接修改当前浏览器中的字幕显示。

核心链路只依赖浏览器标准 API：

HTMLVideoElement → video.textTracks → TextTrack → VTTCue → cue.text

因此理论上适用于任何使用原生 TextTrack 渲染字幕的播放器：

• Jellyfin（内置 manualTrack 适配器）
• 自建视频网站 / HTML5 视频播放器
• 在线课程网站
• 其他使用原生 TextTrack / VTTCue 的播放器

不修改任何服务端、视频文件或字幕文件。 整个功能完全运行在浏览器端。

隐私说明：字幕转换完全在用户浏览器本地执行，不会上传字幕内容，也不会调用任何远程翻译 API 或 LLM。

---

技术栈

• WXT（浏览器扩展框架）
• TypeScript
• React 19
• Tailwind CSS
• shadcn/ui 风格组件（基于 Radix UI）
• Manifest V3
• opencc-js（本地繁简互转）

---

开发环境

• Node.js 18+（建议 20+）
• npm 或 pnpm
• Chrome / Edge（Chromium 内核）

---

安装依赖

npm install
# 或使用 pnpm
pnpm install

安装后会自动执行 wxt prepare 生成类型声明。

---

开发命令

# 启动开发模式（自动监听文件变化并热更新）
npm run dev

# Firefox 开发模式
npm run dev:firefox

# 类型检查
npm run typecheck

---

构建命令

# 构建生产版本（输出到 .output/chrome-mv3）
npm run build

# 打包为 zip
npm run zip

---

在 Chrome / Edge 中加载扩展

1. 执行 npm run build。
2. 打开浏览器扩展管理页：
   • Chrome：chrome://extensions
   • Edge：edge://extensions
3. 打开右上角「开发者模式」。
4. 点击「加载已解压的扩展程序」。
5. 选择项目根目录下的 .output/chrome-mv3 文件夹。
6. 打开任意使用原生 TextTrack 渲染字幕的视频页面（例如自部署的 Jellyfin Web），点击工具栏中的扩展图标查看状态。

开发时也可以直接运行 npm run dev，然后同样加载 .output/chrome-mv3 目录（开发模式会自动重新构建）。

---

支持的场景

• 任何通过 video.textTracks 暴露 subtitles / captions 轨道的网页播放器。
• Jellyfin（内置 manualTrack 适配器，任意域名 / IP / 端口，不依赖固定域名）。
• 页面动态创建 / 重新创建 video、SPA 页面切换。
• 播放存在内嵌 SRT（chi）的 MKV 等，字幕为繁体或简体中文。
• 支持「繁体 → 简体」「简体 → 繁体」双向转换，切换方向后自动重新转换。
• 切换电影 / 剧集、切换字幕轨道后自动重新检测。
• 关闭扩展后，字幕恢复为原始内容。
• 刷新页面后扩展自动重新工作。

---

字幕样式

在扩展弹窗中可实时调整以下样式（直接修改 VTTCue）：

• 时间轴偏移：整体提前 / 延后字幕（秒）
• 位置：顶部 / 中部 / 底部 / 默认

所有修改均基于原始快照，关闭扩展后即恢复原始状态。

无法直接工作的场景

以下播放器不使用浏览器原生 TextTrack 渲染字幕，需要单独开发适配器：

• 用 <div class="subtitle"> 等自定义 DOM 绘制字幕的网站
• 使用 Canvas / Shadow DOM / WebAssembly 渲染字幕的播放器
• 自带字幕渲染器（如部分视频站点）

这些场景通过新增 lib/adapters/ 中的适配器即可扩展，无需改动核心引擎。

---

当前限制

• 仅支持「台湾繁体 ↔ 中国大陆简体」双向转换（tw2sp / sp2tw）。
• 仅能处理通过浏览器原生 TextTrack / VTTCue 暴露的字幕；自定义 DOM / Canvas / Shadow DOM 渲染的字幕需新增适配器。
• 不修改 ASS 特效、字幕渲染器等，仅修改 VTTCue 的文本、时间轴与位置。
• 字幕转换在 content script 中执行，首次转换时会懒加载 OpenCC 字典（含简→繁大字典，约 1MB 量级）。

---

后续计划

• AI 翻译、双语字幕
• 字幕编辑器 / 字幕导出
• 更多转换方向（粤语 / 香港繁体等）
• 更多播放器 / 网站适配器（YouTube、Netflix 等）
• 更多样式选项（字体、颜色、描边等，需自定义渲染层支持）
• 可配置的调试日志开关

---

项目结构

entrypoints/
  background.ts               # 后台 service worker（安装/更新生命周期）
  subtitle-enhancer.content.ts  # content script 入口
  popup/                      # 扩展弹窗（React）
components/
  popup/                      # 弹窗业务组件
  ui/                         # shadcn/ui 风格基础组件
lib/
  adapters/                   # 播放器适配器（generic-vtt / jellyfin）
  engine/                     # 通用字幕增强引擎 + video 观察器
  subtitle/                   # 轨道检测、cue 处理、备份、转换门面
  opencc/                     # OpenCC 懒加载与转换实现
  logger.ts                   # 统一日志
  settings.ts                 # 扩展设置（WXT Storage）
  messaging.ts                # popup ↔ content script 消息协议
  utils.ts                    # cn() 工具
assets/                       # 全局样式（Tailwind）

如何新增一个适配器

1. 在 lib/adapters/ 中新建文件，实现 SubtitleAdapter 接口的 id 与 match(track)。
2. 在 lib/adapters/index.ts 的 adapters 数组中注册。
3. 核心引擎与轨道检测无需改动。