whiteboard-animation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

白板手绘动画生成器

Whiteboard Hand-Drawn Animation Generator

从输入图片生成白板手绘动画视频，动画分为两个阶段：

线稿绘制 — 手持笔在白板上逐步画出黑白线稿
上色 — 手持笔沿内容轮廓逐步涂上彩色，还原为原图

支持两种模式：单张模式和批量模式。

Generate whiteboard hand-drawn animation videos from input images, the animation is divided into two stages:

Line art drawing — A hand holding a pen gradually draws a black and white line art on the whiteboard
Coloring — A hand holding a pen gradually applies color along the contour of the content, restoring the original image

Two modes are supported: Single mode and Batch mode.

模式判断

Mode Judgment

用户提供单张图片路径 → 使用单张模式
用户提供多张图片路径（数组/列表） → 使用批量模式

If the user provides a single image path → Use single mode
If the user provides multiple image paths (array/list) → Use batch mode

单张模式工作流

Single Mode Workflow

第一步：准备环境

Step 1: Prepare the Environment

先用

--check

检测环境是否就绪：

bash

python <skill目录>/scripts/setup_env.py --check

如果成功（退出码 0）：最后一行输出
```
PYTHON_PATH=<路径>
```
，捕获该路径用于后续步骤，直接跳到第二步
如果失败（退出码 1）：运行完整安装：

bash

python <skill目录>/scripts/setup_env.py

安装脚本会自动创建

.venv

虚拟环境并安装缺失依赖（

opencv-python

、

numpy

、

av

），最后一行同样输出

PYTHON_PATH=<路径>

。

First use

--check

to detect if the environment is ready:

bash

python <skill目录>/scripts/setup_env.py --check

If successful (exit code 0): The last line outputs
```
PYTHON_PATH=<path>
```
, capture this path for subsequent steps and jump directly to step 2
If failed (exit code 1): Run the full installation:

bash

python <skill目录>/scripts/setup_env.py

The installation script will automatically create a

.venv

virtual environment and install missing dependencies (

opencv-python

numpy

av

), and the last line also outputs

PYTHON_PATH=<path>

第二步：确认输入图片

Step 2: Confirm Input Image

从用户请求中获取图片路径，确认文件存在。支持格式：PNG、JPG、JPEG、BMP、TIFF。

白色或浅色背景的图片效果最佳。

Obtain the image path from the user request and confirm the file exists. Supported formats: PNG, JPG, JPEG, BMP, TIFF.

Images with white or light backgrounds work best.

第三步：确定参数

Step 3: Determine Parameters

收集可选参数，所有参数都有合理的默认值：

参数	标志	默认值	说明
图片路径	位置参数（必填）	--	输入的彩色图片路径
输出目录	`--output-dir`	`./output`	视频输出目录
时长	`--duration`	`10000`	视频总时长（毫秒）
无手部	`--no-hand`	默认显示手	禁用手部覆盖效果

Collect optional parameters, all parameters have reasonable default values:

Parameter	Flag	Default Value	Description
Image path	Positional parameter (required)	--	Input color image path
Output directory	`--output-dir`	`./output`	Video output directory
Duration	`--duration`	`10000`	Total video duration (milliseconds)
No hand	`--no-hand`	Show hand by default	Disable hand overlay effect

第四步：运行生成脚本

Step 4: Run Generation Script

使用第一步获取的

PYTHON_PATH

运行生成脚本：

bash

<PYTHON_PATH> <skill目录>/scripts/generate_whiteboard.py <图片路径> [--output-dir <目录>] [--duration <毫秒>] [--no-hand]

示例：

bash

<PYTHON_PATH> <skill目录>/scripts/generate_whiteboard.py /path/to/photo.png --output-dir ./output --duration 20000

Use the

PYTHON_PATH

obtained in the first step to run the generation script:

bash

<PYTHON_PATH> <skill目录>/scripts/generate_whiteboard.py <图片路径> [--output-dir <目录>] [--duration <毫秒>] [--no-hand]

Example:

bash

<PYTHON_PATH> <skill目录>/scripts/generate_whiteboard.py /path/to/photo.png --output-dir ./output --duration 20000

第五步：返回结果

Step 5: Return Results

脚本会将最终视频路径打印到 stdout，将该路径告知用户。输出文件命名格式：

vid_YYYYMMDD_HHMMSS_h264.mp4

。

The script will print the final video path to stdout, inform the user of this path. Output file naming format:

vid_YYYYMMDD_HHMMSS_h264.mp4

批量模式工作流

Batch Mode Workflow

当用户提供多张图片（图片路径数组）和对应的时长数组时，使用批量模式。

When the user provides multiple images (image path array) and the corresponding duration array, use batch mode.

第一步：准备环境

Step 1: Prepare the Environment

与单张模式相同。先运行

setup_env.py

获取

PYTHON_PATH

。

Same as single mode. First run

setup_env.py

to get

PYTHON_PATH

第二步：校验输入

Step 2: Verify Input

从用户请求中获取：

图片路径数组：多张图片的路径列表（必填）
时长数组：与图片一一对应的时长列表（毫秒，必填）

必须满足：

图片路径数组和时长数组长度相同
每张图片文件都存在
每个时长为正整数（毫秒）

Obtain from the user request:

Image path array: List of paths for multiple images (required)
Duration array: List of durations corresponding to the images one-to-one (milliseconds, required)

Must satisfy:

The length of the image path array and the duration array are the same
Each image file exists
Each duration is a positive integer (milliseconds)

第三步：运行批量生成脚本

Step 3: Run Batch Generation Script

使用

PYTHON_PATH

运行批量脚本，通过

--images

和

--durations

传入一一对应的图片路径和时长：

bash

<PYTHON_PATH> <skill目录>/scripts/batch_generate.py \
  --images /path/to/img1.png /path/to/img2.png /path/to/img3.png \
  --durations 10000 15000 8000 \
  [--output-dir ./output] [--no-hand]

脚本内部会自动校验：

```
--images
```
和
```
--durations
```
数量必须一致
每张图片文件必须存在

校验通过后串行逐个调用单张生成脚本，每完成一个打印进度。

Use

PYTHON_PATH

to run the batch script, pass in the one-to-one corresponding image paths and durations through

--images

and

--durations

bash

<PYTHON_PATH> <skill目录>/scripts/batch_generate.py \
  --images /path/to/img1.png /path/to/img2.png /path/to/img3.png \
  --durations 10000 15000 8000 \
  [--output-dir ./output] [--no-hand]

The script will automatically verify internally:

The number of
```
--images
```
and
```
--durations
```
must be consistent
Each image file must exist

After passing the verification, call the single generation script one by one serially, and print the progress after each completion.

第四步：返回结果

Step 4: Return Results

脚本输出所有任务的汇总信息（成功/失败数量）。告知用户：

总共生成了多少个视频
成功几个，失败几个
输出目录路径
如有失败，列出失败的图片

The script outputs summary information of all tasks (number of successes/failures). Inform the user:

How many videos were generated in total
How many succeeded, how many failed
Output directory path
If there are failures, list the failed images

故障排除

Troubleshooting

ModuleNotFoundError
：重新运行
```
setup_env.py
```
确保依赖完整安装。
虚拟环境创建失败：确认系统已安装 Python 3.8+，且
```
python3
```
命令可用。
批量模式单个任务失败：不影响后续任务继续执行，最终汇总会列出所有失败项。

ModuleNotFoundError
: Rerun
```
setup_env.py
```
to ensure complete installation of dependencies.
Virtual environment creation failed: Confirm that Python 3.8+ is installed on the system and the
```
python3
```
command is available.
Single task failure in batch mode: Does not affect the continued execution of subsequent tasks, and the final summary will list all failed items.