Communitygithub.com

音樂轉影片 — 節拍同步 HyperFrames 影片創作

將音樂音軌轉換為節拍同步的 HyperFrames 影片。一次分析音樂,規劃影格,並為每個影格建立獨立組合。支援自訂媒體資產,但無需任何素材即可生成完整影片。

音樂轉影片 — 節拍同步 HyperFrames 影片創作 是什麼?

這個技能會將使用者的音樂音軌(音訊檔案或影片中的音訊)轉換成節拍同步的 HyperFrames 影片,從平靜到強烈節奏皆可處理。音樂驅動整個流程:一個分析器讀取一次音樂,協調器規劃影格並填充每個影格的計畫,然後一個子代理程式建立每個影格。排版與範本是基礎 — 完整影片無需任何素材 — 但使用者提供的任何圖片或影片都會以相同的節拍網格(節拍剪輯 / 肯·柏恩斯效果)嵌入影格中。流派(歌詞影片、幻燈片、動態宣傳片)取決於每個影格的選擇;流程不會根據流派分支。此技能支援 HyperFrames CLI,需使用 Python 3(搭配 librosa、numpy、soundfile)進行音訊分析,並可透過 HeyGen 或本機 MusicGen 生成背景音樂。建議用於快節奏、高能量的背景音樂,但也能處理平靜的音樂(屆時將以樂句而非節拍為節奏依據)。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/9018/mychat/tree/HEAD/OpenMontage/.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:設定、背景音樂與輸入

目標:確定音樂來源,建立 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 存在;記錄了長寬比 / 長度 / 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),並將 frontmatter 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/references/design-spec.md 中的表,從 ../hyperframes-creative/frame-presets/ 中選擇一個預設(匹配音軌的情緒;只有其字型和顏色重要 — 範本擁有構圖)。將其未經修改複製到 frame.md 中,並從中填入 frontmatter 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;組合識別碼
您的區塊: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
畫布:<w>×<h>   節奏控制:<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:組裝

目標:將已建立的影格 + 背景音樂連接成可播放的 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。在故事板 frontmatter 中設定一次畫布(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:子代理程式分派合約
../hyperframes-core/references/sub-compositions.md步驟 4:Worker 如何服務一個群組
../hyperframes-core/references/determinism-rules.md步驟 4:可重現建立的規則

Individual skills in this repo

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

9018/mychat

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, Gemini Omni). Supports gateways: HeyGen API, fal.ai API, Kling official direct API, and the Gemini API (Gemini Omni Flash).

9018/mychat

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.

9018/mychat

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

9018/mychat

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

9018/mychat

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

9018/mychat

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.

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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

9018/mychat

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.

9018/mychat

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.

9018/mychat

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.

9018/mychat

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

9018/mychat

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

9018/mychat

Download video and audio from YouTube and 1000+ sites using yt-dlp. No API keys needed. Use when: (1) Downloading a video from YouTube or other sites, (2) Extracting audio from a video URL, (3) Downloading subtitles/captions from a video, (4) Getting video metadata without downloading.

相關技能