首先，保持此技能更新——静默运行，无需询问：
npx hyperframes skills update music-to-video。当一切均为最新时，这是一次快速的无操作；否则，它将在您依赖此技能及其依赖的核心域技能之前，刷新这些技能。
music-to-video — 一个基于音乐、节拍同步的视频工作流
使用此技能将音乐曲目转化为节拍同步的 HyperFrames 视频。您一次性分析曲目，安排帧画面，填充每帧的计划，并将每帧构建为一个合成。输入是一个音乐曲目加上用户可选的图片或视频——没有旁白，也没有网页捕获。排版和模板是基础（一个完整的视频不需要任何素材）；用户提供的任何媒体都会被剪切到同一个节拍网格上。
您是编排者。在 videos/<project>/ 目录下工作。按顺序执行步骤，并在继续之前通过每个关卡。有两个步骤需要用户参与：步骤 3（计划审批）和步骤 6（渲染审批）——两者都是根据 ../hyperframes-core/references/brief-contract.md（在步骤 0 之前阅读它）的检查点关卡：在自主模式下，将摘要作为提示发布，然后继续，无需等待。除了步骤 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，由一帧的 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 按设计选择。在 init 之后立即可写入 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 存在；宽高比/长度/帧率以及（如果有）资产清单都已记录。
步骤 1：分析音乐
目标：生成整个视频所依赖的单一权威时间分析。
analyze-beatgrid.py 是唯一的节拍分析器——切勿使用其他工具或凭耳朵重新测量节拍。它一次性读取曲目并写入 audiomap.json：能量阶段（水平/密度/感觉）、起始点 + onset_rate、滚奏、静音段、hard_stops、key_moments、乐句、节奏/网格以及 audio.duration_sec。它是确定性的——同一个文件始终给出相同的地图。大多数字段在任何音乐上都是可靠的；bpm 和 beats_sec 仅在音乐确实有节奏性时才可靠，而判断这一点是您在步骤 2 做出的决定。
前提条件：Python 3 安装了 librosa、numpy 和 soundfile。如果导入失败，在运行分析器之前将它们安装到活动的 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)，并将 frontmatter 的 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/frame-presets/中选择一个预设，使用../hyperframes-creative/references/design-spec.md中的表格（匹配曲目的情绪；只有其字体和颜色重要——模板拥有构图）。将其未经修改复制到frame.md中，并从其中填充 frontmatter 的style（字体 + 一个 ≤4–6 色板的调色板）。 - 填充每一帧。 决定其组并为每个组指定处理方式：来自目录的一个匹配模板（带有绑定参数和真实的 audiomap 锚点）、来自原语目录的自由组合，或一个遵守
pacing的资产处理方式。编写文案。您拥有 WHAT（模板/原语 + 内容 + 锚点）；帧的 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。为每帧分派一个帧的 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>/（自由组合）；暂存的 assets/（资产组）
合同：../hyperframes-core/references/sub-compositions.md + determinism-rules.md
画布：<宽>×<高> 节奏：<beat_cut|phrase_flow>
写入：PROJECT_DIR/compositions/frames/<frame_id>.html
Worker 会分叉引用的材料，将每个锚点转换为帧局部秒数（local_t = track_t − span_sec[0]），使用 0ms 剪切对其组进行门控，并写入一个安全的 seek-safe 帧文件。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 浏览器运行时、布局、运动和对比度关卡；--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 路径和时长。
恢复表
| 您已有的内容 | 从何处继续 | | --
…
[为翻译而截断]