bangumi-frames — Bilibili Anime Frame & Character Organizer

Overview

ep

BV

• no

  --ref

  (cluster mode) — group every character crop by CCIP identity into

  characters/char_NN/

  .
• with

  --ref DIR

  (one-vs-rest mode) — given ONE character's reference folder, pull every crop in the video that matches it into

  matched/

  , filenames prefixed with distance (closest first) so a tight threshold yields a pure set.

When to use / when NOT to use

• Use when the user wants to collect/extract/organize anime frames or screenshots from a Bilibili video — by character, by scenery, or to pull out one specific person.
• Don't use for live-action video (needs an insightface-class face stack instead), or for generic video editing/trimming/transcoding.

Bundled resources

references/pipeline.md

--height

--prefer

--scene

--interval

--dedup

--skip

--clean

--conf

--min-area

--redo

references/modes.md

--eps

--min-samples

--ref-eps

scripts/bangumi_frames.py

scripts/remove_overlay.py

Prerequisites

1. ffmpeg

   on PATH;

   yt-dlp

   on PATH for downloads (a local-file input skips download).
2. Python 3.9+,

   pip install dghs-imgutils

   (first run pulls ~300 MB of models from HuggingFace, then cached locally).
3. A Bilibili cookie (Netscape

   cookies.txt

   ). Resolution order:

   --cookies

   >

   $BILIBILI_COOKIES

   >

   ~/bb_up/bb_cookies/www.bilibili.com_cookies.txt

   . 1080p+ / premium episodes need a cookie with membership; a preview-only download means the cookie lacks access to that episode. Local-file input needs no cookie.
4. Run the CCIP step on CPU — do not set

   ONNX_MODE=CoreML

   (CCIP crashes; the script pops it before clustering/matching). Person detection is fine on CoreML.
5. (Only for

   --clean

   )

   pip install rapidocr-onnxruntime simple-lama-inpainting

   .
6. (Only for

   --engine pyscenedetect

   )

   pip install scenedetect

   .

Usage

SKILL=skills/bangumi-frames/scripts/bangumi_frames.py

# Mode 1 — cluster everyone into char_NN groups
python3 $SKILL https://www.bilibili.com/video/BV15qVm68E2h --out ~/frames
python3 $SKILL ep1231575 --out ~/frames           # ep / BV id also accepted
python3 $SKILL ~/local.mp4 --out ~/frames          # local file, skips download

# Mode 2 — pull out ONE character (ref folder = ~200 crops of that character)
python3 $SKILL BV15qVm68E2h --ref ~/refs/紫灵 --ref-eps 0.04 --out ~/frames

# Optional: strip burned-in subtitles + watermark before analysis
python3 $SKILL ep1231575 --clean --out ~/frames

stdout

{"ok", "data", "next", "meta"}

{"ok": false, "error"}

--format

stderr

0

1

2

3

--dry-run

--schema

references/pipeline.md

Output

<out>/<id>/                     # id = BV id / ep id / local filename
├── frames/  frames.json        # keyframes + timestamps
├── scenery/                    # frames with no detected character
├── crops/  features.npy        # character crops + cached CCIP features
├── detect.json                 # frame -> person boxes / crops
├── characters/                 # MODE 1: char_NN_crop/ + char_NN_full/ (paired), _unsorted/, _montage.png
├── matched/                    # MODE 2: 0.012_<crop>.jpg (distance-prefixed) + index.json
├── matched_montage.png         # MODE 2 sample montage
└── index.json                  # MODE 1: char group -> {crop, frame, time}

characters/_montage.png

matched_montage.png

index.json

references/modes.md

Limits

• Anime / 2.5D-render art only; live-action needs a different (face-recognition) stack.
• CCIP may split one character's different forms (outfit / transform) into separate groups — usually fine for "group by visual appearance"; for mode 2, put each form in the ref.
• 1080p+ on Bilibili needs a membership cookie; download is for personal offline analysis only and uploads nothing.