painted-animation

绘制动画

一种完全通过代码制作短篇动画的方法，源自 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>        # add --keep-demo to keep the example scene hooked up

这会复制模板、移除演示场景、运行 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（格式见指南：故事梗概、世界观 + 调色板变化、主题元素、角色的情绪变化，然后是带有理解要点的镜头——即观众必须理解的内容及其时序列表）。完成示例：examples/xiaozhen/（一部 31 秒的歌词视频：含故事板和完整场景代码）。

先向用户展示故事板并听取反馈，再开始制作，除非用户说直接开始。

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        # key frames
node render.mjs --strip=2.1:2.6 --out=out/check/strip.jpg                             # every frame of a moment
node render.mjs --sheet=2.3 --crop=760,420,500,400 --w=500 --out=out/check/face.jpg   # full-res detail

使用 Read 打开每张图片，并根据指南中的检查清单实际核对：事件是否清晰？角色是否足够大？理解要点的时序是否能让初次观看的人看明白？是否有预备动作 / 收势？有没有动作突变？双脚和手持道具是否接触到物体？每个衔接处的转场是否自然？是否没有文字、3D、纯黑 / 纯白和浑浊的光晕？预算：每个镜头至少 1 张联系表、每个关键动作和转场至少 1 条连续帧带、每张承载故事信息的脸至少 1 张裁剪图。

4. 渲染视频

node render.mjs --clip --out=out/video.mp4                                   # short videos, one worker
node render.mjs --frames --workers=4 && node render.mjs --encode --out=out/video.mp4 [--audio=assets/song.mp3]   # long ones, parallel + resumable

报告输出路径、时长和每帧毫秒数。提供 open out/video.mp4。

最重要的规则

以下是本指南规则的精简版；完整指南具有权威性。

1. 手绘媒介。 只能使用 paint() / inkLine()（p5.brush）——绝不能使用普通 p5 rect/ellipse/fill。仅限平面 2D：转身必须通过绘制关键视图（turn()、spinView()）完成，绝不能使用 3D 投影。使用 glow()（加色）表现光线，因为颜料混合会让蓝色上面的黄色变成绿色。
2. 没有文字。 不要添加字幕、标签、标牌或对话气泡；要用画面表现。反应要画成表情符号（!、汗滴、爱心……）。唯一例外是歌词视频中的卡拉 OK，以及少量大型音效字。
3. 每个镜头都要有事情发生——事件、起因 → 反应，以及之后会有回报的铺垫。
4. 给观众留出时间。 列出每个镜头的信息点；一次呈现一个信息点；动作要快，含义要停留；引导视线；镜头时长由信息点决定。这是生成式动画最容易失败的地方。
5. 鲜活。 没有什么是静止的（通过 feel() 制作待机动作、让摄像机漂移、加入抖动）；表情通过 emotions() 变化，绝不能靠替换表情来实现；角色要画得够大（中景 u≈20–28，特写 40–70）；所有内容都要跟着节拍动。
6. 每个衔接处都要有转场，并根据故事选择合适的转场（笔刷擦除、虹膜 / 形状虹膜、快速摇摄、匹配剪辑、动作剪辑、摄像机延续运动）。
7. 整体连贯。 一个世界、一段色彩弧线、一条情感线索、彼此关联的场景，以及一个与开场呼应的结尾。

引擎注意事项

• 关于 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 …）。
• 更高的推理投入通常会带来更夸张、更精细的场景。