music-to-video 是一个以音乐为依据、节拍同步的视频制作工作流，用于将一首音乐轨道转换为 HyperFrames 视频。其输入是音乐轨道，以及可选的用户图片或视频；没有旁白，也不抓取网站。排版与模板是基本盘（一个完整视频可以零素材完成），用户提供的任何媒体都会按照同一节拍网格被剪辑进来。
用途与定位 该技能面向需要把音乐变成节拍对齐视频的场景，例如歌词视频、幻灯片等。它把整条流程拆成编排者（你）与逐帧构建者两层：你负责分析与规划，逐帧构建由子代理完成。
主要能力
- 音乐分析：analyze-beatgrid.py 是唯一的节拍分析器，只读取一次音频并写入 audiomap.json，包含能量阶段（level / density / feel）、起音 + onset_rate、滚奏、静音、hard_stops、key_moments、乐句、tempo / grid 以及 audio.duration_sec。它具备确定性，同一文件总是得到相同结果。多数字段在任何音乐上都可靠；bpm 与 beats_sec 仅在音乐确实有节奏时可靠，在平静音乐上该网格是追踪器强加进来的节拍器，此时应按乐句与能量来控制节奏，不要硬切。
- 帧骨架：读取 audiomap.json 后，在真实音乐变化处切分轨道（hard_stops、SURGE / DROP 类 key_moments、滚奏边缘、无起音的一段、大的能量跳变），边界吸附到 audiomap 锚点。每个帧设定 span_sec、pacing（beat_cut 或 phrase_flow）、mood 与一行 feel。
- 计划填充：选择一个品牌预设（字体 + 调色板），为每个帧决定其分组并给出处理方式：匹配目录中的模板（带绑定参数与真实 audiomap 锚点）、基于原语目录的自由创作，或遵守节奏的素材处理。
- 逐帧构建：每个帧由一个 frame-worker 构建为一个自包含的合成文件 compositions/frames/NN-<frame_id>.html。
- 装配与渲染：assemble-index.mjs 确定性地把各帧按累计 data-start 引用、把 assets/bgm.mp3 挂到 11 轨，并硬切帧到帧；随后通过 CLI 校验并渲染为 MP4。
使用方式 安装与保持更新：在设置或新鲜度命令前，若本技能位于 HyperFrames 插件内，遵循插件执行规则；独立安装则使用下述更新说明。先保持本技能为最新——运行前与用户确认：npx hyperframes skills update music-to-video。 工作目录：videos/<project>/。/project 以 kebab-case 命名，来自简报，例如 midnight-drive-loop，不要用时间戳。 初始化（仅在 hyperframes.json 缺失时）： npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=music-to-video mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders" cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3"
仅当用户提供了图片/视频时：
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public 分析（前置条件：Python 3 且可用 librosa、numpy、soundfile；若导入失败先安装）： python3 -m pip install librosa numpy soundfile python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" -o "$PROJECT_DIR/audiomap.json" --print 校验计划： node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates 装配： node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" --hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json" 校验与渲染： ( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots ) ( cd "$PROJECT_DIR" && npx hyperframes preview --background ) ( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 ) 在首次需要认证的提供商操作之前，运行 npx hyperframes auth status 并原样转达其输出。若已登出：协作模式下等待登录或用户明确选择用本地提供商离线继续；自主模式下说明状态并继续走可用的本地提供商。若没有离线提供商能满足所需音乐能力，则提出该阻塞。切勿把密钥写入每个仓库的 .env。
流程与检查点 Step 0 设置、BGM 与输入 → hyperframes.json + assets/bgm.mp3；Step 1 分析 → audiomap.json；Step 2 骨架 → STORYBOARD.md（帧、分组为 TBD）；Step 3 计划 → 完整的 STORYBOARD.md + frame.md；Step 4 构建 → compositions/frames/NN-*.html；Step 5 装配 → index.html；Step 6 渲染 → renders/video.mp4。 两个需要用户的检查点：Step 3（计划批准）与 Step 6（渲染批准），均按 ../hyperframes/references/brief-contract.md 执行。自主模式下，Step 3 摘要作为预告发出后继续；Step 6 渲染批准仍会询问，是唯一保留的问题。除 Step 4 外每一步都由你亲自完成，Step 4 为每帧派发一个子代理。
适用场景与限制
- 音乐是主轴：先确定一条轨道。本技能针对快速、高能量的 BGM 调优：强节拍网格驱动剪辑（平静音乐同样可用，但按乐句而非节拍来控制节奏）。
- 歌词视频：若需歌词与演唱同步，通过 /media-use 转写轨道获得词/行时间，或向用户索取歌词文本，把行放在节拍网格上。
- 品牌（字体 + 调色板）在 Step 3 选择，不在 Step 0；不要预先挑选流派或轨道类型。
- 画布：默认横屏 1920x1080，竖屏 1080x1920，方形 1080x1080；在 storyboard frontmatter 中设置一次（canvas: { w, h, fps }）。
- 失败处理：最廉价的安全修复是编辑出问题的 compositions/frames/NN-*.html；绝不要为掩盖同步问题而改变时长或音频时序。
- 若某处失败（如音频时序、节拍可靠性判断）需依据分析结果决定；关于收费、价格、平台与具体效果等信息，资料暂未提供。