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 存在;記錄了寬高比/長度/幀率以及(如果有的話)素材清單。
步驟 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
您的區塊: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
工作者複製引用的素材,將每個錨點轉換為框架本地秒數(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。在 storyboard 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:每個框架工作者的合約 |
../hyperframes-core/references/subagent-dispatch.md | 步驟 4:分派和協調子代理 |
../hyperframes-core/references/sub-compositions.md | 步驟 4:框架工作者合約 |
../hyperframes-core/references/determinism-rules.md | 步驟 4:框架工作者合約 |
references/bgm.md | 步驟 0:背景音樂來源決策 |
../hyperframes-creative/references/design-spec.md | 步驟 3:品牌選擇(字型 + 調色板) |