bangumi-frames

bangumi-frames — Bilibili アニメフレーム・キャラクター整理ツール

概要

Bilibili の動画（bangumi の ep リンク、UP 主がアップロードした BV リンク／ID、またはローカル動画ファイル）を指定すると、ダウンロード → シーン切り替わりのキーフレームを抽出 → 背景とキャラクターのフレームに分類 → キャラクターの切り抜きを整理します。一度の実行で、2 つのモードに対応します。

• --ref なし（クラスターモード） — キャラクターの切り抜きを CCIP の識別情報ごとにグループ化し、characters/char_NN/ に保存します。
• --ref DIR を指定（1 対残りモード） — 1 人のキャラクターの参照フォルダーを指定すると、動画内で一致する切り抜きをすべて 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	2 つのモードの選択・調整時 — モード 1 のクラスタリング（--eps／--min-samples）とモード 2 の 1 対残り（--ref-eps、距離帯ヒストグラム、圧縮埋め込みのしきい値に関する知見）、出力レイアウト全体
scripts/bangumi_frames.py	エントリーポイント（全ステージ + 両モード）
scripts/remove_overlay.py	フレームディレクトリまたは単一画像に対する、字幕・透かしの単独除去

前提条件

1. ffmpeg が PATH にあること。ダウンロードする場合は yt-dlp も PATH にあること（ローカルファイル入力ではダウンロードをスキップします）。
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. CCIP のステップは CPU で実行してください — 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 の特徴量がキャッシュされるため、クラスタリング／照合は毎回再実行されます）。各フラグのステージごとのトレードオフや、しきい値に関する知見については、上記の 2 つのリファレンスファイルをお読みください。

エージェントネイティブな出力： 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が必要です。ダウンロードは個人的なオフライン分析のみを目的としており、アップロードは行いません。