srt-whiteboard-animation：SRT 字幕转白板手绘视频

SRT 白板动画 Skill 详细部署教程

项目概述

srt-whiteboard-animation 是一个将 SRT 字幕转换为按叙事顺序绘制的白板手绘视频的 AI Skill。它结合了分区遮罩编排与流式笔迹绘制，每个元素跟随字幕依次出场，笔尖在区域内连续落墨，再逐步添彩，最终导出 MP4。

核心机制：

• 分区遮罩：将画布按区域切分，每块对应一个元素（人物、道具、场景），只在被分配的时间窗口内显示
• 流式笔迹：在区域内连续落墨绘制——先 ink 铺线稿，再 color 添彩，完全模拟真人手绘
• 字幕驱动：按字幕事件而非画面坐标，为元素建立语义化的绘制顺序
• 逐步确认：工作流拆分为 7 步，每步完成后等待确认，避免分镜未定稿就开始渲染浪费算力

适用场景：知识讲解、故事口播、课程字幕、短视频文案制作成暖米黄色纸张底的手绘动画。

视觉规范：暖米黄色纸张背景（建议 #F5EBD7）、深灰色素描线条，红橙蓝仅作少量概念性点缀。

---

部署前准备

系统要求

项目	要求
操作系统	Windows / macOS / Linux（本次教程以 Windows 为例）
Python	3.8+（项目自带独立的 Python 虚拟环境准备脚本）
AI Agent	Codex（推荐）或 Claude Code，需支持 Skills 功能
磁盘空间	最低 1GB（用于虚拟环境和渲染输出）

安装 AI Agent

根据社区实践经验，最省事的安装方式是把仓库地址发给 Codex。如果你的 Codex 能够使用 Skills 功能，安装过程会非常简单。

---

方案一：通过 AI Agent 安装（推荐）

这是最简单的方式，适合大多数用户。

步骤 1：向 AI Agent 发送安装请求

打开 Codex 或其他支持 Skills 的 AI Agent，发送以下提示：

text

帮我安装这个 Skill：github.com/geeklee/srt-whiteboard-animation

Agent 会自动读取仓库信息并完成 Skill 的安装。

步骤 2：验证安装

安装完成后，你可以在 Agent 中确认 Skill 是否可用。

步骤 3：使用 Skill

准备一份标准 SRT 字幕文件（格式如下）：

text

1
00:00:00,000 --> 00:00:05,000
小猴子坐在猴子山顶，手里拿着香蕉。

2
00:00:05,000 --> 00:00:10,000
大猴子看到了，一把抢走了香蕉。

然后将字幕文件发给 Agent，并说：

text

把这个字幕做成白板动画。

Agent 会按照工作流逐步执行。

---

方案二：手动安装（通过 Skills CLI）

如果你使用 Claude Code、Cursor 等支持 Skills CLI 的 Agent，可以使用以下命令安装。

步骤 1：执行安装命令

npx skills add geeklee/srt-whiteboard-animation --skill srt-whiteboard-animation -g -y

参数说明：

• -g：全局安装
• -y：跳过确认

步骤 2：验证安装

安装完成后，可以在 Agent 中使用 /skills 命令查看已安装的 Skill。

---

方案三：从源码克隆并手动配置

如果你需要自定义或进行开发，可以手动克隆仓库。

步骤 1：克隆仓库

git clone https://github.com/geeklee/srt-whiteboard-animation.git
cd srt-whiteboard-animation

步骤 2：准备 Python 虚拟环境

Skill 自带独立的 Python 虚拟环境准备脚本。首次运行时执行：

# 检查环境
python scripts/prepare_env.py --check

# 准备环境
python scripts/prepare_env.py

成功后第一条命令会输出 ENV_PY=<路径>；后续渲染请使用该解释器，确保依赖隔离。

步骤 3：验证环境

# 使用输出的解释器路径验证
<ENV_PY> -c "import cv2; print('OpenCV 版本:', cv2.__version__)"

---

工作流详解

SRT 白板动画 Skill 的关键在于字幕驱动、逐步确认。每一步完成后都等待确认，避免在分镜、线稿或标注尚未定稿时浪费渲染成本：

Step 1：解析 SRT，输出分镜与配图策略

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

按建议的 25–35 秒时长拆分场景，输出分镜建议。

Step 2：确认后生成统一风格的线稿

Agent 会根据分镜生成统一风格的线稿（极简手绘插图、纯素描草图风格）。

Step 3：创建标注并载入预览台

确认线稿后，结合字幕和原图创建标注（annotation.json），并载入预览台。

Step 4：生成分区与方向检查图

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

Step 5：在预览台调整

打开 assets/preview.html，使用”打开文件夹”载入场景目录，即可编辑区域、顺序、时间与字幕关联。

Step 6：逐幕渲染 MP4

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

Step 7：多幕项目合并

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

---

标注格式说明

每个元素使用原图的整数像素坐标，并通过 sequence、subtitle 与 narrativeRole 关联字幕中的事件。区域应按”场景铺垫 → 关键人物/物体 → 动作或变化 → 反应/结果”排序：

{
  "sceneId": "scene-01",
  "canvas": { "width": 1672, "height": 941 },
  "storyBasis": "小猴在猴子山上拿着香蕉，大猴抢走香蕉，孩子们在旁观看。",
  "sceneDurationMs": 9000,
  "elements": [
    {
      "id": "rockery",
      "label": "猴子山场景",
      "sequence": 1,
      "narrativeRole": "故事的场景铺垫",
      "subtitle": "小猴子坐在猴子山顶，手里拿着香蕉。",
      "type": "structure",
      "region": { "x": 20, "y": 120, "width": 540, "height": 780 },
      "reveal": {
        "direction": "top_to_bottom",
        "startMs": 300,
        "durationMs": 2600,
        "maskPaddingPx": 22,
        "protectedRegions": []
      },
      "handPath": { "start": [290, 130], "end": [290, 890], "easing": "easeInOut" }
    }
  ]
}

关键字段说明：

• sequence：叙事顺序编号
• narrativeRole：在故事中的角色
• subtitle：关联的字幕内容
• protectedRegions：需要延后显示的区域（避免遮挡元素提前露出）
• handPath：手部运动路径（用于预览台矩形代理）

---

项目素材结构

text

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

图片与标注必须同名，例如 scene-01-demo.png 对应 scene-01-demo.annotation.json。

---

质量检查清单

根据官方文档，渲染完成后应检查以下内容：

• □

  首帧是干净的暖米黄纸张底色，没有提前露出的线条

• □

  canvas 与原图尺寸一致，所有区域都是画布内的整数像素坐标

• □

  sequence、startMs 与字幕的叙事顺序一致

• □

  中段帧中，未开始区域和保护区不会提前出现

• □

  笔尖贴近当前流式笔迹；线稿清晰时可选择 --ink-path skeleton

• □

  每幕结束后至少停留 0.5 秒完整画面

• □

  多幕合并顺序与字幕分镜一致

---

实践经验分享

根据社区用户的实际测试经验：

适合的内容类型

1. 故事类内容：如”猴子山抢香蕉”，有清晰的情节推进
2. 知识科普：如”水循环”，有明显的变化过程
3. 概念讲解：如”AI Agent 工作流程”，用图标和简单动作表达

操作建议

• 画图前：检查分镜是否把一句话拆得太碎
• 视频出来后：从头播放一遍，确认主体没有”抢跑”（提前出现）
• 线稿越简单越稳：主体挤在一起或遮挡太多，后面划分绘制区域会麻烦很多
• 一幕尽量只讲一个过程：人物和物体之间留点空白
• 避免大段文字直接画进图片：图片模型生成的文字容易乱码

三个题材的实际效果

1. 故事类（猴子山）：验证基础流程，效果好
2. 知识科普（水循环）：非常适合，观众注意力跟着旁白往前走
3. 概念讲解（AI Agent）：只要画面可以拆出清楚的关系，就值得尝试

---

常见问题排查

问题	解决方案
Python 环境准备失败	检查 Python 版本（3.8+），确保网络可访问 PyPI
渲染时依赖缺失	使用 prepare_env.py 输出的 ENV_PY 解释器，确保依赖隔离
图片与标注不匹配	确认图片和标注文件同名（如 scene-01-demo.png 对应 scene-01-demo.annotation.json）
渲染后画面元素提前出现	检查 protectedRegions 配置，确保遮挡元素正确设置
中文字体显示异常	确认系统已安装中文字体，或配置字体路径
多幕合并顺序错误	检查 merge_scenes.py 的输入顺序是否与字幕分镜一致

---

输出文件说明

文件类型	说明
.png	原始线稿（暖米黄纸张背景）
.annotation.json	标注文件（区域/时序/字幕关联）
-whiteboard.mp4	最终成片（流式笔迹白板动画）
-preview.mp4	标注检查视频（用于验证区域和时序）

---

总结

部署方式	适用场景	难度	推荐度
AI Agent 安装	大多数用户	⭐	⭐⭐⭐⭐⭐
Skills CLI 安装	Claude Code/Cursor 用户	⭐⭐	⭐⭐⭐⭐
源码克隆	开发/自定义需求	⭐⭐⭐	⭐⭐

对于大多数用户，通过 AI Agent 安装是最简单直接的选择：

text

# 向 Codex 或 Claude 发送
帮我安装这个 Skill：github.com/geeklee/srt-whiteboard-animation

# 安装完成后，将 SRT 字幕发给 Agent
把这个字幕做成白板动画。

Agent 会按照 7 步工作流逐步执行，在每一步完成后等待你的确认。完成渲染后，你可以使用 merge_scenes.py 将多幕合并为完整的 MP4 视频。

本项目基于 MIT License 开源。生成素材、字体与配乐如果来自第三方，仍需分别确认授权。