白板动画真正难的地方，不是画出一只手、一座山或一个箭头，而是让画面在正确的时刻出现，并且持续服务于口播。很多流程把字幕当作最后叠加的轨道：先完成画面，再对齐配音，字幕只是校对。SRT Whiteboard Animation 反过来处理这件事：SRT 是叙事时钟，字幕事件决定元素的出场顺序，annotation.json 把事件落到画布区域，流式渲染器再把区域变成连续的手绘笔迹。
它的价值不是一句“自动生成白板视频”，而是把原本藏在剪辑师脑中的判断拆成可以检查、拖动和保存的中间状态。分镜策略、线稿、标注、预览修改和逐幕 MP4 各自承担职责，最终视频不再是一次性的黑盒，而是一条能返工的视觉生产链。
两层模型：编排先于画法
项目不是把字幕逐字变成大字，也不是对整张插画做一次矩形擦除。README 与 SKILL.md 把工作拆成两层。编排层用区域、字幕关联、语义角色、顺序和遮罩决定“什么可以出现”；画法层用 stream 连续笔迹决定“允许出现的像素如何被画出”。先用 ink 铺线稿，再用 color 添彩，才能把叙事顺序和手绘质感分开控制。
每幕应按“场景铺垫 → 关键人物或物体 → 动作或变化 → 反应或结果”组织。--ink-path grid 是稳妥的默认路径，线稿足够清楚时可试 skeleton；上色默认使用 --color-fill contour-wipe。如果人物出现太早，应改区域或时间，而不是重做源图；如果笔迹不贴轮廓，再比较 grid 和 skeleton。
先把 SRT 变成事件表
官方脚本可以先提出分幕建议：
python scripts/parse_srt.py <字幕.srt> --target-sec 30 --min-sec 25 --max-sec 3525 到 35 秒是管理起点，不是硬规则。每幕最好只表达一个核心意思。解析结果需要人工整理成 story basis，回答谁、做什么、发生什么变化、结果是什么。比如环境出现属于铺垫，角色拿着道具属于关键对象，抢走道具属于动作冲突，围观者出现属于结果。否则后面很容易按画面从左到右排序，而不是按字幕事件排序。
- 字幕时间说明口播何时发生，不自动说明画面需要多少细节。
- 一个字幕条可以支持多个连续元素，只要其中有真实的语义变化。
- 空白时间可以让观众理解，不要用装饰动作强行填满。
- 一幕若有两个独立结论，应该拆幕，而不是继续增加区域。
源图要为可拆分而设计
项目要求暖米黄色纸张背景，建议使用 #F5EBD7，搭配深灰素描线条，红、橙、蓝只作少量概念点缀。源图应简洁、有留白，不使用场景文字、标签、数字、摄影细节、3D 效果或复杂纹理。这不是单纯审美偏好：如果人物、道具、背景线条挤在同一片密集矩形里，后续就很难定义只覆盖目标对象的 region。
把源图当成几个能独立解释的视觉模块。背景结构、人物、道具和动作方向最好有可辨边界；对象重叠时提前预留 protectedRegions。源图越复杂，静态效果可能越漂亮，但区域遮罩、skeleton 追踪和首帧检查都会变难。白板视频优先表达关系和变化，不是展示精细插画。
annotation.json 是可编辑控制面
标注文件是字幕语义和画布之间的合同。sceneId 标识场景，canvas.width 与 canvas.height 必须等于原图像素尺寸，storyBasis 保存事件摘要，sceneDurationMs 保存整幕时间并包含至少 0.5 秒收尾。每个元素需要连续的 sequence、中文 narrativeRole、对应字幕原文 subtitle、整数像素 region、包含 startMs 和 durationMs 的 reveal，以及供预览代理使用的 handPath。
region 不是百分比，也不能靠估算。原点在左上角，x、y、width、height 都应是画布内的整数。矩形过大并不更安全，因为它可能把尚未出场的邻近对象带进允许掩码。sequence、startMs 和 label 要反映字幕事件，而不能只反映画面位置。
遮罩保护决定时序是否可信
同一幕的 stream 画法是一支笔串行移动，区域的 startMs 原则上不重叠；区域之间可以留 100 到 300 毫秒呼吸。区域内部先 ink 后 color，默认比例约为 2:1。任意时间 t，尚未开始的模块不能露出线条、填充或图像。一个区域的允许掩码等于自己的 region，扣除所有后续模块的 region，再扣除自身的 protectedRegions。
人物手臂遮住道具、前景角色压住背景线条时，早期元素必须写出需要延后的重叠区。这样 sequence 正确时，宽矩形也不会把后续主体局部提前显示。direction 和 handPath 主要是预览台的矩形代理，并不代表最终真实笔迹；不要用调整代理直线来掩盖遮罩错误。
预览台负责返工，渲染负责验收
创建标注后，按文档打开 assets/preview.html，用“打开文件夹”载入包含同名 PNG 与 annotation.json 的目录。预览台能改区域、名称、方向、开始和结束时间、字幕关联，也能拖模块列表重排 sequence。人物太早、区域太宽、字幕连错对象、结尾不够停留，都应先在这里修。File System Access API 主要适用于 Chrome 或 Edge，其他浏览器可能需要下载 JSON 后手动覆盖。
环境准备先检查再创建隔离环境：
python scripts/prepare_env.py --check
python scripts/prepare_env.py捕获 ENV_PY 后，用该解释器逐幕渲染：
<ENV_PY> scripts/render_stream_whiteboard.py <图片> <标注> <输出.mp4> assets/drawing-hand.png --ink-path grid --color-fill contour-wipe单幕通过后再合并：
<ENV_PY> scripts/merge_scenes.py --inputs 幕1.mp4 幕2.mp4 --output final.mp4渲染检查至少覆盖开场、中段重叠模块和结尾。首帧只能有暖米黄纸张底，中段不能泄露未开始区域，结尾要显示完整原图并停留至少半秒。合并只能处理顺序，不能修复错误分镜、字幕漂移或音频混音。
实际边界：它不是通用动画软件
SRT 只有文本和时间码，不包含情绪、镜头语言、表演、音效或可靠的视觉语义。字幕切得过碎、时间码漂移或句子缺少关系时，解析脚本只能建议分幕，不能凭空创造好分镜。矩形区域和遮罩最适合少量可分离的概念插画，不适合大量细小对象、复杂透视、快速镜头、照片证据或精确逐帧表演。skeleton 可能更贴轮廓，但不保证适合每种线稿；grid 更稳，却可能牺牲贴合度。画布尺寸、区域数量和幕数增加，渲染成本也会增加。
暖米黄纸张和克制配色能形成系列风格，却不适合高饱和产品界面或密集数据图。判断标准不是“能不能生成”，而是逐步绘制是否比普通剪辑、屏幕录制或信息图更能帮助观众理解。
从一幕试点开始
最适合的项目有稳定旁白、清晰事件顺序、每幕少量主体，并且需要经常调整出场时间。课程解释、故事口播、概念演示和知识短片都可以试。最稳的顺序是：真实 SRT 解析、确认一幕分镜、制作低复杂度源图、完成 annotation.json、在预览台修正时序、逐幕渲染并检查三个时间点，最后才扩展到多幕合并。这样保留的不是一条不可解释的视频结果，而是一套能审查、修改、复用的字幕驱动生产结构。详情见 官方仓库 的 README 与 SKILL.md。