bili-dl 0.1.0__tar.gz

bili_dl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e . pytest
+      - run: pytest

bili_dl-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Cookies / runtime secrets — NEVER commit
+cookies_all.txt
+cookies_bilibili.txt
+cookies_bilibili.txt.bak_*
+*.m4a
+*.mp4
+*.mkv
+*.webm
+!tests/data/*.txt

bili_dl-0.1.0/.python-version

@@ -0,0 +1 @@
+3.9

bili_dl-0.1.0/AGENTS.md

@@ -0,0 +1,168 @@
+# AGENTS.md — bili-dl 项目记忆
+
+> 本文件沉淀"读代码难悟到"的项目事实；与全局规则配合使用。
+
+## 1. 技术栈
+
+- **语言**：Python 3.9+（目标 3.9 兼容，CI 跑 3.9/3.13）
+- **构建**：hatchling（`pyproject.toml` 声明，`src/` 布局）
+- **运行时依赖**：**零** —— 仅用标准库（`subprocess`、`urllib`、`pathlib`、`ctypes`、`argparse`、`json`、`shutil`）。
+- **外部程序依赖**：`yt-dlp`（必需，找不到则报错退出）、`ffmpeg`（可选，缺失则降级跳过音频提取/容器修复）。
+- **工具链**：ruff（lint+format）、pytest（测试）。无 mypy 强制。
+- **分发**：目标 PyPI，包名 `bili-dl`，脚本入口 `bili-dl`。
+
+## 2. 已踩通的坑
+
+### 2.1 原 bd.ps1 的 PowerShell 作用域 bug（重构根因）
+- **现象**：`bd.ps1` 在主流程定义 `$commonOpt`，在函数 `Invoke-DownloadVideo` 内用 `@commonOpt` 引用；PowerShell 函数默认读不到调用者作用域的普通变量，导致 Cookie/Referer 参数被静默丢弃，非会员 1080P 实际下载退化为匿名。
+- **根因**：作用域隔离 + 静默失败。
+- **解法**：Python 版把 common 选项作为显式 `list[str]` 传入 `downloader.download()`，参数显式 threading，该 bug 类无法复现。位置：`src/bili_dl/downloader.py` 的 `_common_args()` + `download()` 签名。
+- **教训**：任何"胶水脚本把公共参数定义在一处、函数内隐式引用"的设计都要在移植时显式化。
+
+### 2.2 ffmpeg List[string].AddRange 在 PowerShell 不可用
+- 原 bd.ps1 重构时用 `New-Object System.Collections.Generic.List[string]` + `.AddRange(@(...))` 会抛 `MethodException`：`Object[]` 无法转 `IEnumerable[string]`。
+- 解法：改用 PowerShell 原生数组 `@(...) += @(...)`。Python 版无此问题。
+
+### 2.3 音频容器标准化（foobar2000 兼容）必须覆盖两条路径
+- **现象**：B 站 DASH 音频原始容器 `moov` 在尾、`major_brand=M4A`，foobar2000 起播慢或比特率显示异常。
+- **根因**：容器布局，非编码问题。
+- **解法**：`ffmpeg -i in -map 0:a -c:a copy -map_metadata 0 -movflags +faststart out`，零损失重封装为 `moov` 前置的 isom 容器。
+- **关键**：`all` 模式（从视频抽流）和 `a` 模式（直接下载音频）**两条路径都要走 `repair_audio_container`**。这是本项目的"产品差异化"。
+- **验证**：ffprobe 看到 `compatible_brands=M4A isom iso2`，`moov` 在 offset 36（紧跟 ftyp）。
+- **位置**：`src/bili_dl/ffmpeg.py` 的 `repair_audio_container()` / `extract_audio()`，后者提取后必调前者。
+
+### 2.4 Cookie 隐私模型（核心不变量）
+- 永远只从 `cookies_all.txt` 提取含 `bilibili` 的行；其他站点 Cookie 不解析、不存储、不外发。这是项目隐私承诺，任何 PR 不得破坏。
+- 位置：`src/bili_dl/cookies.py` 的 `import_bili_cookie_from_all()` —— 用列表推导显式过滤 `"bilibili" in line`。
+- 测试锚定：`tests/test_cookies.py` 的 `test_extract_drops_other_sites()` 断言 `other_secret` 不泄漏。
+
+### 2.5 nav API 在线校验的降级策略
+- **现象**：在线校验 Cookie 需调 `https://api.bilibili.com/x/web-interface/nav`，但网络/SSL 错误时不能因此阻断下载（本地格式可能仍有效）。
+- **解法**：`_online_check()` 返回 `True`（已登录）/`False`（未登录）/`None`（网络错误）；`None` 时降级为仅本地格式校验并打印警告，仍返回 True。
+- 位置：`src/bili_dl/cookies.py::_online_check()` + `test_cookie_valid()`。
+
+### 2.6 nav API 必须伪装浏览器 User-Agent（412 根因，非 SSL）
+- **现象**：Python 版上线后实测每次都走降级（"无法在线验证 Cookie ... 降级为本地格式校验"），而原 bd.ps1 PowerShell 的 `Invoke-RestMethod` 一直能成功显示已登录用户名。曾被误判为本机证书链问题。
+- **根因**：B 站 nav API 对 urllib 默认 UA `Python-urllib/3.x` 返回 **HTTP 412 Precondition Failed**（反爬）。`Invoke-RestMethod` 内部默认带 PowerShell/browser UA 故一直成功。代码的 `except Exception` 把 412 也吞进"网络/SSL 错误"分支，导致降级提示与真实根因描述不符——既误导用户也让 SSL 甩锅。
+- **解法**：`config.py::USER_AGENT` 放一个固定 Chrome UA 字符串；`cookies.py` 的两处 `urllib.request.Request` header 都加 `"User-Agent": USER_AGENT`。仅 nav 探测用，yt-dlp 下载阶段自带 UA。
+- **验证**：实跑 `bili-dl`（无 URL）开头即显示 `[OK] Cookie 有效 | 已登录: <uname>`。
+- **启示**：`except Exception` 太宽会把业务级 HTTP 错误（412/403/404）混进"网络问题"分支。后续若想精确分级，可在 `_online_check` 单独 catch `urllib.error.HTTPError` 拿 status，把 412/403 报为"被风控"而非"网络错误"。当前简单加 UA 已解。
+- **关联**：用户曾因 `-k` 也无效而怀疑证书；`-k` 只影响 yt-dlp 的 `--no-check-certificate`，**对 urllib 探测无影响**（urllib 默认就校验，且本机 CA 没问题）。下次有人误以为证书，先查 UA。
+
+### 2.7 TLS 证书校验默认开（安全硬化）
+- 原 bd.ps1 无条件 `--no-check-certificate` 是降级项；Python 版默认启用校验，仅 `-k/--insecure` 显式关闭，用于自签证书环境。
+- 位置：`cli.py` 的 `--insecure` 参数 → `downloader.py::_common_args()` 条件追加 `--no-check-certificate`。
+
+### 2.8 跨平台路径不绑平台 API
+- 原 bd.ps1 用 `[Environment]::GetFolderPath('MyVideos')` 是 Windows 专属；Python 版 `paths.py` 用 `sys.platform` 分支 + XDG 约定，同一代码三平台通用。
+- Windows 用 `%APPDATA%\bili-dl` 存 cookie，`~/Videos` 改为 `Path.home()/"Videos"`（避免 SHGetKnownFolderPath 零依赖约束）。
+
+### 2.9 Windows CJK 编码策略：绝不强制 UTF-8（踩坑沉淀）
+- **现象**：初版曾加 `subprocess.run(..., encoding="utf-8")` 解码 yt-dlp 的 `--print filename` 输出 + `sys.stdout.reconfigure("utf-8")`。结果**任何非 ASCII 标题的下载都 `[失败]`**：phase1 预测路径与 phase2 yt-dlp 实际写入磁盘的文件名不一致，`out_path.exists()` 返回 False。
+- **根因**：yt-dlp 在 Windows 默认按系统 locale（cp936/gbk）编码 stdout。强制用 UTF-8 解码 cp936 字节得到的是真·乱码 unicode，与 yt-dlp 用 Win32 UTF-16 写入磁盘的正确文件名不匹配；反之默认 locale 解码（yt-dlp encode 与 Python decode 同为 cp936）虽然 unicode 含 GBK 外字符会丢字符，但 predict 路径字符串与磁盘文件名（同样经 yt-dlp encode）完全一致，`exists()` 稳定 True。
+- **解法（已固化）**：`src/bili_dl/cli.py` 顶部注释明确"**不** reconfigure stdio、**不**设 `PYTHONUTF8`"，`downloader.py` predict 用 `subprocess.run(..., text=True)` **不传 encoding**，让两侧都用宿主默认 locale。
+- **权衡**：常见汉字全在 GBK 范围内（99% 标题无丢失），少数生僻字/emoji 在 yt-dlp 内部已 replace，不影响路径定位。这是最少惊讶、跨平台最稳的方案。**任何"加 UTF-8 更现代"的 PR 都必须先验证 CJK 标题下载不破。**
+- **测试锚定**：暂无单测（需真实 yt-dlp 子进程）；集成验证靠实跑 BV1froEBxEcX（《春死诀》全 CJK 标题）确认 `[完成!]` 而非 `[失败]`。
+- **环境差异**：bd.ps1 原版在 PowerShell 下靠 `chcp 65001 + PYTHONUTF8=1` 强制全程 UTF-8（PowerShell 调子进程的固有编码坑）；纯 Python 跨平台版不沿用，因 Python 与终端/yt-dlp 默认 locale 自洽。
+
+### 2.10 `-v` 被占用，`--version` 用 `-V`（CLI 短选项冲突）
+- **问题**：`-v` 已用于 `--video`（仅视频模式），再加 `-v/--version` 会被 argparse 拒绝（mutually exclusive group 与 version action 重复 dest）。
+- **惯例**：`yt-dlp`、`curl`、`pip` 等都用大写 `-V` 表示 `--version`，与 `-v`/`--verbose` 区分。沿用此惯例用户零学习成本。
+- **解法**：`cli.py::_build_parser()` 中 `--version` 用 `action="version"`，短选项 `-V`（不进 mutually exclusive group，否则会与 mode 冲突触发 `SystemExit(0)` 之外的限制验证）。
+- **实测**：`bili-dl -V` → `bili-dl 0.1.0`；`bili-dl --version` 同效；`bili-dl -v <url>` 仍仅视频模式。
+- **教训**：CLI 短选项是稀缺资源（26 字母），命名时优先排雷 `-V/--version`、`-v/--verbose`、`-h/--help` 这类高频占用。本工具占用清单：`-a/-v` 模式、`-k` insecure、`-V` version、`-h` help。
+
+## 3. 项目结构
+
+```
+bili-dl/
+├── pyproject.toml                 # hatchling + ruff + pytest 配置（单文件）
+├── README.md                      # 宣传门面（务必随版本同步功能表）
+├── CHANGELOG.md                   # Keep a Changelog 格式
+├── LICENSE                        # MIT + 依赖合规说明
+├── .python-version                # pyenv/uv 用，固定 3.9（向下兼容基准）
+├── .gitignore                     # 含 cookies_*.txt 与媒体文件，防泄密
+├── AGENTS.md                      # 本文件
+├── src/bili_dl/
+│   ├── __init__.py                # __version__
+│   ├── __main__.py                # python -m bili_dl
+│   ├── cli.py                     # argparse + REPL + main()（主入口）
+│   ├── config.py                  # 纯常量，无可变状态
+│   ├── paths.py                   # 跨平台路径（Win/macOS/Linux）
+│   ├── cookies.py                 # Netscape 提取 + 在线/本地校验
+│   ├── ffmpeg.py                  # ffprobe/ffmpeg 探测 + 零损失重封装/提取
+│   ├── downloader.py              # yt-dlp 两阶段下载（预测路径 → 实下）
+│   └── ui.py                      # ANSI 彩色输出（Win10+ 启用 VT）
+├── tests/
+│   ├── test_cookies.py            # 隐私核心测试（其他站点不泄漏）
+│   ├── test_paths.py              # 跨平台路径分支（mock platform）
+│   ├── test_package.py            # 包导入冒烟测试
+│   └── data/sample_cookies_all.txt
+└── .github/workflows/ci.yml       # Win/macOS/Linux × Py3.9/3.13 矩阵
+```
+
+## 4. 关键约定
+
+### 4.1 依赖方向
+`cli → downloader → ffmpeg`；`cli → cookies`；`cli → paths → config`；`ffmpeg/downloader → ui/config`。
+- `config` 是叶节点（只导出常量），任何模块可依赖它，它不依赖任何内部模块。
+- `ui` 也接近叶节点（仅 `mode_label` 懒导入 `config`）。
+- 禁止反向依赖或循环导入。
+
+### 4.2 零运行时依赖（硬约束）
+- 不可引入 `requests`/`colorama`/`rich` 等三方包。HTTP 用 `urllib.request`，彩色输出用 ANSI + `ctypes`，路径用 `pathlib`。
+- 任何"加个依赖更方便"的提案都需先权衡"零依赖"这个卖点。
+
+### 4.3 命名
+- Python 模块用 `snake_case`；CLI 旗帜沿袭 Unix 惯例（`--all/-v/-a` 模式、`--proxy`、`-k/--insecure`、`-V/--version`）。短选项占用清单见 §2.10。
+- yt-dlp format 串集中放 `config.py`（`FMT_AV`/`FMT_AUDIO`），不散落。
+
+### 4.4 提交规范
+- Conventional Commits 中文风格可接受（项目面向中文用户为主），但英文 commit 便于国际贡献者，建议英文。
+- 任何改动到 cookies.py / ffmpeg.py 者必须跑 `tests/test_cookies.py` / 相关测试，不得破坏隐私断言。
+
+## 5. 常用命令
+
+```bash
+# 开发安装
+pip install -e .
+
+# 检验
+ruff check src tests
+ruff format --check src tests
+pytest            # 或 pytest -q
+
+# 实测下载（需 yt-dlp + ffmpeg，且 cookie 目录有可用 cookies_bilibili.txt）
+bili-dl https://www.bilibili.com/video/BVxxxxx
+bili-dl -a https://www.bilibili.com/video/BVxxxxx   # 验证音频 faststart
+
+# ffprobe 检查产物（验证 moov 在前 + isom 容器）
+ffprobe -v error -show_entries format=format_name:format_tags=major_brand,compatible_brands path.m4a
+ffmpeg -v trace -i path.m4a -f null - 2>&1 | findstr /R "moov mdat"   # Win
+ffmpeg -v trace -i path.m4a -f null - 2>&1 | grep -E "moov|mdat"       # Unix
+
+# 构建
+pip install build
+python -m build            # dist/ 出 wheel + sdist
+```
+
+## 6. 环境特异事实（开发者备注）
+
+- **gh / git SSL**：本机证书链存在问题，但实测 `gh api user` 与 SSH 协议 git 操作均正常（账号 Echoziness，git protocol=ssh）。若将来 gh API 失败，再考虑 `git config --global http.sslVerify false`（高风险，需用户批准）。当前无需关闭。
+- **SSH 22 端口被封，走 443**：`git push` 实测 `ssh: connect to host github.com port 22: Connection refused`。解法：`git remote set-url origin ssh://git@ssh.github.com:443/Echoziness/bili-dl.git`，首次 push 用 `GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=accept-new"` 登记 `ssh.github.com:443` 的 host key（ED25519）。此 remote URL 已固化在本地仓库，后续 push 无需再处理。不改全局 config，避免影响其他仓库。
+- **PowerShell 编码**：PowerShell 调子进程时需注入 `chcp 65001` + UTF8，但纯 Python 跨平台版不涉及此（Python3 默认 UTF-8）。此条仅对 bd.ps1 维护有意义。
+
+## 7. 发布 checklist
+
+### 已完成（v0.1.0 首发上线）
+- [x] 替换 `pyproject.toml` 中 `authors`、`project.urls` 占位（handle=Echoziness，邮箱用 GitHub noreply）
+- [x] 替换 README 徽章 / CHANGELOG 链接中的占位 handle
+- [x] GitHub 建仓库 `Echoziness/bili-dl`（PUBLIC）、推送 main、CI 三平台全绿
+- [x] 占位符清零扫描、敏感文件扫描（无 cookie/媒体进仓库）、lint/format/test 全绿
+
+### 待办（发 PyPI）
+- [ ] `pip install build && python -m build` 生成 dist（wheel + sdist）
+- [ ] `pip install twine && twine check dist/*` 通过
+- [ ] `twine upload --repository testpypi dist/*` 先发 TestPyPI，验证 `pipx install -i https://test.pypi.org/simple/ bili-dl` 能装能跑
+- [ ] 正式 `twine upload dist/*` 发 PyPI
+- [ ] 打 `v0.1.0` tag 并推送，触发 GitHub Release（`gh release create v0.1.0 --notes-from-tag`）

bili_dl-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial public release.
+- Three download modes: `all` (video+audio merged to MP4), `v` (video only),
+  `a` (audio only, M4A).
+- Cookie management: extract only `.bilibili.com` entries from a
+  `cookies_all.txt` Netscape export into a dedicated `cookies_bilibili.txt`,
+  with on-disk backup before overwrite.
+- Online Cookie validity check via the Bilibili `/x/web-interface/nav` API
+  with graceful degradation to local-only validation on network errors.
+- Audio container standardization via ffmpeg zero-copy remux
+  (`-c:a copy -movflags +faststart`) for both `all` and `a` paths —
+  produces `moov`-first ISOM containers friendly to foobar2000 and others.
+- Cross-platform path defaults (Windows Videos/Music, macOS Movies/Music,
+  XDG `~/.local/share/bili-dl` elsewhere).
+- Interactive REPL mode plus one-shot non-interactive mode (`bili-dl <URL>`).
+- CLI flags: `--all/-v/-a` modes, `--proxy`, `--insecure/-k`,
+  `--output-dir/--audio-dir`, `--cookie-dir`.
+- TLS certificate verification enabled by default; opt-out via `-k`.
+- MIT-licensed, zero runtime Python dependencies (stdlib only).
+
+### Fixed
+- nav API probe now sends a browser User-Agent; previously Bilibili returned
+  HTTP 412 to `Python-urllib/x.y` and the broad `except` silently degraded to
+  local-only validation, masking the real cause as a "network/SSL error".
+
+### Changed
+- `--version` is now exposed as `-V` (capital), since `-v` is taken by
+  `--video`. Matches yt-dlp / curl / pip convention.
+
+[Unreleased]: https://github.com/Echoziness/bili-dl/releases/tag/v0.1.0

bili_dl-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 bili-dl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+NOTE: This tool is a thin wrapper around yt-dlp (Unlicense) and ffmpeg
+(LGPL/GPL). Users must install those separately. Limitations or obligations
+imposed by those licenses on the binaries (e.g. ffmpeg's GPL build) may apply
+to the binaries you use but do not affect this wrapper's MIT license.

bili_dl-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: bili-dl
+Version: 0.1.0
+Summary: Cross-platform Bilibili video/audio downloader built on yt-dlp + ffmpeg.
+Project-URL: Homepage, https://github.com/Echoziness/bili-dl
+Project-URL: Repository, https://github.com/Echoziness/bili-dl
+Project-URL: Issues, https://github.com/Echoziness/bili-dl/issues
+Project-URL: Changelog, https://github.com/Echoziness/bili-dl/blob/main/CHANGELOG.md
+Author-email: Echoziness <217080389+Echoziness@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,bilibili,downloader,ffmpeg,video,yt-dlp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# bili-dl
+
+> Cross-platform Bilibili downloader — a thin, fast wrapper around `yt-dlp` + `ffmpeg`.
+
+[![CI](https://github.com/Echoziness/bili-dl/actions/workflows/ci.yml/badge.svg)](https://github.com/Echoziness/bili-dl/actions/workflows/ci.yml)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`bili-dl` is a small command-line tool for downloading Bilibili videos and
+audio with the best available quality (up to 1080p for non-premium accounts).
+It started life as a Windows PowerShell script (`bd.ps1`) and was rewritten in
+pure Python so the **same code runs unchanged on Windows, macOS and Linux**,
+with **zero runtime dependencies** (standard library only).
+
+It does one thing well: pick the right `yt-dlp` format, manage your Bilibili
+cookie safely, and standardise every audio file into a foobar2000-friendly
+container — all without re-encoding.
+
+---
+
+## Why
+
+- **Cookie-safe.** Drop a full-browser `cookies_all.txt` export next to the
+  tool and it extracts *only* the `.bilibili.com` entries into a dedicated
+  file. Cookies for every other site are never parsed, stored, or sent
+  anywhere.
+- **Cookie-verified.** Before downloading it pokes the Bilibili `nav` API to
+  confirm your session is actually logged in, falling back to a local check
+  when the network is unavailable.
+- **Audio you can actually play.** Both the "audio only" download and the
+  audio extracted from a video are routed through `ffmpeg -c:a copy
+  -movflags +faststart` — a zero-loss remux that produces a `moov`-first
+  ISOM container. foobar2000 and friends play it instantly without bitrate
+  quirks from Bilibili's raw mux.
+- **No quality downgrade bugs.** A scoping bug in the original PowerShell
+  version meant the cookie/referer args were silently dropped inside the
+  download function, quietly capping quality. The rewrite passes all options
+  explicitly, so this class of bug can't recur.
+- **Zero install footprint beyond the tools you already have.** No `pip`
+  dependencies, no `requests`, no `colorama` — just the standard library. If
+  you have Python installed, `pipx install bili-dl` is enough.
+
+---
+
+## Install
+
+`bili-dl` needs `yt-dlp` and `ffmpeg` on your `PATH`. Both are one-liners:
+
+```bash
+pip install -U yt-dlp      # or: winget install yt-dlp / brew install yt-dlp / pipx install yt-dlp
+# ffmpeg:
+winget install ffmpeg       # Windows
+brew install ffmpeg         # macOS
+sudo apt install ffmpeg     # Debian/Ubuntu
+```
+
+Then install bili-dl itself:
+
+```bash
+pipx install bili-dl        # recommended: isolated, exposes the `bili-dl` command
+# or, if you must:
+pip install bili-dl
+```
+
+Verify:
+
+```bash
+bili-dl --help
+bili-dl -V          # show version
+```
+
+---
+
+## Quick start
+
+### Cookies (one-time)
+
+Bilibili returns HTTP 412 to anonymous requests, so you need a login cookie.
+On Windows `yt-dlp --cookies-from-browser` can't read Chromium's App-Bound
+Encryption, so export manually:
+
+1. Install the [Get cookies.txt LOCALLY](https://microsoftedge.microsoft.com/addons/detail/get-cookies-txt-locally/ccpbcjjkcbiojbicneopklbjmhklbpca) Edge/Chrome extension.
+2. Log in to [bilibili.com](https://www.bilibili.com).
+3. Export **All Cookies** in Netscape format.
+4. Save as `cookies_all.txt` in the cookie directory (see below).
+5. Run `bili-dl` once — it extracts only the `.bilibili.com` entries into
+   `cookies_bilibili.txt` and reuses it thereafter.
+
+Cookie directory defaults to:
+
+| OS | Path |
+|---|---|
+| Windows | `%APPDATA%\bili-dl` |
+| macOS | `~/Library/Application Support/bili-dl` |
+| Linux | `~/.config/bili-dl` |
+
+Override with `--cookie-dir`.
+
+### Download
+
+```bash
+# interactive REPL — paste URLs, switch modes with all/v/a, quit with q
+bili-dl
+
+# one-shot
+bili-dl https://www.bilibili.com/video/BVxxxxxxxx
+
+# audio only → standalone, foobar2000-friendly M4A
+bili-dl -a https://www.bilibili.com/video/BVxxxxxxxx
+
+# video only (single-file MP4 when available)
+bili-dl -v https://www.bilibili.com/video/BVxxxxxxxx
+
+# through a proxy, skipping TLS verification for a self-signed environment
+bili-dl --proxy http://127.0.0.1:7890 -k https://www.bilibili.com/video/BVxxxxxxxx
+```
+
+Download destinations default to:
+
+| OS | Videos | Audio |
+|---|---|---|
+| Windows | `~/Videos/bilibili_videos` | `~/Music/bilibili_audio` |
+| macOS | `~/Movies/bilibili_videos` | `~/Music/bilibili_audio` |
+| Linux | `~/Downloads/bilibili_videos` | `~/.local/share/bili-dl/audio` |
+
+Override with `--output-dir` / `--audio-dir`.
+
+---
+
+## Modes
+
+| Mode | Flag | What it downloads | Container |
+|---|---|---|---|
+| **all** | `--all` (default) | best video + best audio, merged | MP4 + extracted M4A |
+| **video** | `-v` | video (single-file MP4 if a combined stream exists) | MP4 |
+| **audio** | `-a` | best audio stream | M4A (faststart ISOM) |
+
+In `all` mode the merged MP4 is kept in the videos directory **and** a
+zero-loss M4A is extracted to the audio directory. Both audio paths (direct
+download *and* extraction) go through the same ffmpeg remux, so they're
+byte-layout-identical.
+
+---
+
+## How audio standardisation works
+
+Bilibili serves DASH audio with `moov` at the tail and an `M4A` major brand.
+Some players (notably foobar2000) read bitrate metadata incorrectly or show
+a noticeable start delay. `bili-dl` runs:
+
+```
+ffmpeg -i in.m4a -map 0:a -c:a copy -map_metadata 0 -movflags +faststart out.m4a
+```
+
+`-c:a copy` means **no re-encode** — the AAC frames are copied verbatim, so
+bitrate (e.g. 201 kbps for the 203k stream) is preserved exactly. Only the
+container layout changes: `moov` moves to the front for instant playback, and
+the compatible brand set becomes `M4A isom iso2`. Net effect: same audio,
+friendlier file.
+
+---
+
+## Privacy
+
+- The cookie importer reads `cookies_all.txt` line by line and keeps **only**
+  lines containing `bilibili`. Lines for other domains are discarded in
+  memory; they're never written to disk or sent over the network.
+- The only network requests `bili-dl` makes go to `api.bilibili.com` (the
+  login probe) and the URLs you give it (via `yt-dlp`). No telemetry, no
+  analytics, no "phone home".
+- `cookies_bilibili.txt` is created with restrictive handling and a timestamped
+  backup is kept before any overwrite.
+
+---
+
+## Project layout
+
+```
+bili-dl/
+├── src/bili_dl/
+│   ├── __init__.py        # version
+│   ├── __main__.py        # python -m bili_dl
+│   ├── cli.py             # argparse + REPL entry point
+│   ├── config.py          # constants (endpoints, format strings, labels)
+│   ├── paths.py           # cross-platform path resolution (Win/mac/Linux)
+│   ├── cookies.py         # Netscape extraction + (online) validity check
+│   ├── ffmpeg.py          # ffmpeg discovery + zero-loss audio remux/extract
+│   ├── downloader.py      # yt-dlp two-phase download (predict + fetch)
+│   └── ui.py              # ANSI-colored output (enables VT on Windows)
+├── tests/                 # pytest: cookies, paths, package smoke
+├── pyproject.toml         # hatchling build, ruff, pytest config
+└── .github/workflows/ci.yml
+```
+
+---
+
+## Contributing
+
+`bili-dl` is MIT-licensed and welcomes contributions. The project uses
+`ruff` for lint/format and `pytest` for tests. Before sending a PR:
+
+```bash
+pip install -e . pytest ruff
+ruff check src tests
+ruff format --check src tests
+pytest
+```
+
+CI runs the same checks on Windows, macOS and Linux across Python 3.9–3.13.
+
+---
+
+## License
+
+[MIT](LICENSE). Note that `bili-dl` is a *wrapper*; the actual downloading is
+done by [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) (Unlicense) and
+[`ffmpeg`](https://ffmpeg.org) (LGPL/GPL). You must install those separately,
+and any obligations imposed by their licenses apply to those binaries — not
+to this wrapper's MIT license.