手绘动画
一种完全用代码制作短动画的方法,源自 JohnHeibel/PDoomVideo(一部由 Claude Opus 绘制的 156 秒音乐视频)及其通用工具包 ClaudeAnimationBase(MIT 协议),本工具包以 template/ 形式集成在此。
工作原理: 每一帧都是时间 t 的纯函数。studio.html 加载 p5.js + p5.brush 以及你的场景文件;每个镜头用填充水彩和沸腾墨水线条绘制整个 1920×1080 帧。render.mjs 驱动无头 Chrome 并行渲染联系表以供预览,或逐帧渲染所有帧,并由 ffmpeg 编码为 MP4(可选音频)。
工作流程
0. 脚手架
bash ~/.claude/skills/painted-animation/scripts/new_project.sh <project-dir> # 添加 --keep-demo 以保留示例场景的链接
此命令会复制模板,取消演示场景的链接,运行 npm install 并检查 node / ffmpeg / Chrome 的安装情况。然后在设计任何内容之前完整阅读 <project-dir>/ANIMATION_GUIDE.md:它包含了规则、动画原理以及完整的引擎/Clawd API。使用 Read 工具查看 docs/emotions.jpg 和 docs/views.jpg(模型表)。
对于音乐视频或超过 20 秒的视频,请同时阅读 references/music-video.md。对于歌词视频,请先请求歌曲文件和 LRC 歌词,并用 scripts/beat_grid.py 测量节奏:歌词行通常比你以为的要快。
1. 先写故事板,再写代码
在项目中编写 STORYBOARD.md(格式见指南:一句话梗概、世界 + 色调弧线、主题、角色情感弧线,然后列出镜头及其可读信息——即观众必须理解的定时信息)。给用户展示故事板,让他们在开始制作之前做出反应,除非他们直接说可以继续。
2. 逐镜头构建
- 在
src/config.js中设置duration、bpm、offset(以及audio)。 - 在
src/scenes/中为每个场景/章节创建一个 IIFE 封装的单独文件,以shots([[t0, fn], ...])结尾;并将对应的<script>标签添加到studio.html。 - 先确定关键姿态,将其作为静态图片检查,然后再添加它们之间的动作。
3. 渲染与检查——每个镜头,多次
光看代码是看不出动作效果的。在项目目录中运行:
node render.mjs --sheet=0.1,0.8,1.6,2.4 --cols=4 --w=480 --out=out/check/a.jpg # 关键帧
node render.mjs --strip=2.1:2.6 --out=out/check/strip.jpg # 某个瞬间的每一帧
node render.mjs --sheet=2.3 --crop=760,420,500,400 --w=500 --out=out/check/face.jpg # 全分辨率细节
使用 Read 工具打开每张图片,并根据指南的检查清单进行核对:事件是否清晰?角色是否足够大?可读信息的时机是否确保初次观看者能理解?是否有预备动作/跟随动作,没有生硬衔接?角色双脚和手持道具是否与地面/手接触?每个接缝处是否有转场?没有文字,没有 3D,没有纯黑/纯白,没有浑浊的光晕?修正后再次检查。预算:每个镜头至少一张联系表,每个关键动作和转场一张条带,每个承载故事的(角色)脸部一个裁剪区域。
4. 渲染视频
node render.mjs --clip --out=out/video.mp4 # 短视频,一个工作者
node render.mjs --frames --workers=4 && node render.mjs --encode --out=out/video.mp4 [--audio=assets/song.mp3] # 长视频,并行 + 可恢复
报告输出路径、视频长度和毫秒/帧。提供 open out/video.mp4 命令。
最重要的规则
以下是指南规则的浓缩版;指南本身具有权威性。
- 手绘媒介。 只使用
paint()/inkLine()(p5.brush)——绝不要使用纯 p5 的rect/ellipse/fill。仅限平面 2D:转向通过绘制的关键视图完成(turn()、spinView()),绝不用 3D 投影。通过glow()(加法混合)模拟光照,因为颜料混合会使黄色叠蓝色变成绿色。 - 没有文字。 没有字幕、标签、标志或气泡对话;用画面展示。反应通过绘制情绪符号(惊叹号、汗珠、爱心……)。唯一的例外是歌词视频中的卡拉 OK,以及最多几个大号的特效字。
- 每个镜头都有事件发生——一个事件、因果反应、伏笔应验。
- 给观众留足时间。 列出每个镜头的可读信息;一次只传达一条可读信息;快动作,慢含义;引导视线;可读信息决定了镜头长度。这是生成的动画最容易失败的地方。
- 有生命力。 没有一帧是静止的(通过
feel()实现待机动作、缓慢移动的摄像机、线条沸腾);面部通过emotions()变化而非替换;角色要画大(中景 u≈20–28,特写 40–70);所有动作都踩准节拍。 - 每个接缝处都有转场,根据故事内容选择合适类型(刷子擦拭、圆形/剪影划像、甩镜头、匹配剪辑、动作剪辑、相机跟随)。
- 整体统一。 一个世界、一个色彩弧线、一条情感线索、相互关联的场景、一个与开头呼应的结尾。
引擎注意事项
- 关于
t的纯函数。 帧之间并行且乱序渲染:不允许跨帧状态、不允许使用Math.random()、不允许逐帧物理。使用hash(i)实现稳定随机性,jit()实现线条沸腾。 - 在每个独立的背景元素/道具之前调用
boilSeed(key),否则移动的物体会导致其后绘制的一切每一帧都重新沸腾(产生抖动)。 - 不要将全局变量命名为与 p5 相同。 p5 将
line、OVERLAY、text、color、scale……定义为全局变量;顶层function line()会报错Cannot redefine property,导致页面永远无法就绪(渲染器超时)。将辅助函数放在场景 IIFE 内部,或使用不同的名称。 - 在门口、窗户和屏幕处的分层绘制: 先绘制内部内容,然后在其上绘制周围的墙壁/框架,以免超出开口的部分被看到(火车车厢的
inDoor+ 门框,电视的边框部件)。 - 点列表中的
NaN会抛出Failed to construct 'OffscreenCanvas'错误——请防御退化的几何图形。 - 当摄像机缩放大于 2 倍时,巨大的形状会丢失轮廓线;轮廓线宽度会随缩放比例变化,因此在特写镜头中需要减小
sw。 - 性能开销 = 填充和描边的数量。目标控制在每帧约 1.5–2.5 秒(日志会打印毫秒/帧)。优先使用更少、更大的形状。在没有真正 GPU 的机器上,水彩填充会很慢——考虑减少
fill形状的数量,或者最后手段使用--soft-gl。 - macOS:渲染器默认使用
--use-angle=metal,并自动查找/Applications/Google Chrome.app;否则请通过--chrome=<path>参数指定。
适配
- Clawd 是默认主角,但不强制使用。新角色、道具和情绪使用相同的工具(
paint、ribbon、through、glow)绘制,并在各镜头中保持模型一致;新情绪添加到src/clawd.js中的EMO对象中。 src/karaoke.js(模板)通过core.js中的window.overlayHook钩子为歌词视频添加逐字卡拉 OK 效果。LOOPS.name = t => {...}; LOOPS.name.len = 4;+node render.mjs --loop=name --png可生成一个无缝循环,用于 GIF(ffmpeg -i out/loop_name/f%04d.png …)。- 更高的推理努力度往往会产生更奢华、更详细的场景。