bangumi-frames

bangumi-frames — Bilibili 动画画面与角色整理工具

概述

提供一个 Bilibili 视频（bangumi ep 链接、UP 主上传的 BV 链接/ID，或本地 视频文件）；工具会下载视频 → 提取场景变化关键帧 → 区分背景画面与角色画面 → 整理角色裁剪图。一次处理，两种模式：

• 不使用 --ref（聚类模式） — 按 CCIP 身份对所有角色裁剪图分组，存入 characters/char_NN/。
• 使用 --ref DIR（一对多模式） — 提供一个角色的参考文件夹，将视频中所有匹配的 裁剪图提取到 matched/，文件名以距离为前缀（最接近的排在最前），因此设置较严格的阈值可得到纯净结果集。

模型专为动画设计（deepghs 动画人物检测 + CCIP 角色身份嵌入），不适用于真人影像。

适用场景 / 不适用场景

• 适用：用户想按角色或背景画面收集、提取、整理 Bilibili 视频中的动画画面或截图，或提取某个特定人物。
• 不适用：真人视频（需要使用 insightface 人脸处理方案），或通用视频编辑、剪辑、转码。

随附资源

资源	阅读时机
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）与模式 2 一对多（--ref-eps、距离区间直方图、压缩嵌入阈值说明）；完整输出布局
scripts/bangumi_frames.py	入口脚本（包含所有处理阶段和两种模式）
scripts/remove_overlay.py	对帧目录或单张图片独立执行字幕/水印去除

前置条件

1. PATH 中需有 ffmpeg；下载时 PATH 中需有 yt-dlp（输入本地文件时会跳过下载）。
2. Python 3.9+，并运行 pip install dghs-imgutils（首次运行会从 HuggingFace 下载约 300 MB 的模型，随后缓存在本地）。
3. Bilibili cookie（Netscape 格式的 cookies.txt）。读取顺序： --cookies > $BILIBILI_COOKIES > ~/bb_up/bb_cookies/www.bilibili.com_cookies.txt。 1080p+ / 大会员剧集需要包含会员权限的 cookie；如果只下载到试看内容，说明该 cookie 无权访问此剧集。输入本地文件无需 cookie。
4. 在 CPU 上运行 CCIP 阶段 — 不要设置 ONNX_MODE=CoreML（CCIP 会崩溃；脚本会在聚类/匹配前将其移除）。人物检测可正常使用 CoreML。
5. （仅用于 --clean）pip install rapidocr-onnxruntime simple-lama-inpainting。
6. （仅用于 --engine pyscenedetect）pip install scenedetect。

用法

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

各处理阶段均为幂等（如果输出已存在，就会跳过该阶段；由于 CCIP 特征已缓存，聚类/匹配始终会重新运行）。有关所有标志、各阶段的权衡以及阈值说明，请阅读上述两个参考文件。

面向 Agent 的原生输出：stdout 是一个 JSON 封装（成功时为 {"ok", "data", "next", "meta"}，失败时为 {"ok": false, "error"} — 管道输出时为 JSON，在 TTY 上显示人类可读摘要；可用 --format 强制指定），stderr 输出人类可读的进度日志，退出码固定（0 成功 · 1 运行时错误 · 2 认证错误 · 3 验证错误）。使用 --dry-run 可在不下载的情况下预览计划，使用 --schema 可打印输出契约。详情见 references/pipeline.md。

输出

<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（模式 1）或 matched_montage.png（模式 2）判断效果，再读取 index.json。如果分组/匹配效果不理想，请参阅 references/modes.md 了解需要调整的设置。

限制

• 仅支持动漫 / 2.5D 渲染风格的画作；真人影视需要使用不同的人脸识别技术栈。
• CCIP 可能会将同一角色的不同形态（服装 / 变身）拆分为不同组 ——对于“按视觉外观分组”通常没问题；对于模式 2，请将每种形态都放入参考图中。
• 在 Bilibili 下载 1080p 及以上画质需要会员 Cookie；下载仅用于个人离线分析 ，不会上传任何内容。