首先，保持此技能最新——静默运行，无需询问：
npx hyperframes skills update music-to-video。如果一切已是最新，则快速无操作；否则，在依赖此技能及其核心领域技能之前刷新它们。
music-to-video — 一个音乐驱动的节拍同步视频工作流
使用此技能将音乐曲目转化为节拍同步的 HyperFrames 视频。你需分析曲目一次，布置帧，填充每帧的计划，并将每帧构建为合成画面。输入为音乐曲目加上可选的用户图片或视频——无旁白，无网页捕获。排版和模板是基础（完整的视频不需要任何素材）；用户提供的任何媒体都会在同一节拍网格上剪切。
你是编排者。在 videos/<project>/ 目录下工作。按顺序执行步骤，并在继续前通过每个门控。两个步骤需要用户参与：第3步（计划审批）和第6步（渲染审批）——均为每 ../hyperframes-core/references/brief-contract.md（在第0步前阅读）的检查点门控：在自主模式下，发布摘要作为通知并继续，而不是等待。除第4步外，每一步都由你自行完成，第4步中你为每帧调度一个子代理。设计和其他规则不在本文件中——它们位于 references/ 和 frame-worker 子代理中。
SKILL_DIR = 此技能目录。PROJECT_DIR = videos/<project-name>/。
工作流：第0步设置 → hyperframes.json + assets/bgm.mp3；第1步分析 → audiomap.json；第2步骨架 → STORYBOARD.md（帧，组 TBD）；第3步计划 → 完整的 STORYBOARD.md + frame.md；第4步构建 → compositions/frames/NN-*.html；第5步组装 → index.html；第6步渲染 → renders/video.mp4。
塑造一切的两个理念
- 一个分析器，并且你信任它。
analyze-beatgrid.py是唯一的节拍分析器——切勿使用其他工具或凭耳朵重新测量节拍。其能量/密度/滚奏/起音/静音始终可靠。其bpm和beats_sec仅在音乐真正有节奏时才可靠；对于平静音乐，网格是跟踪器强加的节拍器，因此需根据乐句和能量来定速，切勿硬切到它。判断你处于哪种情况是每帧pacing（第2步）的任务。 - 一帧 = 一个文件；组存在于内部。 第2步将曲目切割为帧，每帧成为一个合成文件
compositions/frames/NN-<frame_id>.html，由一个 frame-worker 构建。一帧可以细分为组（每个组是一个模板或运动原语组合）。额外的密度放在_组内_，因此帧数对应不同的处理方式，而非节拍——快曲目不会增加子代理数量。
第0步：设置、BGM 和输入
目标：确定音乐来源，创建 HyperFrames 项目，并记录用户提供的任何媒体。
简报从意图层开始。 打开规则，按顺序：(1) BRIEF.md 存在 → 读取它，不询问它所回答的任何问题——其 flow/storyboard 推导模式（简报合同 § 1）。(2) 无 BRIEF.md 但项目存在 → 从磁盘恢复；绝不重新询问。(3) 一个直接到达这里的全新创建请求 → 读取 /hyperframes 并运行其意图层（references/intent-interview.md）：它确认此路径的必需品（音乐来源，目的地 → 宽高比 — ../hyperframes/references/routes/music-to-video.md），并宣布哪些内容延迟——品牌和体裁由设计在第3步选择。在初始化后立即写入 BRIEF.md（绝不之前——init 拒绝非空目录），并记录基于偏好的答案（brief-format.md）。编辑请求跳过所有这些。
音乐是脊梁——在一切之前确定一首曲目。此技能针对快节奏、高能量的 BGM 优化：强大的节拍网格驱动剪切（平静曲目也可，但按乐句而非节拍定速）。如果用户提供了音频——音乐文件或要提取音频的视频——则使用它。否则从请求中选择情绪，并通过 /media-use（references/bgm.md）生成曲目。在第一次经过身份验证的提供者操作之前，运行 npx hyperframes auth status 并逐字中继其输出。如果已登出，应用一个分支：
- 协作模式： 等待登录或明确选择通过本地提供者继续离线操作。
- 自主模式： 说明状态，通过可用的本地提供者继续。
如果没有离线提供者能够满足所需的音乐能力，则指出阻碍。切勿将密钥写入每仓库的 .env 文件。身份验证所有权和离线备用方案位于 /media-use references/setup-providers.md § 提供者。生成的曲目位于 assets/bgm.mp3。将用户提供的图片或视频暂存，以便帧能在节拍网格上使用它们；否则排版承载视频。
歌词视频： 为与歌词同步的歌词，通过 /media-use 转录曲目以获取单词/行时间，或让用户提供歌词文本并将行放置在节拍网格上。
仅当 hyperframes.json 缺失时才初始化。根据简报以 kebab-case 命名 <project>，例如 midnight-drive-loop——绝不用时间戳。init 检查已安装的技能与 GitHub 上的最新版本，如果任何技能过时则更新全局集。
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
品牌（字体 + 调色板）在第3步选择，而不是这里。不要预先选择体裁或曲目类型——素材只是一个可选成分，体裁从每帧的选择中浮现。
门控： hyperframes.json + assets/bgm.mp3 存在；宽高比/长度/fps 和（如果有）素材清单已记录。
第1步：分析音乐
目标：生成整个视频构建所依赖的唯一规范时间分析。
analyze-beatgrid.py 是唯一的节拍分析器——切勿使用其他工具或凭耳朵重新测量节拍。它读取曲目一次并写入 audiomap.json：能量阶段（级别/密度/感觉），起音 + onset_rate、滚奏、静音、hard_stops、key_moments、乐句、节拍/网格，以及 audio.duration_sec。它是确定性的——同一文件始终给出相同映射。大多数字段在任何音乐上都可靠；bpm 和 beats_sec 仅在音乐真正有节奏时才可靠，而判断这一点是你在第2步做出的决定。
先决条件：安装了 librosa、numpy 和 soundfile 的 Python 3。如果导入失败，在运行分析器之前将它们安装到活动 Python 环境中：
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
门控： audiomap.json 存在；audio.duration_sec 已知。
第2步：帧骨架（仅结构）
目标：读取音乐并布置帧——STORYBOARD.md 的骨架。
读取 references/frame-skeleton.md。亲自将 audiomap.json 转换为 STORYBOARD.md 的骨架——没有中间 JSON。在真实的音乐变化处（hard_stops、SURGE/DROP key_moments、滚奏的边缘、没有起音的段落、大的能量跳跃）将曲目切割为帧，将每个边界对齐到 audiomap 锚点。为每帧设置 span_sec、pacing（来自第1步信任判断的结论——当网格真实时为 beat_cut，当它是施加在平静音乐上的节拍器时为 phrase_flow）、mood 和一行 feel（第3步匹配模板的纯音乐情况）。在这里仅进行分类和布置：将每帧的 ### Groups 保留为 TBD (Step 3)，并将前置元数据 style 留空——没有模板、文案、颜色或字体。预计约1–6帧。
门控： 帧覆盖整个曲目（第一帧从0开始，最后一帧在 duration_s 结束）；每帧携带 span_sec + pacing + mood + feel；每个 ### Groups 为 TBD；任何地方都没有内容。
第3步：填充计划（用户门控）
目标：将骨架转换为已批准的完整 STORYBOARD.md。
读取 references/planning.md、storyboard-format.md、template-catalog.md、motion-primitive-catalog.md 和 montage.md（仅当用户提供了素材时）。在同一文件中就地编辑，做两件事：
- 选择品牌。 使用
../hyperframes-creative/references/design-spec.md中的表格从../hyperframes-creative/frame-presets/中选择一个预设（匹配曲目的情绪；仅其字体和颜色重要——模板拥有合成）。将其不加修改复制到frame.md，并从前置元数据style中填充它（字体 + 一个不超过4–6种颜色的调色板）。 - 填充每帧。 决定其组，并为每个组指定处理方式：从目录中匹配的模板（带有绑定参数和真实的 audiomap 锚点）、从原语目录中自由组合、或遵循
pacing的素材处理。编写文案。你拥有 WHAT（模板/原语 + 内容 + 锚点）；frame-worker 拥有 HOW——切勿将毫秒级补间写入故事板。
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
修复每个 ✗（硬错误：时长不匹配、帧未覆盖曲目、缺少 src）；警告尽力而为。然后向用户显示逐帧摘要并迭代直到他们批准。在自主模式下这是一个检查点门控：发布摘要作为通知并继续（validate-plan.mjs 通过是一个质量门控，仍然阻塞）。
门控： frame.md 是逐字复制的预设；validate-plan.mjs 退出码为0；用户批准了计划（自主模式：摘要已作为通知发布）。
第4步：根据计划构建帧
目标：将每帧构建为一个独立的合成文件。
创建 compositions/frames/。读取 sub-agents/frame-worker.md 和 ../hyperframes-core/references/subagent-dispatch.md。为每帧调度一个 frame-worker，尽可能并行（否则分批）。每个 worker 只得到一个帧和以下上下文：
PROJECT_DIR: <绝对路径>
frame_id: <NN-frame_id> # = 帧文件主干，例如 02-f2；合成 ID
你的块：PROJECT_DIR/STORYBOARD.md 中的 `## Frame N — <frame_id>` 块
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
素材：对于每个组，<SKILL_DIR>/references/templates/<id>/index.html（模板）和
<SKILL_DIR>/references/motion-primitives/<id>/（自由）；暂存的素材/（素材组）
合同：../hyperframes-core/references/sub-compositions.md + determinism-rules.md
画布：<w>×<h> 定速：<beat_cut|phrase_flow>
写入到：PROJECT_DIR/compositions/frames/<frame_id>.html
worker 分叉引用的素材，将每个锚点转换为帧局部秒数（local_t = track_t − span_sec[0]），以0ms剪切门控其组，并写入一个安全的帧文件。worker 绝不运行 hyperframes CLI——这些命令操作已组装的（尚不存在的）项目，因此会报告到错误文件上。worker 只写入合同并停止；你在组装后（第6步）验证。当每个 worker 返回时，你可以确认其文件已落地磁盘。
门控： 每帧的 compositions/frames/NN-*.html 已存在于磁盘上。
第5步：组装
目标：将构建的帧 + BGM 连接到可播放的 index.html 中。
assemble-index.mjs 是确定性的——没有子代理，没有判断。它在累积的 data-start 处引用每个帧文件，将 assets/bgm.mp3 挂载到音轨11上，并硬切帧到帧（帧覆盖曲目且无间隙，因此没有过渡注入器）。
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
修复它报告的任何 ✗——缺失或空白的帧文件意味着该 worker 写入了部分文件；重新调度它（第4步）并重新组装。
门控： index.html 存在；总时长 == audiomap.audio.duration_sec。
第6步：验证和渲染
目标：验证组装的视频，获得用户批准，并渲染最终的 MP4。
在已组装的项目上运行 CLI——那是正确的单元（每帧的 worker 无法运行它）。check 在一步中运行结构 lint 和 headless-browser 运行时、布局、运动和对比度门控；--snapshots 还会生成审查帧。
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
检查 t=0、每个帧开始、最强的 DROP/SURGE、每个 hard_stops[].t 和最后一帧。失败时，自行进行最便宜的安全修复：编辑有问题的 compositions/frames/NN-*.html。切勿更改时长或音频时序来隐藏同步问题。一旦门控通过，暂停等待用户审查，然后仅在批准后渲染（自主模式：询问一个保留问题——“先预览还是渲染？”——然后提供 MP4 和联系表）：
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
门控： check 通过且快照已检查；用户批准（自主模式：检查通过，交付包括联系表）；renders/video.mp4 存在且包含音频，时长 == audiomap.audio.duration_sec。最终回复说明 MP4 路径和时长。
恢复表
| 你已有 | 从何处继续 | | --
…
[此处截断以供翻译]