paint-mv-skills Skill 技能

技能简介

paint-mv-skills 是一套给 AI Agent 用的 MV（音乐视频）制作技能：输入一首歌的音频和歌词，输出一支手绘水彩风格的动画 MV（MP4）。它的流程完全照 PDoomVideo（Claude 为《I'm Upping My P(doom)》画的 MV）的源码来做——每一帧都是歌曲时间的纯函数，由 p5.js + p5.brush 在 headless Chrome 里画成水彩与墨线；导演写分镜、并行子代理一章一章作画、联系表检查，最后用 ffmpeg 与歌曲合成。画风固定，内容跟着歌词走：水彩加墨线的绘本观感、纸纹、"沸腾"的线条、卡拉 OK 字幕、笔刷转场都沿用原作，而构思、角色、场景和道具每首歌都从歌词重新设计。

核心能力

• 四个技能分工明确：paint-mv 总控（建项目、测节拍与对齐歌词时间、落地角色、给每章派子代理、统稿、出片）；paint-mv-storyboard 从歌词写分镜（构思与反转、角色表、每章场景、每句歌词一个镜头、有动机的转场）；paint-mv-animate 画师规范（引擎 API、按原作风格设计角色、技法目录、原作九章示例）；paint-mv-render 负责联系表检查、短片、全片并行可续渲、局部重渲、编码与验收、排错。
• 歌词驱动创作：角色、场景、道具全部从歌词重新设计。演示片《凌晨录音室》里的角色——唱歌的"我"小夜、"街上只剩红绿灯"的灯灯、"每个没被听见的字都还有体温"的字灵、"耳机里的鼓点"鼓点仔、"白天的嘈杂"嘈杂怪——都直接来自歌词意象。
• 每一帧都是时间的纯函数：保证可复现、可续渲、可局部重渲，调整某一段不影响其他帧。
• 并行章节作画：每章一个子代理并行绘制，各自用联系表（contact sheet）自检，再统一处理章节交界、转场与性能。
• 自动对齐歌词：纯文本歌词先用 faster-whisper 自动对齐成时间轴；也可使用 LRC 文件。
• 完整可复现示例：demo/project/ 内含分镜（STORYBOARD.md）、角色（characters.js）、共享场景（sets.js）、五个章节源码与封面绘制脚本，可一键复现整支 MV。

安装配置

• 环境要求：Node.js ≥ 18、ffmpeg、Google Chrome、git、patch；纯文本歌词自动对齐还需要 uv。
• 克隆并拉取原作源码：

git clone https://github.com/lintsinghua/paint-mv-skills.git
cd paint-mv-skills
node skills/paint-mv/scripts/fetch_upstream.mjs   # 按固定提交拉取 PDoomVideo 源码并打补丁

• 放置技能目录：把 skills/ 下的四个目录放到你的 Agent 读取技能的位置——Cursor 放 .cursor/skills/，Claude Code 放 .claude/skills/ 或 ~/.claude/skills/（本仓库已用符号链接指向 skills/，直接在仓库里打开即可使用）。
• 关于原作源码：PDoomVideo 未声明开源许可证，因此本仓库不包含它的任何文件，而是由 fetch_upstream.mjs 从 GitHub 按固定提交拉取引擎与示例，再应用 template.patch（把歌曲参数移到 song.js、支持 macOS 的 WebGL 后端、中日韩字体与卡拉 OK 扫字速度）。

使用步骤

1. 对 Agent 说："用这首歌和歌词做一支 MV：song.mp3、lyrics.lrc"。没有合适的歌时，可以像演示那样先用 YuE2 贴歌词生成一首。
2. new_project.mjs 建项目：生成引擎模板、分析节拍（BPM、首拍）、把歌词转成时间轴；纯文本歌词先自动对齐。
3. 先出对拍短片确认时间与节奏是否准确。
4. 按 paint-mv-storyboard 从歌词写 STORYBOARD.md（构思与反转、角色表、每章场景、每句歌词一个镜头）。
5. 写本片角色 characters.js 与共享场景 sets.js，输出角色模型表确认形象。
6. 每章派一个子代理并行作画，各自用联系表检查构图与连续性。
7. 统稿处理章节交界、转场与性能，随后全片逐帧渲染并编码为 MP4：

node render.mjs --frames=0: --workers=4   # 逐帧渲染，可续渲
node render.mjs --encode --out=out/mv.mp4

8. 需要手工对齐纯文本歌词时，可单独运行对齐脚本：

uv run --python 3.12 --with faster-whisper --with zhconv python skills/paint-mv/scripts/align_lyrics.py 
    song.mp3 lyrics.txt --out lyrics.srt --lang zh

适用场景

• 独立音乐人做 MV：预算有限但有原创歌曲的创作者，用歌词驱动生成专属动画 MV。
• AI 生成歌曲的配套视觉：为 YuE2、Suno 等工具产出的歌曲快速配上完整 MV。
• 社媒音乐短片：把副歌片段做成有统一画风的竖屏或横屏短片。
• 歌词可视化：把歌词意象转成角色与场景，做卡拉 OK 式扫字字幕视频。
• 绘本/水彩风格内容实验：需要固定手绘水彩＋墨线美术风格的动画项目。
• 音乐教育与内容展示：为歌曲讲解、作品集提供高质量视觉呈现。

适用人群

• 独立音乐人、音乐内容创作者与 MV 导演。
• 使用 AI 生成歌曲、需要配套视觉的创作者。
• 会用 Claude Code / Cursor 并希望把动画制作流程自动化的设计师与开发者。
• 需要批量产出统一画风音乐短视频的内容团队。

工作原理

整套流程把 MV 制作拆成"导演—分镜—作画—渲染"四层技能。引擎上，每一帧都是歌曲时间的纯函数，由 p5.js 与 p5.brush 在 headless Chrome 中绘制成水彩与墨线画面，因此同一时间点永远渲染出同一帧，支持断点续渲与局部重渲。项目建立阶段会分析 BPM 与首拍、把歌词对齐到时间轴；创作阶段由导演技能从歌词生成分镜并落地角色与场景；执行阶段由并行子代理一章一章作画并用联系表自检；最后用 ffmpeg 把逐帧画面与歌曲合成，可加卡拉 OK 字幕与笔刷转场。

官方链接

• GitHub 仓库：https://github.com/lintsinghua/paint-mv-skills
• 原作流程参考 PDoomVideo：https://github.com/JohnHeibel/PDoomVideo
• 水彩笔刷引擎 p5.brush：https://github.com/acamposuribe/p5.brush
• 演示用歌曲生成工具 YuE2：https://noiz.ai/lp/yue2