Skip to content

HK-hub/AgentSkills / bangumi-frames

bangumi-frames

Verified

Extract and organize frames from a Bilibili video (bangumi episode, UP upload, or a local file) into scenery shots and per-character image groups, using anime-specific person detection + CCIP character-identity embeddings. Two modes — cluster everyone, or pull out one (or several) named characters via reference folders. Use when the user wants to collect, extract, or organize anime frames/screenshots by character or by scenery from a Bilibili video. Read-only download for personal viewing/analysis; uploads nothing.

FileKindSize
SKILL.mdskill md7.1 KB
references/modes.mdmarkdown4.5 KB
references/pipeline.mdmarkdown6.8 KB
scripts/bangumi_frames.pyscript36.3 KB
scripts/remove_overlay.pyscript5.3 KB

scripts/bangumi_frames.py

View on GitHub
#!/usr/bin/env python3
"""Organize frames of a Bilibili video (bangumi episode, UP upload, or a local
file) into scenery shots and per-character image groups, using anime-specific
models.

ONE pass, TWO modes:
    no  --ref : unsupervised — cluster every crop by CCIP identity into char_NN
    with --ref: one-vs-rest — pull every crop matching a reference into matched/
                (filenames distance-prefixed, closest first). A ref folder of
                *.jpg = ONE character -> matched/; a ref folder of per-character
                subfolders = each character -> matched/<name>/

Agent-native contract (see agent-native-design):
    stdout : a single JSON envelope — {"ok": true, "data": {...}, "meta": {...}}
             on success, {"ok": false, "error": {...}} on failure. Auto-detected:
             JSON when stdout is not a TTY, a human summary when it is; override
             with --format json|table.
    stderr : human-readable progress logs (liveness for long runs).
    exit   : 0 ok · 1 runtime · 2 auth · 3 validation.
    --dry-run previews the plan without downloading or running models.
    --schema prints the output-envelope schema and exits.

Pipeline (each stage skipped when its output already exists):
    download  yt-dlp pulls the video-only stream (skipped for a local file)
    extract   ffmpeg scene-change keyframes + perceptual-hash dedup
    clean     (--clean) OCR-locate subtitles + watermark, LaMa-inpaint them out
    classify  anime person detection -> scenery/ vs character crops
    cluster / match   CCIP identity embeddings -> characters/ or matched/

Cookie resolution: --cookies > $BILIBILI_COOKIES > ~/bb_up/bb_cookies/www.bilibili.com_cookies.txt
Run the CCIP step on CPU (do NOT set ONNX_MODE=CoreML — CCIP crashes there).
"""
import argparse, json, os, re, shutil, subprocess, sys, time
from pathlib import Path

from PIL import Image, ImageDraw, ImageFont

HOME = Path.home()
DEFAULT_COOKIES = HOME / "bb_up" / "bb_cookies" / "www.bilibili.com_cookies.txt"
SCHEMA_VERSION = "0.5.0"
# stable exit codes (agent-native-design: documented, distinct per failure class)
EXIT_OK, EXIT_RUNTIME, EXIT_AUTH, EXIT_VALIDATION = 0, 1, 2, 3


class CliError(Exception):
    """A failure with a machine-routable code + stable exit code."""
    def __init__(self, code, message, exit_code=EXIT_RUNTIME, retryable=False):
        super().__init__(message)
        self.code, self.message = code, message
        self.exit_code, self.retryable = exit_code, retryable


def log(msg):
    # human channel — never pollutes the stdout JSON envelope
    print(msg, file=sys.stderr, flush=True)


# ----------------------------------------------------------------- input
def ep_id(url):
    m = re.search(r"(ep\d+|BV[0-9A-Za-z]+)", url)
    return m.group(1) if m else re.sub(r"\W+", "_", url)[-40:]


def full_url(arg):
    if arg.startswith("http"):
        return arg
    if arg.startswith("ep"):
        return f"https://www.bilibili.com/bangumi/play/{arg}"
    if arg.startswith("BV"):
        return f"https://www.bilibili.com/video/{arg}"
    raise CliError("validation_error",
                   f"cannot resolve input to a bilibili URL / BV / ep / local file: {arg}",
                   EXIT_VALIDATION)


def resolve_input(arg):
    """A local video file stays local (download skipped); anything else is a
    bilibili URL / BVxxxx / epNNN to fetch."""
    p = Path(arg).expanduser()
    if p.is_file():
        return "file", p
    return "url", full_url(arg)


# ---------------------------------------------------------------- download
def stage_download(url, wd, cookies, height, prefer="size"):
    # only a COMPLETE file counts as already-downloaded; an interrupted
    # yt-dlp leaves video.mp4.part, which must NOT be mistaken for the video
    # (else extract runs on a truncated file) — yt-dlp resumes .part itself
    vids = [v for v in wd.glob("video.*") if v.suffix != ".part"]
    if vids:
        return vids[0]
    if not Path(cookies).exists():
        log(f"[download] warning: cookie file not found ({cookies}); "
            f"premium / 1080p+ episodes may download as preview only")
    log(f"[download] {url} (<= {height}p, video only, prefer SDR/{prefer})")
    # prefer SDR (HDR/PQ frames come out gray/washed as JPEG). among equal-res
    # SDR streams: 'size' picks the smallest (HEVC, ~half the bytes, sharp
    # enough at 4K for crops); 'bitrate' picks the largest (AVC, marginally
    # sharper). default 'size' to match the disk-saving 4K-HEVC strategy.
    sort = "+size" if prefer == "size" else "br"
    # route yt-dlp's stdout to OUR stderr so it stays in the human channel and
    # never pollutes the stdout JSON envelope (agent-native: stdout = JSON only)
    r = subprocess.run(["yt-dlp", "--cookies", cookies, "--no-playlist",
                        "-f", "bv*/b", "-S", f"res:{height},hdr:SDR,{sort}",
                        "-o", str(wd / "video.%(ext)s"), url],
                       stdout=sys.stderr, env={**os.environ, "LC_ALL": "C"})
    if r.returncode != 0:
        raise CliError("download_error",
                       f"yt-dlp failed (exit {r.returncode}); check cookies / access",
                       EXIT_RUNTIME, retryable=True)
    vids = list(wd.glob("video.*"))
    if not vids:
        raise CliError("download_error", "yt-dlp produced no video file",
                       EXIT_RUNTIME, retryable=True)
    return vids[0]


# ----------------------------------------------------------------- extract
def dhash(path, size=8):
    img = Image.open(path).convert("L").resize((size + 1, size))
    px = list(img.getdata())
    bits = 0
    for r in range(size):
        for c in range(size):
            bits = (bits << 1) | (px[r * (size + 1) + c] > px[r * (size + 1) + c + 1])
    return bits


def _extract_ffmpeg(video, frames_dir, scene_thr, interval, skip):
    """ffmpeg scene-cut selection -> ordered [(Path, timestamp)]."""
    sel = f"gt(scene,{scene_thr})"
    if interval:
        # also keep a frame every N seconds so long takes are covered
        sel += f"+isnan(prev_selected_t)+gte(t-prev_selected_t,{interval})"
    for a, b in skip:
        # exclude OP/ED time ranges
        sel = f"({sel})*not(between(t,{a},{b}))"
    proc = subprocess.run(
        ["ffmpeg", "-hide_banner", "-i", str(video),
         "-vf", f"select='{sel}',showinfo",
         "-fps_mode", "vfr", "-q:v", "2", str(frames_dir / "%05d.jpg")],
        capture_output=True, text=True, env={**os.environ, "LC_ALL": "C"})
    times = re.findall(r"pts_time:([0-9.]+)", proc.stderr)
    files = sorted(frames_dir.glob("*.jpg"))
    if not files:
        raise CliError("extract_error",
                       f"ffmpeg produced no frames:\n{proc.stderr[-2000:]}",
                       EXIT_RUNTIME)
    return [(f, float(times[i]) if i < len(times) else None)
            for i, f in enumerate(files)]


def _extract_pyscenedetect(video, frames_dir, threshold, skip):
    """PySceneDetect ContentDetector -> one mid-scene frame per scene, ordered
    [(Path, timestamp)]. Heavier, but its adaptive content metric is more robust
    on fades/dissolves than the raw ffmpeg `scene` score. Lazy import; needs
    `pip install scenedetect`. Threshold is on PySceneDetect's ~0-100 scale
    (default 27), NOT ffmpeg's 0-1 --scene."""
    try:
        from scenedetect import open_video, SceneManager, ContentDetector
    except ImportError:
        raise CliError("dependency_error",
                       "--engine pyscenedetect needs `pip install scenedetect`",
                       EXIT_VALIDATION)
    import cv2
    sm = SceneManager()
    sm.add_detector(ContentDetector(threshold=threshold))
    sm.detect_scenes(open_video(str(video)), show_progress=False)
    scenes = sm.get_scene_list()
    if not scenes:
        raise CliError("extract_error",
                       "PySceneDetect found no scene cuts (try a lower --pyscene-threshold)",
                       EXIT_RUNTIME)
    cap = cv2.VideoCapture(str(video))
    out = []
    for i, (start, end) in enumerate(scenes):
        mid = (start.get_seconds() + end.get_seconds()) / 2
        if any(a <= mid <= b for a, b in skip):     # exclude OP/ED ranges
            continue
        cap.set(cv2.CAP_PROP_POS_MSEC, mid * 1000)
        ok, im = cap.read()
        if not ok:
            continue
        f = frames_dir / f"{i:05d}.jpg"
        cv2.imwrite(str(f), im, [cv2.IMWRITE_JPEG_QUALITY, 95])
        out.append((f, round(mid, 3)))
    cap.release()
    if not out:
        raise CliError("extract_error", "PySceneDetect produced no frames", EXIT_RUNTIME)
    return out


def stage_extract(video, wd, scene_thr, interval, dedup, skip=(),
                  engine="ffmpeg", pyscene_thr=27.0):
    meta = wd / "frames.json"
    sig = wd / ".frames.sig"
    # extraction params (engine + thresholds + skip ranges) are the cache key,
    # so changing any of them re-extracts instead of reusing stale frames
    want = json.dumps([engine, scene_thr, pyscene_thr, interval, dedup,
                       sorted([list(r) for r in skip])], sort_keys=True)
    if meta.exists() and sig.exists() and sig.read_text() == want:
        return json.load(open(meta))
    frames_dir = wd / "frames"
    shutil.rmtree(frames_dir, ignore_errors=True)
    frames_dir.mkdir()
    if engine == "pyscenedetect":
        log(f"[extract] engine=pyscenedetect threshold={pyscene_thr}")
        cand = _extract_pyscenedetect(video, frames_dir, pyscene_thr, skip)
    else:
        log(f"[extract] engine=ffmpeg scene={scene_thr} interval={interval}s")
        cand = _extract_ffmpeg(video, frames_dir, scene_thr, interval, skip)

    # shared perceptual-hash dedup (drops near-identical consecutive frames)
    frames, last = {}, None
    for f, ts in cand:
        h = dhash(f)
        if last is not None and dedup and bin(h ^ last).count("1") <= dedup:
            f.unlink()
            continue
        last = h
        frames[f.name] = ts
    json.dump(frames, open(meta, "w"), indent=1)
    sig.write_text(want)
    # frames just changed -> any cached detection/features are stale
    (wd / "detect.json").unlink(missing_ok=True)
    (wd / "features.npy").unlink(missing_ok=True)
    log(f"[extract] kept {len(frames)}/{len(cand)} keyframes")
    return frames


# ------------------------------------------------------------------- clean
def stage_clean(wd, frames, sub_band, min_conf, no_watermark):
    """Remove burned-in subtitles + the bilibili watermark from frames/ in
    place, so every downstream crop is clean. OCR locates subtitle text; the
    semi-transparent corner logo is masked by a fixed box; holes are filled by
    LaMa. Idempotent: a signature marker over the (param, frame-set) pair skips
    frames already cleaned, and re-extraction wipes frames/ so the marker is
    naturally invalidated. Heavy deps (rapidocr + torch/LaMa) load lazily and
    are only needed when --clean is passed.
    """
    import cv2
    sys.path.insert(0, str(Path(__file__).resolve().parent))
    import remove_overlay as ro
    sig = wd / ".frames.clean.sig"
    want = json.dumps([round(sub_band, 3), round(min_conf, 3), no_watermark,
                       sorted(frames)], sort_keys=True)
    if sig.exists() and sig.read_text() == want:
        return False
    frames_dir = wd / "frames"
    log(f"[clean] removing subtitles/watermark from {len(frames)} frames")
    n_sub = 0
    for i, name in enumerate(sorted(frames), 1):
        path = frames_dir / name
        im = cv2.imread(str(path))
        if im is None:
            continue
        mask, boxes = ro.build_mask(im, sub_band=sub_band, min_conf=min_conf,
                                    pad=8, wm_h=0.14, wm_w=0.18,
                                    no_watermark=no_watermark)
        n_sub += len(boxes)
        if mask.any():
            cv2.imwrite(str(path), ro.inpaint(im, mask))
        if i % 25 == 0:
            log(f"[clean] {i}/{len(frames)} frames")
    sig.write_text(want)
    log(f"[clean] done: {n_sub} subtitle box(es) across {len(frames)} frames")
    return True


# ---------------------------------------------------------------- classify
def stage_classify(wd, frames, conf, min_area):
    det_meta = wd / "detect.json"
    if det_meta.exists():
        return json.load(open(det_meta))
    from imgutils.detect import detect_person
    scenery, crops_dir = wd / "scenery", wd / "crops"
    for d in (scenery, crops_dir):
        shutil.rmtree(d, ignore_errors=True)
        d.mkdir()
    records, n = {}, 0
    for name in sorted(frames):
        path = wd / "frames" / name
        img = Image.open(path)
        W, H = img.size
        boxes = [(b, s) for b, _, s in detect_person(path)
                 if s >= conf and (b[2] - b[0]) * (b[3] - b[1]) >= min_area * W * H]
        if not boxes:
            shutil.copy2(path, scenery / name)
            records[name] = []
        else:
            entry = []
            for i, (b, s) in enumerate(boxes):
                # pad the person box slightly so CCIP sees full silhouettes
                px, py = int((b[2] - b[0]) * 0.08), int((b[3] - b[1]) * 0.08)
                box = (max(b[0] - px, 0), max(b[1] - py, 0),
                       min(b[2] + px, W), min(b[3] + py, H))
                crop = f"{path.stem}_p{i}.jpg"
                img.crop(box).save(crops_dir / crop, quality=92)
                entry.append({"crop": crop, "box": list(map(int, box)),
                              "score": round(float(s), 3)})
            records[name] = entry
        n += 1
        if n % 25 == 0:
            log(f"[classify] {n}/{len(frames)} frames")
    json.dump(records, open(det_meta, "w"), indent=1)
    n_scenery = sum(1 for v in records.values() if not v)
    log(f"[classify] scenery {n_scenery} | frames with characters "
        f"{len(records) - n_scenery} | crops {sum(map(len, records.values()))}")
    return records


# ----------------------------------------------------------- CCIP features
def load_features(wd, crops_dir, crops):
    """Cached CCIP feature matrix for crops/, rows in sorted-crop-name order.
    Re-used across cluster/match so re-running with a different threshold is
    instant. CCIP crashes under CoreML, so this path runs on CPU."""
    import numpy as np
    fp = wd / "features.npy"
    if fp.exists():
        feats = np.load(fp)
        if len(feats) == len(crops):
            return feats
    from imgutils.metrics import ccip_batch_extract_features
    log(f"[ccip] embedding {len(crops)} crops (CPU)")
    feats = np.asarray(ccip_batch_extract_features([str(crops_dir / c) for c in crops]))
    np.save(fp, feats)
    return feats


# ------------------------------------------------------------------ montage
def montage(groups, crops_dir, out_path, thumb=160, per_row=10):
    # default PIL font can't render CJK; load a system CJK TTF so labels show
    font = None
    for fp in ("/System/Library/Fonts/PingFang.ttc",
               "/System/Library/Fonts/STHeiti Medium.ttc"):
        if Path(fp).exists():
            try:
                font = ImageFont.truetype(fp, 14)
                break
            except OSError:
                pass
    rows = []
    for label, names in groups:
        ims = [Image.open(crops_dir / n) for n in names[:per_row]]
        ims = [im.resize((int(im.width * thumb / im.height), thumb)) for im in ims]
        row = Image.new("RGB", (sum(im.width for im in ims) + 4 * len(ims), thumb + 22),
                        "white")
        x = 2
        for im in ims:
            row.paste(im, (x, 22))
            x += im.width + 4
        ImageDraw.Draw(row).text((4, 4), f"{label} ({len(names)} crops)",
                                 fill="black", font=font)
        rows.append(row)
    W = max(r.width for r in rows)
    sheet = Image.new("RGB", (W, sum(r.height for r in rows)), "white")
    y = 0
    for r in rows:
        sheet.paste(r, (0, y))
        y += r.height
    sheet.save(out_path)


# ---------------------------------------------- mode 1: unsupervised cluster
def mode_cluster(wd, frames, records, eps, min_samples):
    os.environ.pop("ONNX_MODE", None)  # CCIP crashes under CoreML — force CPU
    import numpy as np
    from imgutils.metrics import ccip_batch_differences
    from sklearn.cluster import AgglomerativeClustering
    crops_dir = wd / "crops"
    crop2frame = {e["crop"]: f for f, ents in records.items() for e in ents}
    crops = sorted(crop2frame)
    char_root = wd / "characters"
    shutil.rmtree(char_root, ignore_errors=True)
    char_root.mkdir()
    if not crops:
        log("[cluster] no character crops found")
        json.dump({}, open(wd / "index.json", "w"))
        return {"mode": "cluster", "characters": [], "unsorted": 0,
                "characters_dir": str(char_root), "montage": None,
                "index": str(wd / "index.json")}
    feats = load_features(wd, crops_dir, crops)

    # average-linkage resists the chain-merging DBSCAN suffers from on this
    # compressed 3DCG embedding; 0.10 keeps distinct characters apart (over-
    # splitting one character is harmless, merging two is not).
    if len(crops) >= 2:
        diffs = ccip_batch_differences(list(feats))
        log(f"[cluster] agglo eps={eps:.3f} over {len(crops)} crops")
        labels = AgglomerativeClustering(
            n_clusters=None, distance_threshold=eps,
            metric="precomputed", linkage="average").fit_predict(diffs)
    else:
        labels = [0]

    clusters = {}
    for i, lb in enumerate(labels):
        clusters.setdefault(int(lb), []).append(i)
    big = sorted((idx for idx in clusters.values() if len(idx) >= min_samples),
                 key=len, reverse=True)
    small = [i for idx in clusters.values() if len(idx) < min_samples for i in idx]

    index, groups = {}, []
    for ci, idx in enumerate(big, 1):
        names = [crops[i] for i in idx]
        cname = f"char_{ci:02d}"
        # crops and their source frames go to SEPARATE sibling folders
        # (char_NN_crop / char_NN_full) so each kind can be browsed on its own
        cropdir = char_root / f"{cname}_crop"
        fulldir = char_root / f"{cname}_full"
        cropdir.mkdir()
        fulldir.mkdir()
        items = []
        for n in names:
            shutil.copy2(crops_dir / n, cropdir / n)
            src = crop2frame[n]
            full = fulldir / src           # full frame keeps its own name (deduped)
            if not full.exists():
                shutil.copy2(wd / "frames" / src, full)
            items.append({"crop": n, "frame": src, "time": frames.get(src)})
        index[cname] = items
        groups.append((cname, names))
    if small:
        udir = char_root / "_unsorted"
        udir.mkdir()
        for i in small:
            shutil.copy2(crops_dir / crops[i], udir / crops[i])
        index["_unsorted"] = [{"crop": crops[i], "frame": crop2frame[crops[i]],
                               "time": frames.get(crop2frame[crops[i]])}
                              for i in small]
    montage_path = None
    if groups:
        montage_path = char_root / "_montage.png"
        montage(groups, crops_dir, montage_path)
    json.dump(index, open(wd / "index.json", "w"), indent=1)
    log(f"[cluster] {len(groups)} characters | unsorted {len(small)} "
        f"-> {char_root} (review _montage.png)")
    return {"mode": "cluster",
            "characters": [{"name": c, "crops": len(n)} for c, n in groups],
            "unsorted": len(small), "characters_dir": str(char_root),
            "montage": str(montage_path) if montage_path else None,
            "index": str(wd / "index.json")}


# -------------------------------------------- mode 2: one-vs-rest ref match
BANDS = [0.04, 0.06, 0.08, 0.10, 0.12, 0.16, 0.20]


def _match_one(ref_imgs, ref_eps, crops, crop2frame, crops_dir, feats, frames,
               out, montage_path):
    """Pull every crop within ref_eps of the ref prototype set into `out`,
    distance-prefixed. Returns the per-ref result dict (no 'mode' key)."""
    import numpy as np
    from imgutils.metrics import (ccip_batch_extract_features,
                                  ccip_batch_differences)
    shutil.rmtree(out, ignore_errors=True)
    out.mkdir(parents=True)
    if not crops:
        json.dump([], open(out / "index.json", "w"))
        return {"prototypes": len(ref_imgs), "matched": 0,
                "bands": {f"{b:.2f}": 0 for b in BANDS},
                "matched_dir": str(out), "montage": None, "index": str(out / "index.json")}
    pfeats = [np.asarray(f) for f in
              ccip_batch_extract_features([str(p) for p in ref_imgs])]

    # per-crop MIN distance to the prototype set (no margin test — one class)
    N = len(crops)
    mind = np.full(N, 9.0, np.float32)
    CH = 4000
    for s in range(0, N, CH):
        e = min(s + CH, N)
        cross = ccip_batch_differences(list(feats[s:e]) + pfeats)[:e - s, e - s:]
        mind[s:e] = cross.min(axis=1)

    band_counts = {f"{b:.2f}": int((mind < b).sum()) for b in BANDS}
    order = list(np.argsort(mind))
    sel = [i for i in order if mind[i] < ref_eps]
    index = []
    for i in sel:
        n = crops[i]
        src = crop2frame[n]
        # distance prefix => a name-sorted browser shows closest matches first
        shutil.copy2(crops_dir / n, out / f"{mind[i]:.3f}_{n}")
        index.append({"dist": round(float(mind[i]), 4), "crop": n,
                      "frame": src, "time": frames.get(src)})
    json.dump(index, open(out / "index.json", "w"), ensure_ascii=False, indent=1)
    mp = None
    if sel:
        samp = sel[::max(1, len(sel) // 48)][:48]
        mp = montage_path
        montage([("matched", [crops[i] for i in samp])], crops_dir, mp)
    return {"prototypes": len(pfeats), "matched": len(sel), "bands": band_counts,
            "matched_dir": str(out), "montage": str(mp) if mp else None,
            "index": str(out / "index.json")}


def _load_crops_feats(wd, records):
    """crops_dir, crop2frame map, sorted crop names, and their cached features."""
    crops_dir = wd / "crops"
    crop2frame = {e["crop"]: f for f, ents in records.items() for e in ents}
    crops = sorted(crop2frame)
    feats = load_features(wd, crops_dir, crops) if crops else []
    return crops_dir, crop2frame, crops, feats


def mode_match(wd, frames, records, ref_imgs, ref_eps):
    os.environ.pop("ONNX_MODE", None)  # CCIP crashes under CoreML — force CPU
    crops_dir, crop2frame, crops, feats = _load_crops_feats(wd, records)
    log(f"[match] {len(ref_imgs)} ref prototypes vs {len(crops)} crops")
    out = wd / "matched"
    r = _match_one(ref_imgs, ref_eps, crops, crop2frame, crops_dir, feats, frames,
                   out, wd / "matched_montage.png")
    log("[match] distance bands (cumulative crops): "
        + " ".join(f"<{k}:{v}" for k, v in r["bands"].items()))
    log(f"[match] {r['matched']} crops < {ref_eps} -> {out} (distance-prefixed, closest first)")
    return {"mode": "match", "ref_eps": ref_eps, "crops_total": len(crops), **r}


def mode_match_multi(wd, frames, records, refs, ref_eps):
    """refs: {name: [ref jpgs]}. One matched/<name>/ per character, sharing the
    same crop features. Returns a match dict carrying a 'characters' list."""
    os.environ.pop("ONNX_MODE", None)  # CCIP crashes under CoreML — force CPU
    crops_dir, crop2frame, crops, feats = _load_crops_feats(wd, records)
    base = wd / "matched"
    shutil.rmtree(base, ignore_errors=True)
    base.mkdir(parents=True)
    chars = []
    for name in sorted(refs):
        out = base / name
        log(f"[match] {name}: {len(refs[name])} ref prototypes vs {len(crops)} crops")
        r = _match_one(refs[name], ref_eps, crops, crop2frame, crops_dir, feats, frames,
                       out, out / "_montage.png")
        log(f"[match] {name}: {r['matched']} crops < {ref_eps} -> {out}")
        chars.append({"name": name, **r})
    return {"mode": "match", "ref_eps": ref_eps, "crops_total": len(crops),
            "matched": sum(c["matched"] for c in chars),
            "matched_dir": str(base), "characters": chars}


# -------------------------------------------------------------- orchestration
def _next_hints(data):
    if data["mode"] == "cluster":
        if not data["characters"]:
            return ["no groups formed — lower --scene (more frames) or --min-samples"]
        return [f"review montage: {data['montage']}"] if data["montage"] else []
    if "characters" in data:                         # multi-character match
        hints = [f"review montages under {data['matched_dir']}/"]
        empty = [c["name"] for c in data["characters"] if not c["matched"]]
        if empty:
            hints.append(f"0 matches for {', '.join(empty)} — "
                         "raise --ref-eps (e.g. 0.06) or check those ref folders")
        return hints
    if not data["matched"]:
        return ["0 matches — raise --ref-eps (e.g. 0.06) or check the ref folder"]
    return [f"review montage: {data['montage']}"] if data["montage"] else []


def run(args):
    """Execute the pipeline; return the envelope body (without 'ok'/'meta').
    Raises CliError for any validation/runtime failure."""
    out = Path(args.out).expanduser()
    kind, val = resolve_input(args.input)            # boundary: input resolvable
    if kind == "file":
        wd = out / (re.sub(r"\W+", "_", val.stem)[:60] or "video")
    else:
        wd = out / ep_id(val)

    ref_imgs = None      # single-character: [ref jpgs]
    refs = None          # multi-character: {name: [ref jpgs]}
    if args.ref:                                     # boundary: ref has crops
        rd = Path(args.ref).expanduser()
        # subfolders present -> one character per subfolder; else whole dir = one
        subrefs = ({d.name: sorted(d.glob("*.jpg")) for d in sorted(rd.iterdir())
                    if d.is_dir()} if rd.is_dir() else {})
        subrefs = {n: v for n, v in subrefs.items() if v}
        if subrefs:
            refs = subrefs
        else:
            ref_imgs = sorted(rd.glob("*.jpg"))
            if not ref_imgs:
                raise CliError("validation_error",
                               f"--ref {rd}: no .jpg crops (directly or in subfolders)",
                               EXIT_VALIDATION)
    if args.ref_eps <= 0 or args.eps <= 0:           # boundary: sane thresholds
        raise CliError("validation_error", "--eps and --ref-eps must be > 0",
                       EXIT_VALIDATION)

    if args.dry_run:
        return {"dry_run": True, "would": {
            "mode": "match" if args.ref else "cluster",
            "engine": args.engine,
            "input_kind": kind, "resolved": str(val), "work_dir": str(wd),
            "download": kind != "file",
            "cookies": str(args.cookies) if kind != "file" else None,
            "ref": str(args.ref) if args.ref else None,
            "ref_characters": sorted(refs) if refs else None,
            "ref_eps": args.ref_eps if args.ref else None,
            "eps": None if args.ref else args.eps,
            "min_samples": None if args.ref else args.min_samples,
            "clean": args.clean,
            "output": str(wd / ("matched" if args.ref else "characters")),
        }}

    wd.mkdir(parents=True, exist_ok=True)
    if kind == "file":
        log(f"[input] local file {val} -> {wd}")
        video = val
    else:
        video = stage_download(val, wd, args.cookies, args.height, args.prefer)

    if args.redo == "extract":
        (wd / "frames.json").unlink(missing_ok=True)
        (wd / ".frames.sig").unlink(missing_ok=True)
        (wd / ".frames.clean.sig").unlink(missing_ok=True)
    if args.redo in ("extract", "classify"):
        (wd / "detect.json").unlink(missing_ok=True)
        (wd / "features.npy").unlink(missing_ok=True)

    skip = [tuple(map(float, r.split("-", 1))) for r in args.skip.split(",") if r]
    frames = stage_extract(video, wd, args.scene, args.interval, args.dedup, skip,
                           engine=args.engine, pyscene_thr=args.pyscene_threshold)
    if args.clean:
        if stage_clean(wd, frames, args.clean_band, args.clean_conf,
                       args.clean_no_watermark):
            (wd / "detect.json").unlink(missing_ok=True)
            (wd / "features.npy").unlink(missing_ok=True)
    records = stage_classify(wd, frames, args.conf, args.min_area)

    if refs is not None:
        mode_data = mode_match_multi(wd, frames, records, refs, args.ref_eps)
    elif ref_imgs is not None:
        mode_data = mode_match(wd, frames, records, ref_imgs, args.ref_eps)
    else:
        mode_data = mode_cluster(wd, frames, records, args.eps, args.min_samples)

    data = {"id": wd.name, "input": str(val), "work_dir": str(wd),
            "engine": args.engine, "frames": len(frames),
            "scenery": sum(1 for v in records.values() if not v),
            "crops": sum(len(v) for v in records.values()),
            **mode_data}
    return {"data": data, "next": _next_hints(data)}


SCHEMA = {
    "envelope": {
        "ok": "true | false | 'partial'",
        "data": "object (on success) — pipeline result, see modes below",
        "error": "{code, message, retryable} (on failure)",
        "meta": "{schema_version, tool, elapsed_ms}",
        "next": "[string] optional follow-up hints",
    },
    "data.common": {"id": "str", "input": "str", "work_dir": "str",
                    "frames": "int", "scenery": "int", "crops": "int", "mode": "cluster|match"},
    "data.cluster": {"characters": "[{name, crops}]", "unsorted": "int",
                     "characters_dir": "str", "montage": "str|null", "index": "str"},
    "data.match": {"ref_eps": "float", "prototypes": "int", "crops_total": "int",
                   "matched": "int", "bands": "{<dist>: cumulative_count}",
                   "matched_dir": "str", "montage": "str|null", "index": "str"},
    "data.match.multi": {"ref_eps": "float", "crops_total": "int", "matched": "int (total)",
                         "matched_dir": "str (parent of per-character dirs)",
                         "characters": "[{name, prototypes, matched, bands, matched_dir, montage, index}]"},
    "exit_codes": {"0": "ok", "1": "runtime", "2": "auth", "3": "validation"},
}


def _render_human(env):
    """Compact human summary for a TTY reader (stderr already had progress)."""
    if not env.get("ok", True) is True and "error" in env:
        e = env["error"]
        return f"✗ {e['code']}: {e['message']}"
    if env.get("dry_run"):
        w = env["would"]
        return ("dry-run plan:\n" +
                "\n".join(f"  {k}: {v}" for k, v in w.items()))
    d = env["data"]
    head = (f"✓ {d['mode']} | id={d['id']} | frames={d['frames']} "
            f"scenery={d['scenery']} crops={d['crops']}")
    if d["mode"] == "cluster":
        chars = ", ".join(f"{c['name']}({c['crops']})" for c in d["characters"]) or "—"
        body = f"  characters: {chars} | unsorted={d['unsorted']}\n  -> {d['characters_dir']}"
    elif "characters" in d:                          # multi-character match
        lines = "\n".join(f"  {c['name']}: matched={c['matched']} -> {c['matched_dir']}"
                          for c in d["characters"])
        body = (f"  {len(d['characters'])} characters | total matched="
                f"{d['matched']}/{d['crops_total']} (< {d['ref_eps']})\n{lines}")
    else:
        bands = " ".join(f"<{k}:{v}" for k, v in d["bands"].items())
        body = (f"  matched={d['matched']}/{d['crops_total']} (< {d['ref_eps']})\n"
                f"  bands: {bands}\n  -> {d['matched_dir']}")
    hints = "".join(f"\n  · {h}" for h in env.get("next", []))
    return f"{head}\n{body}{hints}"


def emit(env, fmt):
    if fmt == "json":
        print(json.dumps(env, ensure_ascii=False, indent=2))
    else:
        print(_render_human(env))


def main():
    ap = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("input", nargs="?",
                    help="bilibili URL / BVxxxx / epNNN, or a local video file")
    ap.add_argument("--ref", help="reference folder -> one-vs-rest mode. A folder of "
                    "*.jpg crops of ONE character pulls matches into matched/; a folder "
                    "of per-character SUBFOLDERS pulls each into matched/<name>/")
    ap.add_argument("--ref-eps", type=float, default=0.04,
                    help="mode-2 max distance to a reference prototype "
                         "(tight = pure; 0.04 pristine, ~0.06 recall ceiling)")
    ap.add_argument("--out", default="./bangumi_frames")
    ap.add_argument("--cookies", default=os.environ.get("BILIBILI_COOKIES",
                                                        str(DEFAULT_COOKIES)),
                    help="Netscape cookies.txt (trusted via env/file, not agent args)")
    ap.add_argument("--height", type=int, default=2160)
    ap.add_argument("--prefer", choices=["size", "bitrate"], default="size",
                    help="among equal-res SDR streams: 'size'=smallest (HEVC) / "
                         "'bitrate'=sharpest (AVC)")
    ap.add_argument("--engine", choices=["ffmpeg", "pyscenedetect"], default="ffmpeg",
                    help="keyframe selector: 'ffmpeg' scene metric (default) or "
                         "'pyscenedetect' ContentDetector (more robust on fades; "
                         "needs `pip install scenedetect`)")
    ap.add_argument("--scene", type=float, default=0.3,
                    help="ffmpeg-engine scene-cut threshold 0-1 (smaller = more frames)")
    ap.add_argument("--pyscene-threshold", type=float, default=27.0,
                    help="pyscenedetect-engine ContentDetector threshold ~0-100 "
                         "(smaller = more cuts)")
    ap.add_argument("--interval", type=float, default=0,
                    help="also keep a frame every N seconds (0 = scene cuts only)")
    ap.add_argument("--dedup", type=int, default=6,
                    help="hamming distance below which consecutive frames are dropped")
    ap.add_argument("--skip", default="",
                    help="time ranges (seconds) to exclude, e.g. 80-170,1300-1390 (OP/ED)")
    ap.add_argument("--clean", action="store_true",
                    help="remove burned-in subtitles + watermark before classifying "
                         "(needs rapidocr-onnxruntime + simple-lama-inpainting)")
    ap.add_argument("--clean-band", type=float, default=0.22)
    ap.add_argument("--clean-conf", type=float, default=0.6)
    ap.add_argument("--clean-no-watermark", action="store_true")
    ap.add_argument("--conf", type=float, default=0.45, help="min person-detection score")
    ap.add_argument("--min-area", type=float, default=0.015,
                    help="min person-box area as fraction of frame")
    ap.add_argument("--eps", type=float, default=0.10,
                    help="mode-1 cluster distance threshold (larger = merge more)")
    ap.add_argument("--min-samples", type=int, default=5,
                    help="mode-1 min crops to form a character")
    ap.add_argument("--redo", choices=["extract", "classify"],
                    help="invalidate this stage and the ones after it")
    ap.add_argument("--format", choices=["json", "table"],
                    help="output format (default: json when piped, table on a TTY)")
    ap.add_argument("--dry-run", action="store_true",
                    help="preview the plan (resolved input, work dir, output) without running")
    ap.add_argument("--schema", action="store_true",
                    help="print the output-envelope schema and exit")
    args = ap.parse_args()

    fmt = args.format or ("table" if sys.stdout.isatty() else "json")
    meta = {"schema_version": SCHEMA_VERSION, "tool": "bangumi-frames"}

    if args.schema:
        emit({"ok": True, "data": SCHEMA, "meta": meta}, fmt)
        return EXIT_OK
    if not args.input:
        emit({"ok": False, "error": {"code": "validation_error",
              "message": "missing input (URL / BV / ep / local file)", "retryable": False}}, fmt)
        return EXIT_VALIDATION

    t0 = time.time()
    try:
        body = run(args)
        meta["elapsed_ms"] = int((time.time() - t0) * 1000)
        emit({"ok": True, **body, "meta": meta}, fmt)
        return EXIT_OK
    except CliError as e:
        emit({"ok": False, "error": {"code": e.code, "message": e.message,
              "retryable": e.retryable}, "meta": meta}, fmt)
        return e.exit_code
    except KeyboardInterrupt:
        emit({"ok": False, "error": {"code": "interrupted",
              "message": "interrupted", "retryable": True}, "meta": meta}, fmt)
        return EXIT_RUNTIME
    except Exception as e:                            # last-resort structured failure
        emit({"ok": False, "error": {"code": "runtime_error",
              "message": f"{type(e).__name__}: {e}", "retryable": False}, "meta": meta}, fmt)
        return EXIT_RUNTIME


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall