# Video Subtitle Slicer

> 把「成片视频」（多为竖屏、烧录字幕）切成多张图片，每图一条完整字幕，并**拼台词**成 1080×1440 图文笔记（小红书等）。触发词：拼台词、拼第 N-M 的图、拼 12-17、纯粹保留字幕部分/不用板书/板书我单独放一页、保留板书齐全、纯字幕成图。首选 scan_captions.py 用 RapidOCR 逐帧读烧录字幕、按文字归并，保证一句不漏（同字才算同一句）；成图两条路线：build_pages.py 普通拼台词（头图+竖堆字幕条）、pure_caption.py 纯字幕（只留黑底字幕条贴纯白画布）。另有边缘变化检测（快但会漏）、whisper 词级时间戳切句（自动适配 mlx / openai 后端）、叠字幕、纯文字卡等模式。离线免费，跨平台（Windows/macOS/Linux）。

- Skill: `hunchide/video-subtitle-slicer` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx get-skill add hunchide/video-subtitle-slicer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hunchide/video-subtitle-slicer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Hunchide (https://skillmd.com/u/hunchide)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/hunchide/video-subtitle-slicer

---


# 成片视频 → 每条字幕一张图

> **Agent / 通用运行说明**：本 skill 是纯命令行工具，不绑定任何 agent 框架。所有脚本在同目录 `scripts/` 下，通过 `_compat.py` 统一处理跨平台差异（字体探测、ffmpeg 路径、Pillow 版本、whisper 后端）。任何能执行 Python 的环境（终端 / CI / WorkBuddy / Claude / Codex 等）直接在仓库根目录调用即可。开始前先跑「环境」一节的依赖检查；`PY` 指你的 Python 解释器，`S=./scripts`。

三条取字幕路线（**默认走 OCR**）：

- **OCR（推荐，`scan_captions.py`）**：逐帧读画面里的烧录字幕文字，**同字才算同一句**。文字与原片一致，且不漏句、不重复。
- 边缘变化检测（`slice_subtitles.py` 的 raw）：不读字，靠字幕行边缘变化猜换句，快，但**会漏**（字形相近的两句被并成一句、字幕条位置跳变时整段漏掉）。只在没装 OCR 时用。
- ASR（`--mode sentence/hybrid/frame`）：whisper 词级时间戳听写（自动适配 mlx / openai 后端），用于无烧录字幕的原片。

离线、免费、不需要任何 API Key。竖屏成片（如 1440×2560）直接出 1080 宽图。

## 何时用

- 用户说「把视频切成字幕图」「每句台词一张图」「出一套台词卡片做图文笔记」
- 用户要「完整逐字稿」「每条字幕一张」
- 手里有一段已剪辑好的成片（非长直播），想拆成可发的图片素材
- 用户说「**拼台词**」「拼第 N-M 的图」「拼 12-17」→ 直接走下面「拼台词决策树」出 1080×1440 成图
- 用户说「**纯粹保留字幕部分／不用板书／板书我会单独放一页**」→ 纯字幕路线
- 用户说「**保留板书齐全／注意保留板书完整**」→ 普通拼台词 + 板书专用参数

## 五种模式（先选模式，再跑）

| 模式 | 产出 | 什么时候用 |
|---|---|---|
| `scan_captions.py`（**首选**） | **OCR 读字幕，每条字幕一张图**；一条不漏 | 成片有烧录字幕（绝大多数情况）；要完整逐字稿 + 可复制文本 |
| `raw`（备选） | 边缘变化猜换句，每条字幕一张图 | 没装 OCR 时的应急，**已知会漏句** |
| `hybrid` | 上半视频画面 + 底部模糊底条叠**ASR 完整台词** | 想要「一句完整话」压在一张图上，不介意叠字 |
| `frame` | 视频帧 + 脚本叠加字幕（半透明条+白字描边） | 原片**没有**烧录字幕（纯口播） |
| `sentence` | 按 ASR 整句截中点帧（一句话一张，粒度粗） | 只想每句话一张、不要逐条字幕 |
| `textcard` | 纯文字卡（浅底 + 大字台词 + 时间码），不带画面 | 想要最干净、零歧义的排版 |

## 端到端工作流

```bash
PY=python3   # 或激活 venv 后的 python
S=./scripts   # 本仓库 scripts/ 目录

# ① 首选：OCR 扫字幕，一句不漏（4fps，540 宽抽帧，CPU 就够快；7 分钟片约 6 分钟）
$PY $S/scan_captions.py "<成片>.mov"
#    先只看时间轴、不写真图（很快，配合 --json 缓存后可反复看）
$PY $S/scan_captions.py "<成片>.mov" --review
#    缓存 OCR 结果，调参/重出图不用重跑识别
$PY $S/scan_captions.py "<成片>.mov" --json /tmp/ocr_<片名>.json

# ② 备选（无 OCR 环境）：边缘变化检测，快但会漏句
$PY $S/slice_subtitles.py "<成片>.mp4"

# ③ 画面 + 完整台词（ASR 叠字）/ 纯文字卡
$PY $S/slice_subtitles.py "<成片>.mp4" --mode hybrid
$PY $S/slice_subtitles.py "<成片>.mp4" --mode textcard
```

`scan_captions.py` 输出 `<成片名>_字幕图/`，内含：
- `001.jpg` / `002.jpg` … 一条字幕一张（按时间顺序）
- `manifest.json`：`{video, mode:"ocr", fps, count, images:[{file, text, kind, start, end, bar, ocr_score}]}`
  - `text` = **OCR 读出的字幕原文**（拼台词时可直接拿来做文案）
  - `kind` = `caption`（字幕）或 `slide`（这一段没字幕、是幻灯片/图表，`text` 只是版面摘要）
  - `bar` = 字幕条在画面里的纵向位置（占高比例），拼图时当**锚点**用：
    `find_bar_box(g, anchor=bar中心)` 会选离它最近的暗条。不给锚点就会挑「最大暗条」，
    而画面底部的深色衣物/阴影经常比字幕条还大 → 整条横带切错、一个字都没有。
  - `scene` = `person`（真人出镜）或 `board`（板书/提纲页），按画面中央肤色占比判定；
    拼台词时**头图只能挑 person**（见下节）

## 拼台词决策树（成图前先过一遍）

**术语**：「拼台词 / 拼第 N-M 的图」= `build_pages.py` 成图 —— 头图（第一句真人帧）+ 后续每句字幕条竖向堆叠 → **1080×1440 精确 3:4 竖图**。不是 2×3 帧拼图。分页文件写 `12-17` 一行即「台词 12-17 当一页」。

### 第一步：选路线

| 信号 | 路线 | 产物 |
|---|---|---|
| 只说「拼 N-M」不带后缀；`scene=person` 人物帧 | **A 普通拼台词** `build_pages.py` | 头图 + 竖堆字幕条 |
| 明确带「可以纯粹保留字幕部分／不用板书／板书我会单独放一页」 | **B 纯字幕** `pure_caption.py` | 纯白底 + 只摞黑底字幕条 |
| `scene=board` 板书长段（≥8 句）、用户没带后缀 | **B 主推 + A 备选** | 两套都出、主推明确 |
| 明确带「保留板书齐全／注意保留板书完整」 | **A + 板书专用参数** | 头图保住整页板书 |
| 区间含 `kind=slide` 大字卡 | **只能 A** | 大字卡按原帧呈现 |

⚠️ 帧类型可交叉验证：board 段多半纯字幕、person 段多半普通拼台词。**拿不准就两套都出、主推明确，别只赌一套。**
⚠️ 大字卡帧没有黑底字幕条 → 含 slide 的区间**别走纯字幕**（`pure_caption.py` 会抠坏）。

### 第二步：看 manifest 定页数（别按句数硬套）

- `--check` 的「最多 N 行 / 条高 ~Xpx」是**按整份 pages 文件动态算的**：同一区间单独跑 vs 与其他页一起跑，上限会不同。别拿单页 check 结论套拆页。
- 出图前先看区间内 `bar` 高度差：单行条 ~112px；双行条 `bar=[0.679,0.74]` ~179px，会把单页上限压到 3 行。
- **≥8 句别走单页**：9 句单页头图缩成窄条 + 字幕条互相叠字；6 句单页只缩不叠、可留作备选。
- 先跑 `--check` 筛出**零 `↕首图缩`** 的拆法。含大字卡 + 双行条的区间实测要拆到 **3 行/页** 才零缩（4 页拆法全部至少 1 页缩）。

### 第三步：去重告警必须人工判

`⚠去重:[N]` 用 `text_sig`（字幕条亮像素二值掩膜压到 200×28）算 IoU，阈值 0.82。短句、字数接近、同为黑底黄字时形状签名撞车 → **误删独立台词**（下期V2 #7「发卡和付款」/#8「卡组织和银行」相似度 0.825 刚过阈值）。

**判定法**：见告警先比对原帧 `NNN.jpg` 与上一张的字幕文字；文字不同 = 误删 → 加 `--no-dedupe`。板书帧每句板书完全相同、字幕形状相近，误判更多，**board 段必加 `--no-dedupe`**。反过来 person 段同一句被采两帧（手势不同、字幕相同，OCR text 可能截成半句）时去重是对的。别去改 0.82 阈值（会影响全片其它区间）。

### 定稿命令（A 普通拼台词）

```bash
PY=python3   # 或激活 venv 后的 python
S=./scripts   # 本仓库 scripts/ 目录

$PY $S/build_pages.py "<成片>.mov" --subdir "<成片名>_字幕图_ocr" \
    --pages pages.txt --outdir <输出目录> --prefix <名> \
    --keep-slides --slide-mode raw \
    --slide-pad-bottom 60 --slide-pad-top -40 \
    --headroom 0.02 --header-fit contain --no-dedupe
```

`--keep-slides --slide-mode raw` 让 `kind=slide` 大字卡按原帧呈现（白描边或黄色高亮两行大字、无黑底），完整不裁 —— 老版本默认跳过 slide 是错的。`--no-dedupe` 确认无真重复帧后加。

### 定稿命令（B 纯字幕，只能留字幕、板书另做一页时用）

```bash
# 在项目根运行；换期用 --subdir 指定字幕帧目录（含 manifest.json）
$PY $S/pure_caption.py --start 222 --end 234 --build \
    --subdir "<素材名>_字幕图_ocr" \
    --outdir <输出目录> --prefix <前缀> \
    --no-dedupe
```

- board 板书段（浅背景）：`--no-dedupe`，**不用** `--tight`。
- person 人物帧（室内深色衣物）：必须 `--tight --dedupe`，否则两侧带出画面碎块、重复帧占两条。
- 单行标准条高按区间 `det_h` 中位数**自动算**（上期V2=110px、下期V2 board=99px），别写死。`--per-page 0` 自动均衡（末页过短会重排）、`--gap 22` 调间距。
- `--probe` 先看异常条（<80px 或 >190px）：可能是真三行长字幕（248px 那种），比对原帧确认不是裁歪就保留原高度。
- 项目根的 `pure_caption.py` 是转发壳，**实现只在 skill 包里**，改 bug 别改两份。

### 换期差异（别跨期套结论）

| | 上期V2 | 下期V2 |
|---|---|---|
| board 帧字幕条 | 常规 | **y≈0.82 很靠下**、条高 ~80px |
| `contain` 板书 | 竖版白板缩成窄幅 + **两侧大片模糊补边** | 纯白底文档，**没有糊边** |
| 板书齐全正解 | `--header-fit cover` 消糊边（白板末尾几行被字幕盖）→ 拆 3+3 | `--header-fit contain --headroom 0.02 --no-dedupe`（`cover` 裁首条字幕、`headroom 0` 切板书标题） |
| person 帧 | — | 单行 `bar=[0.695,0.723]`；长句变 `bar=[0.679,0.74]` 双行 |

板书段「保留板书齐全」另两条：`--header-top 0`（板书首行黑字会被 `detect_head_top` 误当头顶，默认 -1 会裁掉大标题）；**5 句单页物理上放不下完整板书**（headroom/header-fit 全组 md5 相同、调参无效），正解是拆页 3+2。

### 第三种素材：白字无底条口播片（转行不降薪.mp4，2026-11-13 新增）

⚠️ **别套上期/下期的黑底字幕条经验**。这类片子长这样：真人半身口播（@Frankly Speaking 水印），
字幕是**白字+细描边直接压在深色衣服/浅墙上，没有黑底条**；`bar` 中心恒定 ≈0.78，
全片无板书、无大字卡（只有片头黄/黑底标题卡 + 片尾关注卡）。1080×1920 / 30fps。

**① 扫字幕必须加两个参数**（默认 105 的暗底判据会 100% 漏掉所有字幕）：

```bash
$PY $S/scan_captions.py "<成片>.mp4" \
    --bg-thresh 256 --cap-yc-min 0.74 \
    --json /tmp/ocr_转行不降薪.json --out-dir "素材/转行不降薪_字幕图_ocr"
```

- `--bg-thresh 256`：放开「字幕框背景亮度中位数 <105」判据。白字框 `bg` 实测 117~205，默认全挡。
- `--cap-yc-min 0.74`：**必加**。放开亮度后片头大字卡 / logo / 片尾关注卡（`yc` 0.50~0.71）会混进来，
  实测多出 4 条脏数据；真字幕 `yc` 稳定 0.78。收紧后 304 条、只剩 1 处 2.75s 片头 logo 空档。
- 两个参数默认值保持 105 / 0.45，**上期/下期历史结果不受影响**（已回归验证）。
- `--json` 缓存 1471 帧 OCR 结果，全片 6 分钟片首次约 6.5 分钟；调判据重跑只需 3.8 分钟且不用重识别。
- 出完 6 张「仍对不上」是 **OCR 认错字**（氙围→氛围、町→盯、琴→零），图本身完整，别当失败重跑。
- `1/2/3` 蓝色方块编号是原片自带的**4 步骤标签**，会进 `text`，不是噪声，别删。
- `make_sheet.py` 的 `--band` 要按实际 `bar` 调成 `0.735,0.845`（默认 0.700,0.800 是黑底片的位置）。

**② 成图只能走 A 普通拼台词，不能走 B 纯字幕**：B 要抠黑底字幕条，这片没有黑条可抠。

**③ 已修的结构性坑（2026-11-13）**：`find_bar_box()` 靠暗条检测，在这片 5/5 全返回 None →
`make_strip()` 原来的「贴画面底部往上切」兜底会切到 y≈0.92~1.0，而字幕在 0.78 →
**下方横带里一条字幕都没有**（头图那句反而是好的）。已给 `make_strip` 加锚点兜底：
`box is None and anchor` 时按 `bar` 中心 ±0.030 定位横带，字幕落在带子中间。
只在原本就检测不到的帧生效，**上期/下期 10/10 定稿 md5 回归完全一致**。

- 该片 `--check` 上限 **3 行/页**（4 行页必 ↕首图缩），按 3 句拆页。
- 定稿命令沿用 A 路线全套开关即可，别额外调 `headroom` / `header-fit`（白字片没有糊边问题）。
- 片头 #1 是 `kind=slide` 大字卡（`bar` 为空数组，正常），出清单时按整帧缩略处理；拼台词别选它当头图。

### 已知结构性坑（别浪费时间调参）

- **下期 board 段普通拼台词的首条字幕会被压成细黑边**：字幕条在 y≈0.82，4~5 行页必压；拆到 3 行页、`--header-fit cover`、`--headroom 0`、4 页拆法全无效 → 正解是纯字幕。
- **board 段的 `↕首图缩` 与糊边是两回事**：headroom 0 / cover / min-pad 都消不掉 ↕（结构性标记），但 cover 视觉干净，别硬调。
- **塞满页时 `--min-pad` / `--strip-ratio` 一律无效**（输出字节相同，剩余空间被填满算法均摊给横带）。`--headroom 0` 能消 person 帧单独一页的 ↕，代价是头顶浮层贴片被裁一点；但会切掉板书标题，板书段别用。

## 底层实现：横带摞图（strip_stack.py，日常不直接调）

A 路线底层是「横带摞图」：每句 = 从该句帧上切一条横带（带子里天然就有那句烧录字幕），直接码起来，所以**普通拼台词**不需要抠字幕条、也不需要找干净底图。B 路线（纯字幕）才反过来：只抠黑底字幕条贴到纯白画布。两条路线别混。

```bash
# 推荐（默认）：第一行「完整人头」——从画面顶部/自动头顶切到字幕条底部，其余行窄带
$PY $S/strip_stack.py "<成片>.mp4" --subdir "<成片名>_字幕图" --start 4 --count 4 --out out.jpg

# 全部等高（不要大图头）
$PY $S/strip_stack.py "<成片>.mp4" --subdir "<成片名>_字幕图" --start 4 --count 5 \
    --header-h -1 --strip-h 288 --out out.jpg
```

- `--start/--count`：从第几张字幕图起、要几行；**自动去重**（同一条字幕的卡拉OK高亮位移不会重复占行），不够行数会继续往后取。
- `--header-mode head`（默认）：第一行按「人头」切 —— 自动找头发顶端（中央区域检测，避开左上角水印）→ 裁到字幕条底部，保完整人头；`--header-top 0` 强制从画面最顶部切，`-1` 自动。
- `--target-ratio 0.75`（默认）：若其余行还放得下字幕条，自动调行高让整图**精确 3:4**；放不下（行数多/字幕条高）就按自动行高，输出更高。
- `--strip-h` 不给（0）则按字幕条高度的 p80 × `--strip-ratio`（默认 1.55）自动算。

批量（只挑口播段、避开幻灯片/片尾卡）：

```bash
# 每 3 句一张「底图 + 贴字幕条」的旧版拼图（lineup.py），自动跳过幻灯片与片尾
$PY $S/batch_lineup.py "<成片>.mp4" --subdir "<成片名>_字幕图" --outdir <输出目录> --per 3 --skip-tail 10
```

## 人工控节奏：清单 → 分页 → 出图（推荐流程）

拼台词的价值在**语言节奏**（每张最后一句留钩子让人想翻），这种判断只能人来定，所以走三步：

```bash
# 1) 出台词清单（把每条烧录字幕原样裁出来，带序号+时间码，可直接读）
$PY $S/make_script_list.py --subdir "<成片名>_字幕图" --prefix 上期V2

# 2) 写分页文件 pages.txt（每行一页，支持范围/逗号，# 后面可写钩子备注）
#    4-7
#    8,9,10
#    11-14   # 末尾留「所以我从来不会先说数字」当钩子

# 3) 一键出图，**强制精确 1080×1440**（定稿参数见上方「拼台词决策树」，
#    裸命令不带这些参数会踩首图缩 / 大字卡被跳过 / 短句被误去重）
$PY $S/build_pages.py "<成片>.mp4" --subdir "<成片名>_字幕图" \
    --pages pages.txt --outdir <输出目录> --prefix 上期 \
    --keep-slides --slide-mode raw \
    --slide-pad-bottom 60 --slide-pad-top -40 \
    --headroom 0.02 --header-fit contain --no-dedupe
```

- `build_pages.py --check`：只跑版式不写文件；`--list`：直接打印序号+时间+ASR 参考文本。
- `--skip 24,34`：排除指定序号（OCR 常留下「上一句的后半截」重复条，如「的都是茶蛋可以内推的企业」）。
- `--only 1-5,9`：只出这几页（页号按分页文件里顺序，保留原编号），草稿很长时先出几页看效果。
- **放不下会明说**：某页句子太多时会打印「本页最多 N 行」；真的塞不下时 `compose_page` 会把**首图等比缩小、两侧用同帧高斯模糊填充**（不是黑边）来保住精确 3:4（清单里标 `↕首图缩`），而不是偷偷裁字。
- **逐行高度**：单行字幕（112px）和双行字幕（177px）混排时，行高按各自字幕条高度分配，双行不会被切。
- 出图清单里会打印每页「末尾一句」，方便核对钩子是否成立。
- `--no-dedupe`：关掉形状签名去重，见决策树第三步。默认仍去重，历史结果不受影响。
- `--header-fit contain|cover`：contain 等比缩+两侧模糊补边；cover 按宽裁、不补边（上期白板消糊边用），但会盖住白板末尾几行。
- `--headroom <0~1>`：头图往上多裁画面。0 能消 person 帧单独一页的 ↕，但会切掉板书标题。
- `--header-top 0`：板书帧强制从画面最顶部切（默认 -1 自动找头顶，板书首行黑字会被误当头顶）。
- `--keep-slides --slide-mode raw`：保留大字卡，按原帧呈现。配 `--slide-pad-bottom/--slide-pad-top` 调大字卡上下留白。
- `--min-pad` / `--strip-ratio`：只在没塞满页时有效；**塞满页时输出字节不变**，别浪费时间调。
- 页数多时用项目里的 `分页草稿/gen_pages.py` 先生成草稿：自己写一份「段落定义」（`起-止 | 段落名`，一段=一个完整意思），它按每页容量**均分、不跨段**，输出可直接喂 build_pages 的 pages.txt 和一份「每页末句」对照表。⚠️ 2026-11-12 已把旧的全量分页方案（`pages_上期.txt` / `pages_下期.txt` / `pages_*_真人.txt` / `*_草稿说明.md`）清掉，**别再找这些文件**；现成可复用的定稿分页文件是 `pages_上期_指定_*.txt` / `pages_下期_指定_*.txt`（一行一个台词区间）。
- 完整参数清单以 `$PY $S/build_pages.py --help` 为准（还有 `--min-pad`、`--strip-ratio`、`--ratio`、`--quality`、`--tight-slide`、`--skip`、`--only` 等）。

### ⚠ 普通拼台词的头图必须是真人：先跑 `scene` 过滤

> 仅适用于 **A 普通拼台词**（要头图）。B 纯字幕没有头图，board 段照样能出；
> 用户说「保留板书齐全」时头图本来就是整页板书，也不受本节约束 —— 见上方决策树。

图文讲解类视频 80% 时长是**板书页**（整页 PPT/表格），只有开头结尾是真人出镜。
板书页整帧塞进头图位 = 一片白底小字 + 两侧黑边，是最难看的失败形态；但它切成横带后
只显示底部字幕条，和真人帧没区别，所以**可以当配行，不能当头图**。

- `scan_captions.py` 出图时会按**画面中央肤色占比**（`skin_ratio`，阈值 0.30；真人半身 ≈0.5，板书页 ≈0.01）
  给每条打 `scene: person / board` 写进 manifest。**别用 OCR 框数判**——图片型板书页读不出字，会被误判成 person。
- 自动分页脚本 `gen_person_pages.py`（按「每页首行必须 person」切整片）及其产物 `pages_*_真人.txt` 已于 **2026-11-12 清理删除**：它的「板书段整段丢弃」规则与现在「指定区间 + 板书另做一页」的做法冲突，留着只会误导。**现在的做法是手工写 pages.txt，一行一个台词区间**（`12-17` 一行 = 台词 12-17 当一页），不要试图找自动分页脚本。
  硬规则（**手工挑区间时**）：A 普通拼台词的**每页第一行必须是 `person` 帧**，板书句只能跟在后面当配行。每页行数按字幕条高度定（单行 4 行 / 双行 3 行），区间太长就拆页。
  ⚠️ 这条硬规则只服务「普通拼台词批量出真人页」，**不是全局禁令**：用户点名要 board 区间时，走纯字幕（`pure_caption.py`）或「保留板书齐全」参数，别因为这句就把整段板书丢掉。

## 环境

```bash
PY=python3   # 或激活 venv 后的 python
$PY -c "from rapidocr_onnxruntime import RapidOCR; print('ocr ok')"   # 缺就装：pip install rapidocr-onnxruntime
$PY -c "import opencc, PIL, numpy; print('ok')"                    # 缺就装：pip install -r requirements.txt
$PY -c "import mlx_whisper; print('mlx ok')"  ||  $PY -c "import whisper; print('openai ok')"   # 听写后端二选一
ffmpeg -version                                                       # 需先安装并加入 PATH
```

- **OCR**：`rapidocr-onnxruntime`（自带中英文模型，CPU ~0.2s/帧@540宽，无需联网、无需 tesseract）。
- **成图**：`numpy` + `Pillow`（`build_pages.py` / `pure_caption.py` 都依赖）。缺就 `pip install numpy Pillow`。
- **听写后端自动适配**：Apple Silicon（macOS）优先 `mlx-whisper` 走 GPU；Windows / Linux / Intel Mac 用 `openai-whisper`（CPU）。两者模型均首次自动下载（约 1.6GB）。脚本 `--backend auto|mlx|openai` 可显式指定。
- 中文字体：按系统自动探测（macOS 华文黑体/苹方；Windows 微软雅黑/黑体；Linux Noto Sans CJK/文泉驿）。可用 `--font` 或 `CJK_FONT` 环境变量指定。

## 关键设计

### OCR 扫字幕：为什么不能用「画面变化」猜（scan_captions.py）
1. **为什么要 OCR**：早先靠「边缘图变化 + IoU 去重」判换句，实测一套 7 分钟片漏了 108 秒内容（32 处空档）。
   漏的两种形态：① 字形相近的两句（「想转出海」/「想进外企」）被判成同一句；② 字幕条纵向位置跳变（口播 ≈0.71、图文卡 ≈0.94），检测带跑偏，整段漏掉。
   **读字就没有这些问题**：文字即身份，同字才算同一句。
2. **抽帧**：`fps=4`（默认）、`scale=540` 宽。短句最短约 0.5s，4fps 至少能采到 2 帧。
3. **怎么认出「这是字幕」而不是幻灯片正文**：真字幕永远压在**深色底条**上 → 看 OCR 框内背景亮度中位数，`< 105` 才算字幕；米色卡/截图正文（中位数 ~200）不算。
4. **双行字幕**：相邻、水平居中对齐、行距小的两个框合并成一条。
5. **归并**：连续帧文字相同（去标点空格后完全相等）→ 同一条字幕；代表帧取组内 **50%~80%** 区间里、且该帧 OCR 文字必须等于整组的那一帧。
   ⚠️ 别选「置信度最高」的帧：最高分常落在字幕刚切换的那一帧（新字幕已淡入、画面主体还是上一句），出图会系统性偏早半句。
6. **补画面页**（`kind=slide`）：没字幕但画面有内容的时段记一条，避免「幻灯片/大字卡讲解段整段丢失」。三条要点：
   - **段内要按文字变化拆页**（`split_slide()`）：一段「无字幕」画面常把大字卡 + 片头 logo + 黑场连成一片，整段只取一帧必然丢页（曾把「跨境支付 Fintech」整段丢在片头 logo 后面）。按每帧去水印后的文字签名做 difflib ≥0.6 归并，逐页出。
   - **代表帧取该页 80% 处**（逐行弹出的大字卡在中点时字还没出全）。
   - **白底 + 居中 + ≤8 字**判片头/片尾署名板（「小茶和 Frank」那种），不占一条；跨 caption 被打断的同一页（字幕条盖在卡上，两次无字幕片段文字几乎相同）用 `dedupe_slides()` 合并回一条。
   - 页面文字取该页 50%~92% 帧的**全部** OCR 框（不只最高分那个），所以「跨境支付」和下面一行「-Fintech-」都会进 `text`。
   - **大字卡压过一瞬的假字幕**（≤0.6s 且文字被邻近卡片覆盖）用 `drop_slide_echo()` 删掉，否则同一句话会出现「卡片一条 + 字幕一条」两遍。
   - `kind=slide` 的页在**旧版**拼图里默认跳过（整页塞不进横带）；现在 `build_pages.py --keep-slides --slide-mode raw` 会把大字卡按原帧完整保留（白描边 / 黄色高亮两行大字、无黑底），是定稿参数的一部分。要它单独成图才用 `manifest` 里那条的 `t` 去截整帧。
7. **清杂**：≤0.6s 且与相邻句相似度 ≥0.75 的半句（出场动画打一半）并进相邻条；无中文且极短的噪声（转场 logo、日期戳）丢掉。
8. **出图后回读校验**（`snap_and_check()`，默认开、`--no-verify` 关）：截完把图再 OCR 一遍，和期望文字比对（包含关系 或 difflib ≥0.55）；不匹配就按 70%/45%/88%/30%/15% 换时间点重截，最多 6 次。
   这是**兜底关键**：OCR 帧时间戳与真实画面可能差半帧，光靠分组猜不准。manifest 会写 `t` = 校验通过的截帧时间，拼图直接复用这个点。

### 旧路线：raw 烧录字幕逐条检测（不需 OCR，会漏）
1. 按 `--detect-fps`（默认 3）抽帧 → 裁**字幕行**（`--sub-band`）→ 转**边缘图**缩成 176×36 签名。
2. **为什么用边缘不用灰度**：卡拉OK逐词高亮只改颜色、不改字形轮廓，边缘图对高亮免疫。
3. 相邻帧边缘差 > `--diff-thresh`（默认 9.5）即认为换了一条字幕 → 分组。
4. 过滤：时长 < 0.45s、或平均边缘强度 < 12 → 丢弃。
5. ⚠️ 参数化的阈值永远在「漏」和「重复」之间走钢丝，**要完整逐字稿就别用这条路**。

### 其它模式（ASR 路线）
1. **词级时间戳**：`word_timestamps=True`，句子 start/end 取真实首词/末词时间（按片段平均分配会导致截到下一句）。
2. **断句**：句末标点必断；≥ `--max-chars` 且落在逗号处则断；超长硬断兜底。
3. **取帧**：`(start+end)/2` 中点帧。
4. 有软字幕流（srt/ass）优先 `ffmpeg` 抽 srt；无则 ASR。whisper 默认繁体 → opencc `t2s`。

## 五个坑（已踩 / 预判）

1. **竖屏成片很大**（1440×2560），截帧务必 `scale=1080:-1` 缩到 1080 宽，否则单张 jpg 好几 MB。脚本已默认缩。

2. **字幕行位置因片而异**：`--sub-band` 默认 0.705–0.795 是 1440×2560 竖屏、字幕在底部营销条上方的常见位置。换片先看一张帧确认字幕行 y 范围，不对就传 `--sub-band`。**带子要窄**（只要字幕行），带太宽会把上方手机录屏/画面内容卷进来，导致误判换句。

3. **静态营销条干扰**：底部固定的「报名/连麦」条在字幕行下方，`--sub-band` 默认已排除；`hybrid` 的底部覆盖区会一并盖掉，`raw` 则保留它。

4. **空字幕帧**：说话间隙字幕会消失，若某段画面在动（如录屏），可能被误当成"有字幕"。脚本用「组平均边缘强度 < 12 丢弃」过滤；仍有个别漏网时调 `--diff-thresh` 或 `--sub-band`。

5. **whisper 分词（ASR 模式）**：偶尔把词切开（「行业」拆成「行」/「业都」），个别图末端断词，可接受；介意可调 `--max-chars`。

## 交付

- 图多时别逐张给（几十张会刷屏）。用 `scripts/make_sheet.py <字幕图目录>` 一键生成「字幕总览」长图（每页 18 行 + 序号 + 时间），用户一眼读完整个逐字稿：
  ```bash
  $PY $S/make_sheet.py "<成片名>_字幕图" --per-page 18 --band 0.700,0.800
  ```
- 再 `present_files` 给 2–3 张样图 + 总览长图 + manifest。
- 提醒：图片按时间顺序编号，可直接拖进小红书图文编辑器；小红书单篇最多 18 图，几十张这种要挑。

### 拼台词成图的交付规范

- **先 `--check` 再出图**，出完必须目视自检：头图是否原尺寸没缩、两侧有无模糊竖条、字幕有无切字/断字/叠字、双行条两行是否齐全、最后一句钩子在不在。
- 拆页时用表格列出「页 / 文件 / 台词区间 / 收尾句 / 头图状态」，并说明**为什么拆**（超行数上限 → 会 ↕首图缩）。有瑕疵的版本别混进主交付，明确标注「弃/备选」。
- 两套都出时要写清**主推哪套、为什么**（如 board 长段主推纯字幕、person 段主推普通拼台词），别让用户自己猜。
- 分页文件（`pages_*.txt`）留在项目里，告诉用户改一行就能重跑；实验废稿挪到 `/tmp`，不留在成图目录。
- 交付后把新踩的坑追加到项目记忆；**能通用化的结论要回流到本 SKILL.md**，别只留在会话记忆里（这正是这份决策树存在的原因）。

## 已知限制

- OCR 会读错个别字（生僻词、英文品牌、手写花字），中文正文准确率很高；**要 100% 原文以图片为准**，`text` 只作检索/文案底稿。
- 回读校验会让出图变慢约一倍（每张多一次 OCR，7 分钟片约 +90s）。**图文卡页容易被误报「对不上」**——画面里本来就有几十个 OCR 框，拼起来跟单句字幕比必然不像；这类图本身是对的，看日志里 `仍对不上` 的列表时先看图再判断。
- 花字/贴纸若压在深色底上，可能被误判为字幕（概率低）；`kind=slide` 是「没字幕的幻灯片段」，旧版拼图默认跳过（`grab_frames(skip_kinds=("slide",))`），清单里仍保留参考；**定稿流程用 `--keep-slides --slide-mode raw` 会保留大字卡**。
- 幻灯片整页塞不进横带 → 旧版拼台词跳过、单独做整图；新版 `build_pages.py` 用 `--keep-slides` 可把大字卡作为一行放进成图，见决策树。
- **`build_pages.py` 没有纯字幕开关**：要「只留字幕、板书另做一页」必须用 `pure_caption.py`，两条路线别混。
- 下期V2 board 段（字幕条 y≈0.82）用 `build_pages.py` 出 4~5 行页时，**首条字幕会被压成细黑边**，属结构性缺陷，拆页和调参都救不回 → 直接走纯字幕，详见决策树「已知结构性坑」。
- ASR 路线不认画面文字（whisper 是听不是看），听写与原字幕可能有出入（如 AdTech 听成 iTech）。
- 多人快速对话 / 字幕 <0.5s 一闪而过时，4fps 可能采不到；可提到 `--fps 6` 重扫（代价是 OCR 时间同比增加）。

