Music Video：纯代码绘制的卡点完整 MV

音乐视频

子命令（先检查这些）

调用	操作
/music-video help、/music-video 无歌曲，或“如何使用？”	逐字打印下面的帮助块，然后检查前置条件（node -v、ffmpeg --version、uv --version、Chrome 存在）并报告每个为 ✅/❌，附带安装命令。停止；不要开始视频。
/music-video lessons	打印 LESSONS.md（最新的条目完整显示，旧条目仅显示标题）。
/music-video <song 文件> [lyrics.srt] [flags] [notes]	解析下面的旗帜，用一行说明哪些门控已开启以及哪些选择已设置，然后运行管道。

帮助

/music-video: 将歌曲转换为完全由代码绘制的节拍同步音乐视频，
             从手绘卡通到清晰的营销风格动态设计。

用法
  /music-video ~/Downloads/song.mp3                     嵌入歌词的 Suno 文件无需其他额外输入
  /music-video ~/Downloads/song.mp3 lyrics.srt          其他歌曲：提供带时间戳的歌词 (.srt)
  /music-video song.mp3 "noir style, cat detective"     可选的创意方向
  /music-video song.mp3 --auto --style=editorial --human=~/me.jpg --dir=~/musicVideos
                                                        完全自动化：每个选择由旗帜设置
  /music-video help | lessons

旗帜（默认：在故事板和预览处都停止等待您的批准）
  --skip=storyboard        不等故事板；仍等预览
  --skip=pilot             等故事板；不等预览
  --skip=all  (或 --auto)  无停止：输入歌曲，输出完成的 MP4，完全代理化
  --design                 更多规划：增加设计阶段（角色模型表、调色板样本、每章节一个风格帧）
                           并在任何动画之前停止以便您在视觉上迭代。结合使用：--design --skip=pilot

选择（未设置的在简短访谈中询问；在 --auto 下取默认值）
  --style=painted|editorial|keynote|geometric|hybrid
                           painted   = 手绘水彩卡通（原始外观）
                           editorial = 温暖纸张、精确细线、衬线字体、平静
                           keynote   = 近乎黑色、渐变发光、光束、粒子
                           geometric = 瑞士网格、色块、参数曲线、粗体无衬线
                           hybrid    = 编辑风格主歌、主题演讲风格副歌
                           ask (默认) = 每种风格渲染一帧静态图像，让您选择
                           自动默认值：editorial
  --lyrics=kinetic|bar|hooks|off   kinetic 排版 / 字幕栏 / 仅钩线 / 无
                           （默认：矢量风格为 kinetic，手绘为 bar）
  --density=bold|every-line|abstract
                           bold (默认) = 每 2–4 行一个强图像，额外笑点作为
                           背景彩蛋；every-line = 每行歌词一个笑点
  --human=PHOTO|pip        谁扮演“你”：从照片漫画化，或使用默认的 Pip
  --dir=PARENT             歌曲文件夹存放位置（默认 ~/PROJECTS）；PARENT/_shared/
                           在多个视频间保留可复用内容（您的照片、您的角色）
  --interview / --no-interview   强制或跳过前期访谈 (G0)

  跳过的门控并不意味着跳过工作：工件仍然被制作并自我审查，
  其选择记录在 DECISIONS.md 中供您之后阅读。

过程（有停止时约 1.5–2 小时；使用 --auto 约 45–60 分钟）
  1. 分析歌曲：节奏、落点、段落、歌词时间
  1b. 访谈：风格静态图像 + 任何未设置的选择，停止     （除非 --auto / 全部已设置）
  2. 编写 STORYBOARD.md 并停止等待您的批准         （除非 --skip）
  2b. 使用 --design：模型表 + 风格帧，停止以迭代
  3. 构建 30 秒预览剪辑并停止供您观看   （除非 --skip）
  4. 并行构建剩余部分（子代理），检查每个场景变化
  5. 渲染 out/<song>_full.mp4（1080p，H.264 + AAC），准备上传 YouTube

需要   Node 20+、Google Chrome、ffmpeg、uv  (Mac: brew install node ffmpeg uv)
成本    无 API 费用；使用您的 Claude 计划（整首歌曲会消耗相当数量的使用量）
输出    项目文件夹（默认 ~/PROJECTS/<song>-video/，或 --dir），在任何仓库之外
之后    “将今天的经验添加到 music-video 技能”使下一个视频更好

完成的示例是 zoo2 视频（“Please Select Your Ending”，4:30）：约 100 个镜头，大约 1 小时 40 分钟实际时间构建。 examples/zoo2/ 包含其故事板、每个章节文件以及制作过程，包括时间线、令牌和成本。开始前阅读 LESSONS.md：它是改进日志，并且覆盖此文档中与之矛盾的任何内容。

为什么用代码，而非生成

图像模型（Deforum、SDXL-Turbo img2img 等）每帧重新猜测，导致闪烁、面部变形和手部缺陷。 Zoo2 的第一版尝试过夜生成但被拒绝。代码绘制的帧是歌曲时间的纯函数： 平滑、符合模型且完全贴合节拍。云视频模型（Kling、Seedance、Veo）是另一条路，每首歌曲约需 70–300 美元。

旗帜和门控

从参数以及普通词语中解析旗帜：“无停止”、“完全自主”、“直接制作”等同于 --skip=all；“跳过故事板审批”表示 --skip=storyboard；“让我先看角色”、“更详细地规划”表示 --design。值用逗号组合（--skip=storyboard,design）。未知旗帜：说明并停止。

门控	默认	跳过时
G0 访谈	当任何选择未设置时停止	在 --auto/--no-interview 下，未设置的选择采用默认值并记录到 DECISIONS.md。
G1 故事板	停止	编写后，对照歌词表进行一次自我批评（每行一个想法？每段副歌都有回报？主题在结尾回归？），然后继续。
G2 设计（仅与 --design 一起）	停止，迭代直到批准	--skip=design 保留阶段但自我批评模型表而非等待。
G3 预览	停止	仍构建预览（它创建章节所需的共享 SETS）。在继续前进行两次联系表审查并修复常见首轮错误。

选择（--style、--lyrics、--density、--human、--dir；详见帮助）。普通词语同样有效：“干净”、 “企业”、“营销”、“非幼稚”、“清晰”表示矢量风格（询问哪种，或在 --auto 下使用 editorial）； “像动物园视频”、“手绘”表示 painted。在 STORYBOARD.md 顶部和 src/config.js 中记录最终选择，以 PROJECT.style、PROJECT.lyrics 形式，以便子代理继承。

仅当用户明确说明时才跳过门控；有疑问时停止。停止是真实的：结束本轮并等待。 对于每个跳过的门控，追加到 DIR/DECISIONS.md：门控、决定内容、权衡的替代方案以及审查的图像路径。在最终报告中链接 DECISIONS.md，以便用户审计。 绝不要跳过步骤 8 中的最终 ffprobe 检查以及歌词/帧抽检：这些是验证，而非审批。

管道（按顺序执行；除非旗帜跳过，否则停止是真实的）

1. 项目。 在任何仓库之外创建项目文件夹：PARENT/<song-slug>/，其中 PARENT 是 --dir （默认 ~/PROJECTS），并将歌曲移动到其 assets/。将参考照片（--human）放入 PARENT/_shared/。 bash ~/.claude/skills/music-video/scripts/setup_project.sh PARENT/<song-slug> 这将克隆 ClaudeAnimationBase 在 UPSTREAM_PIN、添加 src/cast.js（Pip、道具、卡拉 OK）并连接卡拉 OK。 需要 Node 20+、Chrome、ffmpeg、uv 和 git。
2. 分析。 uv run ~/.claude/skills/music-video/scripts/analyze_song.py SONG --project DIR [--srt LYRICS.srt] 这将写入 src/config.js（相位拟合的 bpm 和偏移）、src/lyrics.js 和 analysis.json。绝不要信任 librosa 的 BPM。 使用拟合值。对照 [Chorus] 部分开头检查 energy_drops。Suno 导出的文件 嵌入了带 [Section] 标签的 SRT 轨道；对于其他歌曲，先获取时间（询问用户，或使用 whisper 对齐）。 拟合的 BPM 可能输出为感觉节奏的两倍（低连贯性，一行歌词 = 两“小节”）：在故事板中注明 感觉节奏并使用 bt(2k) 表示感觉节拍。 2b. 访谈 (G0)。 仅当每个选择都已设置或给出 --auto/--no-interview 时跳过。否则：
   • 首先展示风格，用图片。 如果 --style 未设置，渲染比较帧：node design/style_tests.mjs （由 setup 复制）将相同的歌词时刻以 editorial、keynote、geometric 和 hybrid 风格绘制 （--line1/--line2/--stamp 设置文字），输出到 out/design/style_test_*.jpg 和 style_tests_all.jpg。连同 如果用户尚未见过，发送它们以及 zoo2 示例的一张手绘帧。人们无法从文字中挑选风格。
   • 然后在一次 AskUserQuestion 轮次中询问其余未设置的选择（歌词、密度、人类），外加 故事板本身无法确定的歌曲特定调用：如何字面展示真实品牌或产品，以及 如何展示敏感的歌词行（暴力、丑闻、真实事件）。
   • 复用优先于重绘： 如果 PARENT/_shared/cast/ 已经为此人拥有角色（例如 <name>.js + <name>_body.js，在早期视频中已批准），将这些文件复制到 src/vec/，在 vec.js 之后添加它们的 <script> 标签，并直接使用（包括表情和姿势控制）。 仅当用户要求更改时才重绘。新角色批准后，将其文件复制到 PARENT/_shared/cast/（在 _shared/README.md 中添加一行），以便下一个视频复用。
   • 对于新的 --human 照片，查看它并将漫画化特征写入 STORYBOARD.md（头部形状、头发或无、 面部毛发、眉毛、眼睛、通常穿着）。从特征绘制；绝不要描摹或粘贴照片到视频中。 G0 — 停止 发送帧和问题后。将答案合并到选择中，然后继续。
3. 阅读 DIR/ANIMATION_GUIDE.md（工具包的规则）、LESSONS.md 和一个示例章节 （examples/zoo2/scenes/c01_pilot.js），然后再编写任何内容。对于矢量风格（除 painted 外的任何风格）， 指南的引擎部分仍然适用（时间线、shots()、摄像机、缓动、节拍、审查循环），但外观规则 相反：请参阅下面的矢量风格。
4. 故事板。 编写 DIR/STORYBOARD.md（格式：examples/zoo2/STORYBOARD.md），包含日志线、 演员表、调色板弧、主题、整首歌曲的章节表以及带有定时“朗读”的逐镜头预览。 图像密度遵循 --density（bold：每 2–4 行一个强图像，其余作为背景彩蛋； every-line：每行一个，由角色表演）。G1 — 停止：向用户展示并等待批准 （使用 --skip=storyboard/all：自我批评，记录到 DECISIONS.md，继续）。 4b. 设计（仅与 --design 一起）。 在任何动画之前，以 out/design/ 中的静态图像确定外观：
   • cast_<name>.jpg 每个角色的模型表：正面、四分之三和侧面视图，4 种表情 （中性、喜悦、恐惧、决心），故事板中的 3 个动作姿势，以及整个演员表的高度排列；
   • palette.jpg：每章节的色样条，显示整首歌曲中的调色板弧；
   • style_<chapter>.jpg：每章节在故事板主角时刻的一个完成关键帧，歌词显示。 使用一次性 scenes/design.js（歌曲时间范围之外的仅模型表章节）和 node render.mjs --sheet=... 绘制它们；角色代码进入 src/cast.js 的补充部分，章节将复用，因此 批准的设计直接带入视频。G2 — 停止： 展示模型表；记录注释（“眼睛更大”， “副歌调色板更暖”），重新渲染，重复直到用户批准。然后更新 STORYBOARD.md 以匹配。
5. 预览。 选择约 30 秒跨越段落边界进入副歌。将其构建为一个章节文件，共享 集在 window.SETS 上导出（参见 c01_pilot.js 末尾）。使用 node render.mjs --sheet=... --out=out/check/x.jpg 和 --strip=a:b 检查它，并查看图像。通常的 首轮错误：角色太小（将摄像机推近至 1.3–1.5 倍）、背景形状不够宽无法支持 摇镜头、道具隐藏在卡拉 OK 栏下。对于矢量风格，在 src/scenes/sets.js 上构建（setup 复制一个 工作版本：房间、窗户、走廊、滚动、情感混合；适应它）。渲染 node render.mjs --clip --range=a:b --out=out/pilot.mp4。 G3 — 停止：用户观看并批准或提出修改（使用 --skip=pilot/all：两次审查， 记录到 DECISIONS.md，继续）。
6. 并行章节。 首先为每个章节在 studio.html 中添加存根文件及其 <script> 标签 （代理绝不能编辑共享文件）。然后为每个章节启动一个子代理（fork 类型，继承 此上下文）。为每个代理提供其时间范围、其歌词行、来自故事板的章节摘要、 “仅您的文件”、共享的 SETS 和全局变量，以及接缝合约：
   • 在章节之间，两侧使用相同颜色的过渡（手绘：brushWipe，最后 0.3 秒内输出 p<.5，进入 .5+lt/.6；矢量：V.wipe，见 CHAPTER_BRIEF.md）；
   • 进入副歌落点时，硬切出和闪光入（flash(1-lt/.18) / V.flash(1-lt/.2)）；矢量章节代理还获得 CHAPTER_BRIEF.md；
   • 联系表仅输出到 out/check/<chapter>_*.jpg，绝不输出到 out/frames 或 MP4；
   • 至少 2 次审查，然后报告镜头列表和已知弱点。 将开头和结尾配对到一个代理中，使结尾与开头呼应。 使用 --design，还给每个代理其批准的 out/design/style_<chapter>.jpg 作为要匹配的外观。
7. 接缝。 在每个边界 ±0.04 和 ±0.2 秒处渲染一张表，并检查过渡是否平滑。

（为简洁截断）