music-to-video

用途

music-to-video 用于把一段音乐音轨制作成节拍同步（beat-synced）的 HyperFrames 视频，风格可从平静到强烈。输入是一首音乐（音频文件，或可从中提取音频的视频），外加可选的用户图片或视频素材；不涉及旁白，也不做网页抓取。排版与模板是基础——即使零素材也能产出完整视频；用户提供的媒体素材会按同一节拍网格切入画面。

主要能力

统一音乐分析：技能指定 analyze-beatgrid.py 为唯一节拍分析器，读入音轨后生成 audiomap.json，包含能量阶段（level / density / feel）、onset 与 onset_rate、rolls、静音段、hard_stops、key_moments、乐句（phrases）、tempo / grid 及 audio.duration_sec。分析是确定性的，同一文件总得到同一结果。
节拍可信度判断：能量、密度、rolls、onset、静音等字段在任意音乐上可靠；bpm 与 beats_sec 仅在音乐确有明显节奏时可靠。对舒缓音乐，网格是追踪器强加的节拍器，此时应按乐句与能量控制节奏，不做硬切。
帧骨架切分：依据真实的音乐变化（硬停、SURGE / DROP 关键时刻、roll 边缘、无 onset 的段落、能量跃升）把音轨切成约 1–6 个帧，边界对齐 audiomap 锚点，并为每帧设定 span_sec、pacing（beat_cut 或 phrase_flow）、mood 与一句话感受。
逐帧规划：从模板目录匹配模板（绑定参数与真实 audiomap 锚点）、用动作原语自由组合，或采用素材处理方式；同时从预设中选定品牌（字体与不超过 4–6 色的配色），并撰写文案。
逐帧构建：每帧对应一个独立的合成文件 compositions/frames/NN-*.html，由 frame-worker 子代理构建；一个帧内可再分组，密度增加放在组内，使帧数对应不同处理方式而非每个节拍。
确定性拼装：assemble-index.mjs 按各帧累计的 data-start 引用帧文件，把 assets/bgm.mp3 挂到第 11 轨，帧与帧之间直接硬切，生成可播放的 index.html。
校验与渲染：用 hyperframes CLI 执行 lint、validate、inspect，确认后渲染为带音频的 MP4。

使用方式（工作流）

工作目录为 videos/<project>/，按步骤顺序执行，每步通过 Gate 才继续。除第 4 步外均由主代理完成；第 3 步（方案批准）与第 6 步（渲染批准）需要用户参与。

Step 0 准备：确定音乐来源；若无则按用户描述的情绪生成（如 “driving synthwave”“trap beat”“upbeat corporate”），经由 /hyperframes-media 生成。生成前运行 npx hyperframes auth status 并原样转述输出，未登录时须停下等待用户选择（登录或离线使用本地 MusicGen），不把密钥写入仓库 .env。音轨最终位于 assets/bgm.mp3。若缺 hyperframes.json 则初始化，项目名用 kebab-case，如 midnight-drive-loop，不用时间戳。
Step 1 分析：运行 analyze-beatgrid.py 生成 audiomap.json。需 Python 3 及 librosa、numpy、soundfile。
Step 2 帧骨架：读取 references/frame-skeleton.md，把 audiomap 转成 STORYBOARD.md 的骨架，只做分类与布局，各组标记 TBD，不写模板、文案、颜色与字体。
Step 3 填充方案（需用户批准）：读取 planning、storyboard-format、template-catalog、motion-primitive-catalog，以及用户提供素材时的 montage。选定品牌预设并原样复制到 frame.md，填写每帧的分组与处理方式、文案与锚点；不写毫秒级补间。随后运行 validate-plan.mjs 修正所有硬错误，向用户展示逐帧摘要并迭代至批准。
Step 4 构建帧：为每帧派发一个 frame-worker（可并行），提供 PROJECT_DIR、frame_id、对应帧块、audiomap、frame.md、模板与原语材料、画布尺寸与 pacing 等上下文；worker 将锚点转为帧内秒数（local_t = track_t − span_sec[0]），写出单个 seek-safe 帧文件，且不运行 hyperframes CLI。
Step 5 拼装：运行 assemble-index.mjs 生成 index.html；若某帧文件缺失或为空，重新派发该帧并重新拼装。
Step 6 校验与渲染（需用户批准）：在项目目录运行 npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect .，在 t=0、各帧起点、最强 DROP / SURGE、各 hard_stops 时间点与最后一帧检查；失败时只做最小安全修改，不改时长或音频时序。通过并获批准后执行 npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30，最终回复给出 MP4 路径与时长。

适用场景

适合已有音乐、希望快速得到节拍驱动画面变化的短视频：快节奏高能量 BGM 效果最佳；舒缓音乐也可用，但按乐句推进。可用于纯排版视频，也可把用户图片/视频按节拍网格切入。

限制与注意事项

技能针对快速高能量 BGM 调校；节奏弱的曲目需改用乐句与能量控制，不对网格硬切。
节拍仅以 analyze-beatgrid.py 为准，不用其他工具或听感重新测量。
逐帧 worker 不运行 hyperframes CLI，校验与渲染只在拼装后的项目上执行。
不修改时长或音频时序来掩盖同步问题。
画布默认横屏 1920x1080，另有竖屏 1080x1920、方形 1080x1080，在 storyboard frontmatter 中以 canvas: { w, h, fps } 设定。
音乐生成依赖凭据与服务；未登录需用户选择登录或离线生成，具体收费、价格与平台支持范围资料未提供。

目录结构

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) }
                motion-primitives/<id>/  { index.html } (+ ../assets/gsap.min.js)
  scripts/      analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs
  sub-agents/   frame-worker.md