JP Live Subtitle CN｜在线日语视频实时中文字幕本地浏览器插件

JP Live Subtitle CN 是一个面向在线日语视频的实时中文字幕本地浏览器插件：Chrome 扩展捕获当前网页视频的标签页音频，本地 Python 引擎完成日语 ASR、日译中翻译和可选说话人标注，最后把简体中文字幕直接叠加到网页视频上。

它适合给 YouTube、Niconico、TVer、网课、访谈、直播回放等在线日语视频补实时中文字幕。只要 Chrome 能捕获该页面的标签页音频，就可以用本地模型生成字幕；音频不上传云端，模型推理在本机完成。

项目默认目标是“本地优先、低延迟、可诊断”：所有关键延迟和 ASR/翻译质量信号都会写入本地日志，方便持续优化。

项目关键词

• 中文：日语视频实时中文字幕、本地浏览器插件、Chrome 字幕插件、在线日语视频翻译、日译中实时字幕、日语听译、实时字幕翻译、本地 ASR、本地翻译。
• English: Japanese video Chinese subtitles, Japanese to Chinese live subtitles, local browser extension, Chrome subtitle extension, real-time subtitle translator, local ASR, local speech translation.

适合场景

• 在线日语视频没有中文字幕，或者现有字幕质量不够好。
• 想在浏览器里直接看日语视频，同时获得实时简体中文字幕。
• 不希望把视频音频上传到云端 ASR 或翻译服务。
• 想持续调试 ASR、翻译、VAD、说话人标注和字幕延迟。

功能概览

• 在线日语视频实时中文字幕：Chrome MV3 扩展使用 tabCapture 捕获当前标签页音频，并在网页内显示中文字幕浮层。
• 日语识别 + 日译中翻译：默认使用本地 ASR 模型识别日语，再用本地翻译模型生成简体中文字幕。
• 伪流式预览：说话过程中会先显示日语预览，完整句或稳定片段通过后再翻译成中文。
• 新字幕即时显示：每条中文翻译完成后立即替换到当前字幕行，不再等待上一句的显示停留时间；上一句会保留为历史行辅助理解。
• 可选说话人标注：make engine-speaker 可以启用本地声纹识别，为多人对话标注 A/B/C...，并在字幕浮层中显示颜色和标签。
• 坏样本采集与回放：页面内可点击 标记坏样本 保存音频片段；本地脚本可生成优先级报告并回放 ASR 结果。
• 多后端保留：除默认本地模型路线外，还保留可选 ASR/翻译对比和回退入口，按需安装即可。

项目优势

• 隐私友好：音频、字幕、日志都在本机处理，不依赖云端 ASR 或翻译服务。
• Apple Silicon 优化：默认 ASR 和翻译走本地 MLX/Metal 路线，适合 M 系列 Mac 本地运行。
• 低延迟优先：AudioWorklet 小块传输、Silero VAD 切句、ASR final 优先调度、翻译 worker 池共同降低等待时间。
• 抗噪和防幻觉：内置 no-speech、logprob、重复文本、高温垃圾、低置信短句等过滤策略，减少无声片段被翻译成流畅错句。
• 上下文翻译：本地翻译模型会收到短上下文和动态术语提示，改善短句、省略句、口语和特定词汇的翻译效果。
• 可观察、可复盘：logs/subtitles.jsonl 会记录 ASR、翻译、VAD、说话人、队列和总延迟；坏样本可单独回放分析。
• 浏览器体验完整：支持页面按钮、右键菜单、快捷键启动；浮层可拖动，支持刷新最近音频和重置当前视频上下文。

工作原理

Chrome 标签页音频
  -> MV3 tabCapture
  -> offscreen document + AudioWorklet
  -> WebSocket 发送 Float32 单声道音频
  -> 本地 Python 引擎
  -> Silero VAD 切句
  -> 本地日语 ASR
  -> ASR 质量过滤 / 预览稳定判断
  -> 本地日译中翻译
  -> 可选 sherpa-onnx 说话人标注
  -> WebSocket 返回字幕事件
  -> Chrome content script 渲染网页浮层

环境要求

推荐环境：

• macOS + Apple Silicon（M 系列芯片）
• Chrome 或 Chromium 系浏览器
• Python 3.11+
• make
• 足够的磁盘空间下载本地模型

说明：

• 默认 make engine 依赖 MLX/Metal，主要面向 Apple Silicon。
• 首次下载和首次启动模型会比较慢，后续会复用本地缓存。
• Chrome 只能捕获普通网页标签页音频，不能捕获 chrome://、扩展页或 DevTools 页。

快速开始

1. 获取代码

git clone https://github.com/ruiw2674-cloud/jp-live-subtitle-cn.git
cd jp-live-subtitle-cn

2. 安装依赖并自动下载默认运行资产

make install

这会创建 apps/engine/.venv，安装本地引擎依赖，并自动把默认日语 ASR 模型和日译中模型下载到项目内的忽略目录：

• models/asr/default/
• models/translation/default/
• models/hf-cache/

这些目录已在 .gitignore 中忽略，不会被提交到 Git。

3. 启动本地字幕引擎

make engine

保持终端窗口不要关闭。默认服务地址是：

ws://127.0.0.1:8765/ws?token=local-subtitle-dev

4. 加载 Chrome 扩展

1. 打开 chrome://extensions。
2. 开启右上角“开发者模式”。
3. 点击“加载已解压的扩展程序”。
4. 选择项目目录下的 apps/extension。
5. 打开或刷新一个真实的视频网页。

5. 开始字幕

在视频网页中任选一种方式启动：

• 点击页面内浮层上的 启动字幕。
• 右键页面，选择 启动 JP Live Subtitle CN。
• 按 Alt+Shift+S 切换字幕。
• 也可以打开扩展 popup，点击启动按钮。

如果 Chrome 提示 Extension has not been invoked for the current page，先在该视频页使用右键菜单或 Alt+Shift+S 授权一次。

启动模式

命令	用途
make engine	默认模式：本地日语 ASR + 本地日译中模型，推荐 Apple Silicon 使用
make engine-speaker	默认模式 + 本地说话人标注
make engine-mock	Mock 字幕，用于验证扩展、WebSocket 和浮层，不需要真实模型
make engine-whisper	可选 C++ ASR fallback，需要先运行 make install-apple-asr
make engine-quality	更高 ASR 质量的可选 fallback 配置，延迟更高
make engine-faster	可选 CPU ASR fallback，需要额外下载模型
make engine-nllb	可选翻译 fallback，需要额外准备模型
make engine-argos	可选轻量翻译 fallback，用于对比

可选：开启说话人标注

安装说话人模型：

make install-speaker

启动带说话人标注的引擎：

make engine-speaker

说话人模式会为字幕片段标注 A/B/C...，并在浮层上显示颜色和标签。它适合普通双人/多人对话，但不是重叠语音分离器；多人同时说话或背景噪声很大时，系统会倾向于保持未知或延续最近说话人，以避免污染声纹。

常用调参

翻译并发

make engine TRANSLATION_WORKERS=3

如果本地翻译排队明显，可以尝试增加 worker。若显存/Metal 压力变大，可降回：

make engine TRANSLATION_WORKERS=1

VAD 切句

如果句子切得太早：

make engine VAD_MIN_SILENCE=430

如果希望更快闭合句子，可以尝试较小的静音阈值，但可能更容易切碎句子。

关闭部分修复逻辑

追求最低延迟时，可以关闭二次 ASR 或 rescue：

make engine ASR_SECOND_PASS=--no-asr-second-pass-enabled
make engine ASR_RESCUE=--no-asr-rescue-enabled

诊断与日志

查看最近字幕诊断：

make recent-diag

查看说话人统计：

make speaker-report

检查 Apple Silicon / MLX / MPS / 可选 ASR fallback 状态：

make check-accel

核心日志：

• logs/subtitles.jsonl：每条字幕的 ASR、翻译、VAD、说话人、队列、延迟等诊断信息。
• logs/bad_segments/：手动标记的坏样本音频和元数据。

坏样本回放

页面浮层中点击 标记坏样本 可以保存最近一条字幕对应的音频片段，并可选填写人工校正的日文原文。

生成坏样本优先级报告：

make bad-report

报告会生成：

• logs/bad_segments/bad_segment_report.md
• logs/bad_segments/replay_priority.txt

回放优先级列表中的样本：

make replay-bad-priority-mlx

回放所有 user-marked 样本：

make replay-bad-mlx

如果你想对比可选 C++ ASR profile：

make install-apple-asr
make replay-bad

开发与验证

基础检查：

make check

Mock smoke test：

make smoke

清理本地日志：

make clean-logs
make clean-bad-segments

目录结构

apps/extension/                  Chrome MV3 扩展和字幕浮层
apps/engine/realtime_subtitle/   本地实时字幕引擎
config/translation_hints.json    翻译术语和 ASR 纠错提示
scripts/                         安装、诊断、坏样本回放脚本
docs/                            架构和模型说明
logs/                            本地运行日志和坏样本
models/                          本地模型缓存
third_party/whisper.cpp/         可选 whisper.cpp fallback，会在需要时自动下载

隐私说明

默认工作流不会把音频上传到云服务。Chrome 扩展只把当前标签页音频发送到 127.0.0.1 上的本地引擎；ASR、翻译、说话人标注和日志都在本机完成。

请注意：

• 如果你改造代码接入云模型，请自行更新隐私说明。
• logs/ 可能包含字幕文本和手动保存的音频片段，公开仓库前请不要提交个人日志或坏样本。
• 模型文件体积较大，通常不应提交到 Git 仓库。

已知限制

• 默认配置主要面向日语音频到简体中文字幕。
• 首次模型加载会有明显等待时间。
• 背景音乐、人声重叠、远场噪声、极短口头禅仍可能造成 ASR 漏识别或误识别。
• 说话人标注是“片段级近似声纹标签”，不是专业说话人分离。
• Chrome 对标签页音频捕获有权限限制，部分页面或浏览器内置页面无法捕获。

许可证

本项目使用 MIT License，详见 LICENSE。