whiteboard-animation

Whiteboard Hand-Drawn Animation Generator

Generate a whiteboard hand-drawn animation video from an input image. The animation is divided into two stages:

1. Line art drawing — a hand holding a pen gradually draws the black-and-white line art on the whiteboard
2. Coloring — a hand holding a pen gradually applies color along the content outlines, restoring it to the original image

Supports two modes:Single modeandBatch mode。

---

Mode determination

• User providesa single image path → use single mode
• User providesmultiple image paths(array/list) → use batch mode

---

Single mode workflow

Step 1: Prepare the environment

First use --check to check whether the environment is ready:

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

• If successful (exit code 0): the last line outputs PYTHON_PATH=<路径>，capture that path for subsequent steps, and skip directly to step 2
• If failed (exit code 1): run the full installation:

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

The installation script will automatically create .venv a virtual environment and install missing dependencies (opencv-python、numpy、av), and the last line also outputs PYTHON_PATH=<路径>。

Step 2: Confirm the input image

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

Images with a white or light background work best.

Step 3: Determine parameters

Collect optional parameters. All parameters have reasonable default values:

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

Step 4: Run the generation script

Use the PYTHON_PATH obtained in step 1 to run the generation script:

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

Example:

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

Step 5: Return the result

The script will print the final video path to stdout. Tell the user that path. Output file naming format:vid_YYYYMMDD_HHMMSS_h264.mp4。

---

Batch mode workflow

Use batch mode when the user provides multiple images (an array of image paths) and a corresponding array of durations.

Step 1: Prepare the environment

Same as single mode. First run setup_env.py to get PYTHON_PATH。

Step 2: Validate the input

Get from the user request:

• Image path array: a list of paths to multiple images (required)
• Duration array: a list of durations corresponding one-to-one with the images (milliseconds, required)

Must satisfy：

• The image path array and the duration array have the same length
• Every image file exists
• Each duration is a positive integer (milliseconds)

Step 3: Run the batch generation script

Use PYTHON_PATH to run the batch script, passing the one-to-one corresponding image paths and durations via --images and --durations :

<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 automatically validates:

• --images and --durations counts must match
• Every image file must exist

After validation passesseriallycall the single-image generation script one by one, printing progress after each completion.

Step 4: Return results

The script outputs summary information for 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: Rerun setup_env.py to ensure dependencies are fully installed.
• Virtual environment creation failed: Confirm that Python 3.8+ is installed on the system and that the python3 command is available.
• A single task failed in batch mode: It does not affect the continued execution of subsequent tasks; the final summary will list all failed items.