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,由一個影格工作者建構。一個影格可以細分為 群組(每個群組是一個模板或一個動畫原語組合)。額外的密度放在群組_內部_,因此 影格數量追蹤不同的處理方式,而不是節拍 — 快速的曲目不會增加子代理的數量。
步驟 0:設定、背景音樂與輸入
目標:確定音樂來源,建立 HyperFrames 專案,並記錄任何使用者提供的媒體。
音樂是主幹 — 先確定一首曲目再做其他事情。此技能專為 快速、高能量的背景音樂 而調整:強烈的節拍網格驅動剪輯(平靜的音樂也可以,但要根據樂句而非節拍來設定節奏)。如果使用者提供了音訊 — 一個音樂檔案,或一個需要從中擷取音訊的影片 — 就使用它。如果沒有,就生成一個:根據使用者的描述選擇氛圍(例如 "動感合成波", "陷阱節拍", "積極向上的企業風格"),並透過 /hyperframes-media 生成曲目(references/bgm.md — 有憑證時使用 HeyGen 檢索,否則使用本地 Lyria / MusicGen;ElevenLabs 或其他生成器也可以)。在生成之前,執行 npx hyperframes auth status 並 逐字轉述其輸出(不要改寫或重寫) — 它會顯示背景音樂來自 HeyGen 還是本地 MusicGen,如果未登入,還會顯示如何登入。如果未登入,請停止並等待使用者選擇 — 登入,或繼續離線使用本地 MusicGen — 然後再生成曲目;不要將金鑰寫入每個儲存庫的 .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、滾奏的邊緣、沒有起音的一段區域、重大的能量跳躍)處將曲目切割成 影格,將每個邊界對齊到音訊地圖的錨點。為每個影格設定 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 (僅當使用者提供了素材時)。就地編輯同一個檔案,執行兩件事:
- 挑選品牌。 從
../hyperframes-creative/frame-presets/中選擇一個預設,使用../hyperframes-creative/references/design-spec.md中的表格(匹配曲目的氛圍;只有它的字型和顏色重要 — 模板擁有構圖)。將它複製到frame.md不做修改,並從中填入 frontmatterstyle(字型 + 一個 ≤4–6 色調色板)。 - 填補每個影格。 決定其群組,並為每個群組指定一種處理方式:從目錄中匹配一個模板(帶有綁定參數和真實的音訊地圖錨點)、從原語目錄中自由組合、或一個 遵循
pacing的素材處理方式。撰寫文案。您擁有 WHAT(模板/原語 + 內容 + 錨點);影格工作者擁有 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。為每個影格派遣一個影格工作者,儘可能平行(否則分波進行)。每個工作者只獲得一個影格和以下上下文:
PROJECT_DIR: <絕對路徑>
frame_id: <NN-frame_id> # = 影格檔案主體,例如 02-f2;合成 ID
Your block: PROJECT_DIR/STORYBOARD.md 中 `## Frame N — <frame_id>` 區塊
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materials: 針對每個群組,<SKILL_DIR>/references/templates/<id>/index.html(模板)和
<SKILL_DIR>/references/motion-primitives/<id>/(自由式);已整理素材/(素材群組)
Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas: <w>×<h> Pacing: <beat_cut|phrase_flow>
Write to: PROJECT_DIR/compositions/frames/<frame_id>.html
工作者會 fork 引用的素材,將每個錨點轉換為影格本地秒數(local_t = track_t − span_sec[0]),以 0ms 剪輯來限制其群組,並寫入一個可尋址的安全影格檔案。工作者絕不執行 hyperframes CLI — 那些命令作用於組合後的專案,而該專案還不存在,因此它們會報告錯誤的檔案。工作者只根據合約寫入並停止;您在組合後(步驟 6)進行驗證。當每個工作者返回時,您可以確認其檔案已存在於磁碟上。
關卡: 每個影格都有其 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"
修正它報告的任何 ✗ — 缺少或空白的影格檔案意味著該工作者寫入了部分檔案;重新派遣它(步驟 4)並重新組合。
關卡: index.html 存在;總時長 == audiomap.audio.duration_sec。
步驟 6:驗證與渲染
目標:驗證組合後的影片,獲得使用者批准,並渲染最終的 MP4。
在 組合後的專案 上執行 CLI — 這是正確的單元(逐影格的工作者無法執行它)。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:為素材群組挑選蒙太奇模式(僅限使用者提供了素材時) |