1实现原理 · 为什么它能做到
这是端到端 7 步带 Gate 的 workflow 技能：Step0 建项目（hyperframes.json+assets/bgm.mp3）→ Step1 音乐分析（audiomap.json）→ Step2 帧骨架（STORYBOARD.md）→ Step3 用户门禁的计划填充 → Step4 每帧一个 frame-worker 子代理并行构建 → Step5 确定性组装 index.html → Step6 用户门禁的 check+render。
skills/music-to-video/SKILL.md
Workflow: Step 0 setup → `hyperframes.json` + `assets/bgm.mp3`; Step 1 analyze → `audiomap.json`; Step 2 skeleton → `STORYBOARD.md` (frames, groups `TBD`); Step 3 plan → complete `STORYBOARD.md` + `frame.md`; Step 4 build → `compositions/frames/NN-*.html`; Step 5 assemble → `index.html`; Step 6 render → `renders/video.mp4`.
注：两个用户门禁：Step 3 计划批准与 Step 6 渲染批准（autonomous 模式发 heads-up 继续）；'Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**.'
节拍分析由单一权威脚本落地：analyze-beatgrid.py（Python：librosa beat tracker + 16 分音 bar grid + 鼓组 band-split 分类 + riser/glitch/hard-stop 事件 + 能量叙事），写确定性 audiomap.json；SKILL 禁止再用其它工具/耳朵重测节拍。
skills/music-to-video/SKILL.md
`analyze-beatgrid.py` is the **only** beat analyzer — never re-measure beats with another tool or by ear. Its energy / density / rolls / onsets / silences are always reliable.
注：脚本头部 docstring：'Turns a BGM track directly into a deterministic `audiomap.json`… merges: reliable tempo + beat grid + downbeat (librosa beat tracker), metrical position per event, drum-element classification (band-split), special audio events, energy narrative, phrase layer + density budgets'；Deps: ffmpeg/ffprobe + librosa/numpy/soundfile。
脚本对不可靠字段诚实：bpm/beats_sec 仅在音乐真正有节奏时可靠——平静音乐上网格是 tracker 强加的节拍器，每帧的 pacing（beat_cut/phrase_flow）在 Step 2 由 orchestrator 裁决。
skills/music-to-video/SKILL.md
Its `bpm` and `beats_sec` are reliable **only when the music is genuinely rhythmic**; on calm music the grid is a metronome the tracker imposed, so pace by phrases and energy instead and never hard-cut to it.
注：pacing 是 Step 2 起每帧必填字段，且在 Step 3/4 约束资产处理与模板选择（asset treatment 必须 obey pacing）——把音乐感知判断显式建模进数据结构。
人力分配模型：orchestrator（本技能）只做计划与装配，每帧交给一个 frame-worker 子代理按固定上下文（PROJECT_DIR/frame_id/Storyboard 块/audiomap/frame.md/素材路径/契约）构建单个 composition 文件；frame 数量跟『不同处理』而非拍数（组内加密度），避免快速音乐撑爆子代理数。
skills/music-to-video/SKILL.md
Extra density goes _inside_ a group, so **frame count tracks distinct treatments, not beats** — a fast track does not blow up the number of sub-agents.
注：frame-worker.md 实测：worker 只写文件不跑 hyperframes CLI（'those commands operate on the assembled project, which doesn't exist yet'），Step 6 由 orchestrator 统一 check/snapshot/render——契约明确防止子代理对错误单元跑验证。
确定性装配由脚本保证：assemble-index.mjs 无子代理无判断，按 STORYBOARD 的累计 data-start 挂每帧、BGM 上 track 11、帧间硬切（无 transition injector——帧已无隙铺满轨道）；validate-plan.mjs 在 Step 3 校验计划（时长不匹配/帧未铺满/缺 src 为 hard error）。
skills/music-to-video/SKILL.md
`assemble-index.mjs` is deterministic — no subagent, no judgment. It references each frame file at its cumulative `data-start`, mounts `assets/bgm.mp3` on track 11, and hard-cuts frame → frame (frames tile the track with no gaps, so there is **no transition injector**).
注：『Frame count tracks distinct treatments』+ 硬切装配 = 时间线数学简单可验：总时长必须等于 audiomap.audio.duration_sec（Gate 判据）。
素材/BGM 来源链清晰：用户给音频/视频 → 提取；没有 → 走 /media-use 的 mood→track 生成（provider auth 属 media-use，SKILL 只跑 `npx hyperframes auth status` 中继输出并声明 'Never write keys into a per-repo .env'）；离线本地 provider 兜底。
skills/music-to-video/SKILL.md
If signed out, apply one branch: - **Collaborative:** wait for sign-in or an explicit choice to continue offline with the local provider. - **Autonomous:** state the status and continue through the available local provider.
注：执行面划分：本 workflow 自身不持 key；'Auth ownership and offline fallbacks live in `/media-use` `references/setup-providers.md` § Providers.'
2核心能力
01权威节拍/能量/事件分析（analyze-beatgrid.py → 确定性 audiomap.json）
02基于音乐结构的帧骨架设计（hard_stops/key_moments/roll 边缘/onset 空洞切帧，snap 到 audiomap anchor）
03模板/运动原语双目录：L1 templates（card-flyby/held-text-strobe-burst 等，带 program.json）+ L0 motion-primitives（42 个 index.html 食谱）
04计划校验（validate-plan.mjs：时长匹配/铺满/缺 src 硬错误）与确定性组装（assemble-index.mjs）
05素材 staging（stage-assets.mjs 把用户图片/视频按帧切上同一节拍网格）
06帧级并行构建（每帧一个 frame-worker 子代理）与 resume 表（从任意中间态续跑）
07交付前验证闭环：check . --snapshots 在 t=0/帧起点/DROP-SURGE/hard_stops/末帧目检 + 用户批准后 render
3外部依赖
| 类型 | 依赖 |
|---|---|
| package | Python3 + librosa/numpy/soundfile（analyze-beatgrid.py；缺失时 pip install） |
| cli | ffmpeg/ffprobe（analyze-beatgrid.py 解码） |
| cli | hyperframes CLI（init/update/auth status/check/render；render 带 --skill=music-to-video） |
| network | （间接）pip/npm 官方注册表首次拉包；BGM 生成走 /media-use provider（HeyGen/Lyria 等，auth 属 media-use） |
| network | 产物运行期 CDN（模板引用 jsdelivr gsap/three；作品级依赖） |
4风险提醒 风险提醒：黄色 · 留意使用
风险提醒：黄色 · 留意使用
- 依赖 Python 生态与 CLI 链：librosa/numpy/soundfile、ffmpeg、hyperframes CLI 缺一即卡在某步 — SKILL 指引 pip install 兜底，但离线/受限环境需预装；版本不匹配会改变 audiomap 数值。
- autonomous 模式把两个用户门禁降级为 heads-up，交付节奏由 orchestrator 自判 — 计划/渲染门禁在 collaborative 模式强制；autonomous 需宿主信任 agent 判断。
- auth status 中继 + 委托 media-use 生成会接触账户状态/云端生成端点 — 本技能不持 key；但整链跑通时 HeyGen/Lyria 等凭证与用量面被激活，归 media-use（orange）承担。
- 帧 worker 并行度 = 帧数（可到几十），编排成本与失败重派需 orchestrator 管理 — frame count tracks treatments 缓解（组内加密度），但复杂曲目仍会触发多子代理波次。
风险提醒：黄色，留意使用。本 workflow 自身无凭证接触（明示不写 key、auth 归 /media-use），但会：① 执行本地 Python 分析（缺依赖时 `pip install librosa numpy soundfile`，PyPI 官方包）；② 运行官方 hyperframes CLI（init/update/check/render，render 需用户批准）并经 npm/GitHub 官方渠道拉包；③ 运行 `npx hyperframes auth status` 中继账户登录/用量状态（账户级状态读取，非明文 token——若视作凭证接触则按统一分档从宽说明，未升 orange 的理由：不读 key、不外发、对象官方可预期）；④ BGM 生成委托 /media-use（其凭证面在 media-use，orange）。外发对象均为官方/可预期端点 → yellow。
5第二遍独立确认
- [ok] 『analyze-beatgrid.py 是唯一分析器』 — SKILL.md Step 1/Two ideas 两处声明 + 目录实测无其它分析脚本；audio 相关生成/转写均指向 media-use。
- [ok] 帧数与子代理数解耦声称 — SKILL.md 'frame count tracks distinct treatments, not beats' + frame-worker.md 'One frame = one file; groups live inside' 复核一致。
- [ok] worker 不跑 CLI 的纪律 — SKILL.md Step 4 'The worker never runs the `hyperframes` CLI…' + frame-worker.md 'Writing the file is your terminal action; the orchestrator runs lint/check' 双重复核。
- [discrepancy] auth status 是否触碰凭证 — 首轮注记『无凭证面』需细化：Step 0 确实运行 `npx hyperframes auth status` 并中继输出（登录/用量状态，账户级而非明文 token），且 BGM 生成委托 media-use 时其凭证面在 media-use。已在 credential_reads/reason 如实表述并维持 yellow。
- [ok] 渲染门禁与时长一致性判据 — Gate 文本 'the user approved … `renders/video.mp4` exists with audio, duration == audiomap.audio.duration_sec' 与 assemble 的确定性设计自洽。
6结论
适合：适合把一首音乐（文件/提取/按 mood 生成）变成 beat-synced 成片的创作会话（lyric video/slideshow/kinetic promo），尤其有明确节奏、无旁白、可零素材交付的场景；也是研究『确定性装配 + 子代理并行构建 + Gate 工作流』的完整范本。
不适合：不适合有旁白/解说的内容（→ /hyperframes 输入匹配 workflow，如 faceless-explainer/general-video）；不适合音乐只作铺底而非驱动节拍的内容；不适合无音乐文件且拒绝生成/登录的场景（BGM 缺失则 Step 0 卡住，除非用本地 provider）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-09
方式 A · 人下载镜像包下载 music-to-video.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent7806505645ff0114…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库heygen-com / heygen-com/hyperframes
原始 GitHubheygen-com/hyperframes ↗
Stars48297
最近推送2026-09-09
本 skill commit
b8328f9573许可Apache-2.0（仓库根 LICENSE；GitHub API spdx Apache-2.0）
本站信息
收录日期2026-09-06
分类文档与知识
侦查报告2026-09-06 · 2 遍
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。