music-to-video

**插件安装：**在设置或检查更新的命令之前，如果此技能位于 HyperFrames 插件中，请遵循插件执行规则。独立安装请遵循下方的更新说明。

首先，保持此技能为最新版本——运行前请向用户确认： npx hyperframes skills update music-to-video。如果所有内容均为最新版本，该命令会快速执行并结束；否则，它会更新此技能及其依赖的核心领域技能，然后你再依赖它们开展工作。

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

使用此技能，将一首音乐曲目制作成与节拍同步的 HyperFrames 视频。你只需分析一次曲目、安排画面、填写逐帧计划，并将每一帧制作成一个合成。输入是一首音乐曲目，以及可选的用户图片或视频——没有旁白，也不截取网站内容。排版和模板是基础配置（完整视频不需要任何素材）；用户提供的任何媒体素材都会按同一节拍网格剪入。

你是编排者。在 videos/<project>/ 中工作。按顺序执行各步骤，并通过每个关卡后再继续。两个步骤需要用户参与：步骤 3（计划审批）和步骤 6（渲染审批）——根据 ../hyperframes/references/brief-contract.md（步骤 0 之前先阅读），两者都是检查点关卡：在自主模式下，发布步骤 3 的摘要作为提示，然后继续；步骤 6 仍需请求渲染审批，这是唯一保留的提问。除步骤 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：设置、背景音乐和输入内容

目标：确定音乐来源，创建 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）。编辑请求跳过所有这些步骤。

音乐是主线——先确定一首曲目，再处理其他内容。此技能针对快速、高能量的背景音乐进行了调校：强劲的节拍网格推动剪辑（平静的曲目也可以，但应按乐句而非节拍来控制节奏）。如果用户提供了音频（音乐文件，或可提取音频的视频），就使用它。否则，根据请求选择情绪，并通过 /media-use 生成曲目（audio/references/bgm.md）；如果宿主应用提供自己的音乐工具，则使用该工具。在首次执行需要身份验证的提供方操作前，运行 npx hyperframes auth status，并原样转达其输出。如果未登录，选择以下一种方式：

• **协作模式：**等待登录，或等待用户明确选择继续使用本地提供方离线操作。
• **自主模式：**说明状态，并使用可用的本地提供方继续操作。

如果没有离线提供方能够满足所需的音乐功能，请说明阻碍。绝不要将密钥写入仓库专属的 .env。身份验证管理和离线备用方案见 /media-use references/setup-providers.md § Providers。生成的曲目保存到 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"   # 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 的素材处理方式。在自由组合某种指定风格前，先搜索实时目录：对于用户要求的每种风格、效果、处理方式或转场——例如“CRT 扫描线”“故障效果”“胶片颗粒”“微光扫过”——运行 npx hyperframes catalog --query "<用通俗英文描述该风格>" --json，并阅读排名靠前的结果。template-catalog.md 和 motion-primitive-catalog.md 仅列出此技能自身的本地素材；搜索会对整个托管注册表（约 400 个区块和组件）进行排名，无需安装任何内容——无需项目、无需预先执行 add，也无需账户。只有当搜索没有找到合适的内容时，才自由组合这种风格。撰写文案。你负责 WHAT（模板 / 图元 + 内容 + 锚点）；frame-worker 负责 HOW——绝不要在 storyboard 中编写毫秒级补间动画。

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

修复所有 ✗（硬性错误：时长不匹配、帧未铺满整首曲目、缺少 src）；警告尽力处理。然后在聊天中以提案形式逐帧展示摘要（../hyperframes/references/review-loop.md § 1），并根据用户的回复持续调整，直到用户批准；若为 storyboard: yes，还要将摘要呈现为画板 boards/storyboard.html（../hyperframes-creative/references/storyboard-recipe.md）。在自主模式下，这是一个检查点关卡：发布摘要作为提示后继续执行（validate-plan.mjs 的检查仍是质量关卡，且会阻止后续操作）。

关卡：frame.md 是预设的原样副本；validate-plan.mjs 以 0 退出；用户已批准方案（自主模式：已发布摘要作为提示）。

---

第 4 步：根据计划构建帧

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

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

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

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 是确定性的——无需子 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"

修复它报告的任何 ✗——帧文件缺失或为空，说明对应的 worker 写入了不完整文件；重新派发该 worker（第 4 步），然后重新组装。

门槛：index.html 已存在；总时长 == audiomap.audio.duration_sec。

---

第 6 步：验证并渲染

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

在组装后的项目上运行 CLI——这是正确的检查对象（逐帧 worker 无法运行 CLI）。check 会一次性运行结构检查以及无头浏览器的运行时、布局、动态效果和对比度门槛检查；--snapshots 还会输出供审阅的帧图。

( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )

检查 t=0、每帧的起始位置、最强的 DROP / SURGE、每个 hard_stops[].t，以及最后一帧。如果检查失败，自己进行成本最低的安全修复：编辑有问题的 compositions/frames/NN-*.html。绝不要通过更改时长或音频时间来掩盖同步问题。所有门槛检查通过后，打开最终的 Studio 预览（( cd "$PROJECT_DIR" && npx hyperframes preview --background )），暂停并等待用户审阅——现在渲染，还是需要修改？只有获得批准后才渲染（自主模式下也相同，作为唯一保留的问题），然后交付 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 路径和时长。

---

恢复进度表

你已有的内容	从此步骤继续
仅有 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/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 (mounts the scene), scene.html (the sub-composition) } (+ ../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)