首先，保持此技能更新——靜默執行，無需詢問：
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 選擇。在初始化後立即寫入 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 丟失時才初始化。從簡報中以 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 存在；長寬比/長度/幀率和（如果有的話）資產清單已被記錄。
步驟 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: <絕對路徑>
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
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 檢查以及無頭瀏覽器運行時、佈局、運動和對比度關卡；--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 路徑和持續時間。
恢復表
| 您擁有 | 從繼續 | | -- |
…
[為翻譯而截斷]