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外部依赖

Kind	Dependency / Endpoint
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管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: python3 analyze-beatgrid.py assets/bgm.mp3 -o audiomap.json（本地解码分析；ffmpeg s
scripts/ 或 SKILL.md: 声明动态安装外部语言包依赖
网络端点: 声明外部网络访问: pip install（PyPI 官方包，仅缺依赖时）、npx hyperframes 首次/更新拉包（npm/GitHub 官方渠道）
本地工作目录: 文件读写与工件输出: videos/<project>/ 全套项目产物：hyperframes.json、assets/bgm.mp3、audiomap.json、STOR

审计说明： 。本 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结论

七步流水线 + 每步 Gate + 双用户门禁，把『音乐→视频』从玄学变成可检查、可 resume 的确定性流程

单权威 audiomap 贯穿全链，beat/pacing 决策显式建模（beat_cut/phrase_flow 每帧必填），防多工具漂移

编排-执行分离：orchestrator 定 WHAT、frame-worker 定 HOW、脚本负责确定性数学，职责边界可审计

零素材可成片 + 用户素材同网格，模板/原语两级目录降低每帧创作成本

适合： 适合把一首音乐（文件/提取/按 mood 生成）变成 beat-synced 成片的创作会话（lyric video/slideshow/kinetic promo），尤其有明确节奏、无旁白、可零素材交付的场景；也是研究『确定性装配 + 子代理并行构建 + Gate 工作流』的完整范本。

不适合： 不适合有旁白/解说的内容（→ /hyperframes 输入匹配 workflow，如 faceless-explainer/general-video）；不适合音乐只作铺底而非驱动节拍的内容；不适合无音乐文件且拒绝生成/登录的场景（BGM 缺失则 Step 0 卡住，除非用本地 provider）。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload music-to-video.tar.gz

sha256: 7806505645ff0114…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b8328f9573.