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 的产物命名与文案中不使用该词。
核心定则(用户拍板,不可违反)
- 绝不裁剪:每帧都是原始完整截图。裁过的图"变短了",不是原始截图(v2 被否)
- 相邻两图衔接 = 下图压上图 165px(默认,约一行多微信消息,该视频实测实际衔接 159-163px):选帧目标是「内容窗口 − 165」即推进 ≈ 窗口 − 165。⚠️ 因帧间滚动离散,名义 overlap 与实际衔接会有偏差(本视频 165 档实测 159-163px),只要衔接 >100px 即不断档。若视频总滚动量不足(末段推进 < 目标),末帧照常并入放长,允许多压前一张图信息——这是素材决定,不是缺陷(用户 2026-08-30 裁定)
- 推进量不得超过内容窗口高度:录屏界面顶部状态栏/导航栏、底部输入框是固定 UI,不随滚动移动,实际内容窗口 = 屏高 − 固定区(微信聊天页本视频实测 1128px = 1280 − 固定UI上11/下139;文章页约 1165-1196px;小屏机型窗口更小,见坑②的 992px 案例)。推进超过窗口高度 = 中间漏内容
- 长图拼接缝处白线只裁精确像素行(用户 2026-08-30 终裁 3px):白线 = 每帧段底的输入框上沿白条(约 2px,行 mean 240-242 且 std<5)+1px 过渡行(mean
223 std11)。修白边前必须逐行测量缝 ±10px 的 mean/std 定位白线精确行数,只裁问题行——绝不为此大面积裁标题栏/输入框/工具栏(实测教训:裁掉 45px 标题栏导致文字丢失,被用户否决"你把原来的文字给修复掉了,白边很细很细")。先按用户口径试裁(5px 嫌大 → 3px 定稿)
一条命令用法
python3 ~/.workbuddy/skills/video-to-evidence-layout/scripts/record2evidence.py 录屏.mp4 -o 输出目录
完整长图(独立脚本,按需单独生成,主脚本跑完后执行):
python3 ~/.workbuddy/skills/video-to-evidence-layout/scripts/long_image.py 输出目录
聊天里保存的照片/文件证据排版(独立脚本,与本 skill 主流程分工:主流程管录屏→截图,本脚本管照片→排版):
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 步人工)
- 侦察:ffprobe 取时长/分辨率
- 密集抽帧:15fps(滚动快的录屏加密到 20fps);随后自动检测并裁除编码黑边(见坑④),只去补边不动屏幕内容
- 逐帧滚动偏移:相邻帧小步长(上限 0.6 屏)灰度 MAE 对齐,得每帧推进量——全屏搜索必假对齐,见坑①
- 自动分段:原地内容突变(shift≈0 且 MAE>18)判场景切换;短于 0.5s 的过渡段(半透明滑入动画)自动丢弃;每段按行方差自动测内容窗口
- 选链:段内累加推进,达「内容窗口 − overlap」选帧;末帧并入(若与上帧推进 <0.15 窗口则替换,去停顿重复)
- 排版+自检:A4 竖版(每页1/2/4/6张可选)、等比完整居中不裁剪、每张图右下角跨页连续顺序编号 1,2,3…(白底黑字小标签)、阅读顺序左上→右上→左下→右下;页面底部不打页码(2026-08-31 用户拍板取消,图片编号已可定位);自检页数/帧数/绘制尺寸一致性
- ⚠️ 复核顺序铁律:先复核、后长图(必做):跑主脚本前先问用户两件事——①要一面4块(单张更大)还是一面6块(省纸,单张6.0cm,微信截图优先建议6块);②要不要顺便生成完整聊天长图。主脚本跑完后,必须先把
小样图复核/逐页看完(查重复图/断档)+ 核对选帧报告.txt衔接量,确认无误再执行 long_image.py。带着已知异常往下跑,只会让注定失败的脚本先跑一轮、白等一次(2026-09-19 实测:末尾静止段造成的重复帧在小样图上肉眼可见,却先跑长图、直到崩溃才发现)。全部确认后再删_raw中间帧目录 - 完整长图拼接(用户要才执行,独立脚本):
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 的错值。**检测方法:取同段两帧逐行算 |
| ⑦ 段内无滚动(推进 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 失效(坑⑥),本次从发现到修复的完整打法,后续照此办理:
- 先跑完再诊断,不要预判:主脚本照常跑,先目检长图整条缩略图 + 各缝 ±30px 拼图。本次靠缩略图发现"作者栏每隔约一个推进量重复一次"。
- 两个问题签名,指向同一根因(固定区测错):
- 长图里固定栏/状态栏周期性重复 → 固定区被当成滚动内容(fixed 值偏小)
- 选帧报告衔接量普遍为负或推进 ≥ 窗口 → 窗口 W 虚大(同样是 fixed 偏小) 白底页报"疑似白线 ⚠"则多为正常段落间背景,目检确认即可,绝不机械去裁(坑⑤教训)。
- 固定区精确测量法(两帧逐行差异):取同段相距较远的两帧(如 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)。 - 修正固定区后必须重跑主脚本,不能只重拼长图——选帧的推进目标 = 窗口−overlap 依赖 W,窗口修正后组2 从 16 帧补到 18 帧,原断档消除。长图用同样参数重跑。
- 按组覆盖,别动好组:只对失效的组传覆盖值,格式
--fixed-top "2:140" --fixed-bottom "2:150",组1 继续走自动检测。 - 终检三件套:①长图各缝 ±30px 目检(内容连续、无白线、无重复固定栏);②长图整条缩略图(固定栏只出现一次、正文无断档);③小样图复核逐页过。总高校验差 0px 为正常口径。
- 工程细节: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+ 亦可)。
法律科技实务工具 · 维护者陆凌燕律师(北京德恒·无锡)