Communitygithub.com

Army161/OpenMontage

根据音乐轨道(音频文件或视频中的音频)自动生成节拍同步的 HyperFrames 视频,风格可从平静到强烈。音乐驱动一切:一次分析、编排帧序列、为每帧制定计划,并由一个子智能体构建每帧。仅需排版和模板即可生成完整视频,用户提供的图片或视频素材也会按节拍网格自动剪辑。

OpenMontage 是什么?

该技能是一个端到端的音乐驱动视频生成工作流,专为 HyperFrames 平台设计。其核心理念是“一次分析、一次编排”:通过 `analyze-beatgrid.py` 对音频进行唯一一次节拍分析,生成包含能量相位、起始点、滚奏、静音等详细信息的 `audiomap.json`;随后编排器根据音乐结构将轨道切割为 1-6 个“帧”,每个帧对应一个独立的合成文件,并由专门的子智能体 `frame-worker` 构建。工作流分为 6 个步骤:设置与音频源建立(Step 0)、音乐分析(Step 1)、帧骨架布局(Step 2)、填充并审批计划(Step 3,需用户确认)、并行构建帧(Step 4,每帧一个子智能体)、组装并渲染最终 MP4 视频(Step 5-6)。该技能不依赖预设的“流派”分支,而是通过每帧的模板选择自然衍生出歌词视频、幻灯片、动态宣传片等风格。其关键优势在于严格的依赖关系与确定性执行:每帧的构建独立于组装,验证环节确保时长一致,且整个流程通过 `validate-plan.mjs` 和 `assemble-index.mjs` 等脚本保证高度自动化。用户仅需提供音乐和可选的视觉素材,即可获得节拍同步、风格统一的视频输出。

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

在你喜欢的 AI 中提问

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

文档

music-to-video — 一个基于音乐、节拍同步的视频工作流

使用此技能将音乐轨道转换为节拍同步的 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:设置、BGM 和输入

目标:确定音乐源,创建 HyperFrames 项目,并记录任何用户提供的媒体。

音乐是核心——在开始之前先确定一个轨道。此技能针对快速、高能量 BGM 进行了调整:强大的节拍网格驱动剪辑(平静的轨道也可以,但应根据乐句而非节拍来安排节奏)。如果用户给了您音频——一个音乐文件,或一个要从中提取音频的视频——请使用它。如果没有,生成一个:根据用户的描述选择情绪(例如“驱动合成波”、“陷阱节拍”、“振奋人心的企业音乐”),并通过 /hyperframes-media(references/bgm.md——凭证有效时使用 HeyGen 检索,否则使用本地 Lyria / MusicGen;ElevenLabs 或其他生成器也有效)生成一条轨道。在生成之前,运行 npx hyperframes auth status 并逐字输出其结果(不要改述或重写)——它显示 BGM 是来自 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"   # 如果需要,先从视频中提取
# 仅当用户给了您图片/视频时:
nnode <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),并将前言的 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>/(自由组合);暂存的 assets/(资产分组)
契约:../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 切换对其分组进行门控,并写入一个可查找安全的帧文件。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——这是正确的单元(逐帧 workers 无法运行它)。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仅当用户提供了资产:使用蒙太奇技巧(Ken Burns、节拍剪辑)

Individual skills in this repo

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

Army161/OpenMontage

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax). Supports two gateways: HeyGen API and fal.ai API.

Army161/OpenMontage

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Army161/OpenMontage

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

Army161/OpenMontage

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

Army161/OpenMontage

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

Army161/OpenMontage

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Army161/OpenMontage

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Army161/OpenMontage

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

Army161/OpenMontage

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.

Army161/OpenMontage

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`).

Army161/OpenMontage

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.

Army161/OpenMontage

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`.

Army161/OpenMontage

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.

Army161/OpenMontage

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).

Army161/OpenMontage

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.

Army161/OpenMontage

Best practices for Remotion - Video creation in React

Army161/OpenMontage

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

Army161/OpenMontage

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.

Army161/OpenMontage

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

Army161/OpenMontage

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

相关技能