外掛安裝： 在執行設定或更新命令之前，當此技能位於 HyperFrames 外掛內部時，請遵循外掛執行規則。獨立安裝則保留下面的更新說明。
首先，保持此技能最新——請在使用前與用戶確認是否執行：
npx hyperframes skills update music-to-video。如果一切已是最新，則該命令會快速執行且無實際操作；否則它會刷新此技能及其依賴的核心領域技能。
music-to-video — 一個以音樂為基礎、節拍同步的影片工作流程
使用此技能將音樂曲目轉換為節拍同步的 HyperFrames 影片。您將分析曲目一次，規劃畫格，填寫每個畫格的計畫，並將每個畫格建立為一個合成畫面。輸入是一個音樂曲目以及用戶可選的圖片或影片——沒有旁白和網站擷取。版式和模板是基礎（一個完整的影片不需要任何素材）；用戶提供的任何媒體都將被剪輯到相同的節拍網格上。
您是編排者。在 videos/<project>/ 目錄中工作。按順序執行步驟，並在繼續之前通過每個關卡。有兩個步驟需要用戶參與：步驟 3（計畫核准）和步驟 6（渲染核准）——兩者都是每個 ../hyperframes/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 中選擇。初始化後立即編寫 BRIEF.md（絕不在之前——init 拒絕非空目錄），並記錄基於偏好的答案（brief-format.md）。編輯請求跳過所有這些。
音樂是主幹——在任何事情之前先確定一個曲目。此技能專為快速、高能量的背景音樂而調整：強大的節拍網格驅動剪輯（平靜的曲目也可以，但應根據樂句而不是節拍來安排節奏）。如果用戶提供了音訊——一個音樂檔案，或一個要從中提取音訊的影片——請使用它。否則，從請求中選擇情緒，並通過 /media-use（references/bgm.md）生成一個曲目。在執行第一個經過身份驗證的提供者操作之前，請執行 npx hyperframes auth status 並逐字轉發其輸出。如果未登入，則套用一個分支：
- 協作模式： 等待登入或明確選擇使用本地提供者繼續離線操作。
- 自主模式： 陳述狀態並通過可用的本地提供者繼續操作。
如果沒有離線提供者能夠滿足所需的音樂功能，則顯示阻礙因素。切勿將金鑰寫入每個儲存庫的 .env。身份驗證所有權和離線後備方案位於 /media-use references/setup-providers.md § 提供者。生成的曲目標準降落在 assets/bgm.mp3。暫存提供的圖片或影片，以便畫格可以在節拍網格上使用它們；否則版式將承載影片。
歌詞影片： 對於與人聲同步的歌詞，請通過 /media-use 轉錄曲目以獲取單詞/行時間，或者要求用戶提供歌詞文字，並將歌詞行放置在節拍網格上。
僅在 hyperframes.json 缺失時才進行初始化。根據簡報以烤肉串命名法命名 <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 存在；記錄了方向/長度/幀率以及（如果有的話）素材清單。
步驟 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 將與模板匹配的純音樂情況）。僅在此分類和佈局：將每個畫格的 ### 群組 保留為 TBD（步驟 3），並將 frontmatter style 留空——沒有模板、文案、顏色或字體。預計約 1–6 個畫格。
關卡： 畫格拼貼了整個曲目（第一個從 0 開始，最後一個在 duration_s 結束）；每個畫格帶有 span_sec + pacing + mood + feel；每個 ### 群組 都是 TBD；任何地方都沒有內容。
步驟 3：填寫計畫（用戶門控）
目標：將骨架轉變為一個已核准的、完整的 STORYBOARD.md。
閱讀 references/planning.md、storyboard-format.md、template-catalog.md、motion-primitive-catalog.md 和 montage.md（僅當用戶提供了素材時）。就地編輯同一個檔案，執行兩件事：
- 選擇品牌。 使用
../hyperframes-creative/references/design-spec.md中的表格，從../hyperframes-creative/frame-presets/中選擇一個預設（匹配曲目的情緒；只有其字體和顏色重要——模板擁有構圖）。將它未經修改地複製到frame.md中，並從其中填充 frontmatterstyle（字體 + 一個 ≤4–6 色樣的調色盤）。 - 填充每個畫格。 決定其群組，並為每個群組賦予一種處理方式：一個來自目錄的匹配模板（帶有綁定的參數和真實的音訊地圖錨點），一個來自基元目錄的自由創作，或者一個服從
pacing的素材處理方式。在為一個命名的外觀進行自由創作之前，先搜尋即時目錄：對於用戶要求的每個外觀、效果、處理方式或轉場——"CRT 掃描線"、"故障"、"影片顆粒感"、"流光掃過"——執行npx hyperframes catalog --query "<該外觀，用簡單英文描述>" --json並閱讀最上面的結果。template-catalog.md和motion-primitive-catalog.md僅列出此技能自己的本地材料；搜尋會對整個託管註冊表（約 400 個區塊和元件）進行排名，並且不需要安裝任何東西——不需要專案、不需要事先add、不需要帳戶。僅在搜尋後沒有找到任何合適的外觀時，才對該外觀進行自由創作。寫入文案。您擁有 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）；警告為盡力而為。然後，在聊天中將逐畫格摘要作為提案呈現（../hyperframes/references/review-loop.md § 1），並根據用戶的回覆進行迭代，直到他們核准；對於 storyboard: yes，也將其編寫為 storyboard.html（../hyperframes-creative/references/storyboard-recipe.md § 3）供他們開啟。在自主模式下，這是一個檢查點關卡：將摘要作為提示發布並繼續（validate-plan.mjs 通過是一個品質關卡，仍然會阻止）。
關卡： frame.md 是逐字複製的預設；validate-plan.mjs 以狀態碼 0 退出；用戶核准了計畫（自主模式：摘要已被作為提示發布）。
步驟 4：根據計畫建立畫格
目標：將每個畫格建立為一個自包含的合成檔案。
建立 compositions/frames/。閱讀 sub-agents/frame-worker.md 和 ../hyperframes/references/subagent-dispatch.md。為每個畫格分派一個 frame-worker，在可能的情況下並行執行（否則分批執行）。每個 worker 獲得一個畫格以及此上下文：
PROJECT_DIR: <絕對路徑>
frame_id: <NN-frame_id> # = 畫格檔案的主體，例如 02-f2；合成 ID
您的區塊：PROJECT_DIR/STORYBOARD.md 中的 `## 畫格 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：組裝
目標：將已建立的畫格 + 背景音樂連接成可播放的 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 以及無頭瀏覽器運行時、佈局、運動…
…
[為翻譯而截斷]