用途
music-to-video 用于将一条音乐轨转化为节拍同步的 HyperFrames 视频。适用场景为用户拥有音乐轨（音频文件，或从中提取音频的视频），希望制作从平静到强烈的、与节拍同步的视频。输入为音乐轨加上可选的用户图片或视频；没有旁白，也不进行网站捕获。排版和模板是基础：一个完整视频无需任何素材即可生成；用户提供的媒体会在同一条节拍网格上被切入。
主要能力
该技能以两个核心思想贯穿整个流程。第一，只有一个分析器，且信任它：analyze-beatgrid.py 是唯一的节拍分析器，绝不用其他工具或凭听感重新测量节拍。其能量 / 密度 / rolls / onsets / silences 始终可靠；bpm 和 beats_sec 仅在音乐确实有节奏感时可靠；对于平静音乐，网格是追踪器强加上的节拍器，此时应按乐句和能量来把握节奏，切勿硬切到该网格。判断属于哪种情况是每一帧的 pacing 任务（Step 2）。第二，一帧 = 一个文件，分组在内部：Step 2 将音轨切分为帧，每一帧成为一个合成文件 compositions/frames/NN-<frame_id>.html，由一个 frame-worker 构建。一帧可以再细分为多个组（每个组是模板或运动原语的组合）。额外的密度放入组内，因此帧数跟踪的是不同处理方式，而不是节拍——快节奏音轨不会使子智能体数量爆炸式增长。
整体工作流为：Step 0 设置、BGM 和输入 → Step 1 分析音乐 → Step 2 帧骨架（仅结构）→ Step 3 填充计划（用户把关）→ Step 4 根据计划构建帧 → Step 5 组装 → Step 6 验证并渲染。
使用方式
Step 0：建立音乐源、创建 HyperFrames 项目并记录用户提供的媒体。音乐是主干，必须先确定一条音轨。如果用户提供了音频（音乐文件，或从中提取音频的视频）则使用它；如果没有，则根据用户描述选择情绪并生成一条音轨。生成前运行 npx hyperframes auth status 并原样转述其输出。如果未登录，STOP 并等待用户选择——登录，或继续离线使用本地 MusicGen——然后再生成音轨；不要将密钥写入每个仓库的 .env。在自主模式下，记录状态并继续离线。无论哪种方式，音轨都放在 assets/bgm.mp3。仅当 hyperframes.json 缺失时初始化。项目名从简报中以 kebab-case 命名，例如 midnight-drive-loop，绝不用时间戳。
Step 1：运行分析器生成 audiomap.json。前置条件：Python 3 需有 librosa、numpy 和 soundfile。分析器读取一次音轨并写入 audiomap.json，包含能量阶段、onsets、rolls、silences、hard_stops、key_moments、phrases、tempo / grid 以及 audio.duration_sec。它是确定性的，同一文件总是给出相同的地图。
Step 2：阅读参考文档，将 audiomap.json 转化为 STORYBOARD.md 的骨架。在真实的音乐变化处将音轨切分为帧，每个边界都对齐到 audiomap 锚点。为每帧设置 span_sec、pacing、mood 和一行 feel。此步骤只做分类和布局，所有帧的 ### Groups 留为 TBD，frontmatter 风格留空。预期约 1–6 帧。
Step 3：将骨架转化为经批准、完整的 STORYBOARD.md。选择品牌（从预设中选一个，复制到 frame.md 并填入 frontmatter style），填充每一帧（决定其分组并为每个组指定处理方式：匹配的模板、从原语调色板自由合成，或遵守 pacing 的素材处理），并编写文案。编排者负责 WHAT（模板 / 原语 + 内容 + 锚点），frame-worker 负责 HOW。运行 validate-plan.mjs 修复所有硬错误，然后向用户展示逐帧摘要并迭代直到批准。
Step 4：将每一帧构建为自包含的合成文件。创建 compositions/frames/ 目录，为每一帧派发一个 frame-worker，尽可能并行。每个 worker 只处理一个帧，接收 PROJECT_DIR、frame_id、块、audiomap、frame.md、材料、契约、画布和 pacing 等上下文。worker 不运行 hyperframes CLI。
Step 5：运行 assemble-index.mjs 将构建好的帧和 BGM 接入可播放的 index.html。该脚本是确定性的，无子智能体、无判断。它引用每个帧文件于其累积 data-start，将 assets/bgm.mp3 挂载到 track 11，并硬切帧 → 帧。修复报告的任何硬错误。
Step 6：在组装好的项目上运行 CLI 进行 lint、validate 和 inspect。在失败时自己做最便宜的安全修复：编辑有问题的 compositions/frames/NN-*.html。绝不更改时长或音频时序来隐藏同步问题。通过后暂停等待用户审查，仅在批准后渲染。
适用场景
该技能适用于需要将音乐轨转化为节拍同步视频的场景，尤其针对快速、高能量的 BGM：强节拍网格驱动切帧；平静音轨也可用，但应按乐句而非节拍来把握节奏。输入为音乐轨加可选用户图片或视频。无旁白，不捕获网站。
限制
- 只有 analyze-beatgrid.py 是节拍分析器，绝不用其他工具或凭听感重新测量节拍。
- bpm 和 beats_sec 仅在音乐确实有节奏感时可靠；平静音乐上的网格是强加的节拍器。
- Step 3（计划批准）和 Step 6（渲染批准）需要用户参与。
- 生成 BGM 前若未登录，必须停止并等待用户选择，不能将密钥写入每个仓库的 .env。
- frame-worker 从不运行 hyperframes CLI；CLI 在组装后的项目上运行，即 Step 6。
- 无法确定确切价格、付费模式、支持平台、性能效果或未在资料中提供的使用步骤。
- 默认格式：横屏 1920x1080；竖屏 1080x1920；方形 1080x1080。画布在 storyboard frontmatter 中设置一次。
恢复表
仅有 assets/bgm.mp3 时从 Step 1 继续；有 audiomap.json 时从 Step 2；有 STORYBOARD.md（骨架）时从 Step 3；有完整的 STORYBOARD.md 时从 Step 4；有所有帧文件时从 Step 5；有 index.html 时从 Step 6。
目录结构
music-to-video/ 包含 SKILL.md、references/（frame-skeleton.md、planning.md、storyboard-format.md、template-catalog.md、motion-primitive-catalog.md、montage.md、templates/<id>/、motion-primitives/<id>/）、scripts/（analyze-beatgrid.py、assemble-index.mjs、validate-plan.mjs、stage-assets.mjs、lib/storyboard.mjs）、sub-agents/（frame-worker.md，每个帧一个子智能体）。