Skip to content

nzl153/paint-video-skill / paint-video

paint-video

Verified

用代码做手绘风格的动画短片:水彩、水墨用 p5.js + p5.brush,蜡笔绘本用自写的 2D canvas 蜡笔引擎,皮影用自写的皮影引擎,打斗用自写的设色水墨引擎;逐帧画,无头 Chrome 渲染,ffmpeg 合成 MP4。用户说「做个短片 / 动画 / MV / 开场动画 / 十几秒的视频」时用这份;配整首歌的长片或 MV 另看同目录的 mv-workflow.md,蜡笔画风看 crayon.md,皮影看 piying.md,打斗和雾山五行风看 wushan.md,科普讲解片(原理科普、HTML 演示 + 代码合成声效 + edge-tts 配音,允许字幕和标注)看 explainer.md。版画系列(孔版、铜版、大理石纹、蓝晒、网点、植物图版,SVG 生成,每段一种工艺)看 prints.md;音符驱动的流体彩墨 MV(WebGL 流体、抽象、不画人)看 fluid.md;沙画(灯箱上的沙底下透光、一幅抹成下一幅,WebGL 高度场)看 sand.md;作业本涂鸦(圆珠笔勾线 + 彩铅排线 + 手机俯拍的作业本,涂鸦小东西活过来,带实物笔和影子)看 doodle.md;共点蒙太奇(同一个形状始终落在画面同一点,快切或画风接力)看 montage.md;走马灯(纸雕灯里的多层剪纸被烛光透过、卷成圆柱转,灯外推进灯里,适合绕圈的故事)看 zoumadeng.md;赛璐珞动画质感(清晰清新、黄昏光、哑光陶土 Clawd、道具经手的叙事 MV、竖排纸条字幕)看 cel.md;90 年代美式动画片头(粗描边平涂、定格大头照、甩镜抖动拖影、串台换画风:黑白胶片、漫画、设定稿、8-bit)看 toon.md;要自己写配乐(Tone.js + 真乐器采样含 VSCO2 管弦乐和真鼓,离线导出,分轨加自写混音台,按拍对画面)看 music.md。

FileKindSize
SKILL.mdskill md26.6 KB
cel.mdmarkdown9.8 KB
crayon.mdmarkdown10.5 KB
directing.mdmarkdown12.5 KB
doodle.mdmarkdown13.3 KB
explainer.mdmarkdown9.4 KB
fluid.mdmarkdown9.2 KB
montage.mdmarkdown6.4 KB
music.mdmarkdown14.0 KB
mv-workflow.mdmarkdown14.3 KB
piying.mdmarkdown9.4 KB
prints.mdmarkdown6.5 KB
sand.mdmarkdown10.2 KB
toon.mdmarkdown9.3 KB
wushan.mdmarkdown22.6 KB
zoumadeng.mdmarkdown9.2 KB

mv-workflow.md

View on GitHub
# 长片 / MV 流程

从两支完整 MV 整理出来:

- 《琵琶曲》:水彩 + 毛笔,DJ 版剪到 2:09,横屏,39 镜,3102 帧。从头到交付花了一晚上加一个下午,这套流程就是在这支片里摸出来的。
- 《呆头鸟》:蜡笔绘本,2:29,36 镜,3590 帧。照这套流程走,从剧本到带字幕的成片不到 2 小时。蜡笔画风特有的东西在 `crayon.md`。

十几秒的短片不用走这套,直接按 SKILL.md 做。

## 整体顺序

音乐 → 剧本 → 逐镜表 → 风格测试 → 关键镜头静帧 → 零件库 → 分批做(静帧拼图 → 自检 → 用户看 → 渲动态)→ 全片 → 局部返修 → 调色 → 字幕 → 交付

每一步都落成文件(`STORYBOARD.md`、`SHOTLIST.md`、`PROCESS.md`、`out/check/*.jpg`),后面的步骤读文件,不靠记忆,上下文被压缩之后也接得上。剧本和手法没跟用户谈定之前不开工做成品。

## 1. 音乐先行

- 音频提取成 48kHz 立体声 WAV,放在项目里但不进仓库。**歌有版权,开源时音频和歌词都不带**,回复里也不整段贴歌词。
- 节拍:`tools/analyze.py <音频>` 用 numpy/scipy 算起音包络,自相关求 BPM,再扫相位,输出 `beats.json` 和能量图 `energy.png`。底鼓不断的曲子测出的可能是半速(《琵琶曲》65、《呆头鸟》68 实为 136 的半速),剪辑点卡在这一层刚好不乱。
- 乐句:低频(<150Hz)能量里鼓空一下的地方就是乐句交界。高频密度能分出段落的满和空。
- 太长就剪:剪掉重复的段落,接口放在乐句交界,保证节拍格子不变,剪完给用户听过再往下走。
- 用歌当剧本:主歌铺景,副歌爆发,间奏最嗨,尾奏收束。
- 要卡某个字(比如叠字每个字落在哪半拍),在人声频段(300–3500Hz)单独算起音找落点,比按歌词时间戳猜准。

## 2. 时间表当数据

- 逐镜表写在一个 Python 脚本里(模板 `tools/make_shotlist.py`),每镜用**拍号**写起止,由脚本换算成秒,同时生成 `SHOTLIST.md`(给人看)和 `src/shotlist_data.js`(给代码读)。
- 代码里不手写秒数:镜头时间一律 `S(n).t0 / S(n).t1`,拍点用 `BT(b) = offset + 60/bpm·b`。改剪辑只改脚本重新生成,画面自动跟上。
- 生成时顺便体检:切点是不是都在拍上、同一种转场是不是用太多、镜头长度是不是太平均。
- 快慢交替:主歌一镜五六秒,副歌三四秒,只有间奏里一段一拍一切。从头一拍一切到尾会累。

## 3. 风格先便宜地试

一张静帧加一段 5 秒动态就能比出风格,成本很低,别跳过。《琵琶曲》试了三轮:纸艺(像恐怖片)→ 剪影(侧脸像鸟嘴)→ 丰子恺式笔刷、不画五官,第三轮才对味。几条路的长处可以混用:主线用笔刷,回忆段用剪影配暖光。

然后挑 4–5 个最难、最关键的镜头先出静帧给用户过(代码放在 `LOOPS` 里,`--loop=keys --sheet=...` 出图),过了再搭零件库。

## 4. 代码结构

```
src/shotlist_data.js     脚本生成,别手改
src/scenes/lib.js        零件库:人物姿势、道具、天色天气、场景分层、转场,挂到 window 上
src/scenes/mv_*.js       成片:每镜一个函数,只组合零件、写镜头运动
src/scenes/timeline.js   最后加载,统一注册镜头
```

- **每镜开头重置场景状态**(`resetScn()`),镜头只声明自己要什么:天色、人物姿势、视差、风。上一镜的设定漏进下一镜,是分批做时最常见的串味。
- 世界按层画(天 / 远山 / 中景 / 水 / 人 / 前景),视差系数挂在层上,镜头运动自然有纵深。
- 人物动作做成参数对象(张嘴、倾身、歪头……),姿势之间按权重混合。**缺的字段一律默认 0**:少传一个字段会得到 NaN,`rotate(NaN)` 让整个人消失,而且不报错。
- 零件在第一批就要做到能被后面复用:后几批几乎都是在组合已有零件,速度才上得来。
- 改零件库之前先留备份(`*.bak-b1` 这样按批次命名),改错了能整体回退。
- **镜头注册集中到最后加载的一个文件**:各段镜头文件只往 `MV[n]` 里挂函数,最后一个文件统一 `shots(SHOTLIST.map(r => [r.t0, MV[r.n] || todo]))`。没做的镜头自动显示占位,改逐镜表不用动任何镜头文件。早期的 demo 文件可以留着给零件复用,它自己的 `shots` 在注册前清掉(`SHOTS.length = 0`)。
- **一镜分成多个格子时,切点避开最后一格**:最后一格落在重拍上,下一镜也从这一拍开始,那一格就一帧都不显示。切点往后挪半拍。

## 5. 分批做

- 按段落分 5 批左右,每批 5–7 镜。每批:
  1. 每镜首、中、尾出一张静帧拼图(`--sheet`)。
  2. 自己按 SKILL.md 的检查循环和下面第 7 节逐项查,修完再出一次。
  3. 发用户看拼图,点头了再渲动态。
- 帧用全局编号(`f{round(t·fps)}`)写进同一个 `out/frames`,所以每批渲完直接合成「从头到当前」的累计版,用户能连着上一批看。
- 用户授权过「一批批继续出」之后可以不等点头连着做,但自检一步都不能省。

## 6. 渲染运维

- **命令有时长上限时分段跑**:有的 agent 环境会在十分钟左右掐断命令,被掐掉的渲染子进程还可能留在后台。每段用 `--frames --range=a:b --workers=3`,控制在上限以内;中断了再跑同一条,已渲的帧会跳过(蜡笔版的 `render.mjs` 会先核对代码签名,代码中途改过就停下,见 `crayon.md`)。
- **每次续渲之前验帧**:用 PIL 把 `out/frames` 逐张打开,打不开或全黑的**挪到 `out/frames_bad`,不删**。
- 强制独显:Windows 双显卡笔记本上 d3d11 参数加 `--force_high_performance_gpu`,否则落在集显上越跑越慢。`--gpu-angle=vulkan` 在 Windows 上看起来快 10 倍,其实全黑。
- 输出要标准 tv range:`-vf scale=out_range=tv,format=yuv420p -color_range tv`,yuvj420p 有的播放器放出来全黑。
- 实测(RTX 4060 笔记本):p5.brush 3 进程有效约 2 秒/帧,全片 3100 帧约 1.5–2 小时;合成 2 分钟的片约 1.5 分钟。
- 蜡笔引擎每帧约 70ms,全片 3590 帧 4 进程约 4 分钟,一条命令就跑完,不用分段。CRF 17 出来 930MB,另压一版 CRF 25(390MB)方便传手机。

## 7. 画面和表演的经验

**画面不能空**:每镜的天、中景、水(或地面)、前景四层都要有东西。动作做不大,就靠场景撑。留白全片只许一两次,而且要是故意设计的情绪点。

**动作最快的那一下换笔刷带过**:飞白、墨线拖尾、泼墨水花、弧线残影。慢的部分照常画。

**道具动作要有物理过程**:《琵琶曲》里竹篙挑布条,第一版是一根直杆伸过去戳一下,全片唯一被用户点名「太难绷」的地方。改成篙横放在船上 → 弯腰两手抄起 → 斜着探进水里点出水纹 → 一抖挑起,篙全程斜着、两只手都握着,才像人在用工具。道具还要够大:挑起的布条放大一倍才看得清。

**过肩镜头别让人物出现两次**:前景画了他的背影,世界里就要把他本人隐藏掉(`himPose: 'none'`),镜头也要收到拍不到他那条船的位置。第一版画面右边缘露出了世界里的他,看起来像「两个男主」。前景的背影按画面一角等比缩小,别占满画面;画纸上要画得出具体内容(她的小像),别只画几道线。

**自检清单**(在 SKILL.md 那份之外):
- 朝向:翻转过的角色,脸、头发、腮红、手里的东西是不是同一个方向。坐标本来就按朝左写的,再翻一次头发就盖到脸上。
- 手必须连着胳膊:顺着袖子找回肩膀。零件要在全片最近的景别下查一遍,中景看不出的悬空手,一到特写就露馅。
- 贴合:人坐船里要「船后半 → 人 → 船舷」三层夹住。
- 颜色撞背景:浅青衣服贴在江水上几乎看不见,特写里要换深一档。
- 放大看头、手、道具,缩略图看不出问题。
- 改过的地方出改前改后对比图一起发。

**p5.brush 的坑**:
- 大多边形多半在画面外时整块填不上色,留下方块边。在 `paint` 底层统一处理:有相机时填色部分先裁到镜头范围里,描边照旧用原形状。
- 水洗是半透明的,压不出实心剪影:剪影用 p5 原生填色,进出前 `flushBrush()`,远近分深浅层。
- p5 2.x 没有 `curveVertex`:自己用 Catmull-Rom 插成点。
- `ellPts` 的旋转参数只是起始角,不会转椭圆,要转用 `rotAbout`。

## 8. 局部返修

用户看完整片指出某一镜,只动那一镜:

1. 代码先留 `.bak`,改这一镜的函数。
2. 把这一镜时间范围的帧**挪到** `out/frames_s<镜号>_v1` 备份,不删。
3. 出这一镜的静帧拼图自检。
4. `--frames --range=<t0>:<t1>` 只渲这一段(蜡笔版要加 `--keep-frames`,否则代码签名对不上会停下),再 `--encode` 整片合成。

一镜 66 帧,重渲加合成共约 4 分钟(p5.brush)。

## 9. 调色放在最后,用 ffmpeg 在成片上做

不重渲。先挑 5 个不同天色的时间点,每点出 4 种调色拼成一张对比图给用户挑,选定再套到整片(`-c:a copy`,约 1.5 分钟):

```
A 原片      null
B 暖纸      colorbalance=rs=.04:gs=.01:bs=-.05:rm=.03:bm=-.03,eq=saturation=1.05
C 浓一点    eq=contrast=1.08:saturation=1.15:gamma=0.97,colorbalance=rm=.02:bm=-.02
D 褪色胶片  curves=all='0/0.05 0.5/0.52 1/0.95',eq=saturation=0.85,colorbalance=rs=.03:bh=-.04
```

本来就偏暖的镜头(黄昏、灯会)套上 C 会更浓,交付时提醒用户留意。原片保留,调色版另存文件名。字幕叠在调色版上。

## 10. 歌词字幕(艺术字)

画面里照旧不写字,字幕是**单独一层透明 PNG 序列**,最后用 ffmpeg 叠到成片上。这样改字不用重渲画面,改一轮几分钟。

现成的工具在 `crayon-kit/sub/`(蜡笔版,细节见 `crayon.md` 的字幕一节),换字体、换质感就能给水彩片用:

| 文件 | 干什么 |
|---|---|
| `song.json` | 这首歌的设定:歌词文件、字体、节拍、怎么拆句、叠字的拍点、从哪一刻起是夜景(照 `song.example.json` 写) |
| `sub.py` | 读歌词、画一帧字幕层(`render(t, specs)`) |
| `probe.mjs` | 探针:记下每帧人物实际画在哪,写 `boxes.json` |
| `layout.py` | 自动排版,输出 `specs.json` |
| `override.json` | 人工指定的位置,优先于自动排版(`{"句号": {"x":..,"y":..,"size":..}}`) |
| `review.py` | 审查拼图:每句三帧 |
| `final.py` | 多进程渲整片字幕层(可续跑),`--encode` 合成 |

**时间**:歌词时间戳是原曲的,剪过歌就要按剪切点换算(每刀减去剪掉的长度和交叉淡化的时长),剪掉那段里的句子直接丢掉。先数清楚剪完剩几句再报数。

**字体**:出对比图给用户挑。把同一句歌词写在白天和夜景两帧上,8 款左右拼成一张,再附一张 1:1 的特写看笔画。用 Google Fonts 上的 OFL 开源字体(放项目的 `fonts/`,不装进系统),开源时能带。系统自带或随 Office 装的字体(华文行楷、方正舒体这些)不能跟着分发。下载字体前先问用户。
- 古风毛笔:龙藏体为主、志莽行书做反差(《琵琶曲》)。
- 蜡笔绘本:马善政楷书(《呆头鸟》)。行书放在蜡笔片里显得端着,幼圆太像电脑字。

**排法**:
- 竖排,一列从上往下,多列从右往左读。后半句要放在前半句的**左边**。
- 一句拆成前后两半,**唱到哪半句才出哪半句**,不是整句一起出来。镜头在句中切换时,前半句跟着切镜淡出,后半句换到新镜头的留白处。
- 出场跟着画风走:毛笔是墨迹顺着书写方向刷出来,蜡笔是一个字一个字从上往下写出来。不做弹跳、发光。
- 副歌开头、点题句可以用反差字体放大。**大字远离人物,小字可以靠近人物**。结尾点题句可以分列在两人左右,像一副对联。

**硬要求**:
- **字绝不能压在人物身上**,包括衣服、背影、剪影。
- **对比度要够**:笔画细的字体要加粗(MaxFilter 3–5)。字底下衬一层浅色(毛笔版是贴字一圈实的、外面一圈柔的;蜡笔版是一整块毛边蜡)。
- **暖色(灯会橙黄)段别用白字**,看着难受。深色墨字配浅色衬底,按段落换墨色:白天用墨黑,灯会用深赭,雨天用青灰,黄昏用暖褐。蜡笔片的夜景是例外:整段深蓝夜色,用暖白字配深蓝衬底。

**自动排版怎么避开人物**,两种办法:
1. **探针(推荐,引擎是自己写的就能用)**:包住画人物的函数,记下它每帧实际画到的屏幕范围。见 `crayon.md`。
2. **猜颜色**(《琵琶曲》用的,p5.brush 画面拿不到绘制调用时):在每个半句显示的整段时间里每秒抽 4 帧,禁区取并集:
   - 成片的深色块(亮度 <0.3,先腐蚀掉细线再膨胀):剪影、头发、船都在里面,山线和雨线不算。
   - 主角衣服的颜色(比如粉衣:红减绿 >0.14、蓝 >0.45)。**一定要卡蓝色通道**,否则灯会的橙色背景整片都会被当成人物。
   - 被墨线围起来的区域:墨线闭合后 `scipy.ndimage.binary_fill_holes` 填洞,连到画面边上的水和天不算。浅色衣服和背景颜色几乎一样时只能靠这一招。剪影段整片都暗(深色占比 >20%),这一项要关掉。

   要调三套规则,还会误判。

找不到完全空的位置时,字号依次降两档,还是不行就改用软约束(按压到的面积重罚,但不排除),并打印出来人工看。**字号要有下限**:不设下限的第一版死循环了二十分钟。

**检查**:每句出开头、中间、结尾三帧拼图,自己逐张看有没有压到人、对比度够不够、读的顺序对不对,修完再合成整片。全片 3100 帧的毛笔字幕层 6 进程约 8 分钟,蜡笔字幕层加合成约 3 分钟。

## 11. 交付

- 成片 + 这批的静帧拼图,说清时长、改了什么、自己查出并修掉了什么,没看的部分明说。
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall