Metadata-Version: 2.4
Name: bili23-cli
Version: 0.2.2
Summary: Headless CLI for downloading Bilibili videos — reuses the Bili23-Downloader GUI login session, no separate login required.
Project-URL: Homepage, https://github.com/1WorldCapture/bili23-cli
Project-URL: Repository, https://github.com/1WorldCapture/bili23-cli
Project-URL: Issues, https://github.com/1WorldCapture/bili23-cli/issues
Author: Lyon Liang
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: bili23,bilibili,bilibili-downloader,cli,video-downloader
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# bili23-cli

> Headless CLI for downloading Bilibili videos — **reuses the [Bili23-Downloader](https://github.com/ScottSloan/Bili23-Downloader) GUI login session**, so the CLI never asks you to log in.

Give it a Bilibili URL, get an `.mp4`. That's it.

```bash
bili23-cli "https://www.bilibili.com/video/BV1GE411Q7Ew/"
```

## Why this exists

The official [Bili23-Downloader](https://github.com/ScottSloan/Bili23-Downloader) is a Qt GUI app — great for clicking around, but not scriptable. The author's separate [CLI repo](https://github.com/ScottSloan/Bili23-Downloader-CLI) was last published to PyPI in **2022** and is now stale (missing modern Bilibili auth: Wbi signing, buvid/ticket cookies, etc.).

`bili23-cli` is a **modern, dependency-light rewrite** that:

- 🍪 **Reuses your GUI login** — reads the cookie the GUI already stored, so you get your account's quality (1080P / 4K / VIP) without logging in again.
- 🔐 **Implements current Bilibili auth** — Wbi signature (`w_rid`), full cookie set (SESSDATA / buvid3/4 / bili_ticket / …), correct UA & Referer.
- 🪶 **Minimal dependencies** — only [`httpx`](https://www.python-httpx.org/) + system `ffmpeg`. No PySide6 / Qt.
- 🧵 **Multi-threaded** — 4 MB chunked Range downloads.
- 🎛️ **Selectable quality / codec** — `-q 1080P -c HEVC`, or `auto` for best-available.

## Prerequisites

1. **The GUI app installed & logged in** — [Bili23-Downloader](https://github.com/ScottSloan/Bili23-Downloader/releases). Log in once; `bili23-cli` reads its session cookie.
   - This is how you get high quality. Anonymous use (`--no-cookie`) works but is limited to ~480P and some videos 403.
2. **ffmpeg** on your `PATH` (for merging audio + video):
   - macOS: `brew install ffmpeg`
   - Linux: `sudo apt install ffmpeg`
   - Windows: <https://ffmpeg.org/download.html>
3. **Python ≥ 3.9**.

## Installation

### As a standalone tool (recommended)

```bash
# with uv
uv tool install bili23-cli

# or with pipx
pipx install bili23-cli
```

This installs the `bili23-cli` command globally, in an isolated environment.

### From source

```bash
git clone https://github.com/1WorldCapture/bili23-cli.git
cd bili23-cli
uv tool install .     # or: pipx install .
```

## Usage

```bash
bili23-cli <URL-or-BVid> [options]
```

### Examples

```bash
# Simplest: download to current dir, auto best quality
bili23-cli "https://www.bilibili.com/video/BV1GE411Q7Ew/"

# Bare BV id works too
bili23-cli BV1GE411Q7Ew

# Choose quality + codec, output dir
bili23-cli BV1GE411Q7Ew -o ~/Downloads -q 1080P -c HEVC

# Multi-part video: pick part 3
bili23-cli "https://www.bilibili.com/video/BVxxxxx/" -p 3

# More threads
bili23-cli BV1GE411Q7Ew -t 16
```

### Options

| Option | Description |
|---|---|
| `url` | Bilibili video URL or bare BV id (positional) |
| `-o, --output DIR` | Output directory (default: current dir) |
| `-q, --quality` | `auto` / `8K` / `杜比视界` / `HDR` / `4K` / `1080P60` / `1080P+` / `1080P` / `720P` / `480P` / `360P` (default: `auto`) |
| `-c, --codec` | `auto` / `AVC` / `HEVC` / `AV1` (default: `auto`, prefers AVC > HEVC > AV1) |
| `-p, --page N` | Part number, 1-based (default: `1`) |
| `-t, --thread N` | Download threads (default: `8`) |
| `--no-merge` | Don't merge; keep `video.m4s` / `audio.m4s` |
| `--no-cookie` | Skip the GUI login cookie (anonymous; quality limited) |
| `--keep-parts` | Keep `.m4s` parts after merge |

## How it works

### Auth reuse (the key trick)

The GUI stores your login in (macOS) `~/Library/Application Support/Bili23 Downloader/config.json` under the `Cookie` key. `bili23-cli` reads it and rebuilds the exact cookie dict the GUI sends — including `SESSDATA`, `bili_jct`, `buvid3/4`, `bili_ticket`, and the `CURRENT_FNVAL=4048` flag — so the CLI looks indistinguishable from the GUI to Bilibili's servers.

On each run it also calls `/x/web-interface/nav` to fetch fresh **Wbi signing keys** (`img_key` / `sub_key`) — it does **not** trust the cached values, which silently expire.

### Download pipeline

Only two API calls are needed:

1. `GET /x/web-interface/wbi/view?bvid=…` (+ Wbi sig) → title, `cid`, parts
2. `GET /x/player/wbi/playurl?bvid=…&cid=…&qn=…&fnval=4048&fourk=1` (+ Wbi sig) → DASH `video[]` / `audio[]` CDN URLs

Then: multi-threaded Range download of `video.m4s` + `audio.m4s`, followed by `ffmpeg -c copy` into `.mp4`.

See [`docs/research-notes.md`](docs/research-notes.md) for the full reverse-engineering writeup of the GUI's internals.

## Scope (v0.1)

**Supported:** user-uploaded videos (BV/av) — parse, quality/codec selection, multi-threaded download, merge.

**Not yet:** bangumi / movies / courses / audio / favorites (different APIs), danmaku / subtitles / cover / metadata, batch download, cross-process resume, login flow (by design — reuse the GUI).

## Acknowledgements

This project is an independent CLI companion to — and **not affiliated with** — [ScottSloan/Bili23-Downloader](https://github.com/ScottSloan/Bili23-Downloader). The auth and download logic is a clean-room reimplementation based on studying that project's source.

Bilibili is a trademark of Shanghai Kuoyu Network Technology Co., Ltd. This tool is for personal use; please respect Bilibili's Terms of Service and copyright.

## License

[GPL-3.0](LICENSE)
