BiliScriptor（哔稿匠）

把 B 站视频解析成本地可追踪数据包：Markdown 报告、字幕、弹幕、评论、播放流候选与详细排障日志，一次归档，后续随便分析。

Bilibili · CLI · Markdown Report · JSONL · SRT · ASR · OCR · Local First

BiliScriptor 面向需要整理视频资料、归档评论弹幕、生成 Markdown 阅读报告的场景。它不会默认下载音视频文件，而是优先保存元数据、分 P、字幕、当前弹幕、评论、播放流候选和阶段 manifest，方便后续接入 ASR、OCR、抽帧或 LLM 分析流程。

如果这个项目刚好解决了你的资料归档、内容研究或 B 站数据整理问题，欢迎 Star 关注后续能力。

功能亮点

解析 B 站视频链接或 BV 号，生成结构化本地数据包
支持扫码登录、本地 Cookie 导入和阶段级断点续传
导出官方字幕与 B 站 AI 字幕为 raw JSON、JSONL、SRT、TXT
抓取当前弹幕、官方热度候选评论、章节看点、互动视频图和播放流候选
生成 content/index.json 与 content/timeline.json，统一索引字幕、ASR、OCR、关键帧、章节、弹幕和评论
可选执行百炼 ASR、QwenVL-OCR 或 PaddleOCR，结果落入标准外部处理目录
提供 verify、logs、batch、tools media-plan 等维护和批量能力
Cookie、token、API key 和内容正文不会进入日志或 manifest；报告只保留经过转义且有数量上限的正文预览

适合谁使用

场景	BiliScriptor 能做什么
内容创作者	把视频资料整理为可读报告，快速回看分 P、字幕、评论和弹幕线索
研究与资料归档	保存结构化 JSON/JSONL，方便后续检索、统计和二次处理
自动化工作流	将 B 站视频解析结果接入 ASR、OCR、抽帧或 LLM 分析流程
开发者排障	通过详细结构化日志定位 API 请求、阶段状态、重试和文件写入问题

效果预览

一次 parse 会生成基础数据包；显式运行 ASR/OCR 后，会继续补充同一数据包：

output/BVxxxx/
  manifest.json
  video.json
  pages.json
  player/page_001.json
  chapters/page_001.json
  streams/page_001.json
  subtitles/page_001_0_zh-CN.jsonl
  subtitles/page_001_0_zh-CN.srt
  danmaku/page_001.current.jsonl
  valuable/danmaku/page_001.current.jsonl
  comments/comments.jsonl
  comments/tree.json
  content/index.json
  content/timeline.json
  asr/page_001_bailian.jsonl          # 可选：tools run-asr
  asr/page_001_bailian.srt            # 可选：tools run-asr
  asr/page_001_bailian.txt            # 可选：tools run-asr
  asr/page_001_bailian.meta.json      # 可选：tools run-asr
  visual/frames/page_001.index.json   # 可选：tools run-visual
  visual/ocr/page_001.jsonl           # 可选：tools run-visual --ocr
  visual/ocr/page_001.meta.json       # 可选：tools run-visual --ocr
  visual/keyframes/page_001.json      # 可选：tools run-visual --keyframes
  report.md

report.md 会把关键信息整理成适合阅读和引用的 Markdown：

# 视频标题

- BV 号：BVxxxx
- 分 P 数：1
- 字幕：已保存
- 当前弹幕：已保存
- 评论：已保存
- 内容索引：已生成
- ASR/OCR：按需接入

站点标题、简介、字幕、评论和弹幕在进入报告前都会按 Markdown/HTML 上下文转义；报告只展示少量有上限的预览，不会保留可触发外链图片、原始 HTML 或表格注入的语法。

日志 JSONL 适合脚本检索和问题定位：

{"event":"pipeline.stage_success","stage":"comments","status":"ok","elapsed_ms":1234,"count":20}
{"event":"client.request_success","endpoint":"/x/web-interface/view","status":200,"elapsed_ms":321}

日志不会写入完整响应正文、字幕正文、评论正文、弹幕正文，也不会写入 Cookie 值、token 或 API key。

安装

核心包支持 Python 3.10-3.14，项目使用 uv 管理 Python、虚拟环境和依赖。先安装 uv，再在仓库根目录同步项目环境：

uv sync

如需使用百炼 ASR 或 QwenVL-OCR，可复制 .env.example 为 .env 并填写 DASHSCOPE_API_KEY。CLI 启动时会自动读取当前目录 .env，但不会覆盖已经显式设置的系统环境变量，也不会把 key 写入日志。同一配置项的优先级为“显式 CLI 参数 > 环境变量（系统环境优先于 .env）> 内置默认值”。

可选能力按需安装：

uv sync --extra asr-bailian
uv sync --extra ocr-qwenvl
uv sync --extra ocr-paddle

可选能力的运行支持如下；具体 wheel 可用性仍以依赖上游和当前平台为准：

能力	Python	额外要求
核心解析、百炼 ASR、QwenVL-OCR	3.10-3.14	ASR/OCR 在线调用需要用户自己的 API key
PaddleOCR 本地执行器	3.10-3.13	安装 `ocr-paddle` extra；当前 `paddlepaddle 3.3.1` 提供对应 CPython wheels
自动抽帧与媒体切片	3.10-3.14	系统 `PATH` 中可用的 FFmpeg

项目不下载、捆绑或维护 FFmpeg 二进制。需要自动抽帧、音频切片时请先通过操作系统包管理器安装 FFmpeg；已有帧可使用 --frames-dir 或 --frame-extraction none，无需自动抽帧。

安装后可使用命令行工具：

uv run biliscriptor --help

也可以使用模块入口：

uv run python -m biliscriptor --help

快速开始

# 1. 扫码登录，保存本地 Cookie
uv run biliscriptor login

# 2. 解析视频并生成数据包
uv run biliscriptor parse "https://www.bilibili.com/video/BV1QEVY6jEYv/"

# 3. 基于已有数据包重新生成报告
uv run biliscriptor report output/BV1QEVY6jEYv

# 4. 仅抓取字幕
uv run biliscriptor subtitles BV1QEVY6jEYv

# 5. 校验已有数据包
uv run biliscriptor verify output/BV1QEVY6jEYv --strict

常用参数：

uv run biliscriptor parse BV1QEVY6jEYv \
  --output-dir output \
  --valuable-comment-limit 20 \
  --valuable-danmaku-limit 30 \
  --rate-limit 1.0 \
  --page 1

默认运行产物会分目录保存：登录 Cookie 和二维码在 runtime/，详细日志写入 logs/，解析数据输出到 output/。评论阶段默认使用官方热度候选规则：请求热评/默认结果、点赞排序和时间排序第一页，按 rpid 去重并轻量过滤低价值内容后写入 comments/comments.jsonl。弹幕仍完整写入 danmaku/，同时生成 valuable/danmaku/ 高价值筛选视图；默认按视频时长动态保留，每 10 分钟约 30 条，先按文本去重，再优先按接口 weight 字段筛选并做轻量时间分散，没有 weight 时按时间均匀抽样。

归档与续跑语义

普通 parse 重跑会重建当前 BV 的核心快照，避免 --page 或 --skip-* 混入旧解析文件；显式生成的 asr/、visual/ 结果会保留并重新校验。subtitles 与外部工具命令采用增量更新。
新写入的 manifest 文件引用统一为数据包内相对 POSIX 路径，数据包移动后仍可 verify。旧 manifest 中的绝对路径只会重定位到当前数据包内，不会继续读取原目录或包外路径。
可恢复阶段会记录页范围、相关配置和上游文件摘要指纹；文件缺失或指纹变化时重新执行，而不是沿用过期结果。
阶段成功一部分、失败一部分，评论安全上限命中，或内容源损坏时使用 partial 并保留已成功数据；失败列表只保存本次仍有效的问题。
多 P content/timeline.json 按 (page_index, start_ms) 排序，时间桶也携带 page_index，避免不同分 P 的局部时间互相交错。

命令说明

命令	作用
`login`	扫描 B 站二维码并保存 Cookie
`login import-cookies`	导入用户提供的 Netscape Cookie 文件
`parse`	解析视频并导出完整数据包
`batch`	批量解析文本、收藏夹、合集或 UP 主视频来源
`report`	从已有输出目录生成 `report.md`
`subtitles`	仅抓取指定视频的字幕
`verify`	校验已有输出数据包
`logs`	聚合本地 JSONL 日志并生成排障摘要
`tools media-plan`	生成外部 yt-dlp / FFmpeg 处理建议
`tools run-asr`	对已有数据包显式执行可选 ASR
`tools run-visual`	对已有数据包显式执行可选视觉 OCR

parse 支持按需跳过部分阶段：

uv run biliscriptor parse BV1QEVY6jEYv --skip-comments --skip-streams

如需使用旧的分页评论抓取，可显式传入分页参数或指定 --comment-mode paged：

uv run biliscriptor parse BV1QEVY6jEYv --all-comments --comment-pages 5 --reply-pages 3

默认评论模式只抓取少量高价值候选，不默认翻取楼中楼分页；如需调整默认候选数量：

uv run biliscriptor parse BV1QEVY6jEYv --valuable-comment-limit 30

如需调整高价值弹幕密度，--valuable-danmaku-limit 表示每 10 分钟保留多少条；显式小配额会被严格遵守，不再强制提高到 30：

uv run biliscriptor parse BV1QEVY6jEYv --valuable-danmaku-limit 50

如需让画面文字补充字幕/ASR 没有覆盖的信息，可以在已有数据包上显式运行视觉 OCR：

uv run biliscriptor tools run-visual output/BV1QEVY6jEYv --ocr --page 1 \
  --cookie-file runtime/cookies.txt

该命令默认调用系统 FFmpeg，从播放流或本地视频智能抽取少量关键帧，再交给 QwenVL-OCR；也可以通过 --provider paddleocr 使用本地 PaddleOCR。智能抽帧会参考字幕或 ASR 时间轴，优先保留文本边界、长文本空窗中的探针帧和明显画面变化，抽帧索引只记录时间戳、原因、视觉差异、图片哈希和脱敏覆盖统计，不保存完整播放流 URL、Cookie、API key 或图片 base64。默认 parse / batch 仍不下载媒体、不执行 ASR/OCR/抽帧。

如需在字幕缺失时显式补充 ASR，可以对已有数据包运行：

uv run biliscriptor tools run-asr output/BV1QEVY6jEYv --page 1 --allow-download \
  --cookie-file runtime/cookies.txt

run-asr 结果写入 asr/，同时生成 JSONL、SRT、TXT 和 meta 文件，不会伪装成官方字幕或 B 站 AI 字幕。--allow-download 只允许临时下载音频到 runtime/asr_tmp/ 并在执行后清理；当 B 站播放流 URL 无法被百炼长音频转写服务直接访问时，会回退到本地下载和分片识别，并按片段偏移拼回完整时间轴。--timeout 同时约束 SDK 等待和本地处理。外部工具需要登录态时必须显式传 --cookie-file，不会从 manifest 读取或信任凭据路径。

日志系统

所有 CLI 命令默认都会生成详细日志，文件名形如：

logs/20260624-010203-parse-12345.log
logs/20260624-010203-parse-12345.jsonl

.log 适合直接阅读，.jsonl 适合用脚本检索和分析。
默认日志级别是 DEBUG，会记录命令启动/结束、阶段状态、HTTP 请求、重试、限速等待、文件写入、报告生成、登录轮询等事件。
控制台仍保持简洁；命令结束时会打印本次日志路径。
日志只记录 URL 路径和查询参数名、响应字节数、状态码、耗时、计数和文件路径，不记录完整响应正文、字幕正文、评论正文或弹幕正文。
Cookie 值、SESSDATA、bili_jct、DedeUserID、qrcode_key、csrf、token、w_rid 等敏感字段会写成 <redacted>。
DASHSCOPE_API_KEY、通用 *_API_KEY 和损坏 Cookie 文件的原始内容也不会进入日志、manifest 或失败摘要。

常用日志参数：

uv run biliscriptor parse BV1QEVY6jEYv --log-level INFO
uv run biliscriptor parse BV1QEVY6jEYv --log-format jsonl
uv run biliscriptor parse BV1QEVY6jEYv --log-dir my_logs
uv run biliscriptor parse BV1QEVY6jEYv --log-to-stderr
uv run biliscriptor parse BV1QEVY6jEYv --no-file-log

排障时优先查看 .jsonl 中的结构化事件，例如按 event、stage、request_id 或 elapsed_ms 过滤；控制台只保留命令摘要和本次日志路径。

真实解析烟测示例：

uv run biliscriptor parse "https://www.bilibili.com/video/BV11kVt6sEWA?"

该命令已用正式接口验证通过，结束摘要为 Failures: 0，输出包生成在 output/BV11kVt6sEWA/。本次运行会生成一组 logs/<timestamp>-parse-<pid>.log 和 logs/<timestamp>-parse-<pid>.jsonl；抽检 JSONL 可正常解析，Cookie 只记录名称，不记录值。

为什么 Star

项目专注“本地优先”的 B 站资料整理，不默认下载音视频文件，适合轻量归档。
输出格式面向二次处理：Markdown 给人读，JSON/JSONL 给脚本和 LLM 工作流读。
日志系统默认开启且严格脱敏，方便排障，也尽量降低隐私风险。
如果你需要更多解析阶段、批量处理或报告模板，Star 能帮助我判断优先级。

Roadmap

提升 ASR、OCR、关键帧和字幕/AI 字幕之间的交叉验证质量
继续完善 content/index.json 的关键词、时间桶和跨来源关联
增强长音频 ASR 分段、失败片段重试和更多 provider 适配
深化画面信息提取、OCR 后处理和可追溯结构化输出
提供更细粒度的恢复、校验修复和数据包浏览能力

本地开发

运行测试：

uv sync
uv run pytest
uv pip check

项目结构：

biliscriptor/
  cli.py              # 命令行入口与参数
  pipeline.py         # 解析流程编排
  client.py           # B 站接口请求
  extractors.py       # API 数据归一化
  content.py          # 统一内容索引与时间线
  events.py           # 统一内容事件模型
  executors.py        # 可选执行器兼容门面
  executor_asr.py     # ASR provider 与分片识别
  executor_ocr.py     # OCR provider 与视觉编排
  executor_visual.py  # 视觉抽帧与 OCR 流程编排
  executor_media.py   # FFmpeg、媒体与帧处理
  executor_manifest.py # 外部执行结果原子更新
  executor_types.py   # 执行器公开选项与类型
  integrity.py        # 数据包校验
  log_aggregator.py   # 日志聚合
  media_plan.py       # 外部媒体处理计划
  logging_config.py   # 文本/JSONL 日志与脱敏
  report.py           # Markdown 报告生成
  utils.py            # 文件与通用工具
tests/
  test_client.py
  test_cli_logging.py
  test_content_extractors.py
  test_content_integrity_report.py
  test_executor_*.py
  test_integrity.py
  test_login*.py
  test_network_config.py
  test_pipeline*.py
  test_report.py

贡献前请阅读 CONTRIBUTING.md。开发新功能或修改关键流程时，请同步补充结构化日志事件，并遵守脱敏规则。

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github		.github
assets		assets
biliscriptor		biliscriptor
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

BiliScriptor（哔稿匠）

功能亮点

适合谁使用

效果预览

安装

快速开始

归档与续跑语义

命令说明

日志系统

为什么 Star

Roadmap

本地开发

Star 曲线

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

BiliScriptor（哔稿匠）

功能亮点

适合谁使用

效果预览

安装

快速开始

归档与续跑语义

命令说明

日志系统

为什么 Star

Roadmap

本地开发

Star 曲线

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages