FluentRead YouTube 全屏菜单与字幕同步:修复原理与浏览器专项验证

原创2026-09-26 20:56:212,260 阅读
文章标签:前端国际化人工智能大模型本地部署语音

FluentRead YouTube 全屏菜单与字幕同步:修复原理与浏览器专项验证

导读

本文以 FluentRead(开源浏览器双语翻译插件)的视频字幕功能为背景,深入解析 YouTube 播放页在浏览器全屏场景下字幕菜单挂载与双语字幕同步的两类关键问题及其修复方案:一是 YouTube 将 html 置为全屏、播放器以固定定位铺满窗口的特殊机制导致的挂载点失效;二是原生字幕文本与时间轴 cue 之间的匹配时序错乱。文章同时给出生产扩展构建下的浏览器专项回归方法、验证范围表格与复现命令,帮助开发者在自己的环境里复现测试并理解视频字幕运行时的底层实现。

背景:YouTube 全屏的特殊 DOM 结构

普通视频站点进入全屏时,浏览器通常会把 <video> 或其播放器容器设为全屏元素。YouTube 却不同:它把 html 文档根元素设为全屏目标,实际播放器通过 CSS position: fixed 撑满整个窗口。这种结构对依赖播放器容器定位的扩展 UI 提出了特殊要求——一旦把菜单或字幕层迁移到高度为 0 的 html 上,所有绝对定位都会失效。

在 src/features/video-subtitle/content/videoPlayerLocator.ts 的 playerForVideo 中,源码对此有明确注释:

YouTube 可以将 html 设为全屏,再用 fixed 撑满实际播放器;html 此时可能高度为 0。只有播放器在全屏子树之外时才需要改用更内层的全屏容器。

该模块通过 #movie_player, .html5-video-player 等选择器定位真实播放器,并监听 fullscreenchange 与 resize 事件触发候选重选(videoPlayerLocator.ts)。

问题一:全屏下菜单与字幕层挂载点失效

旧实现的表现

旧实现把菜单与字幕层迁到被设为全屏的 html 上,导致:

  • 菜单顶部落在视口之外,实测 top = -62px,用户无法看到或点击菜单;
  • 字幕层所在容器高度为 0,双语字幕完全不可见。

修复方案

修复后,菜单与字幕层继续挂在实际的 #movie_player 内,并完整支持进入和退出全屏。在 chooseCandidate 的候选排序中,全屏中的视频拥有最高优先级(isFullscreenVideo 命中即返回),随后才是用户交互中的视频、保持原选择、X 信息流中的当前视频等(videoPlayerLocator.ts)。

从源码结构看,这一设计同时服务于两个目的:

  1. 全屏切换的稳定性:全屏进入/退出时通过 fullscreenchange 触发重同步,字幕层始终跟随真实播放器尺寸;
  2. 多播放器隔离:仅在当前播放器内读取原生字幕,避免使用其他残留播放器的文本。

修复后的真实验证中,全屏字幕层恢复到播放器尺寸,菜单可见、命中检测与模式切换正常。

问题二:字幕匹配的时间边界与重复句

旧实现的两个缺陷

  1. 同文/前缀误匹配:旧字幕匹配可以从其他时间段选中相同文本或前缀相同的字幕,导致重复句中译文张冠李戴;
  2. 未来句借用:会用下一条时间轴字幕替换尚未更新的原生文本,造成"提前剧透"式错位。

修复方案:原文 + 时间轴双重校验

修复后,匹配逻辑同时检查原生文本与 cue 的起止时间,不再提前借用未来句子。核心实现在 src/features/video-subtitle/content/subtitleLogic.ts 的 findProgressiveVideoCaptionCue:

  • 对每个候选 cue 计算时间距离(当前播放时间与 cue 区间的关系)、文本精确度、文本长度差、cue 起始时间四元评分,取字典序最小者为最佳匹配;
  • 同一句原文在不同时间段重复出现(如夹具中的 Sea otters have strong teeth. 出现在 0ms 和 2000ms 两处)时,优先按时间距离区分;
  • 针对部分 YouTube 版本只把"当前词"写入 DOM 的情况,当找不到完整前缀匹配时,会利用播放器时间轴反查完整 cue,避免逐词字幕一直等不到稳定句子。

问题三:字幕变动的清理时序

旧实现的表现

  • 等待 120ms 再处理 YouTube 字幕变动,反应迟钝;
  • 原文清空后仍保留译文 420ms,造成"残留译文"。

修复方案:及时清理 + 异步资格管理

修复后:

  • 及时清理旧显示及异步资格,避免过期请求回写 UI;
  • 整句字幕与逐词字幕在同一双语面板中展示;
  • 译文尚未就绪时,先保留当前原文,避免出现译文先于原文的空档。

这与测试夹具中的"延迟返回"用例对应:Slow translation belongs here. 模拟延迟译文,验证译文未就绪时的原文保留策略(scripts/run-youtube-subtitle-sync-test.cjs)。

字幕数据来源:timedtext 网络桥

YouTube 原生字幕通过 timedtext 接口异步到达,FluentRead 通过一个可注入、可测试的网络桥核心来安全地拦截页面 fetch 与 XMLHttpRequest,见 src/features/video-subtitle/content/youtubeTimedTextBridgeCore.ts。其设计要点:

  • 核心不直接引用全局 window、不解析字幕内容也不操作扩展 UI,页面适配器注入真实环境,视频运行时消费消息;
  • 处理 XHR 复用、同步失败、迟到响应等边界;
  • 站点策略只决定捕获范围和消息数据,X 与 YouTube 共享可卸载的网络桥。

用户配置保留

修复同时确保用户保存的字幕显示模式、位置、颜色、字体、服务配置均被保留。播放器菜单提供四种模式(bilingual 双语、translation-only 仅译文、original-only 仅原文、off 关闭)以及 ±0.5 秒的字幕校时步进,见 src/features/video-subtitle/content/playerMenu.ts 与 playerMenu.ts。校时区间被限制在 ±10 秒以内,且手动偏移只改变显示时钟,区间选择仍严格使用原始时间戳(subtitleLogic.ts)。

验证范围

本次验证基于提交 50b5c39e,真实页面为 YouTube 视频《Our Planet · Coastal Seas》。完整验证矩阵如下:

检查 结果与边界
字幕、播放器与架构专项 12 个测试文件、844 项通过;未运行全量套件
字幕匹配与播放器定位覆盖率 两个纯逻辑模块四项覆盖率均为 100%;不代表整个运行时覆盖率
TypeScript、测试审计 通过
Chrome / Firefox 生产构建、文档构建 通过;Firefox 未做实机验证
新增 YouTube 浏览器专项 15 项通过:文档全屏、菜单切换、稳定定位、重复句、过期/未来字幕、延迟返回、真实视频 seek、空档、原文模式与清理
现有视频字幕浏览器回归 通过,含开关持久化、显示模式、原文/译文下载、10 秒与 30 秒预取、字幕对齐
X 播放器菜单回归 9 项通过,含原生控制栏卸载/重挂载、开关、模式、缓存恢复与下载;使用受控字幕和模拟翻译
真实 YouTube 全屏菜单 在上述视频中复现并确认修复,菜单可见、命中检测和模式切换正常;全屏字幕层恢复到播放器尺寸
真实 YouTube 字幕翻译 未能验证:隔离匿名窗口中的英语原生字幕接口返回 HTTP 200、空响应,原生字幕本身未出现

浏览器专项的运行方式

专项使用生产扩展、临时 Edge profile 与第二屏后台窗口,关键启动参数包括:

  • launchMode=macos-background-cdp
  • focusPolicy=launchservices-no-foreground
  • windowPlacement.mode=background-visible-no-focus
  • browserFrontmost=false

字幕时序夹具使用真实视频进度、受控页面字幕和模拟翻译服务,因此不代表真实服务翻译质量。报告亦注明未借鉴或修改参考仓库。

复现命令

在 docs/testing.md 中记录了完整复现命令:

node scripts/run-youtube-subtitle-sync-test.cjs \
  --extension-dir .output/chrome-mv3 \
  --playwright-root <Node包目录> \
  --focus-safe-helper <focus-safe-browser.cjs路径> \
  --artifacts-dir /private/tmp/fluentread-youtube-sync

该专项在临时 Edge profile 的后台可见窗口中验证:文档全屏、菜单操作、整句/逐词字幕定位、时间边界、重复句、延迟译文、真实视频 seek、空字幕、原文模式和关闭清理。测试脚本本身会先用 ffmpeg 生成 30 秒的受控视频夹具,并注入包含重复句、未来句、延迟译文、时间空档的 cue 序列与确定性翻译映射(run-youtube-subtitle-sync-test.cjs)。

此外,docs/testing.md 还指出同一专项覆盖滚动字幕的上一句残留、窗口裁切的旧行、连续每 40ms 增词、无时间轴的请求启动延迟与缓存重播;报告中的 dispatchMs 只度量原文变化到请求发出的等待,不包含真实供应商耗时,译文仍使用确定性响应,不能据此声称真实视频端到端零延迟。

截图

真实视频中的全屏菜单(浏览器全屏模式、播放器右下角深色半透明菜单,当前选中"双语"模式并提供字幕下载入口):

真实 YouTube 全屏菜单

受控字幕夹具中的统一双语面板(上层黄色中文原文、下层白色英文译文,验证整句与逐词字幕的同面板展示):

字幕同步夹具

局限与边界

  • Firefox:生产构建通过,但未做实机验证;
  • 真实字幕翻译:在隔离匿名窗口中,英语原生字幕接口返回 HTTP 200 但响应为空,原生字幕本身未出现,因此真实 YouTube 字幕翻译链路未被端到端验证;
  • 覆盖率口径:两个纯逻辑模块的 100% 覆盖率不代表整个视频字幕运行时覆盖率;
  • 翻译质量:浏览器专项使用模拟翻译响应,不代表真实服务翻译质量;
  • 全量回归:仅运行了字幕/播放器/架构相关专项,未运行全量测试套件。
登录后查看全文
FluentRead