music-to-video 是一个面向 HyperFrames 的节拍同步视频制作技能，核心是把一首音乐曲目变成与节拍对齐的视频。整个流程由技能自身作为编排者，在 videos/<project>/ 目录内按步骤推进。
用途与输入：输入为一条音乐轨道，另可选用户提供的图片或视频；没有旁白，也不做网页捕获。音乐来源可以是用户提供的音频文件、需要先提取音轨的视频，或根据请求描述的情绪通过 /media-use 生成的曲目；若宿主应用自带音乐工具则使用它。技能针对快速、高能量的背景音乐进行调校，强节拍网格驱动剪辑；平静曲目也能用，但按乐句而非节拍控制节奏。排版与模板是基础保障，完整视频可以零素材完成，用户提供的媒体会被切到同一节拍网格上。
主要能力：整个流程共六步。Step 0 完成初始化、确定音乐来源并暂存用户素材；Step 1 使用唯一的节拍分析器 analyze-beatgrid.py 生成 audiomap.json，包含能量阶段、起音、滚奏、静音、硬停、关键节点、乐句与速度网格等信息；Step 2 依据音乐变化把曲目切分成约 1–6 个帧并设定节奏策略（beats_cut 或 phrase_flow）；Step 3 选择品牌预设（字体与调色板）并逐帧填充计划，组可以是匹配模板、自由组合动作原语或素材处理方式；Step 4 并行派发子代理，每帧一个文件 compositions/frames/NN-*.html；Step 5 用 assemble-index.mjs 把帧和 assets/bgm.mp3 拼装为 index.html；Step 6 运行检查与快照审查，经用户确认后渲染为 renders/video.mp4。
使用方式：按步骤执行对应命令，例如初始化用 npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=music-to-video；分析音频用 python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" -o "$PROJECT_DIR/audiomap.json" --print；校验计划用 validate-plan.mjs；拼装用 assemble-index.mjs；检查用 npx hyperframes check . --snapshots；渲染用 npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30。分析器依赖 Python 3 及 librosa、numpy、soundfile。步骤 3（计划批准）和步骤 6（渲染批准）是用户检查点，自主模式下步骤 3 仅作通报、步骤 6 仍会询问。可选画布格式为横屏 1920x1080（默认）、竖屏 1080x1920、方形 1080x1080。
适用场景与限制：适合制作歌词视频、幻灯片式音乐视频，以及需要把用户图片或视频按节拍切入的项目。限制方面：bpm 与 beats_sec 仅在真正有节奏的音乐上可靠，平静音乐上的网格是追踪器强加的标准节拍，需按乐句与能量推进；分析节拍只能使用该分析器，不得改用其他工具或凭听觉重测；渲染与检查需在拼装后的项目上运行，帧构建子代理不运行 CLI；渲染需用户批准后交付。若离线提供者无法满足所需音乐能力则需提示阻塞，且不得把密钥写入仓库级 .env。具体要求、模板细节与更多参考文件见 资料中的 references 目录说明。