提醒:先讓此技能保持最新狀態 — 在使用前與用戶確認是否執行:
npx hyperframes skills update music-to-video。如果一切已是最新,則此操作快速且無作用;否則它會更新此技能及其依賴的核心領域技能。
music-to-video — 一個由音樂驅動、節拍同步的影片工作流程
使用此技能將音樂曲目轉換為節拍同步的 HyperFrames 影片。您只需分析一次曲目,規劃影格,填寫每個影格的計劃,然後將每個影格建立為一個合成。輸入是一首音樂曲目,以及可選的用戶圖片或影片——沒有旁白,也沒有網站截取。文字排版和模板是基礎(一個完整的影片不需要任何素材);用戶提供的任何媒體都會被剪輯到相同的節拍網格上。
您是協調者。在 videos/<project>/ 目錄下工作。按順序執行步驟,並在繼續之前通過每個關卡。有兩個步驟需要用戶參與:步驟 3(計劃批准)和步驟 6(渲染批准)——這兩個都是依據 ../hyperframes/references/brief-contract.md(請在步驟 0 之前閱讀)設定的檢查點:在自主模式下,將步驟 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,由一個 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(audio/references/bgm.md)生成曲目;當主機應用程式提供其自己的音樂工具時,請使用該工具。在執行第一個經過驗證的提供者操作之前,請執行 npx hyperframes auth status 並如實轉發其輸出。如果已登出,請應用以下分支之一:
- 協作模式: 等待登入或明確選擇以離線方式繼續使用本地提供者。
- 自主模式: 說明狀態並通過可用的本地提供者繼續。
如果沒有離線提供者能滿足所需的音樂功能,則提出阻礙。切勿將金鑰寫入每個儲存庫的 .env。驗證擁有權和離線備援方案位於 /media-use 的 references/setup-providers.md § Providers 中。生成的曲目放置在 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,並從其中填充 frontmatter 的style(字體 + 一個 ≤4–6 色調色板)。 - 填充每個影格。 決定其組別,並為每個組別指定一種處理方式:從目錄中匹配的模板(帶有綁定參數和真實的音訊映射錨點)、從基元目錄中自由創作,或遵循
pacing的素材處理。在您自由創作一個命名的外觀之前,先在實時目錄中搜尋它:對於用戶要求的每個外觀、效果、處理或過渡——"CRT scanlines"、"glitch"、"film grain"、"shimmer sweep"——執行npx hyperframes catalog --query "<the look, in plain English>" --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: <abs path>
frame_id: <NN-frame_id> # = 影格檔案主文件名,例如 02-f2;合成 ID
Your block: the `## Frame N — <frame_id>` block in PROJECT_DIR/STORYBOARD.md
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materials: for each group, <SKILL_DIR>/references/templates/<id>/index.html (templates) and
<SKILL_DIR>/references/motion-primitives/<id>/ (free); staged assets/ (asset groups)
Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas: <w>×<h> Pacing: <beat_cut|phrase_flow>
Write to: PROJECT_DIR/compositions/frames/<frame_id>.html
Worker 會複製引用的素材,將每個錨點轉換為影格本地秒數(local_t = track_t − span_sec[0]),使用 0 毫秒剪輯來門控其組別,並寫入一個可安全定位的影格檔案。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——這才是正確的動作點(index.html 和 compositions 已在 v5/<project>/ 下)。渲染器讀取該目錄,運行一個無頭瀏覽器來演奏每個影格,並將它們合成為一個 MP4 檔案。
cd "$PROJECT_DIR" && npx hyperframes render --output "renders/video.mp4"
關卡(用戶門控): renders/video.mp4 存在;用戶已在聊天中批准渲染(自主模式:渲染是完成狀態,您無需向用戶展示——只需報告已完成即可)。