SRT 白板动画出片前验收：从首帧、遮罩到 MP4 合片的渲染检查表

白板动画真正难验收的地方，不是画面有没有动，而是观众在不该看到的时间看到了什么。一条线提前露出、后续人物的轮廓穿过前景、字幕已经说完但画面还没画完，都会让成片像演示稿而不是可交付的视频。srt-whiteboard-animation 的思路很明确：SRT 决定叙事顺序，annotation.json 负责区域与时序，流式绘制器负责在允许的掩码里落墨，最后再把各幕 MP4 合成完整视频。验收时也应该沿着这条链路逐层检查，而不是只打开最终文件看一眼。

先把验收对象和目录固定下来

一幕至少应有一张源图、一个同名标注文件和一条输出视频，例如 scene-01-demo.png、scene-01-demo.annotation.json、scene-01-demo-whiteboard.mp4。图片与 JSON 不同名，预览台就无法可靠地把标注加载到对应画布上；把标注散落在临时目录里，后续改顺序、重渲染和追溯版本都会变得困难。

首次准备环境不要直接拿系统 Python 碰运气。仓库给出的检查入口是：

python scripts/prepare_env.py --check; python scripts/prepare_env.py

记录第一条命令末行输出的 ENV_PY=...，之后的区域预览、单幕渲染和合片都使用这个解释器。这样 OpenCV、NumPy、PyAV 等依赖不会因为机器上另一个虚拟环境的版本不同而改变结果。验收记录中应保留解释器路径、输入文件名和渲染参数，尤其是多人协作或需要返工时。

首帧先过关：纸张干净，故事不能偷跑

把视频拖到开头，首帧必须是干净的暖米黄色纸张底。项目建议使用 #F5EBD7 一类的旧纸色，而不是纯白背景；更重要的是，首帧不能提前露出线稿、填色、人物局部或后续区域的背景纹理。首帧验收不是审美项，而是编排正确性的第一个证据：如果第一帧已经有内容，说明遮罩、时间判断或源图底色处理至少有一处不符合约束。

不要只看播放器暂停后的缩略图。播放器可能显示关键帧或缩放后的画面，应逐帧抽查视频开头，并在播放器中放大画布四角、对象交界处和第一序列区域的边缘。背景应连续，不能有一块矩形比周围更白，也不能有被擦除后留下的边缘。若源图本身带了文字、标签、数字或复杂纹理，也应在渲染前退回素材；视觉规范要求场景源图保持极简手绘，不把字幕或说明文字画进画面。

先验收画布和区域，再看动画效果

打开 annotation.json，先检查 canvas.width 与 canvas.height 是否等于源 PNG 的真实像素尺寸。每个 region 的 x、y、width、height 都必须是整数，且不能越过画布边界。这里不能用“看起来差不多”的比例坐标替代像素坐标；一旦源图被缩放或裁切，矩形代理、流式笔迹和保护区会各自落在不同位置。

可以先生成编号与方向检查图：

python scripts/render_annotation_preview.py assets/whiteboard/demo/scene-01-demo.png assets/whiteboard/demo/scene-01-demo.annotation.json assets/whiteboard/demo/scene-01-demo-annotation.png

检查图的用途不是证明成片好看，而是核对编号、标签、矩形和原图主体是否对应。重点看四件事：场景铺垫是否排在关键人物之前，动作或变化是否排在相关对象之后，反应或结果是否没有抢跑，以及每个区域是否真的覆盖了应该绘制的主体。若顺序只是按画面从左到右排列，却与字幕事件相反，就应先改 annotation，而不是靠改变笔刷方向掩盖问题。

遮罩与重叠保护：中段最容易暴露问题

每个区域的允许掩码，等于当前矩形扣除所有后续模块的区域，再扣除当前模块的 protectedRegions。这条规则解决的是一个常见穿帮：前景区域的矩形很大，流式笔迹在画边缘时碰到了后续人物；即使后续人物的 startMs 尚未到，轮廓也会提前出现。对于互相遮挡的对象，保护区要用与 region 相同的原图整数像素坐标填写，不能只在预览台里凭感觉缩小框。

抽查时不要只看第一秒和最后一秒。选择一个正在绘制前景、但后续对象尚未开始的中段时间点，确认后续对象的线条和填色完全不可见；再选择交叠对象刚开始绘制的时间点，确认它不会从前一个区域的边界突然穿出。检查画面中人物手臂、山体轮廓、道具边缘和细长线条，这些位置最容易漏保护。预览台里的矩形揭示是代理演示，真正成片由流式绘制器生成，所以预览台通过并不等于 MP4 已经通过，必须对渲染结果复查。

时序不是填数字：要和字幕事件对齐

sceneDurationMs 应来自该幕字幕的时间跨度，建议每幕控制在 25 到 35 秒。可以先用仓库脚本解析字幕并获得分镜建议：

python scripts/parse_srt.py 讲解.srt --target-sec 30 --min-sec 25 --max-sec 35

拿到建议后，逐个对照 sequence、startMs、durationMs 和 subtitle。同一幕是一支笔在持续移动，区域默认应串行作画，后一个区域的 startMs 不应早于前一个区域结束；如果刻意安排 100 到 300 毫秒的呼吸，也要能解释它对应的字幕停顿或叙事转折。不要让“关键画面”因为占比大就提前出现，也不要为了填满时长让一个已经说完的动作拖到下一句字幕。

每个区域内部会按约 2:1 的 ink 与 color 时间比例先铺线稿、再添彩。验收时看线稿是否先建立轮廓，颜色是否在对象可辨认后进入；如果颜色先于线稿出现，或者多个区域颜色同时跳出，通常是标注时序或渲染输入出了问题。全部区域完成后，结尾至少应保留 0.5 秒完整画面，让观众有时间读到结果，也避免视频在最后一笔刚落下时突然切黑。

手路径要服务于笔迹，而不是制造假动作

标注里的 handPath.start、handPath.end 和 easing 主要给预览台的矩形代理使用；最终真实笔迹由流式绘制器自动生成，不能把代理路径当成成片轨迹的精确承诺。播放中段时，手部素材应贴近当前正在推进的线条，不能漂在对象另一侧，也不能在没有新笔迹的地方长时间遮住画面。若线稿边缘清楚，可以尝试骨架路径：

<ENV_PY> scripts/render_stream_whiteboard.py assets/whiteboard/demo/scene-01-demo.png assets/whiteboard/demo/scene-01-demo.annotation.json assets/whiteboard/demo/scene-01-demo-whiteboard.mp4 assets/drawing-hand.png --ink-path skeleton --color-fill contour-wipe

线条复杂、噪声较多时，先使用较稳妥的 --ink-path grid，不要为了“更像手画”盲目切换 skeleton。两种路径都应在相同源图和标注下对比首帧、中段、交叠边界与结尾。验收标准是笔迹连贯、对象没有越界、手部动作与落墨同步，而不是路径名称更高级。

MP4 输出要检查容器，也要检查内容

正式渲染使用环境解释器和流式渲染脚本，若没有显式传入总时长，就让脚本读取标注里的 sceneDurationMs：

<ENV_PY> scripts/render_stream_whiteboard.py assets/whiteboard/demo/scene-01-demo.png assets/whiteboard/demo/scene-01-demo.annotation.json assets/whiteboard/demo/scene-01-demo-whiteboard.mp4 assets/drawing-hand.png --ink-path grid --color-fill contour-wipe

命令末行应出现 OUTPUT=...。这只证明脚本写出了目标路径，不代表画面合格。验收应确认文件确实是 MP4、能被常用播放器打开、时长与标注一致，且没有只生成音频、零帧、黑屏或尾部截断。再按固定的三个检查点抽帧：开场看首帧和提前露出，中段看遮罩与手路径，末尾看完整画面和至少 0.5 秒停留。相同输入重复渲染时，输出时长、画布尺寸、区域顺序和关键检查点应保持一致；若只是编码元数据或压缩细节有差异，也要记录工具版本和参数，避免把不可解释的视觉差异带进发布流程。

多幕合并：顺序正确比“文件变大”更重要

每一幕单独通过验收后，才进入合片。多幕项目使用仓库提供的合并命令：

<ENV_PY> scripts/merge_scenes.py --inputs scene-01.mp4 scene-02.mp4 scene-03.mp4 --output final.mp4

输入顺序必须与字幕分镜顺序一致，不能按文件系统排序或文件生成时间猜测。合片后检查第一幕结尾到第二幕开头的切换，确认没有少幕、倒序、重复一幕或把预览 MP4 当成正式成片。逐幕总时长相加后，应与最终视频时长在编码误差范围内一致；如果合片后某幕时长明显缩短，先回到单幕输出检查，不要只重新运行合并命令。最终视频还要从头到尾快速浏览一次，确认每幕的暖纸背景、线条风格和手部素材没有突变。

把重复性作为最后一道验收门

生产交付不应依赖“这次刚好成功”。保留原始 SRT、PNG、annotation.json、环境解释器路径、渲染参数和合片输入列表，清理旧 MP4 后重新执行一次。第二次应再次通过首帧、重叠中段、末帧和合片顺序检查。若修改了区域、顺序或时间，必须先在 assets/preview.html 中保存标注，再重新生成预览图和 MP4；不要手改视频，也不要在旧成片上继续合片。

可以把验收结果写成四个明确结论：首帧没有提前内容；中段未开始区域与保护区没有漏出；所有区域按字幕语义串行完成且结尾留出完整画面；同一输入经过同一命令可重复得到结构一致的 MP4。四项有一项答不上来，就还不能称为成片。这个项目的价值不只是把字幕和图片拼成视频，而是把“什么时候可以看到什么”变成可检查的渲染契约；验收也应围绕这份契约，而不是围绕播放器里一闪而过的第一印象。更多字段和脚本边界可直接核对 项目 README 与 SKILL.md。