omp packages

bilibili-transcript1.1.0

通过 yt-dlp + Chrome CDP 双重策略获取 B 站视频字幕的工具

GitHub Actions Published 20 days ago MIT ~923 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

Bilibili Transcript

通过 yt-dlp + Chrome CDP 双重策略获取 B 站视频字幕。既可以作为 AI 技能（Skill） 安装给 agent 使用，也可以作为 命令行工具 直接运行。

功能

  • 输入 B 站视频链接或 BVID，输出带时间戳的字幕文本
  • 支持视频的中文字幕 / 英文字幕 / AI 字幕（按 zh-Hans → zh-CN → zh → zh-TW → ai-zh → en 优先级取一条）
  • 优先使用 yt-dlp（可读取浏览器登录态），失败时自动切换 Chrome CDP 兜底
  • 失败时会给出明确原因（未安装 yt-dlp / 412 风控 / Cookie 读取失败 / 无匹配字幕 / 未登录），不再笼统报错

⚠️ 前提

视频本身必须有字幕，且 B 站的字幕接口通常需要登录态（未登录的元数据请求会被 412 风控拦截）。

  • 判断方法：播放视频时播放器控制栏有「字幕」按钮；或 yt-dlp --list-subs <url> 能看到语言列表
  • 没有字幕的视频（纯音乐、纯画面、部分短视频）无法提取文字内容

工作原理

1. yt-dlp（优先）    ← 读取浏览器 Cookie，快速，不需要浏览器自动化
   ↓ 失败（412 风控 / 无匹配字幕 / Cookie 读取失败 …）
2. Chrome CDP（兜底） ← 连接调试模式的 Chrome，直接在页面里抓取字幕
方法 优点 缺点 需要的依赖
yt-dlp 快速、简单、不需要浏览器自动化 可能遇到 412 反爬 yt-dlp
Chrome CDP 几乎不会被拦截 需要调试模式 Chrome 且已登录 puppeteer-core + Chrome

快速开始

第 1 步：准备前置环境

依赖 是否必须 说明 安装
Node.js 22+ 必须 运行脚本 nodejs.org 或 brew install node
yt-dlp 必须 主方案，抓取字幕 brew install yt-dlp
浏览器 + 已登录 B 站 必须 yt-dlp 通过 --cookies-from-browser 读取登录态 用日常浏览器登录 https://www.bilibili.com
Chrome 调试模式 可选 仅 CDP 兜底需要，详见 Chrome CDP 兜底方案 —

读取 Cookie 如果报错，请完全退出浏览器后重试（运行中的 Chrome 会占用 / 加密 Cookie 库）。 yt-dlp 其他平台的安装方式见 https://github.com/yt-dlp/yt-dlp#installation。

第 2 步：安装

方式 A：作为 AI 技能（给 agent 用）

  • Pi Packages

    pi install npm:bilibili-transcript

  • skills.sh

    npx skills add https://github.com/moonmoonCL/bilibili-transcript

技能自带 transcript.js，yt-dlp 主方案零 Node 依赖，装完即可用。 只有需要使用 Chrome CDP 兜底 时，才需要额外装一次依赖：

cd ~/.agents/skills/bilibili-transcript && npm install

方式 B：作为命令行工具

npm install -g bilibili-transcript

会连同 Node 依赖一起装好，并注册全局命令 bilibili-transcript。

第 3 步：使用

  • 技能方式：直接对 agent 说「获取这个 B 站视频的字幕」即可；手动调用为：

    node ~/.agents/skills/bilibili-transcript/transcript.js <BVID或URL>

  • 命令行方式：

    bilibili-transcript <BVID或URL>

输入支持 BVID 或完整 URL：

bilibili-transcript BV13nwdzPEoR
bilibili-transcript https://www.bilibili.com/video/BV13nwdzPEoR/

输出：

# 视频标题

[0:00] 字幕文本第一行
[0:15] 字幕文本第二行
[1:23] 字幕文本第三行

可配置项（环境变量）

变量 默认值 说明
BILIBILI_COOKIES_FROM_BROWSER chrome yt-dlp 读取 Cookie 的浏览器，如 firefox、edge、"chrome:Profile 1"
BILIBILI_SUBTITLE_LANGS zh-Hans,zh-CN,zh,zh-TW,ai-zh,en 请求的字幕语言（逗号分隔）
BILIBILI_CDP_URL http://localhost:9222 Chrome DevTools 调试端点
BILIBILI_YTDLP_TIMEOUT_MS 60000 yt-dlp 超时时间（毫秒）

示例：

BILIBILI_COOKIES_FROM_BROWSER=firefox bilibili-transcript BV13nwdzPEoR
BILIBILI_SUBTITLE_LANGS=en bilibili-transcript BV13nwdzPEoR

Chrome CDP 兜底方案（可选）

当 yt-dlp 失败时，脚本会自动切换到 Chrome CDP：连接一个开着远程调试端口的 Chrome，直接从浏览器里抓取字幕，几乎不会被拦截。

前置条件

  1. 已安装 Node 依赖 puppeteer-core（仅 skills.sh 安装方式需要手动执行一次）：

    cd ~/.agents/skills/bilibili-transcript && npm install

  2. Chrome 以远程调试模式运行在 9222 端口，并且使用了独立的 --user-data-dir

  3. 该 Chrome 已登录 bilibili.com（部分视频字幕需要登录，接口会返回 need_login_subtitle）

第 1 步：以远程调试模式启动 Chrome

⚠️ Chrome 136 起，使用默认用户配置目录时会直接忽略 --remote-debugging-port。 因此必须搭配一个独立的 --user-data-dir（下面示例用 ~/.chrome-cdp）。 这是一个全新的配置目录，需要重新登录一次 B 站；好处是不影响你日常使用的 Chrome，也不用退出它。

macOS

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-cdp"

Windows

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-cdp"

Linux

google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-cdp"

第 2 步：确认调试端口已开启

浏览器访问 http://localhost:9222/json/version，能看到 JSON（含 webSocketDebuggerUrl）即成功；或在终端执行：

curl -s http://localhost:9222/json/version

第 3 步：登录 B 站并提取字幕

在这个 Chrome 里打开 https://www.bilibili.com 并登录账号，保持窗口开着，然后运行提取命令即可。

故障排查

现象 原因 / 解决
[yt-dlp] 未找到 yt-dlp 没装 yt-dlp。brew install yt-dlp
[yt-dlp] 请求被 B 站拒绝：HTTP 412 缺登录态。确认浏览器已登录 B 站；读取 Cookie 前完全退出 Chrome；或用 BILIBILI_COOKIES_FROM_BROWSER 换浏览器
[yt-dlp] 读取浏览器 Cookie 失败 完全退出 Chrome 后重试（运行中的 Chrome 会占用 / 加密 Cookie 库）
[yt-dlp] 未找到匹配的字幕 视频没字幕，或语言不在请求列表。用 yt-dlp --list-subs <url> 查看，再用 BILIBILI_SUBTITLE_LANGS 指定
[CDP] 无法连接 http://localhost:9222 上的 Chrome Chrome 没开调试端口，或没加 --user-data-dir（Chrome 136+ 必须）。按第 1 步重启
[CDP] 未能捕获字幕数据 调试用 Chrome 未登录 B 站（need_login_subtitle），或该视频本身没有字幕
[CDP] 缺少依赖 puppeteer-core 执行 cd <技能目录> && npm install
端口被占用 / 启动后无反应 结束占用 9222 的进程，或用 BILIBILI_CDP_URL 换端口

许可证

本项目采用 MIT 许可证 开源。