密集读帧还原完整口播
何时用
- 短视频口播没有可用 ASR：本地 ASR 模型权重下载被墙（HF / hf-mirror / ModelScope 均不通），或在线 ASR 成本高 / 不准。
- 字幕烧录在画面里（非独立字幕轨），只能"看画面读字"。
- 需要把一整条视频的完整台词还原成分镜脚本（不是只抽关键帧摘要）。
核心原则（已验证）
> ⚠️ 密集抽帧，不是关键帧。 只抽 3 张关键帧会丢大量中间口播。必须按时间轴均匀密集抽帧（如每 2 秒 1 帧，或总帧数上限 600），逐帧读字幕后按时间序拼接，才能还原完整脚本。
工作流（4 步）
- 密集抽帧 + 拼网格 — 跑
scripts/extract_frames.py。
- 输入：单个视频文件，或含视频的目录。
- 默认每 2 秒抽 1 帧（或--max-frames 600控制总量），每 12 帧拼成 1 张网格图（4 列 × 3 行），帧号水印标在左上角。
- 输出：<视频名>_grid/grid_01.png … grid_XX.png（ASCII 目录名，避开中文路径坑）。 - 多模态逐帧读字幕 — 把 grid_*.png 批量交给多模态能力（Read 图片 / 多模态 Agent）逐张读画面字幕，输出每张图里 12 帧的字幕文本 + 对应的画面动作。
- 按时间序拼接 — 把各网格图的字幕按帧号顺序拼成完整口播，自然衔接成一条连贯脚本。
- 回填分镜表（可选） — 按母本结构补：镜头 / 字幕 / 钩子 / 利益点，形成可分镜拍摄的脚本。
⚠️ 必踩的坑（已验证）
- 中文路径：
cv2.VideoCapture在 Windows 读中文路径经常静默失败 → 脚本已处理：打不开时自动复制到临时 ASCII 名再读；帧目录强制用 ASCII 名（v01~vNN），中文原名存 manifest。 - 主线程读大量图触发 400 上限：不要一次性把几百张图塞给单个 Read。先拼网格（12 帧/张）把图数压缩 ~12 倍，再用多个 Agent 并行各自读一批网格图。
- ASR 模型权重被墙：短视频口播基本全上屏为字幕，密集读帧即可还原，无需音频 ASR，省去下载模型的坑。
- 帧率推断：
CAP_PROP_FPS偶尔返回 0，脚本回退到默认 25fps。
脚本清单
| 脚本 | 作用 | 关键参数 |
|---|---|---|
| scripts/extract_frames.py | 密集抽帧 + 网格拼接 | --every-sec 2（抽帧间隔秒）--max-frames 600（总量上限）--grid 12（每格帧数）--cols 4（每行列数） |
依赖
pip install opencv-python numpy
（在 managed Python venv 内安装，不要污染系统环境）
调用示例
cd 你的项目目录
python <skill>/scripts/extract_frames.py "素材/示例视频.mp4" --every-sec 2 --grid 12 --cols 4
# 输出：示例视频_grid/grid_01.png ...
# 然后把 grid_*.png 批量交给多模态读字幕，按帧号拼接
