voice-over-translation 音频下载器深入解析:从 YouTube 提取音轨并交付 Yandex 翻译的三策略架构

原创2026-10-14 09:01:321,635 阅读
文章标签:音视频AI 应用

voice-over-translation 音频下载器深入解析:从 YouTube 提取音轨并交付 Yandex 翻译的三策略架构

导读:本文以仓库 src/audioDownloader/README.md 为核心骨架,讲解 voice-over-translation 项目中"音频下载器"(Audio Downloader)模块的设计与实现。该模块负责在服务器显式请求音频时,从 YouTube 视频中提取原始音轨,分块转发给 Yandex 进行配音翻译。读完本文,你将掌握其三种下载策略(web_sabr、web_abr、web_mse_proxy)的适用场景与降级顺序、分块传输协议、同视频串行队列、失败重试与断点缓存机制,以及它们在实际浏览器/用户脚本/扩展环境下的运行原理。

一、模块定位:为什么需要"从网页里下载音频"

voice-over-translation 是一款在任意浏览器中为视频提供画外音翻译(закадровый перевод)与字幕的扩展/用户脚本。它的核心翻译链路是:

  1. 视频在页面中播放;
  2. 用户选择源语言与目标语言;
  3. 系统将视频的音频轨道交给 Yandex 云端服务完成语音翻译;
  4. 翻译结果作为画外音或字幕回放到视频上。

其中第 3 步存在两种触发模式:多数情况下,Yandex 服务端只需要元数据即可开始翻译;但当服务器显式请求音频(server explicitly requests audio)时,就必须由本模块——音频下载器 从 YouTube 页面中提取真实音轨数据。这正是 src/audioDownloader/README.md 定义的模块职责:

Contains the implementation for extracting the audio track from a YouTube video to send it to Yandex. Used only when the server explicitly requests audio.

换句话说,音频下载器不是常驻功能,而是一条按需触发的数据通路:它在 translationHandler 中由 runAudioDownload 调用,下载完成后才会继续执行真正的翻译流程(译码入口)。

二、已实现的下载策略(README 核心内容)

原 README 明确指出模块已实现两种策略:

  • web_abr
  • web_mse_proxy

从当前仓库源码看,策略清单已经扩展为三种(strategies/audioStrategy.ts 中三种策略常量均有完整实现):

策略常量 Yandex 枚举值 实现文件 核心思路
SABR_STRATEGY WEB_SABR youtubeSabr.ts、youtubeSabrStrategy.ts 复用 YouTube 原生 SABR(Server ABR)流式传输协议,以 protobuf 请求获取音频
WEB_ABR_STRATEGY WEB_ABR webAbr.ts、youtubeWebAbr.ts 模拟网页播放器,从 player 接口获取自适应音频格式(adaptive formats)并分段下载
WEB_MSE_PROXY_STRATEGY WEB_MSE_PROXY mseProxyHandler.ts 创建隐藏的 YouTube embed iframe,代理/捕获其 MSE(Media Source Extensions)音频数据

其中 SABR_STRATEGY 在源码中被刻意作为独立内部策略保留,不与 WEB_ABR 合并——这样既能保持策略选择与诊断信息真实可靠,又避免对核心枚举值产生硬依赖(audioStrategy.ts 中的注释说明了这一点)。

三、调度架构:策略表、自动降级与统一数据契约

所有策略被登记在一张策略表中(strategies/index.ts):

export const strategies = {
  [SABR_STRATEGY]: (options) => getAudioFromBridge(options, SABR_STRATEGY),
  [WEB_ABR_STRATEGY]: (options) => getAudioFromBridge(options, WEB_ABR_STRATEGY),
  [WEB_MSE_PROXY_STRATEGY]: (options) => getAudioFromBridge(options, WEB_MSE_PROXY_STRATEGY),
} as const;

三种策略最终都收敛到统一的桥接入口 getAudioFromBridge(webAudioBridge.ts),它返回统一的数据契约:

  • fileId:本次下载的唯一文件标识(random-${类型}-${crypto.randomUUID()});
  • getMediaBuffers():一个异步生成器,逐个产出 AudioChunk;
  • AudioChunk = { buffer: Uint8Array; isLastChunk: boolean }(audioChunks.ts)。

AudioDownloader 类的默认策略是 "auto",此时按固定顺序尝试(index.ts):

auto → [SABR_STRATEGY, WEB_ABR_STRATEGY, WEB_MSE_PROXY_STRATEGY]

即:优先走 SABR 原生流;失败则回退到 WebABR 分段下载;再失败则使用 MSE iframe 代理兜底。若构造时显式传入某个策略(如 new AudioDownloader(WEB_ABR_STRATEGY)),则只尝试该策略。整个降级过程对外完全透明——上层 translationHandler 只感知到"音频下载成功"或"全部策略失败"(此时派发 onDownloadAudioError 事件)。

WEB_ABR_STRATEGY 的降级链路内部还有第二层矩阵:8 种传输方式按序尝试(webAbr.ts):

parallel_4 → 4mb → parallel_8 → 8mb → parallel_2 → 2mb → stream → original

其中 parallel_N 以 4 MiB 为固定块大小并发请求 Range;Nmb 以固定块大小顺序请求;original 使用渐进增大的 Range 序列(60 KB、80 KB、150 KB、330 KB、460 KB,之后维持最后尺寸);stream 则直接流式读取响应体。每次换传输方式前都会先验证已下载字节数等于 contentLength,在确认完整下载之前不向上层暴露任何音频块(webAbr.ts),从而保证降级安全。

四、分块传输与上传协议

音频以分块形式转发给 Yandex 上传链路,AudioDownloader 对外暴露三个事件(index.ts):

事件 签名 语义
onDownloadedAudio (translationId, { videoId, fileId, audioData }) 整段音频下载完成
onDownloadedPartialAudio (translationId, { videoId, fileId, audioData, version, index, amount }) 单个分块就绪,amount=0 表示非末块
onDownloadAudioError (translationId, videoId, signInSuggested) 全部策略失败;第三个参数表示是否建议登录

分块生成的核心算法在 handleCommonAudioDownloadRequest(index.ts),它使用**单元素前视(one-item lookahead)**处理流:每收到一个真实块先暂存,待下一个块或明确的 EOF 确认后再派发。这样做的目的有两个:

  1. 吸收结尾的零字节终止标记(terminal marker),把最后一个真实块以 amount = 总数 的形式作为终止块发出;
  2. 若迭代中途抛错,已暂存但未确认的块不会外泄。

分块粒度受 config.minChunkSize 控制(各策略均以 pendingSize >= config.minChunkSize 为切块阈值,见 webAbr.ts、mseProxyHandler.ts)。SABR 策略对 minChunkSize 做了防御性处理:当运行环境中该值缺失或非法时,回退到默认值 5,295,308 字节(youtubeSabr.ts),避免 undefined 污染算术导致 NaN。

MSE 代理还有一条分块尺寸的硬约束:只有当缓冲达到 minChunkSize 时才把整批 appendBuffer 数据合并为一块发出;若缓冲达到一半但超过 30 秒没有完整块,则向上层发送进度心跳(progress ping)以延长消息超时(mseProxyHandler.ts)。

五、健壮性设计:串行队列、取消与断点缓存

5.1 同视频 FIFO 串行队列

同一 videoId 的多次下载会被串行化。仓库里有两层队列:

  • AudioDownloader 层面的 audioDownloadTails Map(index.ts):保证"整个下载运行(含策略降级)"按 videoId 严格 FIFO。注释说明这是历史演进的结果——WEB_ABR 队列原先位于 service iframe 的 realm 内,每次下载都会新建 iframe(全新模块状态),同视频多次运行无法共享 Map,于是把排队提升到 iframe 创建之前;
  • 策略内部的下载队列:WEB_ABR_DOWNLOAD_QUEUE(youtubeWebAbr.ts)与 SABR_DOWNLOAD_QUEUE(youtubeSabrStrategy.ts),分别串行化各自策略的执行。

排队等待期间若信号被中止,排队者会立即以 AbortError 退出且绝不进入任何策略(测试 tests/audio-downloader.test.ts 验证了这一行为)。

5.2 全链路取消

下载全程贯彻 AbortSignal 取消:

  • 每次派发分块后、每个分块到达前都会调用 throwIfAborted(signal);
  • 桥接层(webAudioBridge.ts)为每条消息生成随机 messageId,取消时发送 isAborted: true 的终止消息;
  • 流级超时双重保障:单条消息超时 MESSAGE_TIMEOUT_MS = 5 分钟,整个流超时 STREAM_TIMEOUT_MS = 30 分钟;
  • 页面导航检测:若下载期间 location.href 不再包含 videoId(用户跳转了视频页),下载立即中止(webAudioBridge.ts)。

5.3 单条目断点缓存

AudioDownloader 维护一个单条目缓存(非 LRU/TTL):只保留最近一次完整完成的下载(videoId + fileId + 分块数组 + version)。这样当同一视频的上传失败时,可以重放缓存直接重新上传,而无需重新下载(index.ts)。

// 重放:按缓存顺序重新派发所有分块,末块 amount 为总数
private async replayCachedAudio(videoId, translationId, signal): Promise<boolean>

在 runAudioDownload 中,进入队列前和获得队列权限后都会尝试重放缓存(index.ts),并借助 collectingChunks Map 与"运行局部数组 + 身份守卫"来防止并发的同视频前驱在清理时误删自己的收集结果。调用 clearCachedAudio(videoId) 可显式清除缓存(翻译流程在 translationHandler.ts 中调用)。

5.4 针对 Yandex 登录提示的特殊处理

当 WEB_ABR 失败原因是 YOUTUBE_SIGN_IN_SUGGESTED 时,下载器不会继续尝试降级,而是立即派发 onDownloadAudioError(translationId, videoId, true),把 signInSuggested=true 交给 UI 层提示用户登录(index.ts)。

六、浏览器兼容的桥接机制

下载策略需要访问 YouTube 页面的真实 realm(页面主世界),但用户脚本/扩展脚本运行在隔离的沙箱 realm。为此模块实现了多层桥接:

6.1 main-world 消息桥(所有策略共用)

webAudioBridge.ts 定义了消息协议:脚本向页面主世界 postMessage 发送 get-audio-chunks-by-mse-in-main-world 请求(携带 pureVideoId、audioDownloadType、sourceLanguage),页面侧的处理程序(mseProxyHandler.ts 中的 initMseProxyHandler)以 response / iframe-response 方向回传分块。

消息鉴权不使用 event.source 对象身份(Firefox/Safari 的 user script realm 可能通过不同的 WindowProxy 包装暴露同一个页面 Window,身份不可靠),而是采用同源投递 + 每次请求随机的 messageId + 协议字段三重校验。

6.2 三种页面侧执行路径

  • SABR / WebABR(直连路径):直接在当前真实 YouTube 页面上下文中运行,先尝试页面现存函数(可达的函数对象)解决签名与 n 参数,再使用预处理后的 player 代码求解(webAbr.ts 的 collectPageSolutions / solveYouTubeChallenges)。PO token 通过 youtubePoToken.ts 的 mintPagePoToken 铸造,Safari 上还通过注入页面 realm 的自包含脚本桥(safariPageBridge.ts,利用 bevasrsg / havuokmhhs-* 全局)获取;
  • MSE 代理(iframe 兜底路径):由顶层页面创建 2×2 像素、visibility:hidden 的隐藏 /embed/{videoId}?html5=1&autoplay=0&mute=1 iframe(带 #ya_iframe hash),iframe 内的处理程序安装 MediaSource / ManagedMediaSource 子类代理(mseProxyHandler.ts),通过包装 appendBuffer / endOfStream 捕获音频数据;随后播放器以 2 倍速静音播放并定时 seekTo 拉动缓冲,捕获到的音频被按 minChunkSize 合并成块回传。由于 service iframe 与非 www YouTube 主站跨域,顶层还承担了中继转发职责,把 iframe-response 改写为 response 再转发给请求方;
  • getEncryptedEmbedConfig 还会通过 share/get_share_panel 接口获取 encryptedEmbedConfig 注入 embed URL,以兼容部分受限内容。

需要注意:SABR/WebABR 直连路径目前只保留 MSE iframe 作为遗留兜底(见 mseProxyHandler.ts 的注释),在 YaBrowser 中则完全跳过 MSE 代理安装。

七、格式选择、音轨语言与挑战破解细节

7.1 音频格式选择

selectWebEmbeddedAudioFormat 的筛选优先级为:

  1. 过滤出含 url 或 signatureCipher 的纯音频格式(mimeType 含 audio/ 且不含 video/);
  2. 若用户指定了源语言,优先精确匹配 BCP-47 音轨标签,其次匹配基础语言(audioLanguageMatches 允许 en 与 en-US 互通);
  3. 无指定语言时优先默认音轨(audioIsDefault),否则回落到全部纯音频格式;
  4. 剔除 DRC(动态范围控制,xtags 含 drc=1)候选;
  5. 最后用 selectSmallestAudioFormat 选取体积最小者(优先 contentLength,其次 averageBitrate,见 utils.ts)。

7.2 音轨语言提取

getYoutubeAudioFormatLanguage 按序探测 languageCode、language、audioTrack.languageCode/language、audioTrackId(取 . 前的语言段)以及 URL xtags 中的 lang=,并统一做 _ → -、转小写、去空白规范化。

7.3 签名 / n 参数挑战破解

YouTube 的自适应媒体 URL 通常带签名(s)与 n 参数。模块采用多级策略(webAbr.ts):

  1. 优先复用页面中可达的函数(递归遍历 _yt_player 与页面全局的属性描述符,深度 ≤3、节点数 ≤5000 防爆栈)构造 PageUrl 实例读取解密结果;
  2. 从多个 realm(自身、parent、top)收集候选解并做一致性合并(多个候选签名一致才采纳);
  3. 候选不完整时,回退到下载 player 代码并求解:先尝试在页面 realm 的 Function 作用域内执行预处理后的 player 代码(preprocessYouTubePlayer 来自 ytPlayerSolver.js,涉及 Trusted Types policy 与 eval 的兼容处理),失败则放入带 sandbox="allow-scripts allow-same-origin" 的隐藏 iframe 中执行。

SABR 路径还独立实现了 protobuf 级别的请求/响应编解码(varint 读写、顶层消息拆分,见 youtubeSabrSupport.ts),以及音轨切换逻辑 switchYouTubeSabrAudioTrack。SABR 音轨选择遵循严格的白名单策略:仅在 VOT 支持的源语言白名单(ru/en/zh/ko/fr/it/es/de/ja,youtubeSabrSupport.ts)内挑选,绝不盲目使用 availableTrackIds[0] 兜底。

八、测试验证:可验证的行为契约

模块行为由 tests/audio-downloader.test.ts 覆盖(使用 bun 测试框架,通过替换 strategies 表注入桩策略)。可验证的关键契约包括:

  • 终止标记吸收:末尾零字节 isLastChunk 标记被合并进最后一个真实块,派发出的末块 amount 等于块总数;
  • 策略降级顺序:先 SABR(桩直接抛错)→ WEB_ABR → MSE,任一成功即停止;
  • 源语言透传:sourceLanguage 原样传入各策略的 options;
  • 队列取消语义:被中止的排队运行不会进入策略,且不影响后续排队者;
  • 已中止信号:传入已中止的 signal 时运行直接退出,不进入任何策略;
  • 错误降级转缓存:某策略失败后另一策略成功,结果可被重放(replayCachedAudio),且缓存条目会随 videoId 变化而替换。

九、运行环境与适用前提

  • 音频下载器仅在服务器显式请求音频时启用,不是默认翻译路径;
  • 依赖页面具备 YouTube 页面主世界访问能力:Chrome 扩展/CRXJS 构建下由 prelude(src/extension/prelude/index.ts)在 document_start 同步注入 GM polyfill 与消息处理器;Firefox 构建则通过 bridge 注入 prelude.module.js;
  • MSE 兜底路径会创建一个隐藏 iframe 并真实播放音频(静音、2 倍速),对页面有临时副作用,因此被刻意作为最后手段;
  • SABR 路径依赖页面 realm 中的原生 SABR 基础设施(serverAbrStreamingUrl、protobuf 请求体),若页面缺少对应能力会自动落入 WebABR。

从源码结构看,模块的演进方向是以原生 SABR 为主、WebABR 分段下载为辅、MSE 代理作为最终兜底——这与 "auto" 模式的尝试顺序完全一致;原 README 仅列出 web_abr 与 web_mse_proxy 两种策略,但当前仓库已完整实现并登记了第三种 web_sabr。

十、小结

音频下载器是 voice-over-translation 翻译链路中"原料供给"的关键一环,其设计要点可以概括为:

  1. 统一契约 + 策略表:三种策略产出统一的 fileId + getMediaBuffers() 数据源,上层无需关心具体下载方式;
  2. 自动降级:auto 模式下 SABR → WEB_ABR → MSE iframe 逐级尝试,WebABR 内部另有 8 种传输矩阵;
  3. 可靠性:同视频 FIFO 串行、全链路 AbortSignal 取消、30 分钟流超时、单条目断点缓存、严格的分块完整性校验;
  4. 浏览器兼容:以 main-world 消息桥穿透沙箱,Firefox/Safari 各有专门的 realm 与 PO-token 桥接方案。

如需继续深入,建议按以下顺序阅读源码:策略表与枚举 → 调度核心 AudioDownloader → SABR 实现 → WebABR 实现 → MSE 代理 → 行为测试。

登录后查看全文
voice-over-translation