srt-whiteboard-animation 的 annotation.json 字段完整清单：region、sequence、protectedRegions 一文讲透

srt-whiteboard-animation 的 annotation.json 字段完整清单region、sequence、protectedRegions 一文讲透【免费下载链接】srt-whiteboard-animation将 SRT 字幕做成暖米黄纸张底的流式笔迹白板手绘动画 skillmask 分区遮罩编排 stream 连续笔迹ink→color。项目地址: https://gitcode.com/gh_mirrors/sr/srt-whiteboard-animation在 srt-whiteboard-animation 这个 SRT 字幕白板动画 Skill 里annotation.json是把「字幕 → 白板手绘视频」串起来的核心配置文件每个画什么、何时画、画多久、谁保护谁全靠它说了算。本文用仓库自带的示例标注把顶层字段、elements 元素字段、region 坐标、sequence 顺序、protectedRegions 保护区一次性讲透新手照着也能快速看懂并改对配置。上面的动图来自仓库案例三个区域按字幕叙事顺序依次落墨未开始的区域完全隐藏——这正是sequence与reveal.startMs共同编排的效果。一、annotation.json 是什么它是一张图.png的同名伴侣文件例如 examples/scene-01-monkey-mountain-banana.annotation.json 对应scene-01-monkey-mountain-banana.png。渲染器 scripts/render_stream_whiteboard.py 和预览台 assets/preview.html 都直接读取它因此文件名必须与图片同名。二、顶层字段清单字段类型作用sceneId字符串场景编号如scene-01用于多幕管理canvas对象{ width, height }必须与原图像素尺寸完全一致storyBasis字符串该幕字幕的事件摘要帮助标注时对齐叙事sceneDurationMs整数整幕总时长毫秒来自该幕字幕的时间跨度elements数组所有要绘制的元素按叙事顺序排列⚠️ 一个常见坑canvas写错会导致区域坐标整体偏移。标注前务必先获取原图的真实像素宽高。三、elements 元素字段完整清单每个元素描述「画布上的一个区域 它的出场编排」完整字段如下字段位置必填作用id元素✅元素唯一标识如rockerylabel元素✅中文显示名预览图中会标注出来sequence元素✅绘制顺序号从 1 起连续递增narrativeRole元素✅中文说明该元素在叙事中的作用subtitle元素✅对应的 SRT 字幕原文供预览台联动type元素建议structure场景/character人物等region元素✅矩形区域整数像素坐标reveal元素✅出场编排方向、时间、遮罩参数handPath元素建议预览台手部滑行的起止点region整数像素矩形原点左上角region: { x: 20, y: 120, width: 540, height: 780 }规则很硬必须是原图坐标系下的整数像素禁止百分比或估算值且整个矩形必须落在画布内。渲染时该区域就是这支笔的「作画地盘」。sequence按叙事语义排不是按画面位置sequence决定元素的绘制先后排序依据是字幕事件先后推荐节奏为「场景铺垫 → 关键人物/物体 → 动作冲突 → 反应/结果」。示例标注里正好是三段式sequence: 1左侧假山场景 —— 场景铺垫sequence: 2中间抢香蕉的大猴 —— 动作冲突sequence: 3右侧围观小朋友 —— 反应结果在预览台 assets/preview.html 里拖动模块列表即可重排顺序sequence会自动重编号。reveal出场时间编排 protectedRegions 保护区reveal是编排层的核心对象子字段作用direction揭示方向如top_to_bottom仅供预览台矩形代理演示真实笔迹由流式绘制器自动生成startMs开始作画的时间点毫秒durationMs作画时长内部按ink:color 2:1切成「起笔铺线稿 → 添彩」两段maskPaddingPx遮罩外扩缓冲像素protectedRegions本元素需要延后显示的保护区列表时序要点同一幕内各区域应串行作画即下一区域的startMs从上一区域startMs durationMs可加 100–300ms 呼吸间隔开始避免时间轴上互相打架。protectedRegions防止「后续内容提前露脸」这是遮罩编排最关键的一个字段。渲染器的规则是每个区域的允许掩码 自己的region扣除所有后续区域的region再扣除本区域protectedRegions。也就是说当两个主体相互遮挡、或某个矩形框太大可能误伤背景线条时就在较早出场的元素的protectedRegions里框出需要压住的矩形坐标同样是整数像素让被遮挡部分严格等轮到它时才出现。示例里三块区域互不重叠所以都是空数组protectedRegions: []。handPath 与 direction只是「代理」不是真笔迹handPathstart/end/easing配合direction只用于预览台模拟手部滑行演示成片中的真实笔迹由 scripts/render_stream_whiteboard.py 沿骨架或网格自动生成无需精调。四、用完整示例核对字段仓库示例标注可直接打开对照examples/scene-01-monkey-mountain-banana.annotation.json对照示例可以看到典型配置sceneDurationMs: 8600三个元素的startMs分别为300 / 3000 / 5700逐段接力、互不重叠最后一个区域画完后自动补帧到总时长并保证结尾至少停留 0.5 秒完整画面。五、如何校验与编辑字段需求工具解析 SRT 生成建议分镜scripts/parse_srt.py生成区域编号/方向检查图scripts/render_annotation_preview.py可视化拖拽编辑区域、顺序、时间与字幕关联assets/preview.html渲染 MP4 成片scripts/render_stream_whiteboard.py渲染前后建议对照 SKILL.md 中的质量检查清单自查首帧是否为干净纸张底、未开始区域是否提前露线、sequence与字幕事件是否一致、结尾是否有完整画面停留。六、常见误区速查 ❌ 用百分比或估算坐标写region→ ✅ 必须整数像素且先确认canvas与原图一致❌ 按从左到右机械排sequence→ ✅ 按字幕叙事语义排序❌ 重叠主体不设protectedRegions→ ✅ 在较早元素中标出保护区❌ 以为direction控制真实笔迹 → ✅ 它只是预览台演示代理掌握以上字段annotation.json就不再是「神秘配置」而是一份清晰的可读脚本谁先画、画哪里、画多久、护住谁一目了然。【免费下载链接】srt-whiteboard-animation将 SRT 字幕做成暖米黄纸张底的流式笔迹白板手绘动画 skillmask 分区遮罩编排 stream 连续笔迹ink→color。项目地址: https://gitcode.com/gh_mirrors/sr/srt-whiteboard-animation创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考