music-to-video

music-to-video — 一个以音乐为基础、与节拍同步的视频工作流

使用此技能将音乐曲目转化为与节拍同步的 HyperFrames 视频。你只需分析一次曲目、排布画面、填写逐帧计划，并将每一帧构建为一个合成。输入是一首音乐曲目，以及可选的用户图片或视频——没有旁白，也不捕获网站。排版和模板是基础（完整视频无需任何素材）；用户提供的媒体素材则会按照同一节拍网格剪入。

你是编排者。在 videos/<project>/ 中工作。按顺序执行步骤，并通过每个关卡后再继续。两个步骤需要用户参与：步骤 3（计划审批）和步骤 6（渲染审批）。除步骤 4外，其他步骤都由你自行完成；步骤 4 需要你为每一帧分派一个子 Agent。设计和动画规则不写在此文件中——它们位于 references/ 和 frame-worker 子 Agent 中。

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 构建。一帧可以细分为多个组（每组使用一个模板或一组运动原语）。额外的密度放在组内，因此帧数反映的是不同的处理方式，而不是节拍数——快节奏的曲目不会导致子 Agent 数量激增。

---

步骤 0：设置、背景音乐和输入内容

目标：确定音乐来源、创建 HyperFrames 项目，并记录用户提供的媒体。

音乐是整个视频的主线——先确定一首曲目，再做其他事。此技能针对快节奏、高能量的背景音乐（BGM）进行了调优：强烈的节拍网格驱动剪辑（舒缓的曲目也可以，但应按乐句而非节拍控制节奏）。如果用户提供了音频——音乐文件，或可以提取音频的视频——就使用它。如果没有，就生成一首：根据用户的描述选择氛围（例如“强劲的合成器浪潮”“陷阱节拍”“欢快的企业风格”），并通过 /hyperframes-media 制作曲目（references/bgm.md——有凭据时从 HeyGen 获取，否则使用本地 Lyria / MusicGen；也可以使用 ElevenLabs 或其他生成器）。生成前，运行 npx hyperframes auth status，并逐字转达其输出（不要释义或改写）——输出会显示 BGM 来自 HeyGen 还是本地 MusicGen；如果尚未登录，也会说明如何登录。如果尚未登录，请停下并等待用户选择——登录，或继续离线使用本地 MusicGen——然后再生成曲目；不要将密钥写入项目仓库中的 .env。（在自主模式下，记录状态并继续离线操作。）请参阅 /hyperframes-media → Preflight，其中提供了标准指南。无论采用哪种方式，曲目都会保存到 assets/bgm.mp3。将用户提供的图片或视频放好，以便画面能融入节拍网格；否则，整个视频都由文字排版呈现。

仅当缺少 hyperframes.json 时才初始化。根据需求说明，以 kebab-case 为 <project> 命名，例如 midnight-drive-loop——绝不要使用时间戳。init 会检查已安装的技能是否为 GitHub 上的最新版本，如果有过期技能，就更新全局技能集。

npx hyperframes init "videos/<project>" --non-interactive --example=blank
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3"   # extract from a video first if needed
# only if the user gave you images/videos:
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 中判断。

前置条件：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（仅当用户提供了素材时）。在同一个文件中直接编辑，完成两件事：

1. 选择品牌。 根据 ../hyperframes-creative/references/design-spec.md 中的表格，从 ../hyperframes-creative/frame-presets/ 选择一个预设（匹配曲目的情绪；只用其字体和颜色——构图由模板决定）。将其原样复制到 frame.md，并根据该预设填写 frontmatter 中的 style（字体 + ≤4–6 色的调色板）。
2. 填充每一帧。 确定其分组并为每组指定一种处理方式：从目录中匹配模板（带有绑定参数和真实 audiomap 锚点）、从图元目录中自由组合，或遵循 pacing 的素材处理方式。撰写文案。你负责 WHAT（模板 / 图元 + 内容 + 锚点）；帧工作器负责 HOW——绝不要在故事板中写毫秒级补间动画。

node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
  --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates

修复每个 ✗（硬错误：时长不匹配、帧未完整覆盖曲目、缺少 src）；警告尽力处理。然后向用户展示逐帧摘要，并反复迭代直至用户批准。

关卡： frame.md 是预设的逐字副本；validate-plan.mjs 以 0 退出；用户已批准计划。

---

步骤 4：根据计划构建帧

目标：将每一帧构建为独立的合成文件。

创建 compositions/frames/。阅读 sub-agents/frame-worker.md 和 ../hyperframes-core/references/subagent-dispatch.md。为每一帧分派一个帧工作器，并尽可能并行执行（否则分批执行）。每个工作器只负责一帧，并获取以下上下文：

PROJECT_DIR: <abs path>
frame_id: <NN-frame_id>              # = the frame file stem, e.g. 02-f2; the composition id
Your block: the `## Frame N — <frame_id>` block in PROJECT_DIR/STORYBOARD.md
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materials: for each group, <SKILL_DIR>/references/templates/<id>/index.html (templates) and
           <SKILL_DIR>/references/motion-primitives/<id>/ (free); staged assets/ (asset groups)
Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas: <w>×<h>   Pacing: <beat_cut|phrase_flow>
Write to: PROJECT_DIR/compositions/frames/<frame_id>.html

工作器会分叉所引用的材料，将每个锚点转换为帧内局部秒数（local_t = track_t − span_sec[0]），通过 0ms 剪切门控其分组，并写入一个可安全跳转的帧文件。工作器绝不运行 hyperframes CLI——这些命令作用于已组装的项目，而该项目尚不存在，因此它们会针对错误的文件运行。工作器只需按约定写入文件并停止；你会在组装后验证（步骤 6）。每个工作器返回后，你可以确认其文件已写入磁盘。

关卡： 每一帧的 compositions/frames/NN-*.html 均已写入磁盘。

---

步骤 5：组装

目标：将构建好的帧和 BGM 接入可播放的 index.html。

assemble-index.mjs 具有确定性——不需要子 Agent，也无需判断。它会在各帧累计的 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"

修复它报告的任何 ✗——缺失或为空的帧文件表示工作器写入了不完整文件；重新派发任务（步骤 4）并重新组装。

关卡：index.html 存在；总时长 == audiomap.audio.duration_sec。

---

步骤 6：验证并渲染

目标：验证组装好的视频，获取用户批准，并渲染最终 MP4。

对已组装的项目运行 CLI——这是正确的检查对象（逐帧工作器无法运行它）。lint 检查结构，validate 运行无头 Chrome（捕获 JS 错误和缺失的资源），inspect 对帧进行快照。

( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )

检查 t=0、每帧起始处、最强烈的 DROP / SURGE、每个 hard_stops[].t，以及最后一帧。若检查失败，请自行进行成本最低且安全的修复：编辑有问题的 compositions/frames/NN-*.html。切勿更改时长或音频时间，以掩盖同步问题。所有关卡通过后，暂停以供用户审核，只有获得批准后才进行渲染：

( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )

关卡：lint / validate / inspect 均已通过；用户已批准；renders/video.mp4 存在且带有音频，时长 == audiomap.audio.duration_sec。最终回复需说明 MP4 路径和时长。

---

恢复进度表

你已有的内容	从此步骤继续
仅有 assets/bgm.mp3	步骤 1
audiomap.json	步骤 2
STORYBOARD.md（骨架）	步骤 3
STORYBOARD.md（完整）	步骤 4
所有帧文件	步骤 5
index.html	步骤 6

快速参考

**格式：**默认横屏 1920x1080；竖屏 1080x1920；正方形 1080x1080。在分镜脚本 frontmatter 中设置一次画布（canvas: { w, h, fps }）。

脚本位于 scripts/ 下：analyze-beatgrid.py（唯一的分析器）、validate-plan.mjs（计划检查）、assemble-index.mjs（索引组装）、stage-assets.mjs（暂存用户媒体）、lib/storyboard.mjs（供应商解析器）。其他所有内容都是 hyperframes CLI。

阅读	时机
references/frame-skeleton.md	步骤 2：听音乐、安排画面、设定节奏
references/planning.md · storyboard-format.md	步骤 3：选择品牌、填充每个画面、编写计划
references/template-catalog.md	步骤 3：为每组选择一个模板
references/motion-primitive-catalog.md	步骤 3/4：自由组合的 L0 配方
references/montage.md	步骤 3/4：素材处理（节拍剪辑 / ken-burns）
sub-agents/frame-worker.md	步骤 4：调度并构建一个画面
../hyperframes-core/references/subagent-dispatch.md	步骤 4：安全地调度子 Agent
../hyperframes-creative/references/design-spec.md	步骤 3：选择预设（品牌）

目录布局

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>/          { index.html (+ assets/ · program.json) }  ← L1 catalog impls
                motion-primitives/<id>/  { index.html } (+ ../assets/gsap.min.js shared by recipes) ← L0 catalog impls
  scripts/      analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs
  sub-agents/   frame-worker.md   ← the one subagent (one per frame)