cutmap 0.1.0__py3-none-any.whl

cutmap/__init__.py

@@ -0,0 +1,2 @@
+"""cutmap —— 视频分镜分析：感知去重抽画面、B-roll 自动识别、图文对照浏览"""
+__version__ = "0.1.0"

cutmap/_assets.py

@@ -0,0 +1,149 @@
+"""浏览页的 CSS / JS（内联，产物为单文件，无外部依赖）"""
+
+CSS = """
+:root { --bg:#fff; --fg:#1a1a1a; --sub:#666; --card:#f6f6f7; --line:#e3e3e6; --accent:#0b84ff; }
+@media (prefers-color-scheme: dark) {
+  :root { --bg:#141416; --fg:#eaeaec; --sub:#9a9aa0; --card:#1d1d20; --line:#2c2c31; --accent:#4da3ff; }
+}
+:root[data-theme="dark"] {
+  --bg:#141416; --fg:#eaeaec; --sub:#9a9aa0; --card:#1d1d20; --line:#2c2c31; --accent:#4da3ff;
+}
+:root[data-theme="light"] {
+  --bg:#fff; --fg:#1a1a1a; --sub:#666; --card:#f6f6f7; --line:#e3e3e6; --accent:#0b84ff;
+}
+* { box-sizing:border-box; }
+body { margin:0; background:var(--bg); color:var(--fg);
+  font:15px/1.6 -apple-system,BlinkMacSystemFont,"PingFang SC","Helvetica Neue",sans-serif; }
+header { position:sticky; top:0; z-index:20; background:var(--bg);
+  border-bottom:1px solid var(--line); padding:12px 20px 0; }
+.top { display:flex; gap:14px; align-items:flex-start; }
+#player { width:340px; flex:none; border-radius:8px; background:#000; }
+.info { flex:1; min-width:0; }
+h1 { margin:0 0 4px; font-size:16px; font-weight:650; }
+.meta { color:var(--sub); font-size:13px; }
+.tools { margin-top:10px; display:flex; gap:8px; flex-wrap:wrap; align-items:center; }
+input[type=search] { flex:1; min-width:180px; padding:7px 11px; font-size:14px;
+  border:1px solid var(--line); border-radius:8px; background:var(--card); color:var(--fg); }
+button { padding:7px 11px; font-size:13px; border:1px solid var(--line); border-radius:8px;
+  background:var(--card); color:var(--fg); cursor:pointer; }
+button.on { background:var(--accent); color:#fff; border-color:var(--accent); }
+.count { color:var(--sub); font-size:13px; white-space:nowrap; }
+/* Tab */
+.tabs { display:flex; gap:2px; margin-top:12px; }
+.tab { padding:9px 18px; font-size:14px; font-weight:600; cursor:pointer;
+  border:none; background:none; color:var(--sub); border-bottom:2px solid transparent;
+  border-radius:0; }
+.tab:hover { color:var(--fg); }
+.tab.active { color:var(--accent); border-bottom-color:var(--accent); }
+.tab .n { font-weight:400; font-size:12px; opacity:.75; margin-left:5px; }
+/* 网格 */
+.pane { display:none; }
+.pane.active { display:grid; }
+.pane { gap:16px; padding:18px 20px 40px; }
+#pane-frames { grid-template-columns:repeat(auto-fill,minmax(320px,1fr)); }
+#pane-broll  { grid-template-columns:repeat(auto-fill,minmax(360px,1fr)); }
+.card { background:var(--card); border:1px solid var(--line); border-radius:10px; overflow:hidden; }
+.card img, .card video { width:100%; display:block; background:#000; cursor:pointer; }
+.body { padding:9px 11px 11px; }
+.tc { display:flex; gap:8px; align-items:center; flex-wrap:wrap; margin-bottom:5px; }
+.seek { color:var(--accent); font-weight:600; font-size:13px; cursor:pointer;
+  font-variant-numeric:tabular-nums; background:none; border:none; padding:0; }
+.seek:hover { text-decoration:underline; }
+.tag { color:var(--sub); font-size:12px; }
+.sub { font-size:14px; word-break:break-word; cursor:pointer; }
+.sub.clipped .rest { display:none; }
+.sub .more { color:var(--accent); font-size:13px; margin-left:2px; }
+.sub:not(.clipped) .more { display:none; }
+.sub .none { color:var(--sub); font-size:13px; }
+mark { background:#ffd54a; color:#000; border-radius:2px; }
+.hidden { display:none !important; }
+.empty { padding:60px 20px; text-align:center; color:var(--sub); }
+"""
+
+JS = """
+const player=document.getElementById('player');
+const q=document.getElementById('q');
+const count=document.getElementById('count');
+const autoBtn=document.getElementById('auto');
+let autoPlay=true, active='frames';
+
+/* ---- 播放器跳转 ---- */
+function seek(t){
+  player.currentTime=t; player.play().catch(()=>{});
+  window.scrollTo({top:0,behavior:'smooth'});
+}
+document.addEventListener('click',e=>{
+  const el=e.target.closest('[data-t]');
+  if(el){ e.preventDefault(); seek(parseFloat(el.dataset.t)); }
+});
+
+/* ---- 字幕折叠 ---- */
+document.addEventListener('click',e=>{
+  const s=e.target.closest('.sub');
+  if(s && !e.target.closest('[data-t]')) s.classList.toggle('clipped');
+});
+
+/* ---- Tab 切换 ---- */
+document.querySelectorAll('.tab').forEach(t=>{
+  t.onclick=()=>{
+    active=t.dataset.pane;
+    document.querySelectorAll('.tab').forEach(x=>x.classList.toggle('active',x===t));
+    document.querySelectorAll('.pane').forEach(p=>
+      p.classList.toggle('active',p.id==='pane-'+active));
+    autoBtn.classList.toggle('hidden', active!=='broll');
+    // 切走时暂停所有片段，避免后台解码
+    if(active!=='broll') document.querySelectorAll('video.clip').forEach(v=>v.pause());
+    else syncPlay();
+    render();
+    window.scrollTo({top:0});
+  };
+});
+
+/* ---- B-roll 只播视口内 ---- */
+const io=new IntersectionObserver(es=>es.forEach(e=>{
+  const v=e.target.querySelector('video.clip'); if(!v) return;
+  if(e.isIntersecting && autoPlay && active==='broll') v.play().catch(()=>{}); else v.pause();
+}),{rootMargin:'120px'});
+document.querySelectorAll('#pane-broll .card').forEach(c=>io.observe(c));
+function syncPlay(){
+  document.querySelectorAll('#pane-broll .card').forEach(c=>{
+    const v=c.querySelector('video.clip'); if(!v) return;
+    const r=c.getBoundingClientRect();
+    const vis=r.top<innerHeight+120 && r.bottom>-120;
+    (autoPlay && vis && active==='broll') ? v.play().catch(()=>{}) : v.pause();
+  });
+}
+if(autoBtn) autoBtn.onclick=()=>{
+  autoPlay=!autoPlay;
+  autoBtn.classList.toggle('on',autoPlay);
+  autoBtn.textContent='自动播放：'+(autoPlay?'开':'关');
+  syncPlay();
+};
+
+/* ---- 搜索 ---- */
+function esc(s){return s.replace(/[&<>]/g,m=>({'&':'&amp;','<':'&lt;','>':'&gt;'}[m]));}
+function paint(el,raw,kw){
+  const n=parseInt(el.dataset.clip||'48');
+  const hit=s=> kw? esc(s).split(esc(kw)).join('<mark>'+esc(kw)+'</mark>') : esc(s);
+  if(!raw){ el.innerHTML='<span class="none">（无字幕）</span>'; el.classList.remove('clipped'); return; }
+  if(raw.length<=n){ el.innerHTML=hit(raw); el.classList.remove('clipped'); return; }
+  el.innerHTML=hit(raw.slice(0,n))+'<span class="rest">'+hit(raw.slice(n))+
+               '</span><span class="more">…展开</span>';
+  el.classList.add('clipped');
+}
+function render(){
+  const kw=q.value.trim();
+  const cards=[...document.querySelectorAll('#pane-'+active+' .card')];
+  let n=0;
+  cards.forEach(c=>{
+    const el=c.querySelector('.sub'); if(!el) return;
+    const raw=el.dataset.raw||'';
+    if(!kw || raw.includes(kw)){ paint(el,raw,kw); c.classList.remove('hidden'); n++; }
+    else c.classList.add('hidden');
+  });
+  count.textContent = kw ? n+' / '+cards.length : cards.length+(active==='broll'?' 个片段':' 个画面');
+  if(active==='broll') syncPlay();
+}
+q.addEventListener('input',render);
+render();
+"""

cutmap/broll.py

@@ -0,0 +1,148 @@
+"""把视频切成 B-roll 片段，用于研究剪辑手法
+
+分类靠三条纯规则，不需要模型：
+  1. 主镜头(A-roll) = 贯穿全片反复出现的高度相似画面簇（固定机位）
+  2. 转场卡        = 亮度均值极低/极高的纯色帧
+  3. B-roll        = 其余
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+
+from PIL import Image, ImageStat
+
+from . import util
+from .frames import dhash, hamming
+
+CLUSTER_TH = 12        # 聚类相似度阈值（汉明距离）
+AROLL_SPAN = 0.5       # 簇的时间跨度占全片比例超过此值，才可能是固定机位
+AROLL_MIN_FRAMES = 8
+SEG_MAX = 45           # 单段上限（秒）
+
+
+def is_flat(path: str) -> bool:
+    """黑场 / 白场转场卡
+
+    不能用标准差判定：这类卡上常烧录着字幕，标准差被文字拉到 23~33，
+    远高于"纯色"阈值。改用亮度均值——实测真黑场卡均值 <8。
+    阈值也不能放太松：均值 <25 会把偏暗的正常内容误判成转场
+    （某片实测 290s vs 实际 20s）。
+    """
+    st = ImageStat.Stat(Image.open(path).convert("L"))
+    return st.mean[0] < 8 or st.mean[0] > 245
+
+
+def classify(index: dict, root: str, seg_max: float = SEG_MAX) -> tuple[list, float]:
+    frames = index["frames"]
+    total = frames[-1]["time"] + frames[-1]["span"]
+
+    hs = []
+    for f in frames:
+        p = os.path.join(root, f["frame"])
+        hs.append((f, dhash(p), is_flat(p)))
+
+    clusters: list[dict] = []
+    for f, h, flat in hs:
+        for c in clusters:
+            if hamming(h, c["h"]) < CLUSTER_TH:
+                c["items"].append(f)
+                break
+        else:
+            clusters.append({"h": h, "items": [f], "flat": flat})
+
+    flat_ids = {id(f) for f, _, flat in hs if flat}
+    aroll_ids: set[int] = set()
+    for c in clusters:
+        if len(c["items"]) < AROLL_MIN_FRAMES or c["flat"]:
+            continue
+        ts = [x["time"] for x in c["items"]]
+        if (max(ts) - min(ts)) / total >= AROLL_SPAN:
+            aroll_ids |= {id(x) for x in c["items"]}
+
+    def kind(f):
+        if id(f) in flat_ids:
+            return "转场"
+        return "主镜头" if id(f) in aroll_ids else "B-roll"
+
+    segs, cur = [], None
+    for f in frames:
+        k = kind(f)
+        # 同类连续帧合并，但超过 seg_max 强制断开：
+        # 全程屏幕演示、没有主镜头作分隔的视频，否则会并成一整坨
+        # （实测 390s 的视频被切出单个 280s 的"片段"）
+        too_long = cur is not None and (f["time"] + f["span"] - cur["start"]) > seg_max
+        if cur and cur["kind"] == k and not too_long:
+            cur["frames"].append(f)
+            cur["end"] = f["time"] + f["span"]
+        else:
+            if cur:
+                segs.append(cur)
+            cur = {"kind": k, "frames": [f], "start": f["time"],
+                   "end": f["time"] + f["span"]}
+    if cur:
+        segs.append(cur)
+    return segs, total
+
+
+def _cut(video: str, start: float, dur: float, out: str, fmt: str) -> None:
+    ff = util.ffmpeg()
+    common = [ff, "-v", "error", "-ss", f"{start:.2f}", "-t", f"{dur:.2f}", "-i", video]
+    if fmt == "mp4":
+        cmd = common + ["-an", "-vf", "scale=480:-1", "-c:v", "libx264", "-crf", "28",
+                        "-preset", "veryfast", "-movflags", "+faststart", "-y", out]
+    elif fmt == "webp":
+        cmd = common + ["-vf", "fps=12,scale=480:-1", "-loop", "0", "-q:v", "70", "-y", out]
+    else:  # gif —— 体积约为 mp4 的 24 倍且只有 256 色，仅在需要贴进聊天/笔记时用
+        cmd = common + ["-vf", "fps=10,scale=480:-1,split[a][b];[a]palettegen[p];"
+                              "[b][p]paletteuse", "-y", out]
+    subprocess.run(cmd, check=False)
+
+
+def extract(outdir: str, *, fmt: str = "mp4", min_duration: float = 1.5,
+            seg_max: float = SEG_MAX, log=print) -> dict:
+    """从已有的 index.json 切 B-roll，写入 outdir/broll/"""
+    index = json.load(open(os.path.join(outdir, "index.json"), encoding="utf-8"))
+    video = index["source"]
+    segs, total = classify(index, outdir, seg_max)
+
+    stat: dict[str, list] = {}
+    for s in segs:
+        e = stat.setdefault(s["kind"], [0, 0.0])
+        e[0] += 1
+        e[1] += s["end"] - s["start"]
+    for k, (n, t) in sorted(stat.items(), key=lambda x: -x[1][1]):
+        log(f"  {k:>7}: {n:3d} 段, 累计 {t:5.0f}s ({t/total*100:4.1f}%)")
+
+    picks = [s for s in segs
+             if s["kind"] == "B-roll" and s["end"] - s["start"] >= min_duration]
+    bdir = os.path.join(outdir, "broll")
+    os.makedirs(bdir, exist_ok=True)
+    log(f"  导出 {len(picks)} 个 B-roll 片段 ({fmt}) ...")
+
+    meta = []
+    for i, s in enumerate(picks, 1):
+        dur = s["end"] - s["start"]
+        name = (f"{i:03d}_{int(s['start']//60):02d}-{int(s['start']%60):02d}"
+                f"_{dur:.0f}s.{fmt}")
+        _cut(video, s["start"], dur, os.path.join(bdir, name), fmt)
+        # 用独占字段拼接（相邻帧窗口不重叠），并去掉连续重复句作为兜底
+        parts, prev = [], None
+        for f in s["frames"]:
+            t = f.get("subtitle_own") or ""
+            if t and t != prev:
+                parts.append(t)
+                prev = t
+        meta.append({
+            "idx": i, "file": name, "start": round(s["start"], 2),
+            "timecode": util.hhmmss(s["start"]), "duration": round(dur, 2),
+            "frames": len(s["frames"]), "subtitle": "".join(parts),
+        })
+
+    data = {"video": index["video"], "format": fmt, "count": len(meta), "segments": meta}
+    json.dump(data, open(os.path.join(bdir, "broll.json"), "w", encoding="utf-8"),
+              ensure_ascii=False, indent=2)
+    size = sum(os.path.getsize(os.path.join(bdir, m["file"])) for m in meta)
+    log(f"  ✓ {len(meta)} 个片段, 合计 {size/1048576:.1f} MB")
+    return data

cutmap/cli.py

@@ -0,0 +1,140 @@
+"""cutmap 命令行入口"""
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import sys
+
+from . import broll as broll_mod
+from . import frames as frames_mod
+from . import render, util
+
+# 下载能力是可选覆盖模块：公开发行版不包含 download.py。
+# 缺失时 URL 输入会给出明确提示，本地文件分析不受影响。
+try:
+    from . import download as _dl
+except ImportError:  # pragma: no cover
+    _dl = None
+
+
+def _step(n: int, total: int, msg: str) -> None:
+    print(f"\n\033[1m[{n}/{total}] {msg}\033[0m", flush=True)
+
+
+def resolve(target: str, srt_opt: str | None):
+    """输入 → (视频路径, 字幕路径或None, 工作目录)"""
+    if os.path.isdir(target):
+        mp4 = os.path.join(target, "源片.mp4")
+        if not os.path.exists(mp4):
+            cand = glob.glob(os.path.join(target, "*.mp4"))
+            if not cand:
+                sys.exit(f"目录里没有 mp4: {target}")
+            mp4 = max(cand, key=os.path.getsize)
+        srt = srt_opt or os.path.join(target, "字幕.srt")
+        return mp4, (srt if os.path.exists(srt) else None), target
+
+    if os.path.isfile(target):
+        stem = os.path.splitext(target)[0]
+        srt = srt_opt or stem + ".srt"
+        outdir = stem  # 与视频同名的目录
+        os.makedirs(outdir, exist_ok=True)
+        return target, (srt if os.path.exists(srt) else None), outdir
+
+    return None, None, None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    has_dl = _dl is not None
+    desc = "视频分镜分析：抽画面 + 切 B-roll + 生成可浏览页面"
+    if has_dl:
+        desc = "B站视频分析：下载 + " + desc.split("：", 1)[1]
+    p = argparse.ArgumentParser(prog="cutmap", description=desc)
+    p.add_argument("target",
+                   help="视频文件 / 素材目录" + ("/ B站 URL 或 BV号" if has_dl else ""))
+    p.add_argument("--srt", help="字幕文件（默认在同目录按同名查找）")
+    p.add_argument("--terms", help="自定义术语表（默认用内置 AI/科技词表）")
+    p.add_argument("--threshold", type=int, default=10,
+                   help="去重阈值，越小画面越密：6密 / 10默认 / 14疏")
+    p.add_argument("--fps", type=float, default=2, help="密集采样帧率（默认2）")
+    p.add_argument("--cols", type=int, default=4, help="图墙列数")
+    p.add_argument("--rows", type=int, default=4, help="图墙行数")
+    p.add_argument("--thumb-width", type=int, default=480, help="缩略图宽度 px")
+    p.add_argument("--seg-max", type=float, default=45, help="B-roll 单段上限秒数")
+    p.add_argument("--clip-format", default="mp4", choices=["mp4", "gif", "webp"],
+                   help="片段格式；gif 体积约为 mp4 的 24 倍")
+    p.add_argument("--no-broll", action="store_true", help="跳过 B-roll 切片")
+    p.add_argument("--no-frames", action="store_true",
+                   help="不保留单帧，只留图墙（省空间）")
+    if has_dl:
+        p.add_argument("--out", default=".", help="下载输出根目录（默认当前目录）")
+        p.add_argument("--download-only", action="store_true", help="只下载不分析")
+        p.add_argument("--redownload", action="store_true", help="强制重新下载")
+        p.add_argument("-v", "--verbose", action="store_true", help="下载器完整输出")
+    return p
+
+
+def main(argv=None) -> int:
+    a = build_parser().parse_args(argv)
+    target = a.target
+
+    # ---- 可选：下载 ----
+    if not os.path.exists(target):
+        if _dl is None:
+            sys.exit(
+                f"找不到: {target}\n"
+                "本版本不含下载功能，请传入本地视频文件或素材目录。\n"
+                "B站视频可用 BBDown 自行下载：https://github.com/nilaoda/BBDown")
+        try:
+            got = _dl.acquire(target, a.out, a.redownload, a.verbose)
+        except util.MissingDependency as e:
+            sys.exit(f"\n✗ 缺少依赖：\n{e}")
+        if not got:
+            return 1
+        target = got
+        if a.download_only:
+            print(f"\n\033[1m=== 仅下载，已完成 ===\033[0m\n{target}")
+            return 0
+
+    mp4, srt, outdir = resolve(target, a.srt)
+    if mp4 is None:
+        sys.exit(f"找不到: {target}")
+
+    total = 3 if not a.no_broll else 2
+    name = os.path.basename(outdir.rstrip("/"))
+    print(f"\033[1m{name}\033[0m")
+    print(f"  视频: {os.path.basename(mp4)} ({os.path.getsize(mp4)/1048576:.0f} MB)")
+    print(f"  字幕: {'✓ ' + os.path.basename(srt) if srt else '⚠ 无（图文对照将为空）'}")
+
+    try:
+        _step(1, total, "抽画面 + 图墙")
+        data = frames_mod.extract(
+            mp4, outdir, srt, threshold=a.threshold, fps=a.fps,
+            cols=a.cols, rows=a.rows, thumb_width=a.thumb_width,
+            keep_frames=not a.no_frames)
+        data["video"] = name
+        json.dump(data, open(os.path.join(outdir, "index.json"), "w", encoding="utf-8"),
+                  ensure_ascii=False, indent=2)
+
+        n = 2
+        if not a.no_broll:
+            _step(2, total, "切 B-roll 片段")
+            if a.no_frames:
+                print("  跳过：B-roll 分类需要单帧，不能与 --no-frames 同用")
+            else:
+                broll_mod.extract(outdir, fmt=a.clip_format, seg_max=a.seg_max)
+            n = 3
+
+        _step(n, total, "生成浏览页")
+        page = render.build(outdir, a.terms)
+    except util.MissingDependency as e:
+        sys.exit(f"\n✗ 缺少依赖：\n{e}")
+
+    print(f"\n\033[1m=== 完成 ===\033[0m\n{outdir}")
+    print(f"\n打开:  open '{page}'")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cutmap/frames.py

@@ -0,0 +1,156 @@
+"""密集采样 + dHash 感知去重 → 分镜画面 + contact sheet + index.json
+
+为什么不用 ffmpeg 的场景检测（select='gt(scene,X)'）：
+它只识别硬切，抓不到
+  ① 白底页面之间的低对比度切换（整体亮度结构相近，差异分低于阈值）
+  ② 镜头内的内容演进（文字逐行出现、图表数值增长、表格高亮移动）
+实测同一视频：场景检测得 104 个画面，感知去重得 608 个。
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+
+from PIL import Image, ImageDraw
+
+from . import util
+
+
+def dhash(path: str, size: int = 8) -> int:
+    """差值哈希：缩到 (size+1)×size 灰度，比较每行相邻像素亮度，得 size² 位指纹"""
+    im = Image.open(path).convert("L").resize((size + 1, size), Image.LANCZOS)
+    px = list(im.getdata())
+    bits = 0
+    for r in range(size):
+        row = r * (size + 1)
+        for c in range(size):
+            bits = (bits << 1) | (1 if px[row + c] > px[row + c + 1] else 0)
+    return bits
+
+
+def hamming(a: int, b: int) -> int:
+    return bin(a ^ b).count("1")
+
+
+def subtitle_own(cues, t0: float, t1: float) -> str:
+    """起始于 [t0, t1) 的字幕 —— 每条只归属一帧，用于跨帧拼接
+
+    严格半开区间、无回看。带回看会让相邻帧认领同一条字幕，
+    拼接 B-roll 段落时出现整句重复。
+    """
+    return "".join(c[2] for c in cues if t0 <= c[0] < t1)
+
+
+def subtitle_at(cues, t: float) -> str:
+    """该时刻正在说的话 —— 用于单帧显示，允许与相邻帧相同"""
+    for a, b, txt in cues:
+        if a <= t < b:
+            return txt
+    return ""
+
+
+def _label(path: str, idx: int, t: float) -> None:
+    im = Image.open(path).convert("RGB")
+    d = ImageDraw.Draw(im, "RGBA")
+    font = util.load_font(max(14, int(im.width * 0.042)))
+    txt = f"#{idx}  {util.hhmmss(t)}  {t:.1f}s"
+    bb = d.textbbox((4, 4), txt, font=font)
+    d.rectangle([bb[0] - 3, bb[1] - 2, bb[2] + 3, bb[3] + 2], fill=(0, 0, 0, 170))
+    d.text((4, 4), txt, font=font, fill=(255, 235, 60))
+    im.save(path, quality=92)
+
+
+def _sheets(frames_dir: str, outdir: str, cols: int, rows: int, thumb_w: int) -> int:
+    per = cols * rows
+    names = sorted(os.listdir(frames_dir))
+    n = 0
+    for s in range(0, len(names), per):
+        lst = os.path.join(outdir, f"_l{s}.txt")
+        with open(lst, "w") as f:
+            for c in names[s:s + per]:
+                # concat 的相对路径按列表文件所在目录解析，故写绝对路径
+                f.write(f"file '{os.path.abspath(os.path.join(frames_dir, c))}'\n")
+        subprocess.run(
+            [util.ffmpeg(), "-y", "-v", "error", "-f", "concat", "-safe", "0", "-i", lst,
+             "-vf", f"scale={thumb_w}:-1,tile={cols}x{rows}:padding=5:margin=5:color=white",
+             "-frames:v", "1", "-q:v", "3",
+             os.path.join(outdir, f"sheet_{s//per + 1:02d}.jpg")],
+            check=False)
+        os.remove(lst)
+        n += 1
+    return n
+
+
+def extract(video: str, outdir: str, srt: str | None = None, *,
+            threshold: int = 10, fps: float = 2, cols: int = 4, rows: int = 4,
+            thumb_width: int = 480, keep_frames: bool = True,
+            log=print) -> dict:
+    """抽分镜画面，写入 outdir，返回 index 数据"""
+    cues = util.parse_srt(srt)
+    frames_dir = os.path.join(outdir, "frames")
+    os.makedirs(frames_dir, exist_ok=True)
+
+    log(f"  字幕: {len(cues)} 条" if cues else "  字幕: 无")
+    log(f"  密集采样 {fps}fps ...")
+
+    # 临时目录放系统盘：几千个小文件写外置盘（exFAT 簇 1MB）既慢又浪费
+    with tempfile.TemporaryDirectory() as td:
+        subprocess.run(
+            [util.ffmpeg(), "-v", "error", "-i", video, "-vf",
+             f"fps={fps},scale={thumb_width}:-1", "-q:v", "3",
+             os.path.join(td, "%06d.jpg")], check=True)
+        raw = sorted(os.listdir(td))
+        if not raw:
+            raise RuntimeError(f"未能从视频抽出任何帧: {video}")
+        log(f"  {len(raw)} 帧 → dHash 去重 (阈值 {threshold}) ...")
+
+        kept, last = [], None
+        for i, f in enumerate(raw):
+            p = os.path.join(td, f)
+            h = dhash(p)
+            if last is not None and hamming(h, last) < threshold:
+                continue
+            last = h
+            kept.append((i / fps, p))
+        log(f"  保留 {len(kept)} 帧 (压缩率 {len(kept)/len(raw)*100:.1f}%)")
+
+        index = []
+        for n, (t, src) in enumerate(kept, 1):
+            nxt = kept[n][0] if n < len(kept) else t + 1 / fps
+            dst = os.path.join(frames_dir, f"{n:04d}_{util.hhmmss(t,'-')}.jpg")
+            shutil.copy(src, dst)
+            _label(dst, n, t)
+            index.append({
+                "idx": n,
+                "time": round(t, 2),
+                "timecode": util.hhmmss(t),
+                "span": round(nxt - t, 2),
+                "frame": os.path.relpath(dst, outdir),
+                "subtitle": subtitle_at(cues, t),
+                "subtitle_own": subtitle_own(cues, t, nxt),
+            })
+
+    data = {
+        "video": os.path.basename(outdir.rstrip("/")),
+        # 存绝对路径：后续 broll 直接拿它喂 ffmpeg，
+        # 存相对路径会导致换个 cwd 跑就找不到文件
+        "source": os.path.abspath(video),
+        "method": "dense-sample + dHash dedup",
+        "fps": fps, "hash_threshold": threshold,
+        "frame_count": len(index), "frames": index,
+    }
+    json.dump(data, open(os.path.join(outdir, "index.json"), "w", encoding="utf-8"),
+              ensure_ascii=False, indent=2)
+
+    log("  生成 contact sheet ...")
+    n_sheets = _sheets(frames_dir, outdir, cols, rows, thumb_width)
+    if not keep_frames:
+        shutil.rmtree(frames_dir, ignore_errors=True)
+
+    spans = [x["span"] for x in index]
+    log(f"  ✓ 画面 {len(index)} 个 / 图墙 {n_sheets} 张 / "
+        f"平均间隔 {sum(spans)/len(spans):.1f}s")
+    return data