Metadata-Version: 2.4
Name: bbdown
Version: 0.0.1
Summary: BBDown 是一个免费且便捷高效的哔哩哔哩下载与解析工具。
Author: LittleGraper
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: protobuf>=7.35.1,<8
Requires-Dist: qrcode[png]>=8.2
Requires-Dist: starlette>=0.48.0
Requires-Dist: uvicorn>=0.35.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# BBDown

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

`0.0.1` 已按固定原版基线完成 CLI、配置、元数据、WEB/TV/APP/INTL 播放地址、
字幕、弹幕、下载、混流、二维码登录和 `serve` HTTP API 的功能等价验证。
具体自动化与线上证据见 [等价性证据矩阵](docs/equivalence-matrix.md)。

## 安装

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

```powershell
uv tool install bbdown
```

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

```powershell
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` 限制浏览器来源。

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

完整路由和 JSON 字段见 [HTTP API 文档](docs/http-api.md)。

## 外部工具

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

## 开发

```powershell
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：

```powershell
.\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 比速度：

```powershell
uv run python scripts/performance_gate.py
```

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

### 媒体产物差分

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

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

## 许可证

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