dsh-bili-asr
给 DeepSeek Harness(DSH)用的 B 站视频转文字插件: 匿名取音轨 → 本地 Whisper 转写,不需要登录 B 站、不需要字幕轨。
- 普通视频 / 分P → 逐段台词(带起止时间)
- 互动视频(
is_stein_gate=1)→ 抓 B 站 stein 剧情图,输出分支树 + 每个节点的台词 + 结局台词 - 节点截图(
--frames):每个分P/节点抓一帧存进frames/,文档里自动附上 - 音频全局缓存:音轨先存
<dataDir>/cache/audio/,works 里用硬链接,重转同一视频不再下载 - 有字幕轨就直接用:每个分 P / 节点先查
/x/player/v2,拿到平台字幕就跳过音轨下载与 ASR(匿名多数拿不到,可设BILI_SESSDATA补一段 cookie) - 两端:会话里可以调工具;设置 → 「B站转写」 里有一个面板,能起任务、看进度、读文档
为什么需要它
B 站绝大多数视频没有字幕轨(/x/player/v2 返回 0 条字幕),互动视频更是由几十个 7~25 秒的节点拼成的树,没有"正片"。
常见做法要么要求登录拿 AI 字幕,要么只拿到标题和简介。这个插件走另一条路:下载音轨,本地转写。
安装
# 1) 装插件(桌面版也可在「插件 → 添加插件」里输入 dsh-bili-asr)
dsh plugin --profile desktop add dsh-bili-asr
# 不走 npm 也行:直接用 Release 里的安装包
dsh plugin --profile desktop add https://github.com/jzhha/dsh-bili-asr/releases/download/v0.6.0/dsh-bili-asr-0.6.0.tgz
重启 DSH 后,让 agent 调一次 bili_asr_setup(或到 设置 → 「B站转写」 点「装环境」)。它会:
- 建一个独立 Python venv(优先用
uv,没有就用python -m venv) - 装
faster-whisper==1.2.1(默认走清华 PyPI 镜像) - 下载
Systran/faster-whisper-small的 4 个模型文件(约 486 MB,逐个校验 sha256)
默认数据目录 $DSH_HOME/bili-asr(通常是 ~/.dsh/bili-asr),里面是 venv/、model/、works/。
国内网络默认从 hf-mirror.com 下模型(huggingface.co 直连常常超时);可换源:
bili_asr_setup({ pipIndex: "https://pypi.tuna.tsinghua.edu.cn/simple", hfEndpoint: "https://hf-mirror.com" })
用法
会话里(工具)
| 工具 | 说明 |
|---|---|
bili_asr_run({ video, pages?, noAsr?, frames?, at? }) |
起一个转写任务,立即返回 taskId;frames: true 抓节点截图,at 指定取第几秒 |
bili_asr_status({ id? }) |
查进度与最近日志;不传 id 列出最近任务 |
bili_asr_cancel({ id }) |
取消任务:排队中的直接出队,运行中的杀掉 node → python 进程树 |
bili_asr_doctor() |
环境自检:Python / 依赖 / 模型 / 数据目录 / 磁盘 / B站接口,逐项给结论 |
bili_asr_rebuild({ id, srt? }) |
只重建文档:用已有 transcripts + 元数据重出 script.md,不联网 |
bili_asr_delete({ id, files? }) |
删除已结束的任务记录;files: true 连 works/<BV>/ 产物目录一起删 |
bili_asr_doc({ id, offset?, limit? }) |
分页读 script.md(next 非空时继续读) |
bili_asr_setup({ pipIndex?, hfEndpoint? }) |
一次性装环境 |
任务是异步的:run 立刻返回,别等它跑完。
面板(设置 → 「B站转写」)
| 位置 | 能做什么 |
|---|---|
| 顶部 | 输入 BV/链接 → 转写;「装环境」(首次下载 venv + 486 MB 模型)、「刷新」 |
| 选项行 | ☑ 节点截图(勾上后可选取第几秒,自动跳过黑帧)、☑ 导出字幕(SRT/VTT)、分P 输入(如 1,3) |
| 工具栏 | 复制路径 · 取消任务(仅运行中/排队中)· 重建文档(用已有产物重出,不联网)· 环境自检 · 删除 ▾(只删记录 / 连产物一起删,两步确认) |
| 右侧 | 选中任务后显示 script.md;失败时显示错误码、「为什么」与「怎么办」 |
命令行
node bin/setup.mjs # 装环境
node bin/bili-asr.mjs BV1xxxxxxxxx # 普通视频
node bin/bili-asr.mjs BV159WJ63EMK # 互动视频(自动识别)
node bin/bili-asr.mjs BV1xxx --pages 1,3 # 只做指定分P
node bin/bili-asr.mjs BV1xxx --out ./somewhere # 换个输出目录
node bin/bili-asr.mjs BV159WJ63EMK --frames # 每个节点再抓一帧截图(约 25 KB/张)
node bin/bili-asr.mjs BV1xxx --frames --at 3 # 截图取第 3 秒(默认 1;会自动避开黑帧)
node bin/bili-asr.mjs BV1xxx --srt # 额外导出 SRT / VTT 到 subtitles/
node bin/bili-asr.mjs BV1xxx --rebuild # 只用已有产物重建文档(不联网)
node bin/doctor.mjs # 环境自检
产物(默认 $DSH_HOME/bili-asr/works/<BV>/):
graph.json 互动视频的剧情图(节点/选择边/结局)
tree.md 纯结构树
script.md 分支 + 台词(普通视频是逐段台词)
audio/ 节点音轨
frames/ 节点截图(--frames 时)
transcripts/ 逐段转写 JSON(带起止时间)
subtitles/ SRT/VTT 字幕(--srt 时)
meta.json 标题/分P/graph_version,供 --rebuild 使用
配置
在 profile 的插件 config 里改(改完重载):
- id: bili-asr
name: dsh-bili-asr
config:
dataDir: /your/data/dir # 默认 $DSH_HOME/bili-asr
pythonPath: /path/to/python # 可选,默认 dataDir/venv
asrModelPath: /path/to/model # 可选,默认 dataDir/model/faster-whisper-small
pipIndex: https://pypi.tuna.tsinghua.edu.cn/simple
hfEndpoint: https://hf-mirror.com
已知限制
- 任务串行执行:ASR 会吃满 CPU,几个任务一起跑只会互相拖慢(实测:单独 4 分钟的任务,与另一个任务重叠时拖到 21 分钟)。后来的任务显示「排队中 · 第 N 位」。
- 只有音频:画面、字幕样式、jumpscare 都拿不到;要看画面得自己抽帧。
- ASR 有误字:中文专名、同音字常错(例:"纯金雕像"→"纯击在雕像")。文档保留原文,不做润色。
- 静音幻觉:模型在无语音片段可能吐出「字幕由…提供」之类的句子,文档层已按正则过滤。
- 互动视频节点通常没有字幕轨,转写是唯一正文来源;节点数多时耗时随之增长(69 节点约 1 分钟)。
- 平台字幕不一定拿得到:匿名请求多数返回 0 条,想稳定走“字幕优先”就设
BILI_SESSDATA(只放这一小段 cookie,不要整段)。 - 匿名接口有风控:偶发
412会直接停,不会硬刷;音轨走最低码率(30216),也受 CDN 防盗链限制(必须带Referer)。 - 无登录、无账号写入:不碰你的 B 站账号,不做评论/收藏/点赞。
实测数据(Windows 11 / Node 24.19 / 纯 CPU)
| 场景 | 结果 |
|---|---|
| 全新目录装环境(venv + 486 MB 模型) | 79 秒,占用约 708 MB |
| 普通视频 157 秒 | 转写 65 秒(约 0.4× 音频长),757~802 字 |
| 互动视频 48 节点 / 724 秒音频 | 242 秒,3980 字,6 个结局 |
| 30 分钟音频的互动剧(31 分钟音轨) | 单独约 1000 秒;与另一任务重叠时 1289 秒 |
这些是本机数字,CPU 型号不同会差不少。任务已改成串行排队,实际耗时基本按「音频总长 × 0.4~0.6」估算。
出错了怎么办
失败时任务会带一个错误码,面板和 bili_asr_status 都直接给出处置建议:
| 错误码 | 含义 | 怎么办 |
|---|---|---|
SETUP_REQUIRED |
没有 venv 或模型 | 跑一次 bili_asr_setup |
RATE_LIMITED |
被 B 站风控(412) | 等 5~10 分钟;频繁触发就设 BILI_SESSDATA 或换网络 |
AUDIO_FAILED |
音轨全部拿不到 | 会员/地区限制或 CDN 拒绝;可先 --no-asr 只抓结构 |
VIDEO_NOT_FOUND / VIDEO_UNAVAILABLE |
视频不存在/不可见 | 换视频,或确认链接 |
NO_PARTS |
没有可处理的分P | 加 --pages 明确指定 |
GRAPH_UNAVAILABLE |
互动视频没取到 graph_version | 先 --no-asr 看结构,附 BV 号开 issue |
TRANSCRIBE_FAILED |
python 转写进程失败 | 重跑 setup;看 bili_asr_status 的 log |
NETWORK / EXIT_n |
网络或未知退出 | 按 hint 处理,带 log 开 issue |
踩过的坑(写进代码里了,改代码前先看一眼)
- huggingface.co 直连超时:模型默认走
hf-mirror.com;486 MB 的大文件必须支持断点续传(HTTP Range),否则一定断在半路。 - faster-whisper 自带的 av 解码在 av 19 上会抛
open() got an unexpected keyword argument 'metadata_errors':transcribe.py自己用av.AudioResampler解码成 numpy 再喂模型。 - 互动视频的
edge_id必须传choice.id,传 1、2、3 这类顺序值基本都返回-400;节点视频 cid 在choice.cid。 - 静音段会幻觉出「字幕由…提供」这类句子:文档层按正则过滤,别当真台词。
- 匿名接口偶发 412:直接停,不要循环重试,否则风控更久。
- 桌面版宿主里没有
node:插件用process.execPath+ELECTRON_RUN_AS_NODE=1起子进程,别直接spawn("node")。 - 跨工作区写入:DSH 沙箱只允许写当前工作区,命令行调用时用
--out指到当前目录。 - PowerShell 5.1 读无 BOM 的 .ps1 会按 ANSI 解析:自己写 Windows 辅助脚本时存成 UTF-8 带 BOM。
开发
npm pack --dry-run # 看发布内容(.github / CHANGELOG 只在仓库里,不进包)
node bin/setup.mjs # 本地装环境
node bin/bili-asr.mjs BV1xxx # 直接跑 CLI
仓库结构:index.js(宿主:工具 + HTTP)/ client.js(设置页面板)/ bin/(CLI、转写、setup)/ cordis.patch.yml(挂载声明)。
致谢与许可
- 转写引擎 faster-whisper,模型 Systran/faster-whisper-small(MIT)。
- 宿主 API 用法参考了 dsh-bili-scroll(
defineTool兜底、webServer路由 + 信任栅栏)与 dsh-plugin-manager(客户端 slots 契约)。 - 本项目 MIT,见 LICENSE。
No comments yet. Be the first to write one.