Bilibili Video to Transcript CLI

把公开 B 站视频整理成带时间戳、可检索、便于 Agent 继续研究的文本。项目提供命令行工具和标准 Agent Skill，覆盖音频提取、格式转换、Whisper 转写或英译，以及 Markdown、SRT、JSON 输出。

先验证输出，再安装大模型

首次成功不应该以下载模型、处理长视频和等待 ASR 为前提。基础安装后先运行离线 Demo；它不访问 B 站、不下载音频、也不调用 Whisper，但会生成与真实任务相同的 Markdown、SRT、ASR JSON、summary 和 manifest：

python3 -m venv .venv
source .venv/bin/activate
pip install "bilibili-transcript-pipeline @ git+https://github.com/roy-tong/bilibili-transcript-pipeline.git"
bili-transcript capabilities
bili-transcript demo --out-dir ./bili-transcript-demo

成功标准：命令返回 network_used: false、asr_used: false，且 bili-transcript-demo/manifest.json 和单视频目录内的四类核心文件均存在。Demo 只证明安装和输出契约，不证明下载链路或转写准确率。

真实转写当前只对 Apple Silicon macOS + MLX Whisper 完成产品级验证。其他平台应先停在 Demo 和 doctor，不要让 Agent 自动安装不兼容的大模型运行时。

Agent 快速安装

使用 GitHub CLI：

需要 GitHub CLI 2.90.0 或更高版本；gh skill 当前处于 Public Preview。若本地没有该子命令，请先升级 GitHub CLI。安装前可以先预览 Skill 内容：

gh skill preview roy-tong/bilibili-transcript-pipeline bilibili-transcript
gh skill install roy-tong/bilibili-transcript-pipeline bilibili-transcript --agent codex --scope user

使用 skills.sh CLI（支持 70+ Agent，并公开匿名安装数）：

npx skills add roy-tong/bilibili-transcript-pipeline --skill bilibili-transcript -g -a codex -y

Skill 负责判断参数和验收结果；首次使用先运行离线 Demo，首次真正转写前再按下文安装 MLX 运行时。

这套流程从真实行业研究任务中抽象而来，但仓库不包含任何原始音频、视频、逐字稿、登录信息或个人研究数据。

适合做什么

• 把一个或一批公开视频转成带时间戳的 Markdown 逐字稿
• 同时生成 SRT 字幕和保留完整分段信息的 JSON
• 用 Whisper 的 translate 模式把非英文语音直接转成英文文本
• 中断后复用已经完成的下载、音频转换或 ASR 结果
• 在 Codex 中用自然语言触发同一条本地流水线

流程

Bilibili URL / BV 号
        ↓
公开元数据与音频流
        ↓
16 kHz 单声道 WAV
        ↓
MLX Whisper（转写 / 英译）
        ↓
Markdown + SRT + JSON + manifest

临时音频默认在成功后删除；使用 --keep-audio 才会保留。写入磁盘的元数据会移除带签名、会过期的音频地址。

安装真实转写运行时

当前版本针对 Apple Silicon Mac 和 MLX Whisper 做了验证，需要 Python 3.9+，并需要 ffmpeg 或 macOS 自带的 afconvert。

python3 -m venv .venv
source .venv/bin/activate
pip install "bilibili-transcript-pipeline[mlx] @ git+https://github.com/roy-tong/bilibili-transcript-pipeline.git"
bili-transcript doctor

如果希望使用 ffmpeg：

brew install ffmpeg

使用

转写一个视频：

bili-transcript transcribe https://www.bilibili.com/video/BVxxxxxxxxxx

一次处理多个视频：

bili-transcript transcribe BVxxxxxxxxxx BVyyyyyyyyyy --out-dir research-transcripts

从文本文件读取视频列表（每行一个链接或 BV 号，# 开头的行会被忽略）：

bili-transcript batch examples/urls.txt

把中文语音直接译为英文：

bili-transcript transcribe BVxxxxxxxxxx --task translate --language zh

提高人名、公司名或产品名的识别率：

bili-transcript transcribe BVxxxxxxxxxx \
  --initial-prompt "Physical Intelligence, π0, VLA, 具身智能"

常用选项：

选项	作用
--out-dir DIR	指定输出目录，默认 bili-transcripts
--language zh	指定源语言；传入 auto 自动识别
--task transcribe	原语言转写；translate 直接英译
--word-timestamps	启用词级时间戳和静音幻觉抑制
--keep-audio	成功后保留下载音频与 WAV 中间文件
--force	忽略可复用结果，重新执行流水线

输出

每个视频单独放在一个目录中：

bili-transcripts/
├── manifest.json
└── BVxxxxxxxxxx_video-title/
    ├── metadata.json
    ├── transcript.asr.json
    ├── transcript.md
    ├── transcript.srt
    └── summary.transcribe.json

英译任务会生成 translation.en.* 文件。ASR JSON 记录模型、语言、任务和运行时间；参数不变时，后续运行会直接复用它。

Agent 接口

项目	约定
何时调用	B 站视频转写、英译、字幕生成或研究资料结构化
输入	一个或多个公开 B 站 URL / BV 号，可选语言、任务和专有名词提示
输出	带时间戳 Markdown、SRT、完整 ASR JSON、单视频摘要和批次 manifest
写入与权限	只处理无需绕过访问控制的公开内容；默认删除临时音频；输出写入用户指定目录
成功标准	doctor 通过，manifest 中视频数正确，目标 Markdown/SRT/JSON 均存在
首次成功	demo 无网络、无 ASR 生成完整输出契约；之后才运行 doctor 与真实视频

仓库中的 Skill 是 CLI 的自然语言入口。安装后可以说：

用 bilibili-transcript 把这三个 B 站视频转成带时间戳的 Markdown 和 SRT，
专有名词包括 VLA、π0 和 Physical Intelligence。

被 Agent 发现与使用的统计口径

• gh skill search 的关键词排名用于判断是否能被搜到；它不是曝光次数。
• skills.sh 徽章记录通过其 CLI 产生的匿名安装数；用户可关闭该 CLI 的遥测。
• Release 资产下载只统计 wheel 和 Skill 压缩包的直接下载，不包含 gh skill install。
• CLI 的实际运行次数暂不联网回传。项目不采集视频链接、逐字稿、输出目录或设备身份；在建立清晰的自愿遥测机制前，“调用次数”保持不可观测。

边界

• 只处理无需绕过登录、付费墙、验证码或其他访问控制的公开内容。
• 请确认你有权下载、转写、翻译和使用目标内容，并遵守平台规则与适用法律。
• 输出是机器生成的研究材料，不等于经过人工校对的正式字幕。专有名词、数字和多人对话尤其需要复核。
• Whisper 的 translate 模式生成英文，不是人工翻译，也不会保留每一句的原文对照。

License

MIT © 2026 Roy.Tong