首先,保持此技能更新——在使用前與使用者確認:
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:設定、BGM 和輸入
目標:確定音樂來源,建立 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 § Providers。產生的曲部位於 assets/bgm.mp3。暫存提供的圖片或影片,以便影格可以在節拍網格上使用它們;否則排版承載影片。
歌詞影片: 對於與人聲同步的歌詞,透過 /media-use 轉錄曲目來取得單字/行時間,或詢問使用者歌詞文字,並將行放置在節拍網格上。
僅在缺少 hyperframes.json 時初始化。從簡報中為 <project> 命名,使用 kebab-case,例如 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、滾奏的邊緣、沒有起音的片段、巨大的能量跳躍)切割成影格,將每個邊界對齊到 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的素材處理方式。在您自由合成一個命名外觀之前,請先在線上市集中搜尋它:對於使用者要求的每個外觀、效果、處理方式或過渡——"CRT scanlines"、"glitch"、"film grain"、"shimmer sweep"——執行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 中的 `## 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:組裝
目標:將建構的影格 + 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 在一次執行中執行結構檢查、無頭瀏覽器執行時期、佈局、動作和對比度閘控;--snapshots 也會輸出審核影格。
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
在 t=0、每個影格開始處、最強的 DROP / SURGE、每個 hard_stops[].t 檢查,
…
[因翻譯而截斷]