音樂轉影片 — 一個以音樂為基礎、節拍同步的影片工作流程
使用此技能將音樂軌道轉換為節拍同步的 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(僅在使用者提供素材時)。在原地編輯同一個檔案,執行兩件事:
- 選擇品牌。 從
../hyperframes-creative/frame-presets/中選擇一個預設,使用../hyperframes-creative/references/design-spec.md中的表格(與音軌的情緒匹配;只有其字型和顏色重要——模板擁有構圖)。將其未經修改複製到frame.md中,並從中填寫前言style(字型 + 一個 ≤4–6 色調色板)。 - 填寫每個幀。 決定其群組並為每個群組指定一種處理方式:從目錄中選擇一個匹配的模板(包含綁定的參數和真實的 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:分派子代理 |