srt-whiteboard-animation的7步工作流：从字幕文件到成片MP4的完整指南

srt-whiteboard-animation的7步工作流：从字幕文件到成片MP4的完整指南

【免费下载链接】srt-whiteboard-animation将 SRT 字幕做成暖米黄纸张底的流式笔迹白板手绘动画 skill：mask 分区遮罩编排 + stream 连续笔迹（ink→color）。项目地址: https://gitcode.com/gh_mirrors/sr/srt-whiteboard-animation

srt-whiteboard-animation 是一款把SRT 字幕转成白板手绘动画视频的开源工具：线稿以连续手写笔迹在暖米黄纸张背景上逐笔浮现，跟随字幕叙事依次出场，最终导出成片MP4。知识讲解、故事口播、课程字幕，都能用它变成温暖的手绘风视频。下面以仓库自带的"猴子山抢香蕉"案例，带你完整走一遍从字幕文件到成片 MP4 的 7 步工作流。

这种白板手绘动画是怎么实现的？

工具的核心是两套机制的组合（详见 SKILL.md）：

• 分区遮罩编排：画面被切分为若干区域，按字幕叙事顺序逐个揭示，未开始的区域完全隐藏，重叠对象用protectedRegions保护区防止提前露线；
• 流式笔迹画法：每个区域内，"手"沿骨架/网格连续滑行落墨，先ink铺线稿、再color添彩（权重 2:1），所有区域共享一张持久画布。

与逐格跳变的"擦除式"白板不同，这里的笔迹是连贯流动的，而且出场顺序由字幕事件驱动，而不是画面坐标。

准备：两条命令搭好 Python 环境

工具自带依赖隔离的虚拟环境准备脚本 scripts/prepare_env.py，首次使用执行：

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

成功后第一条命令会输出ENV_PY=<解释器路径>，后续渲染命令都用这个解释器运行，保证依赖互不干扰。

第1步：解析SRT字幕，生成建议分镜

用 scripts/parse_srt.py 把字幕解析成结构化字幕条，并按"每幕 25–35 秒口播"自动分组：

python scripts/parse_srt.py <字幕.srt> --target-sec 30 --min-sec 25 --max-sec 35

输出包含每个场景的起止时间、时长（即后续标注里的sceneDurationMs）和字幕文本。据此确定配图策略：每幕的场景编号、核心表达、画面主体、对应字幕区间。关键原则是——每幕只表达一个核心意思。策略确认后，再进入下一步。

第2步：生成统一风格的线稿图

确认策略后，逐幕生成 16:9 的线稿图。所有场景必须遵循同一套视觉语言，保证系列感：

• 暖米黄旧纸张背景（建议#F5EBD7），禁止纯白；
• 深灰色素描线条，红、橙、蓝仅作少量概念性点缀；
• 极简手绘、干净背景、充足留白；
• 画面中不得出现文字、摄影感、3D 效果或复杂纹理。

仓库里的"猴子山抢香蕉"线稿就是这个标准的成品：

主体之间保留充足留白，是后续自动拆分区域的关键。

第3步：先读字幕再看图，创建 annotation.json

这一步不能只凭字幕臆测画面，也不能只按画面位置机械排序。正确做法是：先读该幕字幕 → 实际查看图片 → 获取原图像素宽高，再把图中主体对应到字幕事件，按"场景铺垫 → 关键人物/物体 → 动作或变化 → 反应/结果"的语义顺序安排绘制。

随后创建与图片同名的<图片名>.annotation.json，每个元素包含：

• sequence/narrativeRole/subtitle：绘制顺序、叙事作用、对应字幕文本；
• region：原图坐标系的整数像素矩形区域；
• reveal：startMs、durationMs起始时序与protectedRegions保护区。

仓库自带一份可直接参考的完整标注：examples/scene-01-monkey-mountain-banana.annotation.json。JSON 创建完成后，用 Chrome/Edge 打开 assets/preview.html，通过"打开文件夹"载入标注所在目录，即可在预览台中可视化查看每个区域的编号与顺序。

第4步：生成区域检查图，核对分区与顺序

标注初稿确认后，用 scripts/render_annotation_preview.py 出编号检查图：

python scripts/render_annotation_preview.py <图片路径> <标注路径> <预览图输出路径>

对着检查图核对三件事：编号顺序是否与字幕叙事一致、区域是否都在画布内、相互遮挡的主体是否已用protectedRegions保护。

第5步：预览台拖拽调整区域、顺序与时间

检查图没问题后，回到预览台做精细调整：

• 拖区域四边四角修改region范围；
• 右侧修改名称、开始/结束时间（startMs/durationMs）与对应字幕，选中模块会自动高亮相关字幕；
• 拖动模块列表调整顺序，sequence自动重排；
• 拖时间轴或按播放按钮，预览揭示过程（未开始区域不显示）；
• 点"保存"写回原.annotation.json，并把sceneDurationMs对齐到最后区域结束 + 0.5 秒。

调整完保存，即可进入渲染环节——不用凭空反复出片，改标注、再渲染才是正解。

第6步：命令行渲染单幕成片MP4

确认最终标注与时序后，用 scripts/render_stream_whiteboard.py 逐幕渲染全清 MP4：

<ENV_PY> scripts/render_stream_whiteboard.py <图片路径> <标注路径> <输出.mp4> assets/drawing-hand.png \ --ink-path grid --color-fill contour-wipe

其中 assets/drawing-hand.png 是渲染时执笔的手部素材，笔尖会贴近当前正在推进的笔迹：

两个常用参数：线稿清晰的插画可换--ink-path skeleton（骨架追踪，笔迹更贴合）；上色风格可选--color-fill brush（沿轨迹刷）。渲染后抽查开场、重叠模块中段、结尾三个时间点：未绘制区域不可见、保护区不漏线、结尾完整停留。

第7步：多幕合并为完整成片

多幕项目确认每一幕成片后，用 scripts/merge_scenes.py 按分镜顺序合并成一条：

<ENV_PY> scripts/merge_scenes.py --inputs 幕1.mp4 幕2.mp4 幕3.mp4 --output final.mp4

合并后顺序、时长应与字幕分镜一致。单幕项目可直接跳过这一步。

成片质量自检清单 📋

出片前后对照检查（摘自 README.md 质量检查）：

• 首帧是干净的暖米黄纸张底色，没有提前露出的线条；
• canvas与原图像素尺寸一致，所有区域都是画布内的整数像素坐标；
• sequence、startMs与字幕叙事顺序一致；
• 中段帧中，未开始区域和保护区不会提前出现；
• 每幕结束后至少停留 0.5 秒完整画面；多幕合并顺序与字幕分镜一致。

素材目录约定与相关文件

项目素材统一放在assets/whiteboard/<项目名>/下，图片与标注必须同名（scene-01-demo.png对应scene-01-demo.annotation.json）：

assets/whiteboard/<项目名>/ ├── scene-01-<名称>.png ├── scene-01-<名称>.annotation.json ├── scene-01-<名称>-whiteboard.mp4 └── scene-01-<名称>-preview.mp4

工作流中每一步都会暂停等待确认，避免在分镜、线稿或标注未定稿时浪费渲染成本。更完整的约束与参数说明见 SKILL.md 与 README.md，完整案例素材可在examples/目录中找到。按这 7 步走一遍，你的 SRT 字幕就能变成一板一画的手绘风 MP4 了 ✍️

【免费下载链接】srt-whiteboard-animation将 SRT 字幕做成暖米黄纸张底的流式笔迹白板手绘动画 skill：mask 分区遮罩编排 + stream 连续笔迹（ink→color）。项目地址: https://gitcode.com/gh_mirrors/sr/srt-whiteboard-animation