BBDown

BBDown 是一个使用 Python 重新实现的哔哩哔哩下载与解析命令行工具。

当前版本为 0.0.1a0 开发预览版，已提供完整参数面、配置发现、输入识别、全部元数据获取器， 以及 WEB、TV、APP、INTL 播放响应请求与解析、字幕列表与转换、XML/ASS 弹幕转换、 可恢复的异步 HTTP Range 下载核心，以及 FFmpeg、MP4Box、aria2c 的安全进程调用与混流计划。 DASH、FLV 下载、WEB/TV 二维码登录及 serve HTTP API 已接入 CLI；项目仍在按固定原版 基线逐项验证，在 0.0.1 前不宣称功能完整。

安装

要求 CPython 3.12 或更高版本，推荐使用 uv：

uv tool install bbdown

安装后可以使用任一等价命令：

BBDown --version
bbdown --help
bbd doctor
BBDown login
BBDown logintv
BBDown serve --listen http://127.0.0.1:23333

HTTP 服务

BBDown serve 默认监听 http://0.0.0.0:23333，保留原版任务提交、查询、清理和完成回调 接口。默认开放访问以保持兼容；暴露到不可信网络时，应使用 --token 或 BBDOWN_SERVER_TOKEN 启用 Bearer 认证，并用可重复的 --cors-origin 限制浏览器来源。

$env:BBDOWN_SERVER_TOKEN = "<从安全存储读取的值>"
BBDown serve --cors-origin https://console.example

完整路由和 JSON 字段见 HTTP API 文档。

外部工具

音视频下载与封装兼容 FFmpeg、MP4Box 和 aria2c。项目不会自动下载这些程序；可以通过 --ffmpeg-path、--mp4box-path、--aria2c-path 指定位置，或运行 BBDown doctor 检查 PATH。DASH/FLV 音视频、封面、字幕、弹幕与混流已经接入 CLI。

开发

uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run basedpyright
uv run interrogate src
uv run pytest
uv run mutmut run  # 仅支持具有 fork 的 POSIX 环境
uv build

完整文档通过 uv run mkdocs serve 本地预览。

原版差分测试

原版固定在 origin.lock.json 记录的提交。Windows/PowerShell 下可准备本地 oracle：

.\scripts\setup-origin-oracle.ps1
$env:DOTNET_ROOT = "<脚本输出的目录>"
$env:BBDOWN_DOTNET = "<脚本输出的路径>"
$env:BBDOWN_ORIGIN_DLL = "<脚本输出的路径>"
uv run pytest tests/oracle -m oracle --no-cov

在线烟测

Monthly live smoke 每月及手动下载匿名、会员样本的单个分 P，并同时启用 360P 优先及音视频 最小码率选择。匿名任务用固定原版和 Python 版各下载一次，再执行 ffprobe 语义差分；样本可通过 仓库变量 BBDOWN_SMOKE_INPUT 覆盖。会员烟测必须配置仓库变量 BBDOWN_MEMBER_SMOKE_INPUT 和 Secret BBDOWN_MEMBER_COOKIE。Cookie 只会写入运行器的临时私有凭据文件，不作为命令行参数或 日志输出，产物只保留在临时运行器中。预留的 TV/APP 认证 Secret 名称分别为 BBDOWN_TV_TOKEN 和 BBDOWN_APP_TOKEN。月度烟测会分别通过 WEB、TV、APP 三种认证路径下载 低清晰度样本；三类凭据只能由仓库所有者写入受保护的 GitHub Secrets，工作流和测试不提供 默认值，也不回显其内容。

全部在线烟测任务运行在带有 self-hosted、linux、x64、bbdown-live-smoke 标签的专用 GitHub Actions Runner 上，以使用已验证可访问 Bilibili 的网络。该主机必须预装 git、 ffmpeg 和 ffprobe；工作流会校验这些工具，但不会通过 sudo 修改持久化宿主机。 Python、uv 和固定的 .NET SDK 由已固定提交哈希的官方 Actions 在任务目录中配置。认证任务 无论成功与否都会显式清理临时凭据和下载产物。

Bilibili 当前会对旧的 /x/web-interface/view 返回 HTTP 412，因此 Python 客户端仅在该状态下 回退到响应结构等价的 /x/web-interface/wbi/view。线上差分构建仍固定检出原版提交，随后仅对 临时 oracle 的同一元数据 URL 应用可审计的一行兼容补丁，避免把已失效的上游入口误判为实现差异。

性能回退门禁

固定的 BV 往返、轨道排序、字幕转换和弹幕渲染工作负载不访问网络，也不与 Native AOT 比速度：

uv run python scripts/performance_gate.py

CI 使用宽松的绝对预算阻止数量级回退；较慢的本地诊断环境可用 --budget-multiplier 2 临时放宽，但 CI 始终使用默认预算。

媒体产物差分

安装 FFmpeg/ffprobe 后，可以比较原版与 Python 版产物的轨道类型及数量、编码、画面尺寸、音频 布局、时长、语言、字幕、封面 disposition、章节和关键元数据。容器索引、码率及编码器版本不参与 比较，默认允许 0.25 秒封装时长误差：

uv run python scripts/compare_media.py origin.mp4 python.mp4

许可证

本项目采用 MIT License，归属信息见 LICENSE 与 NOTICE。