成片视频 → 每条字幕一张图
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 |
纯文字卡(浅底 + 大字台词 + 时间码),不带画面 | 想要最干净、零歧义的排版 |
端到端工作流
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 普通拼台词)
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 纯字幕,只能留字幕、板书另做一页时用)
# 在项目根运行;换期用 --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% 漏掉所有字幕):
$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 / 片尾关注卡(yc0.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 路线(纯字幕)才反过来:只抠黑底字幕条贴到纯白画布。两条路线别混。
# 推荐(默认):第一行「完整人头」——从画面顶部/自动头顶切到字幕条底部,其余行窄带
$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)自动算。
批量(只挑口播段、避开幻灯片/片尾卡):
# 每 3 句一张「底图 + 贴字幕条」的旧版拼图(lineup.py),自动跳过幻灯片与片尾
$PY $S/batch_lineup.py "<成片>.mp4" --subdir "<成片名>_字幕图" --outdir <输出目录> --per 3 --skip-tail 10
人工控节奏:清单 → 分页 → 出图(推荐流程)
拼台词的价值在语言节奏(每张最后一句留钩子让人想翻),这种判断只能人来定,所以走三步:
# 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)或「保留板书齐全」参数,别因为这句就把整段板书丢掉。
环境
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)
- 为什么要 OCR:早先靠「边缘图变化 + IoU 去重」判换句,实测一套 7 分钟片漏了 108 秒内容(32 处空档)。 漏的两种形态:① 字形相近的两句(「想转出海」/「想进外企」)被判成同一句;② 字幕条纵向位置跳变(口播 ≈0.71、图文卡 ≈0.94),检测带跑偏,整段漏掉。 读字就没有这些问题:文字即身份,同字才算同一句。
- 抽帧:
fps=4(默认)、scale=540宽。短句最短约 0.5s,4fps 至少能采到 2 帧。 - 怎么认出「这是字幕」而不是幻灯片正文:真字幕永远压在深色底条上 → 看 OCR 框内背景亮度中位数,
< 105才算字幕;米色卡/截图正文(中位数 ~200)不算。 - 双行字幕:相邻、水平居中对齐、行距小的两个框合并成一条。
- 归并:连续帧文字相同(去标点空格后完全相等)→ 同一条字幕;代表帧取组内 50%~80% 区间里、且该帧 OCR 文字必须等于整组的那一帧。 ⚠️ 别选「置信度最高」的帧:最高分常落在字幕刚切换的那一帧(新字幕已淡入、画面主体还是上一句),出图会系统性偏早半句。
- 补画面页(
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去截整帧。
- 段内要按文字变化拆页(
- 清杂:≤0.6s 且与相邻句相似度 ≥0.75 的半句(出场动画打一半)并进相邻条;无中文且极短的噪声(转场 logo、日期戳)丢掉。
- 出图后回读校验(
snap_and_check(),默认开、--no-verify关):截完把图再 OCR 一遍,和期望文字比对(包含关系 或 difflib ≥0.55);不匹配就按 70%/45%/88%/30%/15% 换时间点重截,最多 6 次。 这是兜底关键:OCR 帧时间戳与真实画面可能差半帧,光靠分组猜不准。manifest 会写t= 校验通过的截帧时间,拼图直接复用这个点。
旧路线:raw 烧录字幕逐条检测(不需 OCR,会漏)
- 按
--detect-fps(默认 3)抽帧 → 裁字幕行(--sub-band)→ 转边缘图缩成 176×36 签名。 - 为什么用边缘不用灰度:卡拉OK逐词高亮只改颜色、不改字形轮廓,边缘图对高亮免疫。
- 相邻帧边缘差 >
--diff-thresh(默认 9.5)即认为换了一条字幕 → 分组。 - 过滤:时长 < 0.45s、或平均边缘强度 < 12 → 丢弃。
- ⚠️ 参数化的阈值永远在「漏」和「重复」之间走钢丝,要完整逐字稿就别用这条路。
其它模式(ASR 路线)
- 词级时间戳:
word_timestamps=True,句子 start/end 取真实首词/末词时间(按片段平均分配会导致截到下一句)。 - 断句:句末标点必断;≥
--max-chars且落在逗号处则断;超长硬断兜底。 - 取帧:
(start+end)/2中点帧。 - 有软字幕流(srt/ass)优先
ffmpeg抽 srt;无则 ASR。whisper 默认繁体 → opencct2s。
五个坑(已踩 / 预判)
竖屏成片很大(1440×2560),截帧务必
scale=1080:-1缩到 1080 宽,否则单张 jpg 好几 MB。脚本已默认缩。字幕行位置因片而异:
--sub-band默认 0.705–0.795 是 1440×2560 竖屏、字幕在底部营销条上方的常见位置。换片先看一张帧确认字幕行 y 范围,不对就传--sub-band。带子要窄(只要字幕行),带太宽会把上方手机录屏/画面内容卷进来,导致误判换句。静态营销条干扰:底部固定的「报名/连麦」条在字幕行下方,
--sub-band默认已排除;hybrid的底部覆盖区会一并盖掉,raw则保留它。空字幕帧:说话间隙字幕会消失,若某段画面在动(如录屏),可能被误当成"有字幕"。脚本用「组平均边缘强度 < 12 丢弃」过滤;仍有个别漏网时调
--diff-thresh或--sub-band。whisper 分词(ASR 模式):偶尔把词切开(「行业」拆成「行」/「业都」),个别图末端断词,可接受;介意可调
--max-chars。
交付
- 图多时别逐张给(几十张会刷屏)。用
scripts/make_sheet.py <字幕图目录>一键生成「字幕总览」长图(每页 18 行 + 序号 + 时间),用户一眼读完整个逐字稿:$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 时间同比增加)。