电影级音乐视频导演

一种制作技能，用于制作以歌曲为主线的可观看短片——不是歌词模板，不是幻灯片，也不是一堆无关的生成片段。每一帧都由代码绘制，并且可以从整数帧编号重现。

该技能刻意遵循音乐优先和证据优先的原则：

在想象画面之前先测量歌曲；
在编写任何镜头之前先撰写主题和导演谱；
在渲染之前锁定帧精确的剪辑；
在 10–20 秒的试片中证明外观和运动；
以可恢复的镜头单元进行渲染；
验证你实际交付的文件。

硬性规则： 绝不捏造时间戳、BPM、歌词行、渲染结果或质检通过。如果证据缺失，将该项标记为未验证，并在交付说明中说明。

何时使用

当用户要求制作音乐视频、剪辑到音乐的动画短片、片头序列或“将我的歌曲制作成电影”的任务，并且可以接受本地代码渲染时使用。默认输出为 9:16、1080×1920、24 fps、H.264 + AAC，附带可选的旁白字幕文件。

不要使用此技能下载受版权保护的音频、克隆在世艺术家的肖像或逐镜头复制现有的 MV。请向用户索取他们有权使用的音频。

前提条件（检查，不要假设）

Node 20+、ffmpeg/ffprobe、Google Chrome 或 Chromium。
Python 3.10–3.13，并安装 numpy scipy soundfile librosa（matplotlib 可选，Pillow 用于画板）。
项目 node_modules 中的 puppeteer-core、p5、p5.brush。
足够的磁盘空间用于帧：1080×1920 JPEG q94 ≈ 0.2–0.5 MB/帧；4 分钟的电影 ≈ 1–3 GB。
对于中文歌词，需要用户提供的 LRC/SRT 或本地 Whisper 模型；切勿抓取并将随机歌词网站的时间视为已验证。

运行 scripts/doctor.sh（或 references/render-recovery.md 中的等效命令）并记录结果。如果缺少某个前提条件，请修复它或报告阻塞。

制作流程

0. 收录与版权

收集：音频路径、歌词文本及任何时间文件、宽高比/分辨率/fps、截止日期、语言和使用场景。将音频以只读方式复制到 assets/ 中；切勿覆盖原始文件。在 README.md 中说明版权假设（例如“用户提供的音频，仅供私人使用”）。

1. 音乐主文件（门 M）

python scripts/analyze_music.py assets/song.m4a \
  --out analysis --lrc assets/song.lrc --sections analysis/sections.json \
  --asr analysis/asr/whisper.json --fps 24

生成 analysis/audiomap.json、lyrics.json、lyrics.srt、analysis.md、analysis.png。该映射包含时长、相位拟合的节奏网格、拍子/重拍、能量/频谱曲线、候选高潮窗口、段落跨度以及带来源的行级歌词时间。

验收标准：

时长和采样率与提供的文件匹配；
报告节奏一致性；如果 < 0.6，通过听觉/频谱图检查并考虑节奏映射；
每行歌词都有时间来源（lrc_line、srt_line、cross_checked、untimed）；
未经结构交叉检查，不得将响度视为情感高潮。

如果用户未提供歌词时间，请使用本地 ASR 转录运行 scripts/align_lyrics.py 并审查结果。将短语时间（小节/短语标记，用于剪辑）与人声起始时间（用于字幕）分开。切勿为了剪辑看起来整齐而静默地整体移动歌曲。

2. 三个概念，然后一个（门 D1）

编写 storyboard/concepts.md，包含三个截然不同的电影。根据歌词/音乐匹配度、故事完整性、情感冲击力、视觉原创性、代码可行性和长片可看性进行评分。选择一个并写出理由。在存在镜头代码之前不要开始。

然后编写 storyboard/director_score.json：主题、反主题、情感曲线、视觉章节（世界/调色板/空间/摄影机/语法）、对比图、母题与呼应交待、角色需求/障碍/弧线、镜头角色与交接、声音-视觉映射。

一个镜头如果无法说明其角色、进入交接和离开交接，则尚未准备好。

3. 视觉语言与测试（门 D2）

在制作动画之前编写 style-guide.md 和角色/艺术圣经。定义：包含十六进制值和色彩脚本的调色板；9:16 的镜头/构图语法；线条和纹理规则；角色比例、剪影、服装连续性和表情范围；灯光；转场词汇；电影将不会做的确切事情（例如“没有无叙事原因的漂浮粒子”）。

渲染 1–3 个风格帧和角色画板。以全分辨率判断它们，而不是缩略图。如果外观薄弱，现在更改语言——而不是在 40 个镜头之后。

4. 帧精确剪辑（门 E）

编写 storyboard/timeline.json，包含 fps、total_frames、shots[]，并且对于每个镜头： id、start_frame、end_frame、section、lyric_refs、size、composition、environment、action、expression、camera、transition_in/out、emotion、function、implementation、complexity。镜头必须连续并覆盖整个音频。

python scripts/validate_timeline.py \
  --timeline storyboard/timeline.json --audiomap analysis/audiomap.json \
  --out analysis/timeline_validation.md

验证器是一个硬性门：无间隙、无重叠、最后一帧 ≥ ceil（时长×fps）、每行歌词都已考虑、没有剪辑与拍子/歌词/段落相距荒谬而没有书面理由。

5. 试片（门 P）

渲染 10–20 秒，至少包含：一个广角定场镜头、一个角色中景、一个特写、一个快速动作或冲击，以及一个转场。制作接触印相和可观看的剪辑，并使用真实音频。检查：

风格在 100% 时是否保持？
角色比例、服装和灯光是否连续？
摄影机运动是否有动机，还是无故漂移？
剪辑是否落在音乐事件上？
渲染器能否在无异常的情况下承受 300+ 帧？
测量的 ms/帧和磁盘成本是多少？

在全遍之前修复试片。在 LESSONS.md 中记录测量的性能。

6. 全渲染（门 R）

使用确定性页面合约：window.renderAt(t) -> dataURL，无 Math.random，种子噪声，整数帧索引。逐镜头或逐帧渲染，使用原子写入；维护已完成单元的清单和哈希值，以便更改的镜头仅使自身失效。

node scripts/render.mjs --project . --start 0 --end 232.6 --out renders/frames

优先使用按镜头的单元和 --force/--shot 路径，而不是“删除所有并重新开始”。不要渲染两次已批准的相同镜头。绝不让失败的帧通过为完整：帧必须存在、非零且可解码。

7. 合成（门 A）

ffmpeg -y -framerate 24 -i renders/frames/f_%06d.jpg -i assets/song.m4a \
  -c:v libx264 -preset slow -crf 16 -pix_fmt yuv420p -profile:v high -level 4.2 \
  -c:a aac -b:a 256k -ar 44100 -shortest -movflags +faststart output/final.mp4

主音频不可更改。不要淡入淡出、重新定时或重新编码歌曲以适合画面。最后一个镜头必须覆盖音频尾部；无黑色尾部，无截断的最后和弦。

8. 质量控制（门 Q）

运行两者，并附加证据：

python scripts/qc_video.py output/final.mp4 --audio assets/song.m4a \
  --expected-frames 5583 --timeline storyboard/timeline.json --out analysis/qc

技术：解码、时长与音频比较（容差 ≤ 0.12 秒）、流计数、分辨率、fps、pix_fmt、帧计数、黑帧检测、冻结检测、覆盖率、缺失/占位帧。视觉：全分辨率接触印相、每场景关键帧、剪辑处的连续帧条、A/V 同步抽查、角色连续性检查、标题/字幕安全。

视觉 QC 不能自动化。 明确说明你观看了哪些镜头、在什么分辨率下以及发现了什么。干净的 ffprobe 不是视觉通过。

9. 交付

交付：主 MP4、低分辨率预览、storyboard.md、timeline.json、style-guide.md、qc-report.md、README.md、可选的 SRT 以及可重现的源代码。除非用户有权发布，否则将音频和歌词保留在本地。添加带日期的 LESSONS.md 条目。

文件约定

project/
  assets/            # song.m4a、lyrics.lrc/srt、用户提供的参考资料（不要覆盖）
  analysis/          # audiomap.json、lyrics.json、sections.json、验证、QC
  storyboard/        # concepts.md、director_score.json、timeline.json、storyboard.md
  characters/        # 艺术圣经、模型表
  src/               # 确定性的绘制代码：lib/、custom_shots.js、shots.js
  studio.html        # window.renderAt(t) 合约
  renders/           # frames/（全局序列）、pilot/、清单
  previews/          # pilot.mp4、接触印相、审查板
  output/            # 最终 MP4、预览、SRT、storyboard.md、timeline.json、style-guide.md、QC

不可协商的工艺规则

歌曲是主时间线。画面是针对音乐剪辑的；音乐绝不针对画面剪辑。
一部电影，而不是一系列外观的播放列表。母题会回归并改变。
重复的合唱在视觉上可以押韵；但不得原封不动地重用相同的构图。
角色需要欲望、障碍、选择、后果。面部和手部必须表演。
摄影机运动需要动机（揭示、压力、释放），而不是默认的 Ken Burns 效果。
每个镜头必须包含至少一个属于故事世界的运动元素。
不要用粒子、速度斜坡或过度的泛光来掩盖缺失的故事。
如果诚实的结果是风格化且有限的，在 QC 报告中说明；不要称其为照片级真实。

故障与恢复

渲染器设计为大声失败并廉价恢复：

原子帧写入（*.tmp → 重命名），绝不将半 JPEG 视为完成；
每个镜头的清单，包含源哈希、起始/结束帧和状态；
--shot / --start/--end 仅重新渲染受影响的区域；
保留最后一个已知良好的编码；在 QC 通过之前绝不覆盖主文件。

如果浏览器或 GPU 崩溃，使用新页面/配置文件重试该单元两次。如果帧失败三次，停止，隔离镜头，并报告帧编号和错误。不要用重复帧或静态帧填充。

参考索引

references/directing.md — 概念选择、导演谱、时长、节奏、结局。
references/visual-language.md — 9:16 构图、摄影机、颜色、角色、纹理。
references/audio-lyrics.md — 测量、相位拟合节奏、段落、诚实对齐。
references/render-recovery.md — 确定性合约、清单、编码、恢复。
references/qc.md — 硬/软门、接触印相、自动化无法看到的内容。
templates/ — 导演谱、时间线、镜头卡、风格指南、项目配置。
tests/ — 解析器、覆盖率和验证器测试；运行 bash tests/run_tests.sh。
LESSONS.md — 实际制作中出了问题以及如何修复。

致谢与许可证

引擎模式受 MIT 许可证的 ClaudeAnimationBase（John Heibel）和 claude-music-video-skill（Sage Arbor）启发。工作流概念研究自 musical-mv-storyboard，该作品无许可证；未复制其中的任何代码或文本。请参见 THIRD_PARTY_LICENSES.md。p5 使用 LGPL-2.1、p5.brush 使用 MIT、puppeteer-core 使用 Apache-2.0、librosa 使用 ISC、ffmpeg 使用 GPL。项目中使用的歌曲和歌词不是此技能的一部分。

电影级音乐视频导演工作室