Metadata-Version: 2.4
Name: bbdown
Version: 0.0.1a0
Summary: BBDown 是一个免费且便捷高效的哔哩哔哩下载与解析工具。
Author: LittleGraper
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 2 - Pre-Alpha
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.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：

```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)。
