whiteboard-animation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: whiteboard-animation
description: 从图片生成白板手绘动画视频。将任意彩色图片转换为包含线稿绘制和上色两个阶段的动画，带手部覆盖效果，输出 H.264 MP4 视频。支持单张和批量两种模式。当用户说"把图片做成白板动画"、"白板动画"、"批量白板动画"时触发。
---

# 白板手绘动画生成器

从输入图片生成白板手绘动画视频，动画分为两个阶段：
1. **线稿绘制** — 手持笔在白板上逐步画出黑白线稿
2. **上色** — 手持笔沿内容轮廓逐步涂上彩色，还原为原图

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

---

## 模式判断

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

---

## 单张模式工作流

### 第一步：准备环境

先用 `--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=<路径>`。

### 第二步：确认输入图片

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

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

### 第三步：确定参数

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

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

### 第四步：运行生成脚本

使用第一步获取的 `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
```

### 第五步：返回结果

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

---

## 批量模式工作流

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

### 第一步：准备环境

与单张模式相同。先运行 `setup_env.py` 获取 `PYTHON_PATH`。

### 第二步：校验输入

从用户请求中获取：
- **图片路径数组**：多张图片的路径列表（必填）
- **时长数组**：与图片一一对应的时长列表（毫秒，必填）

**必须满足**：
- 图片路径数组和时长数组长度相同
- 每张图片文件都存在
- 每个时长为正整数（毫秒）

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

使用 `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` 数量必须一致
- 每张图片文件必须存在

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

### 第四步：返回结果

脚本输出所有任务的汇总信息（成功/失败数量）。告知用户：
- 总共生成了多少个视频
- 成功几个，失败几个
- 输出目录路径
- 如有失败，列出失败的图片

---

## 故障排除

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