Communitygithub.com

Army161/OpenMontage

將音樂(音檔或影片音軌)轉換為節拍同步的 HyperFrames 影片,從平靜柔和到強烈震撼皆可。音樂驅動一切:分析器讀取一次,編排器規劃幀與計畫,再由一個子代理建立每個幀。

OpenMontage 是什麼?

此技能將使用者的音樂軌道轉換為節拍同步的 HyperFrames 影片。工作流程從一次音樂分析開始,產生 `audiomap.json` 檔案(包含能量相位、起始點、音節、寂靜等資訊)。接著,編排器(即LLM本身)讀取分析結果,將音軌切割成幀,填入每幀的計畫(包含文字、字型、調色板與模板選擇),並為每個幀分派一個專門的子代理(`frame-worker`)來建立獨立的 HTML 合成檔。最後,所有合成檔會與背景音樂一起組裝成一個可播放的 `index.html`,並可渲染為最終的 MP4 影片。 此技能支援 Claude Code、Codex CLI 與 Cursor,特別設計用於快速、高能量的音樂(具有強烈的節拍網格),但也能優雅地處理平靜的音樂,透過短語與能量來調整節奏。工作流程完全不需外部素材——文字編排與模板提供了豐富的效果——並可將使用者提供的圖像或影片以節拍切割或 Ken Burns 效果融入。關鍵的設計原則為:只有一個權威的節拍分析器(`analyze-beatgrid.py`),且每個幀為一個獨立的檔案,透過子代理平行建構,確保可擴展性與一致性。此技能使用方法驅動,在規劃與渲染階段會暫停以徵求使用者核准。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

音樂轉影片 — 一個以音樂為基礎、節拍同步的影片工作流程

使用此技能將音樂軌道轉換為節拍同步的 HyperFrames 影片。您只需分析音軌一次,規劃幀佈局,填寫每幀計畫,然後將每個幀建立為合成檔。輸入為音樂軌道加上可選的使用者圖像或影片——沒有旁白或網站捕捉。排版與模板是最基本的(一個完整的影片不需要任何素材);使用者提供的任何媒體都會在同一個節拍網格中被切割並融入。

您是編排器。在 videos/<project>/ 目錄下工作。依序執行步驟,並在繼續前通過每個關卡。有兩個步驟需要使用者:步驟 3(計畫核准)與步驟 6(渲染核准)。除了步驟 4(您為每個幀分派一個子代理)之外,請自行執行每個步驟。設計與動畫規則保留在 references/ 與 frame-worker 子代理中。

SKILL_DIR = 此技能目錄。PROJECT_DIR = videos/<專案名稱>/。

工作流程:步驟 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 離線進行——然後再生成音軌;不要將金鑰寫入每個 repos 的 .env 中。(在自主模式下,記錄狀態並繼續離線操作。)請參閱 /hyperframes-media → Preflight 以取得權威指南。無論哪種方式,音軌都會放置在 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 存在;已註明長寬比 / 長度 / 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——這是正確的單元(每幀的 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:為每個群組選擇運動基元
sub-agents/frame-worker.md步驟 4:分派子代理

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.

相關技能