Communitygithub.com

音乐转视频 — 基于音乐、节拍同步的视频工作流

将音乐曲目转化为节拍同步的 HyperFrames 视频,支持从平静到强烈冲击的各种风格。音乐驱动一切:一次性分析音频,编排帧并填充每个帧的计划,再由一个子代理构建每个帧。排版和模板是基础;用户提供的图片或视频可无缝融入节拍网格。

音乐转视频 — 基于音乐、节拍同步的视频工作流 是什么?

该技能是一个完整的音乐驱动视频生成工作流,专为 HyperFrames 平台打造。它从一首音乐曲目开始(用户提供或生成),通过一次性节拍分析(使用 analyze-beatgrid.py)生成 audiomap.json,然后编排帧骨架(STORYBOARD.md),填充每个帧的详细计划(包括品牌、模板或运动原语、文案),并分发帧到独立的子代理进行构建。最后,组装 index.html 并通过 CLI 进行验证和渲染为 MP4 视频。该工作流支持可选的用户资产(图片/视频),并以节拍切割或 Ken Burns 效果融入帧中。输出视频类型(如歌词视频、幻灯片、动态宣传片)由每个帧的选择自然决定,无需全局分支。支持的平台包括 HyperFrames CLI 和框架,可本地或通过 HeyGen 生成背景音乐。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-supabase/tree/HEAD/.agents/skills/music-to-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

音乐转视频 — 一个基于音乐、节拍同步的视频工作流

使用此技能将 音乐曲目 转化为节拍同步的 HyperFrames 视频。您一次性分析曲目,布局帧,填充每个帧的计划,并将每个帧构建为一个合成。输入是一段音乐曲目加上用户可选的图片或视频 — 没有旁白和网站抓取。排版和模板是基础(完整的视频无需任何资产);用户提供的任何媒体都将按照相同的节拍网格切入。

您是 编排者。在 videos/<project>/ 中工作。按顺序运行步骤,并在进入下一步之前通过每个 门。两个步骤需要用户参与:步骤 3(计划批准)和 步骤 6(渲染批准)。除 步骤 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 项目,并记录用户提供的任何媒体。

音乐是脊柱 — 首先确定一个曲目,然后再做其他任何事情。此技能针对 快节奏、高能量背景音乐 进行了调整:强节拍网格驱动切分(平静曲目也可以,但根据乐句而非节拍来规划节奏)。如果用户提供了音频 — 一个音乐文件,或用于提取音频的视频 — 则使用它。如果没有,则生成一个:根据用户描述选择情绪(例如“强劲的合成器浪潮”、“陷阱节拍”、“积极的企业风格”)并通过 /hyperframes-media(references/bgm.md — 有凭据时用 HeyGen 检索,否则用本地 Lyria / MusicGen;ElevenLabs 或其他生成器也可用)生成曲目。在生成之前,运行 npx hyperframes auth status 并 逐字输出其结果(不要改写或重写) — 它显示背景音乐来自 HeyGen 还是本地 MusicGen,如果未登录,则显示如何登录。如果未登录,请停止并等待用户选择 — 登录,或继续离线使用本地 MusicGen — 然后再生成曲目;请勿将密钥写入每个仓库的 .env 文件。(在自主模式下,记录状态并继续离线。)参见 /hyperframes-media → 预检以获得规范指导。无论哪种方式,曲目都位于 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 存在;已记录宽高比/长度/帧率以及(如果有)资产清单。


步骤 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),并将前置元数据中的 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/frame-presets/ 中的表格(匹配曲目的情绪;只有其字体和颜色重要 — 模板拥有构图)从 ../hyperframes-creative/references/design-spec.md 中选择一个预设。将其 未修改地 复制到 frame.md 中,并从前置元数据中填充 style(字体 + 一个 ≤4–6 色板调色板)。
  2. 填充每个帧。 确定其组,并为每个组赋予一种处理方式:从目录中匹配的模板(带有绑定的参数和真实的 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>              # = 帧文件名主体,例如 02-f2;合成 ID
您的区块:PROJECT_DIR/STORYBOARD.md 中的 `## Frame N — <frame_id>` 区块
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
材料:对于每个组,<SKILL_DIR>/references/templates/<id>/index.html(模板)和
          <SKILL_DIR>/references/motion-primitives/<id>/(自由形式);暂存的资产/(资产组)
合同:../hyperframes-core/references/sub-compositions.md + determinism-rules.md
画布:<宽>×<高>   节奏:<beat_cut|phrase_flow>
写入到:PROJECT_DIR/compositions/frames/<frame_id>.html

worker 复制引用的材料,将每个锚点转换为帧本地秒数(local_t = track_t − span_sec[0]),以 0ms 切割门控其组,并写入一个可安全用于 seek 的帧文件。worker 从不运行 hyperframes CLI — 这些命令操作已组装的项目,该项目尚不存在,因此它们会报告错误的文件。worker 仅根据合同写入然后停止;您在组装后验证(步骤 6)。当每个 worker 返回时,您可以确认其文件已写入磁盘。

门: 每个帧都有其 compositions/frames/NN-*.html 文件在磁盘上。


步骤 5:组装

目标:将构建好的帧 + 背景音乐连接到可播放的 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。在故事板前置元数据中设置一次画布(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:分派 frame-worker
../hyperframes-core/references/subagent-dispatch.md步骤 4:分派 frame-worker

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

1345AbhishekKumar/starter-supabase

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

1345AbhishekKumar/starter-supabase

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-supabase

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

1345AbhishekKumar/starter-supabase

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

1345AbhishekKumar/starter-supabase

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

1345AbhishekKumar/starter-supabase

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1345AbhishekKumar/starter-supabase

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

1345AbhishekKumar/starter-supabase

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1345AbhishekKumar/starter-supabase

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-supabase

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-supabase

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-supabase

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

1345AbhishekKumar/starter-supabase

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相关技能