企业官网建设流程全解析

Cobalt 多音轨下载：一个参数切换出视频配音版

【免费下载链接】cobaltbest way to save what you love项目地址: https://gitcode.com/GitHub_Trending/cob/cobalt

当 YouTube 网页播放器的音频菜单里出现多条"音频音轨"选项时，说明这个视频带有官方多语言配音，但多数离线工具下载后只有默认音频，配音版只能在线观看。Cobalt 多音轨下载解决的就是这个问题：在 API 请求里带上dubLang参数，它会替你挑出对应语言的音轨。本文会讲清这个参数背后的选轨逻辑，并给出用 node 或 docker 两种方式跑起自建服务的步骤，以及常见问题的排查方式。

在线播放只有一种语言的时候

场景很常见：一部电影或纪录片你想存下来离线看，页面里原版和配音都有，可下载工具只默认抓第一条音轨。有的工具靠把页面媒体流全部下下来再"碰运气"，笨重也不精确；Cobalt 的思路反过来，不下载"一切"，而是由你指定语言代码，只返回那条语言的音轨。

整件事围绕请求里的dubLang字段展开，先看后端是怎么处理它的。

dubLang 是怎么挑出配音音轨的

先找原版，再找配音

YouTube 处理逻辑默认选中带is_original标记的纯音频流（原版音轨）。当请求里带dubLang时，它会在全部候选流里重新筛一遍：

if (o.dubLang) { let dubbedAudio = adaptive_formats.find(i => checkBestAudio(i) && i.language === o.dubLang && i.audio_track ) if (dubbedAudio) { audio = dubbedAudio; isDubbed = true } }

这里adaptive_formats是 YouTube 为该视频提供的所有音视频流组合。三个条件缺一不可：纯音频（不含视频画面）、language字段与你传入的代码完全相等、带audio_track标记。一条都匹配不上时，它会静默回退到原版音轨，不报任何错误——这就是"传了参数却拿到原版"最常见的来源。查看音轨筛选逻辑

只认两个字母的语言代码

dubLang进入流程前会先过一道verifyLanguageCode校验：只保留前两个字符并转小写作为匹配键，不符合两字母格式时回退成en。所以传ja-JP等价于ja，传Japanese则不会生效。官方文档把这个参数标注为布尔类型，并注明传true时后端会读取请求头里的 Accept-Language（客户端声明偏好的语言的标准 HTTP 头）来推断语言，实际使用中直接传两字母代码最稳妥。

弄清了挑选逻辑，剩下的事就是先把服务跑起来。

从克隆到跑通

node 方式

需要 Node.js 18 及以上版本，setup 脚本会引导你选择 web 还是 api 实例：

git clone https://gitcode.com/GitHub_Trending/cob/cobalt cd cobalt npm run setup npm start

docker 方式

官方文档推荐 docker compose 路线：把 docs/examples/docker-compose.example.yml 拷到目标目录，将里面的示例域名改成自己的，然后启动容器：

docker compose up -d

如果要下载年龄限制等需要登录的内容，在同一目录放一份 cookies.json，格式参考 docs/examples/cookies.example.json。

多音轨下载的请求参数

服务跑起来后，剩下的就是正确组装请求。配音下载最常用的五个参数如下，完整字段说明在 docs/api.md：

命中配音音轨后，文件名会自动带上语言代码后缀（例如_ja），方便和原版文件区分。一次完整请求长这样：

curl -X POST https://your-api-domain/api/json \ -H "Accept: application/json" -H "Content-Type: application/json" \ -d '{"url": "https://www.youtube.com/watch?v=XXXX", "dubLang": "ja", "aFormat": "opus"}'

自建时值得知道的事

实例如果要长期对外提供服务，有几个环境变量值得提前配置：

• 限速：RATELIMIT_MAX默认每 60 秒窗口 20 次请求，超出的请求返回 429（触发限流的状态码）。脚本批量调用时调大该值或在请求间加间隔。
• DURATION_LIMIT默认 10800 秒，超过时长的视频在解析前就会被拒绝，可按机器能力调整。
• 前后端分域名部署时，把CORS_WILDCARD设为 1 或指定CORS_URL，否则浏览器端调不通 API。
• 面向公网时，官方文档建议前面加一层 nginx 之类的反向代理。

常见问题速查

真正开始传语言代码后，最常碰到的是这三种情况：

• 问题：传了dubLang拿到的还是原版音轨。原因：视频本身没有该语言的配音，或代码与音轨 language 字段不完全一致，代码匹配失败会静默回退原版。操作：先在网页播放器音频菜单确认该语言存在，并传两字母代码。
• 问题：批量请求陆续返回 429。原因：撞上了速率限制（默认 60 秒 20 次）。操作：调大RATELIMIT_MAX，或在脚本里给请求加间隔。
• 问题：个别链接提示需要登录或无法解析。原因：视频内容带年龄或地区限制。操作：在实例目录放置 cookies.json，并用COOKIE_PATH指过去。

下一步

如果只是验证流程，先克隆仓库跑一次npm run setup，把 web 实例看跑通即可；后续涉及批量拉取配音音轨时，再对照 API 文档里请求与响应字段的说明做脚本封装。

【免费下载链接】cobaltbest way to save what you love项目地址: https://gitcode.com/GitHub_Trending/cob/cobalt