music-to-video — 一个基于音乐、节拍同步的视频工作流
使用此技能将音乐曲目转换为与节拍同步的 HyperFrames 视频。您分析一次曲目,布置帧,填充每帧计划,并将每个帧构建为一个合成。输入是一首音乐曲目加上可选的用户图像或视频——没有旁白,也没有网站捕获。排版和模板是基础(完整视频无需任何素材);用户提供的任何媒体都会在同一个节拍网格上剪切进来。
您是指挥官。在 videos/<project>/ 中工作。按顺序运行步骤,并在继续之前通过每个关卡。两个步骤需要用户参与:步骤 3(计划批准)和步骤 6(渲染批准)。除了步骤 4(其中您为每个帧分派一个子代理)之外,您自己执行每个步骤。将设计规则和运动规则保留在此文件之外——它们位于 references/ 和 frame-worker 子代理中。
SKILL_DIR = 此技能目录。PROJECT_DIR = videos/<项目名称>/。
工作流:步骤 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 项目,并记录任何用户提供的媒体。
音乐是主轴——在任何其他事情之前先建立一首曲目。此技能针对快速、高能量的 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" # 如果需要,先从视频中提取
# 仅当用户提供了图像/视频时:
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(仅当用户提供素材时)。在原地编辑同一个文件,执行两项操作:
- 选择品牌。 从
../hyperframes-creative/frame-presets/中选择一个预设,使用../hyperframes-creative/references/design-spec.md中的表格(匹配曲目的情绪;只有其字体和颜色重要——模板拥有合成)。将其未经修改复制到frame.md中,并从中填充 frontmatterstyle(字体 + 最多 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);警告是最佳努力。然后向用户显示逐帧摘要,并迭代直到他们批准。
关卡: 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> # = 帧文件名 stem,例如 02-f2;合成 id
您的块:`## Frame N — <frame_id>` 块位于 PROJECT_DIR/STORYBOARD.md
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
画布:<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 无法运行它)。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:为自由组合帧创建基元组合 |
references/montage.md | 步骤 3(如果用户提供素材):编排素材以遵守节奏 |
sub-agents/frame-worker.md | 步骤 4:构建每个帧的合同 |
../hyperframes-core/references/subagent-dispatch.md | 步骤 4:正确分派子代理 |
../hyperframes-core/references/sub-compositions.md · determinism-rules.md | 步骤 4:帧编写规则 |
../hyperframes-creative/references/design-spec.md | 步骤 3:品牌预设 |