口播还原师

要解决什么问题

短视频口播素材常常遇到一个尴尬：字幕不是独立字幕轨，而是直接烧录在画面里，视频也没有可用的 ASR 结果。想拿完整台词做分镜脚本，只能"看画面读字"。更麻烦的是，本地 ASR 模型权重往往被墙——HF、hf-mirror、ModelScope 全都不通；在线 ASR 要么成本高，要么识别不准。这时候需要的就不是语音转写，而是把画面里的字幕逐帧读出来再拼回去。

它是怎么工作的

核心原则只有一条：密集读帧，不是关键帧。只抽 3 张关键帧会丢掉大量中间口播，必须按时间轴均匀抽帧，逐帧读字幕后按时间序拼接，才能还原完整脚本。

具体分四步：

1. 密集抽帧 + 拼网格 — 运行 scripts/extract_frames.py，输入单个视频文件或含视频的目录。默认每 2 秒抽 1 帧（可用 --max-frames 600 控制总量），每 12 帧拼成一张 4 列 × 3 行的网格图，帧号水印标在左上角，输出到 _grid/grid_01.png 等 ASCII 目录，避开中文路径坑。
2. 多模态逐帧读字幕 — 把 grid_*.png 批量交给多模态能力，逐张读出每张图里 12 帧的字幕文本和对应的画面动作。
3. 按时间序拼接 — 把各网格图的字幕按帧号顺序拼成完整口播，自然衔接成一条连贯脚本。
4. 回填分镜表（可选） — 按母本结构补镜头、字幕、钩子、利益点，形成可分镜拍摄的脚本。

适用边界与注意点

• 抽帧间隔要权衡：--every-sec 默认 2 秒，字幕停留短或语速快的素材需要调小；但帧数上限 --max-frames 600 决定了长视频的还原完整度，硬截断会丢尾部台词。
• 不要一次性塞几百张图：主线程读大量图会触发 400 上限。先拼网格把图数压缩约 12 倍，再用多个 Agent 并行各读一批网格图。
• 中文路径：cv2.VideoCapture 在 Windows 读中文路径经常静默失败，脚本已做兜底——打不开时自动复制到临时 ASCII 名再读。
• 帧率推断：CAP_PROP_FPS 偶尔返回 0，脚本会回退到默认 25fps。
• 依赖 OpenCV，建议在 managed Python venv 内安装，避免污染系统环境。