音乐视频（动态图形）
你无法“听到”这首歌。所有视觉内容都基于测量数据，因此首要任务始终是构建歌曲文件夹。如果歌曲数据有误，每一帧都是错误的。
辅助脚本位于此文件旁边。使用技能文件夹中的 run.py 运行它们（默认安装路径如下所示；如果你安装在其他位置，请调整）：
python3 ~/.claude/skills/music-video/run.py song-folder SONG.mp3 OUT_DIR [--fps 30] [--lyrics-lang en|tr] [--lyrics-text known.txt]
python3 ~/.claude/skills/music-video/run.py analyze SONG.mp3 # beats/bars/sections as JSON
python3 ~/.claude/skills/music-video/run.py dance2d SONG.mp3 --out DIR --analysis OUT_DIR/song-map.json --start 23.8 --dur 14.3 [--render]
永远不要声称自己“听过”这首歌。要说“根据分析结果”。
1. 歌曲文件夹（始终优先）
| 文件 | 内容 | 工具 |
|---|---|---|
| passage. | 音频文件的字节级副本（sha256校验）；直接在最终合成中使用 | — |
| song-map.json / .md | BPM、节拍、强拍/小节、能量段落（平静/积累/高涨）、每拍能量、骤降点 | Beat This! → aubio CLI → 内置numpy追踪器 |
| stems/ | 人声/鼓/贝斯/其他（已缓存，重新运行很快） | demucs htdemucs（可选） |
| envelopes.json | 混合音轨及每个分轨的每帧响度（dB + 0..1） | numpy |
| hits.json | 底鼓/军鼓/镲片的起音点，强度0..1 | 基于鼓分轨的波段分离频谱通量 |
| notes.json | 旋律和贝斯音符（可选） | basic-pitch |
| lyrics-passage.json / .md | 带时间戳的歌词行 | whisper.cpp whisper-cli（基于人声分轨） |
| song-story.md | 你需填写的模板：主题、声音特点、情绪弧线、每个段落的代表性画面 | 你本人，依据歌词和分析 |
| README.md | 每个文件的说明、单位（秒）、帧率 | 自动生成 |
规则：
- 段落指的是能量短语（由歌曲自身能量排序的两小节短语），而非主歌/副歌结构。
在
song-story.md中自行命名它们。 --lyrics-text提供真实歌词（每行一句），会将其与 whisper 识别的单词对齐； 无法匹配的单词将获得插值时间（matched: false）。若不提供，则歌词行是 whisper 的原始输出：需要检查。 在无声的人声分轨上出现的行会被标记为suspect（whisper 会在器乐片段中产生幻觉）。纯器乐曲目跳过 whisper。- 每个重要步骤都在降级模式下运行，而非直接失败：无 Beat This! → aubio（外部 CLI）→ numpy 追踪器
（无真实强拍，猜测为 4/4 拍）；无 demucs → 仅混合音轨的包络线和命中点；无 basic-pitch → 无
notes.json；无 whisper → 无歌词。运行报告的
warnings会说明跳过了哪些步骤。请告知用户。 - hits.json 足够用于闪光、抖动和缩放效果，但并非完整的鼓转录：镲片也会在军鼓上触发，贝斯音符可能泄漏到军鼓频段。
song-story.md在重新运行时不会被覆盖。只写那些歌词和分析能够支持的内容；对于不确定的内容，保留标题为“未知”，而不是虚构含义。
2. 创意规划（在渲染前展示）
- 一个基于
song-story.md的概念，一个世界，一套调色板，一个用于歌词排版的开放许可字体（OFL）。 - 章节→场景表：章节变化 = 场景或镜头变化；副歌/能量最高的章节获得最大的视觉创意，每次重复时有所变化；骤降点 = 在强拍上切换、闪光或缩放。
- 歌词排版只出现在关键句上（在其对应单词时间显示的动态文字），而不是每句都做卡拉OK效果。
- 在平静的音乐段落中，按乐句和能量节奏推进；不要在每个追踪到的节拍上都进行硬切。不同视觉处理的数量比剪辑次数更重要。
- 展示计划（表格 + 3-4 张描述性或已渲染的静态画面），在完整渲染前获得用户许可。
- 值得优先阅读的基础模块：HyperFrames 自身的
music-to-video技能 （github.com/heygen-com/hyperframes,skills/music-to-video/, Apache-2.0）包含了节拍剪辑运动基元（闪光切换、碰撞变焦、甩镜头、色差分裂、屏幕抖动、动态文字……）和歌词布局的目录。
3. 内置的2D舞蹈视频
看：平面角色（圆形的深色头部、圆角描边肢体、彩色衬衫和鞋子）、拱形镜面门、紫/青绿/金/粉色的旋转旭日背景、粗体紧凑（Anton字体）的歌词文字（其中带一个重音词）、一排不同颜色的镜像舞者副本、胶片带、王冠和象棋道具。灵感来自 Devarf 的 YouTube 实验“每个努力级别制作一个音乐视频”中的“低投入”2D视频。
规划器（musicvideo/dance2d.py，纯函数且可设定种子）：
- 窗口对齐到强拍；每拍一个姿势关键帧，姿势在节拍上到达；
- 强拍使用大姿势（积累：抬手/指向/拍手，高涨：跳跃/抬手）和一个完整的屈膝；
- 动作集（一个4拍乐句）每小节根据能量水平变化，且不会连续两次重复；
- 场景在章节起始处和每4小节处切换（调色板切换、旭日速度根据能量水平变化、方向交替；平静/积累阶段显示门，高涨阶段显示象棋+5舞者行，王冠出现在领舞身上）；
- 舞者副本数：平静1个，积累3个，高涨5个；
- 歌词 JSON
[{start, end, text, accent}]以窗口秒数为单位 → 每个单词落在某个节拍上。
骨骼系统（runtime/char2d.js，window.Char2D）：SVG 分组，带枢轴点（髋部 > 腿部 > 小腿 > 脚，躯干 > 手臂 > 前臂，头部）。肢体角度以向外为正（0度向下，90度侧向，180度向上），使一个姿势适用于两侧；地面锁定使下方的脚始终接触地面（下蹲会自动降低高度），air 抬起用于跳跃。姿势：待机、迈步左/右、抬手、摇摆左/右、指向左/右、拍手、跳跃、下蹲、双手叉腰（mirror(p) 交换左右侧）。poseAt(keys, t) 保持姿势，然后在最后的 ≤0.26 秒内渐入，并在大的命中点处带过冲。runtime/dance2d.js 从 window.MV_DANCE 绘制计划；一个 GSAP 补间驱动代理设置器 → draw(t)，因此每一帧都是 t 的纯函数。
dance2d 的输出：DIR/plan.json 和 DIR/project/（一个 HyperFrames 项目）。使用 --render 还会生成 DIR/dance2d.mp4：1920×1080，30 fps，H.264 yuv420p，窗口区间内使用歌曲自身的音频（AAC，无淡入淡出）。使用 CC BY 许可的音乐需要在画面上显示 --credit。
渲染是用户的选择。 --render 会运行 npx hyperframes render，它会下载并驱动无头 Chrome/Chromium。使用前请征得同意。不使用 --render 时，仅靠 Python 就能完成项目文件夹之前的所有步骤。GSAP 并未捆绑：将 gsap.min.js 放入 runtime/（或设置 MV_GSAP），否则项目会在渲染时从 jsDelivr CDN 加载 GSAP 3.14.2。
4. 内置骨骼系统以外的角色（使用你自己的）
此技能不附带任何3D模型。如果用户想要3D（Three.js）角色：
- 使用许可允许在完成的视频中重新分发的模型，例如 CC0 模型，或 用户从自己 Mixamo 账户下载的角色和动画（在完成的视频内部没问题；原始文件不得重新分发或提交到公共仓库）；
- 切勿未经检查许可而复制其他项目中的示例模型；
- 或者坚持使用程序化基元（胶囊体、球体、盒子连接的简单骨骼链），这些完全没有许可问题。
帧级确定性仍然适用：每帧使用
mixer.setTime(t * rate)，切勿使用mixer.update(dt)；rate = song_bpm / clip_bpm；在小节边界处切换动画片段。
5. 渲染规则（任何渲染器）
- 所有内容都是
t = 帧 / fps的纯函数。不使用Date、requestAnimationFrame增量或不带种子的Math.random()。 - 小幅度命中效果（镜头抖动、闪光、缩放弹动）根据 hits.json 在底鼓/军鼓上触发；亮度或辉光效果根据 envelopes.json。
- 输出：1920×1080（或用于 Reels/Shorts 的 1080×1920），30 fps，H.264 yuv420p，AAC，长度与歌曲（或所选窗口）相同。
- 光敏性：每秒全屏闪烁不超过3次。
- 预算：更多思考时间能带来更好的动态效果，但需在单个会话中完成审查。针对单个音乐视频的多智能体审查循环会快速消耗 tokens，并且通常在达到限制后重新开始。
6. 交付前检查
- 播放到结束；时长 == 歌曲（或窗口）时长 ±1帧。
- 音频流是原始歌曲（比较解码后的 PCM 哈希值，或在滞后0处进行互相关峰值检测）。
- 同步抽检：渲染副歌强拍上的5帧，确认命中姿势/闪光准确落在该位置。
- 每个段落生成一张接触表（
ffmpeg -i out.mp4 -vf "fps=1,scale=480:-1,tile=4x4" sheet.jpg）并实际检查。 report.md：你制作了什么以及为什么、如何制作、你检查了什么、你不确定什么。