Bilibili Content

一个用于提取、校验、转写和整理 B 站视频内容的通用工具 / AI Skill。

它既可以作为普通命令行工具运行，也可以交给 Hermes、Codex、自定义 Agent 或其他能调用本地命令的 AI 使用。

核心流程：

1. 优先读取 B 站官方字幕，速度最快。
2. 没有字幕时，默认先询问是否启用 Whisper。
3. 字幕疑似错位时，可提示用户改用 Whisper。
4. 用户允许后，下载音频，转成 WAV，再用 Whisper 转写。
5. 输出 transcript 文本和 metadata JSON，供 AI 继续总结、整理或分析。

本项目不包含 Whisper 模型权重，默认模型名为 small。模型文件由用户本地安装或首次运行 Whisper 时自动下载。

---

TL;DR

最简单用法：交给 AI

1. 克隆或下载本项目。
2. 把整个 bilibili-content/ 文件夹放到你的 AI / Skill 工具目录。
3. 复制 .env.example 为 .env，填入 B 站 Cookie。
4. 对 AI 说：

总结这个 B 站视频：BVxxxxxx
如果字幕可疑或没有字幕，就用 Whisper 转写。

AI 应优先运行：

python scripts/analyze_bilibili.py "BVxxxxxx" --verify-subtitle

手动命令行运行

git clone <repo-url>
cd bilibili-content
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env，填入 B 站 Cookie
python scripts/analyze_bilibili.py "BVxxxxxx" --verify-subtitle

Windows PowerShell：

git clone <repo-url>
cd bilibili-content
pip install -r requirements.txt
Copy-Item .env.example .env
# 编辑 .env，填入 B 站 Cookie
python .\scripts\analyze_bilibili.py "BVxxxxxx" --verify-subtitle

---

适用场景

使用方式	说明
普通 CLI 工具	手动运行 Python 脚本，提取字幕或转写音频。
AI Skill	把本项目作为 Hermes / Codex / 其他 Agent 的工具目录。
自动化脚本	读取结构化 JSON 状态，按 success / needs_confirmation / failed 决策。
视频学习助手	把课程、教程、访谈、项目榜等视频转成可总结文本。

---

功能特性

• 提取 B 站官方字幕。
• 支持多 P 视频，使用 --page N 指定分 P。
• 支持字幕语言优先级，例如 --language zh,en。
• 支持字幕可信度检查：--verify-subtitle。
• 无字幕时默认返回 needs_confirmation，不会直接跑耗时 Whisper。
• 用户确认后，可下载音频并用 Whisper 转写。
• 可通过 --force-whisper 跳过 B 站字幕，直接从音频转写。
• 支持 Whisper 语言控制，例如 --whisper-language auto。
• 输出 transcript 文本和 metadata JSON，方便 AI 后续总结。
• 输出结构化状态，便于 AI 或自动化程序判断下一步。

---

为什么需要这个工具

B 站很多视频都有 AI 字幕，但这些字幕并不总是可信。实际测试中出现过：视频标题是 GitHub 开源项目榜，但 B 站返回的字幕却是烧烤、歌词等无关内容。

这个工具的目标不是盲目信任字幕，而是提供更稳的内容提取流程：

场景	默认策略
有正常字幕	直接提取字幕，速度最快。
没有字幕	先询问是否启用 Whisper。
字幕疑似错位	提示用户，或在 --auto 下自动切换 Whisper。
内容很重要	使用 --force-whisper，直接从音频转写。

---

项目结构

bilibili-content/
├── README.md
├── SKILL.md
├── requirements.txt
├── .env.example
├── agents/
│   └── openai.yaml
├── scripts/
│   ├── analyze_bilibili.py       # 主入口：字幕、确认、Whisper fallback
│   ├── fetch_subtitle.py         # 提取 B 站官方字幕
│   ├── fetch_audio_playurl.py    # 通过 playurl API 下载音频并转为 WAV
│   └── transcribe_whisper.py     # 调用 Whisper 转写
└── references/
    ├── bilibili-api-notes.md
    ├── bilibili-api-quirks.md
    ├── bilibili-subtitle-url-issues.md
    └── whisper-setup.md

---

作为 AI Skill 使用

这是最推荐的使用方式。

1. 下载或克隆项目

git clone <repo-url>

或直接下载 ZIP 并解压。

2. 放入 AI / Skill 工具目录

把整个 bilibili-content/ 文件夹交给你的 AI 环境，例如：

skills/
└── bilibili-content/

或按你的 Agent / Skill 系统要求放置。

3. 配置 .env

cp .env.example .env

Windows PowerShell：

Copy-Item .env.example .env

然后填入 B 站 Cookie。

4. 让 AI 调用

你可以直接对 AI 说：

总结这个 B 站视频：https://www.bilibili.com/video/BVxxxxxx
先检查字幕是否可信；如果没有字幕或字幕可疑，再询问我是否使用 Whisper。

AI 应该先运行：

python SKILL_DIR/scripts/analyze_bilibili.py "URL_OR_BVID" --verify-subtitle

然后根据 JSON 状态决定下一步。

---

作为命令行工具使用

1. 安装 Python 依赖

pip install -r requirements.txt

requirements.txt 包含：

requests
python-dotenv
openai-whisper

PyTorch 对系统和 CUDA 版本比较敏感，尤其是 Windows + NVIDIA GPU。建议根据自己的 CUDA 版本单独安装 PyTorch，不要在 requirements.txt 中写死通用版本。

2. 安装 ffmpeg

Whisper 和音频转码都需要 ffmpeg。

Windows, Winget：

winget install ffmpeg

Windows, Chocolatey：

choco install ffmpeg

Windows, Scoop：

scoop install ffmpeg

macOS：

brew install ffmpeg

Ubuntu / Debian：

sudo apt update && sudo apt install ffmpeg

验证：

ffmpeg -version

3. 安装 Whisper

如果使用 pip install -r requirements.txt，会安装 openai-whisper。

也可以单独安装：

pip install -U openai-whisper

或安装官方 GitHub 最新版：

pip install git+https://github.com/openai/whisper.git

官方项目：https://github.com/openai/whisper

首次使用某个模型时，Whisper 可能会自动下载模型文件。默认模型是 small。

---

Cookie 配置

本项目需要使用你的 B 站登录 Cookie 来访问字幕和音频播放信息。

1. 获取 Cookie

1. 在浏览器打开 https://www.bilibili.com 并登录。
2. 打开 DevTools / 开发者工具。
3. 进入：Application → Cookies → https://www.bilibili.com。
4. 复制以下值：
   • SESSDATA
   • bili_jct
   • DedeUserID

2. 填写 .env

BILIBILI_SESSDATA=
BILIBILI_BILI_JCT=
BILIBILI_DEDE_USERID=

说明：

• SESSDATA 和 bili_jct 是必填。
• DedeUserID 建议填写。
• 如果浏览器中显示 %2C，请替换为英文逗号 ,。
• 如果浏览器中显示 %2A，请替换为星号 *。
• 不要把 .env 上传到 GitHub。

---

Whisper 配置

.env.example 中包含可选 Whisper 配置：

# WHISPER_MODEL_DIR=~/.hermes/whisper/models
# WHISPER_TEMP=~/.hermes/whisper/temp
# WHISPER_MODEL=small
# WHISPER_DEVICE=cuda

Windows 示例：

WHISPER_MODEL_DIR=~/.hermes/whisper/models
WHISPER_TEMP=~/.hermes/whisper/temp
WHISPER_MODEL=small
WHISPER_DEVICE=cuda

常用模型：

模型	速度	质量	适合场景
tiny	很快	较低	快速粗略识别。
base	快	一般	短视频、粗略总结。
small	较快	较好	默认推荐。
medium	较慢	更好	重要内容。
large-v3	慢	高	高质量转写。

RTX 4060 实测：small 转写 40 分钟视频通常需要几分钟，具体速度取决于音频长度、GPU、磁盘、CUDA 和 PyTorch 配置。

---

常用命令

默认模式：字幕优先

python scripts/analyze_bilibili.py "BVxxxxxx"

默认行为：

1. 有字幕：直接提取。
2. 无字幕：返回 needs_confirmation，不自动跑 Whisper。
3. 多 P 未指定：返回 needs_page_selection。

检查字幕可信度

python scripts/analyze_bilibili.py "BVxxxxxx" --verify-subtitle

推荐用于教程、课程、技术视频、项目榜等容易出现字幕错位的内容。

无字幕时允许 Whisper

python scripts/analyze_bilibili.py "BVxxxxxx" --whisper

全自动模式

python scripts/analyze_bilibili.py "BVxxxxxx" --auto

字幕可疑时自动切换 Whisper

python scripts/analyze_bilibili.py "BVxxxxxx" --auto --verify-subtitle

强制使用 Whisper

python scripts/analyze_bilibili.py "BVxxxxxx" --force-whisper

多 P 视频

python scripts/analyze_bilibili.py "BVxxxxxx" --page 7 --verify-subtitle

非中文视频

python scripts/analyze_bilibili.py "BVxxxxxx" --auto --whisper-language auto

---

使用模式建议

场景	推荐命令
快速总结	python scripts/analyze_bilibili.py URL
技术教程 / 课程 / 项目榜	python scripts/analyze_bilibili.py URL --verify-subtitle
字幕错位或内容很重要	python scripts/analyze_bilibili.py URL --force-whisper
无字幕时允许转写	python scripts/analyze_bilibili.py URL --whisper
想全自动处理	python scripts/analyze_bilibili.py URL --auto --verify-subtitle
多 P 视频	python scripts/analyze_bilibili.py URL --page N --verify-subtitle
非中文视频	python scripts/analyze_bilibili.py URL --auto --whisper-language auto

---

CLI 参数

参数	用途
--page N	多 P 视频选择第 N P。
--language zh,en	B 站字幕语言优先级。
--whisper	仅在没有字幕时允许 Whisper。
--auto	没有字幕或字幕可疑时自动切换 Whisper。
--force-whisper	跳过 B 站字幕，直接从音频转写。
--verify-subtitle	检查 B 站字幕是否疑似错位或不可信。
--whisper-language auto	Whisper 语言设置，auto 表示自动检测。
--whisper-model small	Whisper 模型名，默认 small。
--device cuda	Whisper 运行设备，常见值：cuda、cpu。
--timestamps	支持时保存带时间戳的转写文本。

---

输出说明

输出文件保存到：

output/

常见文件名：

{bvid}_{title}.txt
{bvid}_{title}.json
{bvid}_p{N}_{title}.txt
{bvid}_p{N}_{title}.json

说明：

• .txt：字幕或 Whisper 转写文本，供 AI 总结。
• .json：元数据，包括标题、来源、分 P、模型、设备、状态和输出路径。

脚本也会在 stdout 打印结构化 JSON。

状态	含义	建议下一步
success	已生成 transcript。	读取 transcript_file 并总结。
needs_confirmation	没有字幕；默认不运行 Whisper。	询问用户是否转写音频。
needs_page_selection	多 P 视频需要指定 --page N。	展示分 P 列表并让用户选择。
subtitle_suspicious	字幕可能错位或不可靠。	建议使用 --force-whisper 或 --auto --verify-subtitle。
failed	Cookie、API、下载、ffmpeg 或 Whisper 错误。	报告 phase 和 message，不要盲目 fallback。

---

字幕可信度检查

--verify-subtitle 是轻量启发式检查，不是语义模型。

它会检查：

• 字幕是否像歌词或重复短句。
• 字幕是否异常短。
• 标题关键词和字幕内容是否几乎没有重合。
• 明显技术类标题的字幕中是否完全没有技术词。
• 技术类标题是否对应大量无关的美食、歌词或情绪词。

示例：

标题：GitHub 开源项目榜
字幕：烧烤、美食、歌词、重复情绪短句
结果：subtitle_suspicious

推荐：

python scripts/analyze_bilibili.py "URL" --auto --verify-subtitle

---

多 P 视频

如果视频有多个分 P 且没有指定 --page，脚本会返回：

{
  "status": "needs_page_selection",
  "pages": [...],
  "message": "该视频有多个分P，请使用 --page N 参数指定要查看的集数"
}

选择指定分 P：

python scripts/analyze_bilibili.py "BVxxxxxx" --page 7

--force-whisper 对多 P 视频同样要求指定 --page N，避免用户想处理 P7 时误转写 P1。

---

AI / Agent 应该如何调用

AI 使用时建议遵循这个流程：

1. 接收用户提供的 B 站 URL 或 BV 号。

2. 先运行：

   python SKILL_DIR/scripts/analyze_bilibili.py "URL_OR_BVID" --verify-subtitle

3. 读取 JSON 状态：

   • success：读取 transcript_file，按用户要求总结。
   • needs_confirmation：说明没有字幕，询问是否使用 Whisper。
   • needs_page_selection：展示分 P 列表，让用户选择。
   • subtitle_suspicious：说明字幕为什么可疑，并建议 Whisper。
   • failed：报告 phase 和 message，不要静默切换路径。

4. 如果 transcript 很长，先分块再总结：

   每块约 40K 字符，重叠约 2K 字符；先总结每块，再合并成最终答案。
   

---

GitHub 上传安全

可以上传到 GitHub 的内容：

README.md
SKILL.md
requirements.txt
.env.example
agents/
scripts/
references/

不要上传：

.env
真实 BILIBILI_SESSDATA
真实 bili_jct
真实 DedeUserID
output/
下载的视频、音频、字幕文件
Whisper 模型权重

推荐 .gitignore：

.env
*.env
output/
*.m4s
*.wav
*.mp3
*.mp4
*.flv
*.ass
*.srt
*.vtt
__pycache__/
*.pyc
*.pt
*.bin
*.ckpt
*.safetensors
.DS_Store

上传前建议检查：

git status
git diff --cached

确认没有把 .env、Cookie、输出文件或模型权重加入提交。

---

故障排查

phase: cookie

B 站 Cookie 缺失或过期。

修复：

1. 在浏览器中重新登录 B 站。
2. 打开 DevTools → Application → Cookies → bilibili.com。
3. 更新 .env。

phase: page_selection

视频有多个分 P，需要指定 --page N。

python scripts/analyze_bilibili.py "URL" --page 2

phase: subtitle_api

B 站字幕 API 返回错误。可能原因：

• Cookie 过期。
• 视频权限限制。
• API 临时不稳定。
• 触发反爬或风控。

可以稍后重试，或使用：

python scripts/analyze_bilibili.py "URL" --force-whisper

phase: playurl

无法获取音频流地址。可能原因：

• Cookie 权限不足。
• 视频需要会员或特殊权限。
• B 站风控。
• playurl API 临时变化。

phase: ffmpeg

ffmpeg 未安装，或不在 PATH 中。

检查：

ffmpeg -version

phase: whisper

Whisper 转写失败。可能原因：

• openai-whisper 未安装。
• PyTorch / CUDA 配置错误。
• 显存不足。
• 模型下载失败。

可以先试：

python scripts/analyze_bilibili.py "URL" --force-whisper --device cpu --whisper-model base

---

已知限制

• 只能处理当前账号有权限访问的视频。
• B 站接口和风控可能变化，playurl 下载不保证永久稳定。
• 字幕可信度检查是启发式规则，不是完整语义判断。
• Whisper 路径会占用时间、磁盘和 GPU / CPU 资源。
• 本项目只提取和转写内容；最终总结质量取决于调用它的 AI。

---

开发检查清单

打包或提交前建议检查：

python -m py_compile scripts/*.py
find . -type d -name "__pycache__" -prune -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

确认不要提交：

.env
output/
*.m4s
*.wav
*.mp3
Whisper 模型权重

---

版本

当前版本：v1.0

已验证能力：

• 单 P 有字幕视频。
• 单 P 无字幕视频。
• Whisper fallback。
• --force-whisper。
• 多 P --page N。
• 字幕可信度检查。
• 字幕错位时切换 Whisper。