name: mv-director description: 把一首歌做成真正的音乐 MV，画面全部用代码画（canvas 逐帧渲染，1080p 60 帧，不用生图）。先听懂歌（拍子、小节、副歌、抽鼓，逐字强制对齐），再读懂歌词、逐句分镜，让画面演出每一句在说什么，并卡准音乐；画风可以从风格库（lemo-opuscar、花叔 huashu-art-motion 等）里挑一种来借。做完用脚本量字幕对不对得上、画面跟没跟拍，不合格自己改。用户说「做 MV」「给这首歌做画面」「歌词视频」「卡点视频」「音乐视频」时用。

MV 导演（mv-director）

一支好的 MV 同时做到两件事：

1. 画面演出歌词在说什么。唱到「下雨」，画面里就下起雨；唱到「你走了」，就有人转身走远。
2. 画面跟着音乐走。字在唱出来的那一刻出现，镜头在小节头上切，进副歌那一拍画面整个炸开。

AI 自己做 MV 最常见的三种坏样子：

• 抓一个好看的意象从头画到尾，歌词只是贴在上面的字幕；
• 字比唱的早半秒到一秒出来；
• 画面在自己飘，小节头上没反应。

这个 skill 用一套流程和脚本把这三件事管住。画风不是它的事：可以从风格库里挑一种借来用，但点子、故事、画面都由你读懂歌词以后自己构思。

铁规矩

1. 按步骤来，每一步的门槛过了才进下一步。不许跳过「读懂歌词」直接画。
2. 每一句歌词，唱的时候画面里都要能看出它在说什么。
3. 时间只从 song.json 来：拍子、小节、每个字的开唱时间都是脚本测的、对齐的。卡点表写 bar9、line3、line3@某个词，不手写秒数。逐字时间必须是强制对齐（song.md 会写来源）；不是的话，歌词只能整句出现，不许逐字卡。
4. 画面只由时间 t 决定：不许 Math.random()、Date、上一帧的状态。随机用 M.hash(i) / M.rng(种子)。
5. 画面全部用代码画：不用生图、照片、网图。借画风只借规则和画法，不搬别人的场景和角色。
6. 脚本报 ✗ 必须改；⚠ 要么改，要么在 plan.md 写一句为什么不改。
7. 每一步跑完都看图：songmap.png、cue_map.png、逐句图、每小节图、审片图。
8. 不上网找别人做好的 MV、代码来改。借了谁的画风、参考代码、字体，在 NOTES.md 写清作者和许可。

步骤

所有脚本在本 skill 的 scripts/，Python 用 python -I，第一个参数是项目文件夹。Windows 报编码错就先设 PYTHONUTF8=1。

0. 检查环境、建项目

python -I scripts/doctor.py          # 缺什么、怎么装（安装说明：references/安装.md）
python -I scripts/new_project.py <项目> --song 歌.mp3 --lyrics 歌词.lrc --start 秒 --end 秒 --demucs

• 歌词：
  • 带时间的 LRC 最好；一行一句的纯文本也行，会先整首对一遍，找出每句的开唱时间，要求整首不超过 5 分钟。
  • 歌词要和唱的一字不差、重复的句子也要写出来。
  • 网上 LRC 的时间常差 0.5–1 秒，只用它的文字和顺序，逐字时间以强制对齐为准。
  • 不是中文歌加 --lang English（日语 Japanese、粤语 Cantonese、韩语 Korean……）。
• 分轨：--demucs 自动分四轨（鼓、贝斯、人声、其他）；已经分好的用 --stems 文件夹。拍点从鼓轨找，逐字时间用人声轨做强制对齐。不分轨也能跑，但拍点可能差半拍，也没法逐字对齐。
• 用户没说做哪一段：先不带 --start/--end 建一个整首的项目，读它的 song.md 挑一段：
  • 从小节头开始，在一句唱完、下一段开始的小节头结束；
  • 一定包含「进副歌」那一下，前面留几小节做反差。
  • 挑好再带上起止秒建正式项目，在 plan.md 写为什么挑这段。
• 产出：song.json song.md songmap.png audio.wav，模板 index.html scene.js cues.json plan.md，运行库 mv/mv.js，字体 fonts/。

1. 拆解音乐

读 song.md，看 songmap.png，填 plan.md 第 1 节：速度、段落、大时刻候选、抽鼓、逐字时间来源。

2. 读懂歌词（最重要的一步）

读 references/读懂歌词.md，填 plan.md 第 2–4 节，同时写进 cues.json：

• story：这一段在讲什么：谁、发生了什么、情绪怎么走、在什么时代和地方。
• board：逐句分镜，每一句都要写：
  • says：字面在说什么；
  • see：画面上具体看到什么；
  • keys：这句里要演出来的原词，1–3 个。
• 主角长什么样、世界什么样，定下来全片不变。
• 门槛：只看 see 那一列，没听过这首歌的人也能把歌词意思猜个八九不离十。

3. 选画风

画风从哪来，听用户的：

• 用户可能给你一个风格库：任何仓库或 skill 都行，比如 lemo-opuscar、花叔的 huashu-art-motion，或者别的画风集合；
• 也可能直接说一种画风、给参考图；
• 什么都没说，就用 references/代码画具体东西.md 里的基础画风。

给了风格库、没说要哪种：

1. 自己去翻这个库：先读它的 README 和索引，弄清楚画风是怎么组织的（每个画风的说明文件在哪、有没有样片源码和样张），把全部画风的名字和一句话简介列出来。
2. 按第 2 步读懂的歌（年代、情绪、要画的东西）挑 3–5 个最配的，每个写一句为什么。
3. 问用户要哪一种（也告诉他全部有哪些），等他回答再往下做。

用户已经说了要哪种：直接用。用户说「你定」或者说了不要问：自己挑最配的，在 plan.md 写理由。

选好以后读 references/接画风.md：

• 读这个画风的说明和样片源码，把规则抄成 plan.md 里的「画风卡」：色板、材质、线条、镜头语言、动作节奏、忌讳；
• 再用这些规则自己画你的分镜。只借画风，故事和画面还是从这首歌来。

4. 定画法、列零件

读 references/代码画具体东西.md：

• 把每句 keys、see 里要出现的东西（人、动物、房子、天气、光、物件、动作）列成零件清单，每样写成一个会动的函数；
• 人和动物用关节剪影或这个画风自己的画法，姿势用关节角度的关键帧。

运行库用法见 references/画面库.md。

5. 卡点表

写 cues.json（格式见 references/卡点表.md），然后跑：

python -I scripts/cue_lint.py <项目>

• 镜头跟着歌词换：每句开唱换一个镜头（"at": "line3"）；关键词上切第二个镜头或加时刻（"at": "line3@某个词"）。
• 进副歌那一拍要有大时刻；起伏 arc、打点规则按需要写。
• 门槛：0 个 ✗。脚本会逐句查：每句都有分镜，唱到这句画面会换，keys 都是歌词原词，镜头切在小节头或歌词上。

6. 画，逐句自查

写 scene.js（零件函数 + 每个镜头），边写边出图：

python -I scripts/render.py <项目> lines            # 每句唱到关键词那一刻一张 → out/stills/逐句.jpg
python -I scripts/render.py <项目> bars --debug     # 每小节一张
python -I scripts/render.py <项目> moments          # 每个大时刻前后 6 帧

• 遮住字幕只看图：能不能看出这句在说什么？画风对不对味？看不出、不对味就重画这一镜。
• 结果填进 plan.md「逐句自查」。
• 也可以开浏览器预览（项目里 python -m http.server）：空格播放，←→ 跳小节，D 显示节拍信息。

7. 草稿 + 审片（循环到过关，最多三轮）

python -I scripts/render.py <项目> video --draft
python -I scripts/check.py <项目> --draft

门槛：

• 每句歌词上屏比开唱早不超过 0.35 秒、晚不超过 0.15 秒；唱的时候 ≥75% 时间在屏上；
• 小节头命中 ≥ 70%，大时刻全炸；
• 没有超过 1 秒的死画面；
• 画面起伏和 arc 的相关 ≥ 0.4；
• 硬切 ≥ 80% 落在拍上或字上。

改法见 references/审片.md。

8. 成片和交付

python -I scripts/render.py <项目> video
python -I scripts/check.py <项目>

在项目里写 NOTES.md：

• 这段歌在讲什么、每句怎么演的（贴逐句自查表）；
• 选了哪个画风、为什么；
• 审片数字、遇到的问题和怎么解决的；
• 署名：借了谁的画风、参考代码、字体（作者、仓库、许可）。

成片是 <项目>/out/mv.mp4。

导演守则

1. 歌词说什么就演什么：名词、动作先画出来。抽象句找一个最能代表它的具体处境。
2. 关键词那一刻兑现：唱到那个词，画面正好变（line3@某个词）。
3. 一句一个画面，长句两个；重复的句子要升级，不原样再放一遍。
4. 主角和世界前后一致，一句接一句讲成一件事。
5. 反差：主歌收着，铺垫越来越紧，抽鼓那一下几乎停住，副歌全放开。
6. 大时刻是画面本身变：尺度跳变、世界翻转、一个人变一群人。闪白、震动只是调料。
7. 拍子分层：小节头换镜头或推镜头，拍上元素脉动，字唱出来的那一刻落下来。
8. 歌词字是画面的一部分：清楚、够大（≥108px），跟着段落换上屏方式，不挡主角的脸和关键动作。
9. 借画风不借内容：画风库的样片只学画法，故事和镜头从这首歌里来。

文件

出问题看 references/排错.md。

mv-director · 让 AI 读懂歌词、卡准节拍，用代码做音乐 MV

给 Codex、Claude Code 这类 AI 编程助手用的 skill。你给它一首歌和歌词，它会：

1. 听懂音乐：把歌分成鼓、人声等几条音轨，找出每一拍、每个小节、副歌和抽鼓；用对齐模型把每个字的开唱时间对到大约 0.1 秒。
2. 读懂歌词：先写清楚这首歌在讲什么、主角是谁、情绪怎么走，再逐句写分镜，每句画面演出这句在说什么。
3. 用你选的画风来画：可以借 lemo-opuscar、花叔 huashu-art-motion 这些风格库里的画风（换别的风格库也行）。它会先翻一遍有哪些画风，推荐几个最配这首歌的，问你要哪个。
4. 卡点、渲染、审片：镜头切在小节头上，进副歌那一拍画面炸开，字在唱出来那一刻出现；渲出 1080p 60 帧，再从成片画面里量一遍字对不对得上、画面跟没跟拍，不合格自己改。

画面全部用代码画（HTML Canvas 逐帧渲染），不用生图。

安装

1. 装环境

需要 Python 3.9+ 和 ffmpeg，然后：

python -m pip install numpy scipy matplotlib pillow playwright demucs torch transformers
python -m playwright install chromium

• demucs：分轨，推荐装。
• torch + transformers：逐字对齐，强烈推荐装。有 NVIDIA 显卡就装 CUDA 版 torch，没有也能用 CPU。
• 对齐模型第一次用时会自动下载约 1.8 GB；国内先设 HF_ENDPOINT=https://hf-mirror.com。

装完在 skill 文件夹里跑一次 python -I scripts/doctor.py，它会告诉你还缺什么。详细说明见 references/安装.md。

2. 装 skill

在 Codex 里发：

$skill-installer 安装 https://github.com/Yari-tuber/mv-director（SKILL.md 在仓库根目录，安装时用 --path . --name mv-director）

也可以自己克隆：

git clone https://github.com/Yari-tuber/mv-director ~/.agents/skills/mv-director    # Codex
git clone https://github.com/Yari-tuber/mv-director ~/.claude/skills/mv-director    # Claude Code

装好后新开一个对话。

3. 准备一个风格库（可选）

想借画风，就把风格库下到你的工作文件夹，比如：

git clone https://github.com/lemomo-ai/lemo-opuscar

花叔的 huashu-art-motion 可以按它的说明装成 skill，也可以 clone 下来。别的风格库也行，只要里面有画风说明。

用法：提示词模板

工作文件夹里放好歌（mp3 / wav）和歌词（带时间的 .lrc 最好；一行一句的纯文本 .txt 也行），然后对 AI 说：

让它翻风格库、推荐几个给你选

用 mv-director 给 song.mp3 做一支 MV，做 30 秒左右，你挑最有戏的一段。
歌是 <歌手> 的《<歌名>》，歌词在 lyrics.lrc。
画风从 lemo-opuscar 里挑：先翻一遍它有哪些画风，按这首歌推荐几个给我选，我选好你再做。

它会列出推荐和全部画风，然后问你。你回一句就行：

就用 <画风名>。

换成花叔的画风库

……画风从花叔的 huashu-art-motion 里挑：先翻一遍有哪些画风，推荐几个给我选。

换成别的风格库

……画风参考 <风格库的文件夹或 GitHub 地址>：先看懂它的画风是怎么组织的，推荐几个给我选。

直接指定画风，不用问

……画风用 lemo-opuscar 的 ink-wash（中国水墨）。

指定段落

……只做 0:45 到 1:20 这一段。

成片在项目文件夹的 out/mv.mp4，制作记录在 NOTES.md。

它和别的 MV skill 有什么不一样

我们读过、跑过十来个开源的 MV / 画风 skill。它们各有长处，但没有一个把这四件事都串起来、用检查卡住：

流程

建项目（分轨、测拍、逐字对齐）→ 拆解音乐 → 读懂歌词、逐句分镜 → 选画风（问你）
→ 画风卡、零件清单 → 卡点表（检查）→ 画、逐句出图自查 → 草稿审片（最多三轮）→ 成片

每一步的做法和门槛写在 SKILL.md，细节在 references/。

局限

• 画得好不好看靠模型：画面是模型现写的代码，画风库只是参考。
• 画风借规则不借内容：故事和镜头都要模型自己构思。
• 逐字对齐需要装模型：没装时只能用 LRC 的整句时间。
• 对齐一次最多 5 分钟：纯文本歌词要整首对齐，所以整首不能超过 5 分钟；带时间的 LRC 没有这个限制。

致谢与许可

• 本 skill：MIT，© 2026 亚里（Yari-tuber）。
• 逐字对齐模型：Qwen3-ForcedAligner-0.6B（阿里通义千问，Apache-2.0），用的时候下载，不随仓库分发。
• 分轨：demucs（Meta，MIT），需要自己安装。
• 参考代码/剪纸木偶/：Miranda Dixon-Luinenburg（cyborggirl963）的 paper-cut 引擎，MIT（见同目录 LICENSE-paper-cut.txt）。只作为关节剪影画法的参考，不直接加载。
• 字体：思源黑体 / Noto Sans SC、霞鹜文楷、抖音美好体、站酷庆科黄油体、Bangers、Anton，都是 SIL OFL 1.1，作者和来源见 fonts/字体授权.md。
• 文档里提到的风格库 lemo-opuscar（LemoLab，MIT）、huashu-art-motion（花叔 alchaincyf，MIT）不随本仓库分发，请到原仓库获取并遵守它们的许可。
• 做的 MV 发布时请署上歌曲的版权信息，以及借用的画风来源。