Video To Evidence Layout

---
name: video-to-evidence-layout
description: 【与"帧册"(chat-recording-evidence)分工：本skill全自动选帧排版，用户要人工逐帧挑画面时用帧册，勿选本skill】录屏转证据截图+一面4块/一面6块A4排版PDF（每张图右下角跨页连续编号；6块为定稿省纸版式：肩并肩放大3%单张6.18cm左装订边1.3cm）+完整聊天长图，一条命令跑完（ffmpeg密集抽帧→逐帧滚动偏移累加选帧→内容窗口防漏页→A4竖版2×2排版→自检+小样图人工复核）。附带照片/文件证据排版能力（独立脚本 photo_layout.py：聊天中保存的照片/PDF一键排版为横版每页2张/竖版1张/4张证据PDF，页码组号-页号）。核心定则：①每帧都是原始完整截图绝不裁剪 ②相邻两张图下图压上图165px（约一行多消息）③推进量不得超过固定UI间的内容窗口 ④长图拼接缝处白线只裁精确像素行（终裁3px），绝不为修白边大面积裁固定UI。适用于微信聊天记录录屏固定为图片证据、及聊天中保存照片文件排版为证据的场景。
license: MIT
metadata:
  slug: video-to-evidence-layout
  displayName: 手机录屏转截图证据
  author: 陆凌燕
  version: 2.0.21
---

# video-to-evidence-layout — 录屏转证据截图 + 一面4块排版

2026-08-30 经 7 个版本迭代（v1 初排 → v2 裁剪被否 → v3 假对齐 → v6 漏内容 → v7 定稿）沉淀的终版流程，自动化脚本经原视频端到端实测，复现人工定稿结果。2026-08-30 夜用户终裁三项：①衔接默认 **165px**（见核心定则第 2 条），末段素材不足时末帧并入放长；②新增**完整聊天长图**交付物（见「长图拼接公式」）；③长图缝处白线只裁 **3px**，绝不为修白边大面积裁固定 UI（见核心定则第 4 条与坑⑤）。2026-09-19 修正：修掉"段内无滚动（推进 0）"引发的重复选帧与长图越界崩溃（见坑⑦），脚本已改，无需用户干预。

## 与相关 skill 的分工（关键词分流，避免混淆）

**本 skill 与 chat-recording-evidence（帧册）都处理"录屏→证据"，按关键词分流：**

| 用户说 | 用什么 |
|--------|--------|
| 录屏转截图 / 视频转证据 / 自动选帧 / 自动排版 / 一键固定录屏 / 录屏转图片（自动） / 完整长图 | **本 skill**（全自动） |
| 帧册 / 抽帧 / 人工挑帧 / 逐帧定位 / 我自己选画面 / 手动截取 / 录屏抽帧 | **chat-recording-evidence**（人工抽帧网页工具） |
| 录屏转图片（语义模糊、未说自动还是手动） | 先问用户：要"自动一键排版"还是"人工逐帧挑" |
| 用户要自己逐帧定位关键画面（正式取证、提交法院） | chat-recording-evidence（帧册，人工抽帧） |
| 排版规则/页码规范/证据册编排与打页码 | case-file-review Phase 10（图片自动排版/页码/压缩拆分） |

> 命名约定：本 skill 输出目录/PDF 前缀为**「录屏证据_」**；「帧册」一词专属于 chat-recording-evidence，本 skill 的产物命名与文案中不使用该词。

## 核心定则（用户拍板，不可违反）

1. **绝不裁剪**：每帧都是原始完整截图。裁过的图"变短了"，不是原始截图（v2 被否）
2. **相邻两图衔接 = 下图压上图 165px**（默认，约一行多微信消息，该视频实测实际衔接 159-163px）：选帧目标是「内容窗口 − 165」即推进 ≈ 窗口 − 165。⚠️ 因帧间滚动离散，名义 overlap 与实际衔接会有偏差（本视频 165 档实测 159-163px），只要衔接 >100px 即不断档。**若视频总滚动量不足（末段推进 < 目标），末帧照常并入放长，允许多压前一张图信息——这是素材决定，不是缺陷**（用户 2026-08-30 裁定）
3. **推进量不得超过内容窗口高度**：录屏界面顶部状态栏/导航栏、底部输入框是固定 UI，不随滚动移动，实际内容窗口 = 屏高 − 固定区（微信聊天页本视频实测 1128px = 1280 − 固定UI上11/下139；文章页约 1165-1196px；小屏机型窗口更小，见坑②的 992px 案例）。推进超过窗口高度 = 中间漏内容
4. **长图拼接缝处白线只裁精确像素行（用户 2026-08-30 终裁 3px）**：白线 = 每帧段底的输入框上沿白条（约 2px，行 mean 240-242 且 std<5）+1px 过渡行（mean ~223 std~11）。**修白边前必须逐行测量缝 ±10px 的 mean/std 定位白线精确行数，只裁问题行**——绝不为此大面积裁标题栏/输入框/工具栏（实测教训：裁掉 45px 标题栏导致文字丢失，被用户否决"你把原来的文字给修复掉了，白边很细很细"）。先按用户口径试裁（5px 嫌大 → 3px 定稿）

## 一条命令用法

```bash
python3 ~/.workbuddy/skills/video-to-evidence-layout/scripts/record2evidence.py 录屏.mp4 -o 输出目录
```

完整长图（**独立脚本**，按需单独生成，主脚本跑完后执行）：

```bash
python3 ~/.workbuddy/skills/video-to-evidence-layout/scripts/long_image.py 输出目录
```

聊天里保存的**照片/文件证据排版**（**独立脚本**，与本 skill 主流程分工：主流程管录屏→截图，本脚本管照片→排版）：

```bash
python3 ~/.workbuddy/skills/video-to-evidence-layout/scripts/photo_layout.py 照片1.jpg 照片2.jpg ... -o 输出目录
python3 ~/.workbuddy/skills/video-to-evidence-layout/scripts/photo_layout.py 照片目录/ -o 输出目录 --group 3
```

> **先问后排**：不传 `--per-page` 时脚本先展示版式菜单（每页1张关键凭证/2张一上一下/2张横版左右/4张截图2×2）请用户选择，再问组号；agent 代跑等非交互环境自动落默认（2张/页竖版一上一下，组号1）并提示；`--yes` 或参数直传可跳过提问。排版规则源自 case-file-review「图片自动排版」（与帧册 Framebook 一致）并按用户习惯调整：**照片类每页 2 张默认竖版一上一下**（横拍照片单格比横版左右格大 33%，且全卷 A4 方向统一便于装订翻阅）；`--landscape` 切横版左右两格（竖拍照片为主的场景更大）；`--per-page 1` 关键凭证竖版整页；`--per-page 4` 截图类竖版 2×2。页码「组号-页号」16pt 底部居中（`--group` 定组号，`--no-page-number` 可关闭——用于页码待材料编排完成后统一回填的场景）；图片等比缩放完整居中**绝不裁剪绝不变形**；手机照片自动 EXIF 方向归一化；支持 jpg/png/bmp/tiff/webp 与 PDF（逐页转图）；页数自检内置。用户把聊天记录中保存的照片/文件直接传入即可出证据排版 PDF。

> 长图脚本读取主脚本的 `selection.json` 与 `_raw/`（人工复核确认前勿删 `_raw/`）；内容窗口与衔接量从选中帧自适应重算、不写死分辨率；段底白线裁除默认 3px（`--trim-bottom` 可调）；自动打印缝处 mean/std 验证与总高校验（Σ段高 = 总推进+内容窗口+fixed_top−段数×裁线量）。

常用参数：`--overlap 165`（衔接像素，默认）｜`--per-page 4`（每页1/2/4/6张）｜`--fps 15`（抽帧密度）｜`--img-scale`（放大系数；**6块版式默认即 1.03 定稿值**，其他版式默认 1.0，可显式覆盖）｜`--fixed-top / --fixed-bottom`（手动覆盖固定UI像素，支持按组 `'2:140'` 或 `'1:147,2:140'`；白底页面自动检测失效时必用，见坑⑥；主脚本与 long_image.py 均支持）

> **每页 6 张（3列×2行，省纸版式）——定稿参数（用户 2026-08-31 拍板）**：肩并肩无缝隙 + **放大 3%**（img_scale=1.03，单张 **6.18cm**），放大宽度由边距自动消化（左装订边收至 **1.3cm**、右边距 1.2cm），**图片绝不压叠**；阅读顺序左→右、上→下；每张图右下角白底黑字**跨页连续顺序编号** 1,2,3…；页面底部不打页码。**选 6 块时无需传 --img-scale，默认即 1.03**；聊天截图多、想省纸用 6；要求单张更大用默认 4。

> 默认 165 已兼顾该视频的「内容连续 + 不断档」，特殊视频可在此值 ±30 微调。末段因素材不足衔接偏大属正常（见核心定则 2）。

> 关于 `--per-page 1/2`：布局始终按竖版 A4 固定两栏排，因此 1 张时落在左上格、2 张时占上排且下半页留白——这是已知的既有行为，不是缺陷。手机录屏场景默认用 4 张即可；1 张可临时用作关键证据放大，2 张对竖长截图无几何优势（横版 A4 的 2 张模式属照片类证据，归 case-file-review 管）。

## 流程（脚本自动化 6 步 + 1 步人工）

1. **侦察**：ffprobe 取时长/分辨率
2. **密集抽帧**：15fps（滚动快的录屏加密到 20fps）；随后自动检测并裁除编码黑边（见坑④），只去补边不动屏幕内容
3. **逐帧滚动偏移**：相邻帧小步长（上限 0.6 屏）灰度 MAE 对齐，得每帧推进量——**全屏搜索必假对齐，见坑①**
4. **自动分段**：原地内容突变（shift≈0 且 MAE>18）判场景切换；短于 0.5s 的过渡段（半透明滑入动画）自动丢弃；每段按行方差自动测内容窗口
5. **选链**：段内累加推进，达「内容窗口 − overlap」选帧；末帧并入（若与上帧推进 <0.15 窗口则替换，去停顿重复）
6. **排版+自检**：A4 竖版（每页1/2/4/6张可选）、等比完整居中不裁剪、每张图右下角跨页连续顺序编号 1,2,3…（白底黑字小标签）、阅读顺序左上→右上→左下→右下；页面底部不打页码（2026-08-31 用户拍板取消，图片编号已可定位）；自检页数/帧数/绘制尺寸一致性
7. **⚠️ 复核顺序铁律：先复核、后长图（必做）**：跑主脚本前先问用户两件事——①要一面4块（单张更大）还是一面6块（省纸，单张6.0cm，微信截图优先建议6块）；②要不要顺便生成完整聊天长图。主脚本跑完后，**必须先把 `小样图复核/` 逐页看完（查重复图/断档）+ 核对 `选帧报告.txt` 衔接量，确认无误再执行 long_image.py**。带着已知异常往下跑，只会让注定失败的脚本先跑一轮、白等一次（2026-09-19 实测：末尾静止段造成的重复帧在小样图上肉眼可见，却先跑长图、直到崩溃才发现）。全部确认后再删 `_raw` 中间帧目录
8. **完整长图拼接（用户要才执行，独立脚本）**：`long_image.py` 单独执行（用法见上），见下方「长图拼接公式」

## 长图拼接公式（2026-08-30 实测定稿，以 590×1280 微信录屏为例；脚本已自适应任意分辨率）

将选中帧按像素级对齐拼成一条完整聊天长图——内容一条不漏、缝处无白线，是"内容完整性"的可视化证据（长图 + PDF 双交付：长图证完整，PDF 证排版）。

```
段起点：
  帧1 = y 0（保留状态栏+标题栏作长图开头上下文）
  帧2/3/4 = y (fixed_top + 衔接量)   # 跳过与上帧的重叠区，fixed_top=11
段终点：
  统一 y = 1138   # = 内容窗口下沿(1139) 再向上裁 3px 白线（用户终裁）
  白线定位法：逐行测段底 ±10px 的 mean/std，
    白条行 = mean 240-242 且 std<5（输入框上沿 2px）
    过渡行 = mean ~223 且 std~11（1px）
    内容行 = std 40-60 —— 只裁前两种，内容行一个像素不动
画布背景：微信灰 #EDEDED (237,237,237)
总高校验：Σ段高 = 总推进 + 内容窗口 + fixed_top − 段数×裁线量（本视频 2449+1128+11−4×3=3576），不符=对齐错误
验证：拼接缝 ±6px 逐行 mean/std——上下行 std 都应 >40（内容行直连，无亮线）
```

> 缝2/缝3 若衔接量大（如末段 613px），缝两侧是同一片内容，视觉完全无缝；缝1 衔接小时（159px）缝处是灰背景对灰背景，同样无白线。

## 八个致命坑（都真实踩过）

| 坑 | 症状 | 根因与对策 |
|----|------|-----------|
| ① 全屏搜索 shift 假对齐 | 报告称"重叠130px"实际压了半屏 | 慢滚动录屏画面大量白底，大范围 shift 搜索会饱和到上限得到假匹配（v3 假象）。**只能相邻帧小步长（≤0.6屏）逐帧算，再累加** |
| ② 推进超内容窗口 | 相邻图之间整段气泡开头消失（内容断档） | 固定 UI 占掉 200-290px，可滚动窗口远小于屏高（v6 推进1150>窗口992 漏内容）。**推进上限 = 内容窗口，衔接目标 = 窗口 − 165** |
| ③ 裁剪"缩短"重叠 | 图变短，证据失真 | 重复内容多时的错误解法是裁图。**正确解法永远是回视频重新选帧** |
| ④ 编码黑边 | 每张截图右/下有细黑边 | 编码器把画面补齐到 8/16 倍数（如 589→592、1277→1280），补出的 2-3px 纯黑边烙在每帧边缘。**脚本自动检测并统一裁除**——只去编码补边、恢复真实屏幕区域，屏幕内容一个像素不动，不违反"不裁剪"定则 |
| ⑤ 修白边裁掉文字 | 用户："你把原来的文字给修复掉了，那个白边很细很细，你只要修 3px 就行了" | 错误做法：为消长图缝处白边，大面积裁标题栏（45px）+输入框（6px），把聊天文字一起裁掉。**正确做法：先逐行测量缝 ±10px 的 mean/std，白线实际只有 2px 白条+1px 过渡行，只裁这 3px**。修任何"细线/细边"前必先精确定位行数，禁止按经验扩大裁剪范围 |
| ⑥ 白底页面固定区检测失效（2026-09-05） | 长图里固定栏重复出现 N 次（如公众号文章页作者栏每 ~1100px 重复一次）；选帧推进超真实窗口导致断档 | 按行方差检测固定 UI 依赖"固定区各行稳定"，但**白底文章页（公众号文章/网页）状态栏和吸顶/底栏区域行方差虚高、正文又是纯白**，自动检测出 fixed_top=16/固定下66 的错值。**检测方法：取同段两帧逐行算 |a−b| 均值，diff<3 的行属固定区**（实测：顶部 0-139 diff≈0，y=140 起跳变；底部 y=1128 起 diff≈0）。量出后用 `--fixed-top "组号:值" --fixed-bottom "组号:值"` 手动覆盖重跑（record2evidence.py 与 long_image.py 均支持，格式 `'2:140'` 或 `'1:147,2:140'`） |
| ⑦ 段内无滚动（推进 0）（2026-09-19） | ①同一画面被选成两张相同截图（PDF 出重复图）；②长图脚本 `ValueError: Coordinate 'lower' is less than 'upper'` 或 `IndexError: list index out of range` 崩溃 | 录屏末尾静止看某一屏（点开图片不动、停在最后一屏）时整段 adv≈0，触发两处连锁失效：**（a）选帧收尾** 原条件 `gap < 0.15*W and len(chain) > 1` 中 `len(chain)>1` 让"末帧替换"失效——段内 0 推进时 chain 只有首帧，于是把同画面的末帧当新帧追加；**（b）`content_window`** 对单帧段做行方差，全 0 → 判成"整屏都是固定区"→ 返回负窗口（如 -1277），crop 越界。**修法（已落地）**：选帧去掉 `len(chain)>1` 限制；`content_window` 在 `seg[1]-seg[0] < 2` 时按整帧返回 `(H, 0, 0)`；long_image.py 拼接时跳过 `tops[k] >= bottom_cut` 的重复帧。**诊断法**：同组两帧直接 `ImageChops.difference` 看是否仅剩编码噪声（mean≈15 且无轮廓 = 同画面；注意状态栏时钟跳变会让"顶部行差异"偏大、底部行 diff 接近 0，仍属同画面）。**排查要扫全链**：推进量/内容窗口被"选帧 → 窗口检测 → 长图拼接"三处共用，发现一个失效点后必须一次扫完其余两处再重跑，别修一处跑一轮。**单帧组的长图**：静止段没有跨帧行方差可比、自测不出固定区，脚本会**自动沿用同视频其余组一致的固定UI**（众数、需 ≥2 组一致才外推）；仅当全片都是单帧段时才需手动传 `--fixed-top/--fixed-bottom`。不处理则长图退化成整帧输出、多带一条输入框区（实测多 158px） |
| ⑧ 快滚段被误判场景切换、整段静默丢弃（2026-09-19） | 段与段之间少了一截内容，而**段内衔接与长图缝验证都查不出来**（各自看都"连续"） | 场景切换判据是"shift≈0 且 MAE>18"，但**帧间位移一旦超过 shift 搜索上限（0.6 屏≈766px），搜索饱和同样返回 0** → 快速滚动被误判成切换点 → 紧随的碎片段（< min_seg）被丢弃。这是**跨段盲区**：报告只列段内衔接，跨段没人算。**修法（已落地）**：丢弃前校验"上一保留段末帧 → 下一保留段首帧"的累加推进量，超出「窗口 − 100px」即把缺口区间恢复为独立段并打印告警（宁多一段不漏内容）。**复核动作**：跨段衔接必须用逐帧小步长累加显式算一遍，不能用两帧直接比对（坑①） |

## 素材边界（提前告知用户，不算缺陷）

- **录屏末尾滚动慢的区间**：衔接必然偏大（本视频实测末段 613px）。总推进量固定时，帧间衔接之和也固定，插中间帧只会更糟——这是素材决定的，脚本已在报告中标注
- **录屏末尾静止停留**（停下不动看最后一屏）：该段推进 0，只出一屏（去重后 1 帧），且与相邻段的衔接极大（本视频实测 892px、重叠约 90%），内容与前一屏高度重复——属素材决定，不是重复选帧的错误
- **页面切换的过渡动画帧**（半透明滑入）：不算内容帧，自动剔除
- **自动选帧 ≠ 证据固定**：产出为整理稿/工作快照；正式提交法院建议用帧册人工重做，并保留原始录屏载体

## 交付物清单（输出目录内）

```
录屏证据_<视频名>_一面4块.pdf   # 最终排版（图片右下角顺序编号；--per-page 6 为 3列×2行省纸版式：放大3%单张6.18cm）
聊天记录完整长图.png         # 由独立脚本 long_image.py 生成（证据完整性直观证明）
照片排版_<名>_一面2张.pdf    # 由独立脚本 photo_layout.py 生成（聊天中保存的照片/文件证据排版）
选帧报告.txt                # 每对相邻帧的推进/衔接量明细+备注
selection.json              # 选中帧清单（可复现）
小样图复核/                  # 每页6帧拼图，供人工复核
_raw/                       # 密集帧（复核确认后可删）
```

## 踩坑杂记

- 中文字体注册用 `/System/Library/Fonts/PingFang.ttc`（TTFont），勿用 pdfmetrics 内置 CID 备用字体
- PDF 抽查渲染用 pymupdf（fitz）；qlmanage 只出首页缩略图
- HEVC 录屏 ffmpeg 读取无碍；用户若在浏览器用帧册工具，HEVC 需 Safari
- 抽帧帧率经验：15fps 兼顾精度与耗时（446 帧/30s 视频约 2 分钟）；滚动极快场景升 20fps

## 实战复盘：混合场景录屏（2026-09-05 国力公证讲座素材，一次跑通的全流程）

一条 30s 录屏含两个场景：组1 微信聊天页（灰底）+ 组2 公众号文章页（白底）。自动检测对组1 有效、对组2 失效（坑⑥），本次从发现到修复的完整打法，后续照此办理：

1. **先跑完再诊断，不要预判**：主脚本照常跑，先目检长图整条缩略图 + 各缝 ±30px 拼图。本次靠缩略图发现"作者栏每隔约一个推进量重复一次"。
2. **两个问题签名，指向同一根因（固定区测错）**：
   - 长图里固定栏/状态栏周期性重复 → 固定区被当成滚动内容（fixed 值偏小）
   - 选帧报告衔接量普遍为负或推进 ≥ 窗口 → 窗口 W 虚大（同样是 fixed 偏小）
   白底页报"疑似白线 ⚠"则多为正常段落间背景，**目检确认即可，绝不机械去裁**（坑⑤教训）。
3. **固定区精确测量法（两帧逐行差异）**：取同段相距较远的两帧（如 f_00350 与 f_00400），逐行算 `np.abs(a-b).mean(axis=1)`，diff<3 的行属固定区，diff 跳变处即边界。本次组2 实测：顶部 0–139 diff≈0、y=140 跳变；底部 y=1128 起 diff≈0 → 上140/下150（自动检测误报 上16/下66）。
4. **修正固定区后必须重跑主脚本**，不能只重拼长图——选帧的推进目标 = 窗口−overlap 依赖 W，窗口修正后组2 从 16 帧补到 18 帧，原断档消除。长图用同样参数重跑。
5. **按组覆盖，别动好组**：只对失效的组传覆盖值，格式 `--fixed-top "2:140" --fixed-bottom "2:150"`，组1 继续走自动检测。
6. **终检三件套**：①长图各缝 ±30px 目检（内容连续、无白线、无重复固定栏）；②长图整条缩略图（固定栏只出现一次、正文无断档）；③小样图复核逐页过。总高校验差 0px 为正常口径。
7. **工程细节**：venv 可能缺 reportlab/pypdf（本机 envs/default 补装过）；管理版 venv 跑脚本用绝对路径；多视频连续处理时输出目录按视频名分开。

## 依赖

ffmpeg/ffprobe、numpy、Pillow、reportlab、pypdf（WorkBuddy 管理版 venv 若缺 reportlab/pypdf，用 `envs/default/bin/pip install reportlab pypdf` 补装；系统 python 3.9+ 亦可）。

---

> 法律科技实务工具 · 维护者陆凌燕律师（北京德恒·无锡）