bilibili-source

# bilibili-source Fetch **real, verifiable** data for a Bilibili video so you can cite it instead of guessing. Engagement numbers are the backbone of any honest "why did this do well" analysis, and hand-typed or estimated numbers are the fastest way a knowledge base rots. This skill makes the numbers cheap to fetch — so there is no excuse to invent them. ## Quick start ```bash scripts/bili-fetch.sh BV1xxxxxxxxx ``` Returns one JSON object with everything from a single `view/detail` API call: ```json { "bvid": "BV1xxxxxxxxx", "aid": 1234567890, "fetched_at": "2026-06-07T13:54:17Z", "url": "https://www.bilibili.com/video/BV1xxxxxxxxx", "title": "<video title>", "up": { "name": "<UP name>", "mid": 12345678, "fans": 45600 }, "pubdate": "2026-01-10T00:50:47Z", "tname": "<partition, may be empty>", "tags": ["<tag>", "<tag>"], "videos": 1, "duration_s": 372, "stat": { "view": 48000, "like": 1200, "coin": 180, "favorite": 950, "share": 64, "reply": 210, "danmaku": 130 }, "pages": [ { "cid": 12345678, "page": 1, "part": "<part title>", "duration": 372 } ] } ``` `bili-fetch.sh` accepts any form a user might paste — **BVID, `av` number, `b23.tv` short link, or full URL** — and normalizes it. For multi-part videos it returns every part's `cid` in `pages[]` (you need the per-part cid to fetch that part's danmaku or subtitles). ## Scripts | Script | What it does | Login | |--------|--------------|-------| | `scripts/bili-fetch.sh <ref>` | Core: full metadata + live stats (run this first) | No | | `scripts/bili-danmaku.sh <ref> [P]` | Danmaku (bullet-comment) full text for a part | No | | `scripts/bili-subs.sh <ref> [browser]` | Subtitle/transcript track | **Yes** | | `scripts/bili-selftest.sh` | Test anonymous metadata, danmaku and selected API shapes | No | | `scripts/bili-access.py` | Diagnose identity, entitlement, subtitle shape and per-part media; replay/probe/verify-report | Explicit cookie file only | The shell fetch scripts **execute** (don't read them as reference). `bili-danmaku.sh` reuses `bili-fetch.sh` to resolve the part's cid, so they must stay siblings in `scripts/`. **Danmaku** are time-synced comments overlaid on the video — a Bilibili-specific signal of *where and how* viewers reacted, qualitatively richer than a flat reply count: ```bash scripts/bili-danmaku.sh BV1xxxxxxxxx # P1; add a part number for multi-part videos ``` ## Rules that keep the data honest - **Live metrics → always cite `fetched_at`.** The same video re-fetched minutes later drifts (a view count can tick up by a few within a single session). That is not an error — it is proof the data is live. A bare "12,000 views" with no timestamp is meaningless and silently goes stale. - **NO FABRICATION.** If a number can't be fetched, write "未获取/未核实" — never estimate. The whole point of the skill is that the number is cheap to fetch. - **The scripts already handle the network quirks** so you don't reinvent them: they strip the local proxy (Bilibili is a domestic CN service that a `127.0.0.1` proxy breaks), send a browser User-Agent + Referer (avoids the occasional HTTP 412), and retry with backoff. If you call the API by hand, do the same — see [references/bilibili_api.md](references/bilibili_api.md). One trap the env-strip does NOT cover: Python `urllib` falls back to the **macOS system proxy** when proxy env vars are absent, causing intermittent 503s in batches — build the opener with an explicit `ProxyHandler({})` (details in the reference's Request basics). - **CJK post-processing trap.** When you later grep/sort the fetched Chinese text or filenames, `sort`/`comm` mishandle CJK collation and report false "missing"/"broken" results. Verify with `find -name` or `grep -F`, not `comm`. ## Subtitles require login (no bypass) Stats and danmaku are login-free. **Subtitles are not.** Verified across many videos (new and old) plus anonymous cookies: the public player API returns an empty subtitle list for anonymous requests, and `yt-dlp` reports *"Subtitles are only available when logged in."* There is **no login-free path** — do not try to bypass it. `bili-subs.sh` therefore needs the user's Bilibili session via browser cookies. Because it reads their logged-in session, **ask the user before running it**: ```bash scripts/bili-subs.sh BV1xxxxxxxxx chrome # or firefox / safari / edge ``` The `ai-zh` track is Bilibili's AI-generated subtitle — treat it as a draft transcript (same-sound/segmentation errors), mark it as AI-ASR in whatever you produce, and don't claim it is a human-checked verbatim. If a video has no subtitle track, there is nothing to fetch — don't invent one. A SESSDATA-env API alternative is documented in the reference. ## Diagnose access before downloading or ASR Run `scripts/bili-access.py probe --bvid BV0000000000 --page 1` for an authorized source; add `--cookie-file <authorized-netscape-jar>` only when that account access is authorized. Never read arbitrary browser cookies through this diagnostic. Omit `--cid` to resolve the selected P from view metadata. Replay captured nav/view/player/playurl/ffprobe JSON offline when diagnosing existing evidence. Consume `download_allowed` before downloading; consume `asr_allowed` only after `verify-report` reads a fresh ffprobe of the actual ASR input. Keep authenticated identity separate from target payment entitlement: logged-in membership alone does not grant every creator's paid video. Stop on paid preview, denied or unknown entitlement; do not send a preview to full-content ASR. Compare duration with the selected CID/P, never the total multi-part duration. Read [the access diagnostic contract](references/bilibili_api.md#access-diagnostic-contract) for JSON states, commands and exits; run `uv run python -m unittest discover -s bilibili-source/tests -v` from the repository root for deterministic synthetic coverage. Inspect each `interfaces` entry's `http` and optional `error` before attributing a failure: HTTP 403/412 responses retain their status and do not imply a network failure or cookie expiry. Network errors, timeouts and invalid JSON have separate categories; these diagnostics do not establish payment rights. ## Going deeper For the full endpoint catalog (UP fan history, video tags, real-time viewer count, danmaku archive, the SESSDATA subtitle path, **favorites-folder enumeration** — `x/v3/fav/*`, login-gated, no WBI needed), the WBI request-signing algorithm needed for `space/wbi/*` endpoints, and every gotcha with a tested command, see **[references/bilibili_api.md](references/bilibili_api.md)**. ## Verified status - **Stats / metadata / danmaku** (`view/detail`, `relation/stat`, `dm/list.so`, `online/total`): verified login-free, 2026-06-07. Metrics re-fetched repeatedly and matched independently; danmaku count matched `stat.danmaku`. - **Subtitles**: confirmed login-gated, 2026-06-07 (empty for anonymous across all videos tested). Needs `yt-dlp` for the cookie path. The SESSDATA/cookie-jar API path verified logged-in 2026-08-29 across a ~400-video batch (multi-part included). - **Favorites** (`x/v3/fav/folder/created/list-all`, `x/v3/fav/resource/list`): verified logged-in 2026-08-29, plain params without WBI; 26 consecutive pages fetched without rate-limiting. Enumeration is login-gated (anonymous list-all answers code 0 with an empty list even for accounts with publicly-readable folders); a public folder's contents are anonymously readable only if you already know its media_id. ## Maintenance This skill wraps a third-party API that drifts over time — fields get renamed, endpoints add WBI signing, anti-bot tightens. Before trusting it after a gap, or whenever output looks wrong, run the health-check: ```bash scripts/bili-selftest.sh ``` It tests anonymous metadata, danmaku and selected endpoint shapes against a public fixture and prints PASS/FAIL rows. It does not test authenticated retrieval, target payment rights or media completeness; a pass only covers the printed checks — not a silent wrong answer. When a row fails, the endpoint paths, field names, and WBI signing needed to fix it are in [references/bilibili_api.md](references/bilibili_api.md); update the "Verified" dates above once you re-confirm.