whiteboard-stream-animation

# 流式笔迹动画生成器 将文章或分镜生成的统一风格源图，或用户直接提供的一张彩色图片，渲染成白板手绘动画。核心特征：**笔尖沿一条连续的笔迹滑行，边走边落墨**，而不是一格一格地跳变揭墨。 动画分三段： 1. **起笔 (ink)** — 笔尖沿墨迹流铺下黑白线稿 2. **添彩 (color)** — 笔尖沿同一条轨迹回头，用原色墨刷把画面点亮，还原为原图 3. **凝视 (gaze)** — 收笔后停留若干秒，展示完整原图 支持**单图模式**与**队列(批量)模式**两种。 --- ## 前置生图模式：从文章或分镜生成源图 当用户提供文章、口播稿或分镜，但尚未提供可渲染图片时，必须先完成本阶段，再进入下方的单图或队列模式。所有面向用户的说明、配图策略和文件名说明使用中文。 ### 统一出图视觉规范（强制） 所有场景的源图必须遵循同一套视觉语言；在生成图片前，将以下要求完整写入出图提示词，并在生成后检查是否满足： - **风格与构图：** 极简手绘插图、纯素描草图风格、类似 Notion 的克制涂鸦美学。以概念表达为主，不追求写实；构图简洁、背景干净、大量留白，整体情感平和、清晰，系列内的线条、人物和配色保持一致。 - **颜色与材质：** 使用米色纸张背景 `#F5EBD7`、深灰色草图线条；仅可用橙色 `#FFA500` 作为少量概念性点缀色。不得使用其他强调色、高饱和度配色或复杂纹理。 - **人物与对象：** 人物统一使用无脸圆形头的人像；对象以简洁轮廓、少量线条和留白表达，强调关系、变化或核心概念，而非真实比例、材质与细节。 - **绝对禁止：** 任何文字、词语、字母、数字、字体或标签；写实感、摄影细节、3D 效果、绘画质感；复杂场景、密集背景、繁复装饰和高饱和度画面。 ### 工作流程 1. 阅读文章或分镜，先输出配图策略，不生成图片。每幕只表达一个核心意思，建议每张图承载 25–35 秒口播；策略应包含场景编号、核心表达、画面主体与对应口播段落。 2. 等待用户确认配图策略。未确认前不得生成图片，也不得开始渲染视频。 3. 确认后，按“统一出图视觉规范”逐幕生成 16:9 暖米黄色旧纸张底线稿图。背景使用 `#F5EBD7`，主体之间保留充足留白，便于自动拆分；不得生成文字、复杂照片、重叠对象或与该规范冲突的视觉元素。 4. 实际查看每张生成图，确认其无文字、主体清晰、留白充分且整组风格一致。发现不符合规范时先重新生成该图。 5. 将通过检查的图片保存到用户项目的 `assets/whiteboard/<项目名>/`；单图进入单图模式，多幕图片连同对应时长进入队列模式。 建议命名：`scene-01-<名称>.png`、`scene-02-<名称>.png`。生成的线稿图是后续流式笔迹渲染的唯一源图；不得在渲染时以未检查的草稿图替代。 多幕场景默认进入队列模式；若用户希望把各幕串成一条完整视频，用队列模式的 `--merge`（详见下方队列模式第三步）。 --- ## 模式判定 - 用户提供**单个图片路径** → 单图模式 - 用户提供**多张图片路径 + 对应时长**（两个数组）→ 队列模式 - 只要各幕的独立视频 → 队列默认行为 - 要把各幕串成一条完整视频 → 队列模式加 `--merge`（单片仍保留，另出一个合并总视频） - 用户提供**文章、口播稿或分镜，且未提供图片** → 前置生图模式；用户确认配图策略并完成生图检查后，按生成图片数量转入单图或队列模式 --- ## 单图模式工作流 ### 第一步：准备环境 先用 `--check` 探测环境是否就绪： ```bash python <skill目录>/scripts/prepare_env.py --check ``` - 成功（退出码 0）：末行输出 `ENV_PY=<解释器路径>`，**捕获该路径供后续步骤使用**，直接进入第二步 - 失败（退出码 1）：执行完整安装： ```bash python <skill目录>/scripts/prepare_env.py ``` 安装脚本会在 skill 目录下建立 `.venv` 虚拟环境并补齐缺失依赖（`opencv-python`、`numpy`、`av`(PyAV，用于纯 pip 的 H.264 转码)），末行同样输出 `ENV_PY=<路径>`。 ### 第二步：确认输入图片 从用户请求中取图片路径并确认文件存在。支持格式：PNG、JPG、JPEG、BMP、TIFF。白色或浅色背景的图效果最好。 ### 第三步：确定参数 可选参数都有合理默认值： | 参数 | 标志 | 默认值 | 说明 | |------|------|--------|------| | 图片路径 | 位置参数（必填） | — | 输入彩色图片 | | 输出目录 | `--out-dir` | `./out` | 视频输出目录 | | 总时长 | `--total-ms` | `10000` | 视频总时长（毫秒） | | 关闭覆盖 | `--bare-tip` | 默认开启手部覆盖 | 不叠加笔尖/手部 | | 自定义笔尖 | `--pen-image` | 内置 `drawing-hand.png` | 替换手部素材 | | 上色风格 | `--color-fill` | `contour-wipe` | 添彩阶段画法：`contour-wipe` 轮廓感知自上而下扫描（默认）；`brush` 沿笔画轨迹刷 | | 停顿节奏 | `--pause` | `heavy` | 起笔段换笔呼吸：`heavy` 明显（默认）；`auto` 按密度自动分档；`off` 关闭；`light` 少量 | | 笔迹路径 | `--ink-path` | `grid` | 起笔段笔迹：`grid` 网格格中心插值（默认）；`skeleton` 骨架级像素追踪（更精准贴合线条） | ### 第四步：运行渲染脚本 用第一步拿到的 `ENV_PY` 运行： ```bash <ENV_PY> <skill目录>/scripts/stream_render.py <图片路径> [--out-dir <目录>] [--total-ms <毫秒>] [其它可选参数] ``` 默认配置已是最优组合（grid 笔迹 + contour-wipe 上色 + heavy 停顿），通常只需指定图片路径和时长： ```bash <ENV_PY> <skill目录>/scripts/stream_render.py /path/to/photo.png --out-dir ./out --total-ms 12000 ``` ### 第五步：返回结果 脚本会把最终视频路径打印到 stdout（末行形如 `OUTPUT=<路径>`），把该路径告知用户。输出文件命名格式：`stream_YYYYMMDD_HHMMSS_h264.mp4`。 --- ## 队列(批量)模式工作流 当用户提供图片路径数组 + 对应时长数组时使用。 ### 第一步：准备环境 与单图模式相同，先跑 `prepare_env.py` 取 `ENV_PY`。 ### 第二步：校验输入 从用户请求中获取： - **图片路径数组**（必填） - **时长数组**（毫秒，必填，与图片一一对应） **必须满足**：两数组长度相同；每张图都存在；每个时长为正整数。 ### 第三步：运行队列渲染脚本 ```bash <ENV_PY> <skill目录>/scripts/queue_render.py \ --images /p/img1.png /p/img2.png /p/img3.png \ --durations 10000 15000 8000 \ [--out-dir ./out] [--bare-tip] [--pen-image <路径>] [--fail-fast] \ [--merge] [--merged-name <文件名>] ``` - `--fail-fast` 可选：某个任务失败立即中止整批；不加则失败不阻塞后续。 - `--merge` 可选：全部渲染完后，把各成功片段**按输入顺序硬切合并**为一条总视频；**单片仍保留**，另在输出目录生成合并视频。合并优先走系统 ffmpeg 无损拼接（`-c copy`，不重编码）；片段尺寸不一致或无 ffmpeg 时自动重编码（ffmpeg filter 或 PyAV）。默认文件名 `merged_YYYYMMDD_HHMMSS.mp4`，可用 `--merged-name` 指定。 - 提示：要无损合并，各幕应统一 16:9、同一渲染参数（默认即满足）；尺寸混用会触发重编码并缩放补边到第一段尺寸。 脚本内部串行调用 `stream_render.py`，逐个打印进度；开启 `--merge` 时末行输出 `MERGED=<合并视频路径>`。 ### 第四步：返回结果 告知用户：生成总数、成功/失败数、输出目录；若有失败则列出失败图片。开启 `--merge` 时，额外告知合并视频路径（脚本末行 `MERGED=`）。 --- ## 三种模式与常用组合 三个独立维度控制动画风格，各有默认值，默认组合已是推荐配置： | 维度 | 标志 | 选项 | 默认 | 说明 | |------|------|------|------|------| | **笔迹路径** | `--ink-path` | `grid` / `skeleton` | `grid` | 起笔段笔尖轨迹：`grid` 沿网格格中心插值（块状感、稳定）；`skeleton` 沿骨架像素追踪（细线条、精准贴合原图、交叉点无碎笔画） | | **上色风格** | `--color-fill` | `contour-wipe` / `brush` | `contour-wipe` | 添彩段画法：`contour-wipe` 颜色自上而下沿轮廓蔓延（涂色覆盖感）；`brush` 沿笔画轨迹逐点刷原色（手绘涂色感） | | **停顿节奏** | `--pause` | `heavy` / `auto` / `light` / `off` | `heavy` | 起笔段换笔呼吸：`heavy` 明显停顿；`auto` 按密度自动；`light` 少量；`off` 关闭 | ### 常用组合 ```bash # 默认推荐（不传参即等同此配置）：grid + contour-wipe + heavy <ENV_PY> <skill目录>/scripts/stream_render.py photo.png --total-ms 12000 # 最强画质：骨架追踪 + 轮廓上色 + 明显停顿 <ENV_PY> <skill目录>/scripts/stream_render.py photo.png --ink-path skeleton --color-fill contour-wipe --pause heavy # 快速生成（关停顿、网格笔迹、沿轨迹上色） <ENV_PY> <skill目录>/scripts/stream_render.py photo.png --pause off --color-fill brush # 只要骨架追踪的精准笔迹，其余默认 <ENV_PY> <skill目录>/scripts/stream_render.py photo.png --ink-path skeleton ``` > 提示：`skeleton` 笔迹对线稿清晰的图（插画、简笔画）效果最好；照片或背景复杂的图用默认 `grid` 更稳定。 --- ## 进阶调参（通常不需要） `stream_render.py` 还接受几个覆盖默认值的旋钮：`--fps`（帧率，默认 60）、`--grid-edge`（网格边长，默认 10）、`--brush-radius`（墨刷半径，默认 40，仅 brush 模式）。仅当用户明确要调整画质/体积时使用。 `contour-wipe` 上色模式（默认）另有几个旋钮：`--wipe-decay`（阻力场向下衰减系数，默认 0.86，越小越快越过轮廓）、`--wipe-delay-ratio`（轮廓处前沿扣减比例×h，默认 0.04，越大轮廓处停留越久）、`--wipe-blocks`（笔尖横向来回趟数，默认 18）。 `skeleton` 笔迹模式的碎片过滤阈值固定为 8 个采样点（骨架笔画短于此即丢弃），无对应 CLI 参数，如需调整改 `Config.skeleton_min_points`。 起笔段停顿由 `--pause` 控制（默认 `heavy` 明显停顿）。若改 `--pause auto` 则按"每格帧数"自动分三档——内容稀疏时多停顿、密集时不停顿。 --- ## 故障排除 - **`ModuleNotFoundError`**：重跑 `prepare_env.py` 补依赖。 - **`无法读取图片`**：确认路径正确、文件非损坏；带中文/空格的路径建议加引号。 - **没有 H.264 输出、只有 mp4v**：系统 ffmpeg 与 PyAV 都不可用时才会发生，脚本保留原始 mp4v 编码并给出 warning。正常情况下 `prepare_env.py` 已装好 PyAV，无系统 ffmpeg 也能得到 H.264；若仍是 mp4v，重跑 `prepare_env.py` 确认 `av` 安装成功，或安装系统 ffmpeg（体积更优）。 - **队列模式单个任务失败**：默认不影响后续任务，最终汇总会列出失败项；如需遇错即止，加 `--fail-fast`。