首先，保持此技能新鮮——靜默執行，無需詢問：
npx hyperframes skills update music-to-video。當一切為最新時，此操作為快速無操作；否則它會刷新此技能及其依賴的核心領域技能，然後再依賴它們。
music-to-video — 一個基於音樂、節拍同步的影片工作流程
使用此技能將音樂軌道轉換為節拍同步的 HyperFrames 影片。您分析一次軌道，佈局影格，填寫每個影格的計畫，並將每個影格建置為一個合成。輸入是一個音樂軌道，加上可選的使用者圖片或影片——沒有旁白，也沒有網站擷取。排版和模板是基礎（一部完整的影片不需要任何素材）；使用者提供的任何媒體都會被剪輯到相同的節拍網格上。
您是編排者。在 videos/<project>/ 中工作。按順序執行步驟，並在繼續之前通過每個閘門。兩個步驟需要使用者：步驟3（計畫批准）和步驟6（渲染批准）——兩者都是每個 ../hyperframes-core/references/brief-contract.md（請在步驟0之前閱讀）中的檢查點閘門：在自動模式下，發布摘要作為通知，並繼續執行，而不是等待。除了步驟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，由一個 frame-worker 建置。一個影格可以細分為群組（每個都是模板或動畫基本元素的組合）。額外的密度進入 一個群組內部，因此影格計數反映不同的處理方式，而不是節拍——快速的軌道不會增加子代理的數量。
步驟0：設定、背景音樂和輸入
目標：建立音樂來源，創建 HyperFrames 專案，並記錄任何使用者提供的媒體。
簡報從意圖層開始。 開啟規則，按順序：(1) BRIEF.md 存在 → 讀取它，並且不要詢問它已經回答的任何問題——其 flow/storyboard 衍伸出模式（簡報合約 § 1）。(2) 沒有 BRIEF.md，但專案存在 → 從磁碟上的內容恢復；永遠不要重新詢問。(3) 一個直接到達此處的新創建請求 → 讀取 /hyperframes 並執行其意圖層（references/intent-interview.md）：它確認此路線的必要條件（音樂來源、目的地 → 長寬比——../hyperframes/references/routes/music-to-video.md），並宣布哪些保持延遲——品牌和類型在步驟3按設計選擇。在 init 之後立即寫入 BRIEF.md（永遠不要之前——init 拒絕非空目錄）並記錄基於偏好的答案（brief-format.md）。編輯請求跳過所有這些。
音樂是主幹——在任何其他事情之前建立一個軌道。此技能針對快速、高能量的 BGM 進行了調整：強大的節拍網格驅動剪輯（平靜的軌道也可以，但根據樂句而不是節拍安排節奏）。如果使用者提供了音訊——一個音樂檔案，或一個要從中提取音訊的影片——請使用它。否則，從請求中選擇情緒並通過 /media-use（references/bgm.md）生成一個軌道。在第一次經過驗證的提供者操作之前，執行 npx hyperframes auth status 並逐字中繼其輸出。如果已登出，則應用一個分支：
- 協作： 等待登入或明確選擇使用本地提供者繼續離線。
- 自動： 陳述狀態並通過可用的本地提供者繼續。
如果沒有離線提供者可以滿足所需的音樂功能，則顯示阻礙。永遠不要將金鑰寫入每個儲存庫的 .env。驗證所有權和離線後備方案位於 /media-use references/setup-providers.md § 提供者。結果軌道位於 assets/bgm.mp3。暫存提供的圖片或影片，以便影格可以在節拍網格上使用它們；否則排版承載影片。
歌詞影片： 對於與歌聲同步的歌詞，通過 /media-use 轉錄軌道來獲取單詞/行時間，或者向使用者詢問歌詞文字，並將行放在節拍網格上。
僅當缺少 hyperframes.json 時才初始化。從簡報中以 kebab-case 命名 <project>，例如 midnight-drive-loop——永遠不要使用時間戳。init 檢查已安裝的技能與 GitHub 上的最新版本，並在有任何過時的情況下更新全域集合。
npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=music-to-video
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（模板 / 基本元素 + 內容 + 錨點）；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）；警告是盡力而為。然後向使用者顯示逐個影格的摘要並迭代直到他們批准。在自動模式下，這是一個檢查點閘門：發布摘要作為通知並繼續（validate-plan.mjs 傳遞是一個品質閘門，並且仍然會阻塞）。
閘門： 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: <abs path>
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>/（自由）；staged 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：組裝
目標：將建置的影格 + 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 無法執行它）。check 在一個傳遞中執行結構 lint 和無頭瀏覽器運行時、佈局、動畫和對比度閘門；--snapshots 還會發出審查影格。
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
在 t=0、每個影格開始處、最強的 DROP / SURGE、每個 hard_stops[].t 以及最後一個影格處進行檢查。失敗時，自行進行成本最低的安全修復：編輯有問題的 compositions/frames/NN-*.html。永遠不要更改持續時間或音訊時間來隱藏同步問題。一旦閘門通過，暫停以進行使用者審查，然後僅在批准後進行渲染（自動模式：問一個保留的問題——「先預覽，還是渲染？」——然後提供帶有聯繫表的 MP4）：
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
閘門： check 已通過並檢查了快照；使用者已批准（自動模式：檢查已通過並且交付物包含聯繫表）；renders/video.mp4 存在，包含音訊，持續時間 == audiomap.audio.duration_sec。最終回覆說明 MP4 路徑和持續時間。
恢復表
| 您擁有 | 從哪裡繼續 |
|---|
--
...
[截斷以進行翻譯]