Back to Details

bangumi-frames

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

bangumi-frames — Bilibili Anime Frame & Character Organizer

bangumi-frames — B站动漫帧与角色整理工具

Overview

概述

Give a Bilibili video (a bangumi 
ep
link, a UP-upload 
BV
link/id, or a local video file); it downloads → extracts scene-change keyframes → splits scenery vs character frames → organizes the character crops. One pass, two modes:
  • 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.
Models are anime-specific (deepghs anime person detection + CCIP character-identity embeddings) — they do not work on live-action footage.
输入B站视频（番剧
ep
链接、UP主上传的
BV
链接/ID，或是本地视频文件）；工具会依次完成下载→提取场景变化关键帧→区分风景帧与角色帧→整理角色截图的流程。一次运行，两种模式：
  • 无
    --ref
    参数（聚类模式）     —— 通过CCIP身份特征将所有角色截图分组到
    characters/char_NN/
    目录下。
  • 带
    --ref DIR
    参数（一对一匹配模式）     —— 给定某个角色的参考文件夹，将视频中所有匹配该角色的截图提取到
    matched/
    目录，文件名前缀为匹配相似度距离（距离越近匹配度越高），设置严格阈值可得到纯净的目标角色集合。
所使用的模型为动漫专用（deepghs动漫人物检测模型 + CCIP角色身份嵌入模型）—— 不适用于真人实拍视频。

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.
  • 适用场景：用户需要从B站视频中收集/提取/整理动漫帧或截图，按角色、风景分类，或是提取特定角色。
  • 不适用场景：处理真人实拍视频（需使用insightface类人脸识别模型栈），或是进行通用视频剪辑/修剪/转码。

Bundled resources

内置资源

ResourceRead it when
references/pipeline.md
Tuning a stage — download (
--height
/
--prefer
), extract (
--scene
/
--interval
/
--dedup
/
--skip
), 
--clean
(OCR+LaMa subtitle/watermark removal), classify (
--conf
/
--min-area
); feature caching; the CPU/CoreML rule; 
--redo
references/modes.md
Choosing/tuning the two modes — mode 1 cluster (
--eps
/
--min-samples
) vs mode 2 one-vs-rest (
--ref-eps
, the distance-band histogram, the compressed-embedding threshold lore); full output layout
scripts/bangumi_frames.py
The entry point (all stages + both modes)
scripts/remove_overlay.py
Standalone subtitle/watermark removal on a frame dir or single image
资源阅读时机
references/pipeline.md
调整各阶段参数时——下载（
--height
/
--prefer
）、提取（
--scene
/
--interval
/
--dedup
/
--skip
）、
--clean
（OCR+LaMa字幕/水印移除）、分类（
--conf
/
--min-area
）；特征缓存；CPU/CoreML规则；
--redo
参数说明
references/modes.md
选择/调整两种模式时——模式1聚类（
--eps
/
--min-samples
） vs 模式2一对一匹配（
--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
    .
  1. 系统PATH中需包含
    ffmpeg
    ；下载功能需PATH中包含
    yt-dlp
    （输入本地文件时跳过下载步骤）。
  2. Python 3.9+版本，执行
    pip install dghs-imgutils
    （首次运行会从HuggingFace下载约300MB的模型，之后会缓存到本地）。
  3. B站Cookie（Netscape格式的
    cookies.txt
    ）。分辨率优先级：
    --cookies
    参数 > 
    $BILIBILI_COOKIES
    环境变量 > 
    ~/bb_up/bb_cookies/www.bilibili.com_cookies.txt
    文件。1080p+清晰度或付费剧集需要带有会员权限的Cookie；若仅能下载预览版，说明Cookie无对应剧集的访问权限。输入本地文件无需Cookie。
  4. CCIP步骤需在CPU上运行——不要设置
    ONNX_MODE=CoreML
    （CCIP会崩溃；脚本在聚类/匹配前会自动禁用该设置）。人物检测可正常使用CoreML。
  5. （仅使用
    --clean
    参数时）需执行
    pip install rapidocr-onnxruntime simple-lama-inpainting
    。
  6. （仅使用
    --engine pyscenedetect
    参数时）需执行
    pip install scenedetect
    。

Usage

使用方法

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

Mode 1 — cluster everyone into char_NN groups

模式1 —— 将所有角色聚类到char_NN分组

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
python3 $SKILL https://www.bilibili.com/video/BV15qVm68E2h --out ~/frames python3 $SKILL ep1231575 --out ~/frames # 支持ep/BV ID格式 python3 $SKILL ~/local.mp4 --out ~/frames # 本地文件，跳过下载步骤

Mode 2 — pull out ONE character (ref folder = ~200 crops of that character)

模式2 —— 提取指定角色（参考文件夹需包含约200张该角色的截图）

python3 $SKILL BV15qVm68E2h --ref ~/refs/紫灵 --ref-eps 0.04 --out ~/frames
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

Stages are idempotent (a stage is skipped when its output already exists; clustering /
matching always re-runs since the CCIP features are cached). For every flag, the per-stage
trade-offs, and the threshold lore, read the two reference files above.

**Agent-native output:** `stdout` is a single JSON envelope (`{"ok", "data", "next", "meta"}`
on success, `{"ok": false, "error"}` on failure — JSON when piped, a human summary on a TTY;
force with `--format`), `stderr` carries human progress logs, and exit codes are stable
(`0` ok · `1` runtime · `2` auth · `3` validation). Use `--dry-run` to preview the plan
without downloading, `--schema` to print the output contract. Details in `references/pipeline.md`.
python3 $SKILL ep1231575 --clean --out ~/frames

各阶段具有幂等性（若阶段输出已存在则跳过该阶段；聚类/匹配步骤会始终重新运行，因为CCIP特征已缓存）。关于所有参数、各阶段的权衡以及阈值说明，请阅读上述两个参考文件。

**Agent原生输出：** 成功时`stdout`为单个JSON包（`{"ok", "data", "next", "meta"}`），失败时为`{"ok": false, "error"}`——管道输出时为JSON格式，终端输出时为人类可读的总结；可通过`--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}
After a run, look at 
characters/_montage.png
(mode 1) or 
matched_montage.png
(mode 2) first to judge quality, then read 
index.json
. See 
references/modes.md
for what to adjust when grouping/matching is off.
<out>/<id>/                     # id = BV ID / ep ID / 本地文件名
├── frames/  frames.json        # 关键帧 + 时间戳
├── scenery/                    # 未检测到角色的风景帧
├── crops/  features.npy        # 角色截图 + 缓存的CCIP特征
├── detect.json                 # 帧 -> 人物框/截图的映射
├── characters/                 # 模式1：char_NN_crop/ + char_NN_full/（配对目录）、_unsorted/、_montage.png
├── matched/                    # 模式2：0.012_<crop>.jpg（前缀为匹配距离） + index.json
├── matched_montage.png         # 模式2的示例拼接图
└── index.json                  # 模式1：角色分组 -> {截图, 帧, 时间}的映射
运行完成后，先查看
characters/_montage.png
（模式1）或
matched_montage.png
（模式2）判断结果质量，再查看
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.
  • 仅支持动漫/2.5D渲染作品；真人实拍视频需使用不同的（人脸识别）模型栈。
  • CCIP可能将同一角色的不同形态（服装/变身）分为不同分组——通常适用于“按视觉外观分组”的需求；若使用模式2，需将每个形态的截图放入参考文件夹。
  • B站1080p+清晰度视频需要会员Cookie；下载仅用于个人离线分析，不会上传任何内容。