我有一幅已经画好的白板风格示意图，希望在视频中呈现出一只手拿着马克笔一笔一画绘制的效果。偶然发现了这个名为whiteboard-animator的开源引擎——只需提供成品图片，就能生成手绘过程的动画。它会先识别图像中的每个墨迹斑块，将文字单独标记并逐字写出，沿着笔迹描边轮廓，再通过逐笔涂刷填充色块。绘制顺序还模拟人类习惯：先画容器再画内容，先画形状后写标签。字母V从笔尖开始绘制，而非从中间向两端生长。GitHub地址：http://github.com/masihsultani/whiteboard-animator… 若配备音频文件，绘制速度会自动与音频时长同步，绘制完成后暂停等待音频结束。多张图片配合多段音频可拼接成完整课程。白纸上纯色马克笔风格的插图动画效果最佳。适用于知识讲解视频或教学课纲演示，能将静态图像转化为动态绘制过程。

masihsultani/whiteboard-animator

来源：https://github.com/masihsultani/whiteboard-animator

whiteboard-animator

将白板风格图像转化为手绘动画。一键生成，仅需CPU。
绘制太阳、树叶和葡萄糖分子：

pip install whiteboard-animator  
whiteboard-animate sketch.png --duration 8 -o sketch.mp4

只需提供一张完成的白板图，它便会逐词书写文本、描绘轮廓、通过笔触填充形状，并像真人白板书写般逐笔绘制分叉线条。加入解说音频后，绘制节奏会自动匹配语音。本引擎是Kinoslide（https://kinoslide.ai）白板功能的渲染核心，现已开源供所有人使用。

示例

以下示例展示了独立插图和光合作用讲座场景的动画效果（通过命令行生成）：
examples/gyroscope.png
examples/equation.png
examples/photosynthesis/03_carbon_fixation.png
examples/photosynthesis/04_energy_flow.png

使用本引擎制作的完整视频

完整的解说视频已公开，点击可在YouTube观看：
《日元套息交易平仓机制》
《两分钟搞懂广义相对论》

快速尝试：

git clone https://github.com/masihsultani/whiteboard-animator  
cd whiteboard-animator && pip install -e .  
whiteboard-animate examples/gyroscope.png --duration 8 -o gyroscope.mp4

图像处理流程

1. 墨迹识别：所有非白色像素连通区域会成为独立组件。内置的CRAFT（https://github.com/clovaai/CRAFT-pytorch）文本检测器（ONNX/CPU格式）会标记文字组件，使文字逐字书写而非像形状般描边。
2. 模拟手绘顺序：容器先于内容绘制，形状先于标签绘制，文字按阅读顺序呈现，小圆点与其所属字形同步绘制。
3. 时间分配：每个组件分配的时间片与其面积平方根成比例，避免大区域填充占用过多时间线。若使用区域规划（见下文），时间片将基于预估解说节奏分配。
4. 像素揭示调度：笔画沿真实端点骨架延伸（V字从笔尖而非顶端开始绘制）。封闭轮廓采用单次推进式前沿；填充先描边，然后根据区域大小选择倾斜扫描或笔刷涂绘。带交叉点的线条艺术会被分解为连续笔路径，防止X形或网格从中心向外生长。
5. 流式帧输出至FFmpeg：新完成的像素仅提交一次，当前帧仅混合正在淡出的像素。除小型文本检测器外，渲染时无其他模型依赖。无需GPU、训练或API密钥。

安装

需要Python 3.10+，且ffmpeg和ffprobe需位于系统PATH中。

先安装FFmpeg：

• macOS（使用Homebrew）：brew install ffmpeg
• Ubuntu/Debian：sudo apt update && sudo apt install ffmpeg
• Windows：从FFmpeg下载页（https://ffmpeg.org/download.html）选择Windows版本，解压后将bin目录（含ffmpeg.exe和ffprobe.exe）加入用户PATH变量。重启终端后验证：

ffmpeg -version  
ffprobe -version

Python环境配置：
使用Python 3.10+解释器（系统默认python指向旧版时使用python3，Windows用py -3）。建议通过虚拟环境隔离依赖：

python -m venv .venv

激活环境（macOS/Linux执行source .venv/bin/activate，Windows PowerShell执行.venv\Scripts\Activate.ps1），然后安装：

python -m pip install whiteboard-animator

安装包包含约83MB文本检测模型及科学计算依赖项。模型随包安装，渲染时无需下载。除可选功能外，渲染无需API密钥。若使用--detect-regions功能（需通过Gemini推断绘图顺序），则需安装gemini扩展并配置GOOGLE_API_KEY。该功能可跳过，手动编写区域规划（见下文）：

pip install 'whiteboard-animator[gemini]'

从源码安装：

python -m pip install -e '.[dev]'  
python -m pytest

测试套件包含真实模型及FFmpeg的CLI到MP4检测。本地缺失FFmpeg/ffprobe时跳过集成测试；CI环境会显式安装并运行。仅运行单元测试：

python -m pytest -m "not integration"

故障排除

• 找不到ffmpeg/ffprobe：按上述步骤安装FFmpeg，并在运行动画器的同一终端中验证版本命令。名为ffmpeg的Python包不会安装这些可执行文件。
• 找不到whiteboard-animate：激活安装包的环境，或使用python -m whiteboard_animator.cli加相同参数运行。
• Pip尝试编译OpenCV：尝试python -m pip install --only-binary=opencv-python-headless whiteboard-animator选择预编译轮子。若不可用，请使用OpenCV支持的Python版本和平台。
• 输入/输出错误：确保图像/音频文件可读，无声场景需设置正数时长，输出文件以.mp4结尾且位于可写目录。CLI会在渲染前识别缺失文件和无效区域JSON。
• FFmpeg编码失败：阅读错误诊断信息，检查ffmpeg -encoders是否包含libx264。使用--verbose查看渲染阶段。

使用方法

固定时长（无音频）：

whiteboard-animate scene.png --duration 8 -o scene.mp4

带解说音频（绘制在音频结束前完成，完成后保持最后一帧直至音频结束）：

whiteboard-animate scene.png --audio scene.wav -o scene.mp4

多场景顺序拼接：

whiteboard-animate a.png b.png c.png --audio a.wav b.wav c.wav -o lecture.mp4

画质预设：low（20fps，500k码率）、medium（24fps，1500k默认）、high（24fps，3000k）。最长边超过1280px的图像会自动缩放。

通过解说文本控制节奏

默认情况下，整张图像会按启发式顺序在场景前70%时间内绘制完成。区域规划（region plan）可指定图像内容、绘制顺序及关联解说文本。启用区域规划后，引擎将前75%音频时长分配给绘制窗口，每个区域的时间占比由解说字符数（70%权重）和边界框面积（30%权重）混合计算。若所有注释文本为空，则仅使用边界框面积。区域可提前完成并等待下一窗口开始。该方式通过文本估算节奏，不分析语音或对齐到单词时间戳。停顿、语速变化或不均匀的短语长度可能导致绘制超前或滞后于语音。
--detect-regions可提议区域及顺序，但不增加音频对齐。如需精确提示时间，请通过低级API WhiteboardAnimator.render_to_file的element_plan参数传递显式start/end时间。

whiteboard-animate scene.png --audio scene.wav --regions scene.regions.json -o scene.mp4

区域规划为JSON格式，坐标归一化为0-1000（原点在左上角）：

{
  "idea": "一张图理解光合作用",
  "regions": [
    {
      "label": "sun",
      "role": "main_concept",
      "object": "a sun with rays",
      "reveal_order": 1,
      "box": {"ymin": 120, "xmin": 40, "ymax": 620, "xmax": 380},
      "expected_visual": "Sun with orange rays",
      "annotation": "Photosynthesis starts with sunlight",
      "reveal": "fill"
    }
  ]
}

安装gemini扩展并设置GOOGLE_API_KEY后，可从图像和解说文本自动检测区域规划：

whiteboard-animate scene.png --audio scene.wav \
  --detect-regions --narration "Photosynthesis starts with sunlight. ..." \
  --save-regions -o scene.mp4

--save-regions会将检测到的规划保存到输出文件旁，便于编辑后用--regions重新渲染。

Python API

from whiteboard_animator import Scene, SnippetRegionPlan, render_video
plan = SnippetRegionPlan.model_validate_json(open("a.regions.json").read())
render_video(
    [Scene("a.png", audio="a.wav", region_plan=plan), Scene("b.png", audio="b.wav")],
    "lecture.mp4",
    quality="high",
)

底层接口WhiteboardAnimator.render_to_file(img_array, draw_duration, total_duration, output_path, fps=24, bitrate="1500k", element_plan=None)接受RGB numpy数组并输出无声MP4。构造函数提供所有调节参数：淡入时长、填充检测阈值、笔刷角度/宽度、决定填充采用笔触或扫描的S曲线，以及线条艺术分解阈值。

优质输入标准

引擎适用于白底墨迹图像。灰度值高于240的像素视为背景，近白色像素会被自动修正为纯白。干净的马克笔风格绘图（少量纯色）动画效果最佳。照片、渐变图及有纹理/彩色背景的图像不适合。

引擎独立版 vs Kinoslide

文本检测模型

whiteboard_animator/models/craft.onnx（83MB）是CRAFT-pytorch（MIT许可）中craft_mlt_25k的ONNX导出版本。设置CRAFT_MODEL_PATH可使用其他文件。若模型加载失败，引擎仍可运行并将文本视为普通笔画处理。

贡献

欢迎提交问题和拉取请求。以下是我们希望获得帮助的方向：

• 非白色背景支持（深色画板、纸张纹理）
• SVG输入（追踪真实矢量路径而非光栅骨架）
• 无区域规划时稠密图表的更优排序方案
• 跟随笔尖移动的手或马克笔精灵图

许可证

MIT。详见LICENSE。