外掛安裝: 在執行設定或更新命令之前,當此技能位於 HyperFrames 外掛內時,請遵循外掛執行規則。獨立安裝則保留下面的更新說明。
首先,保持此技能更新——在執行前與使用者確認:
npx hyperframes skills update music-to-video。如果一切已是最新,則快速跳過;否則它會重新整理此技能及其依賴的核心領域技能,然後再使用。
音樂轉影片——一個以音樂為基礎、節拍同步的影片工作流程
使用此技能將音樂曲目轉換為節拍同步的 HyperFrames 影片。您需分析曲目一次,規劃影格,填寫每個影格的計劃,然後將每個影格建立為一個合成。輸入是音樂曲目加上使用者可選的圖片或影片——沒有旁白,也沒有網頁擷取。排版和模板是基礎(完整影片無需任何素材);使用者提供的任何媒體都會被剪輯到相同的節拍網格上。
您是編排者。在 videos/<project>/ 目錄下工作。按順序執行步驟,並在繼續之前通過每個關卡。兩個步驟需要使用者:步驟 3(計劃批准)和步驟 6(渲染批准)——這兩個都是檢查點關卡,詳見 ../hyperframes/references/brief-contract.md(在步驟 0 之前閱讀):在自主模式下,將步驟 3 的摘要張貼為預先通知,然後繼續;步驟 6 的渲染批准仍需詢問,作為保留的一個問題。除步驟 4 之外的所有步驟由您自行完成,步驟 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 § 提供者。生成的曲目會放置在 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、滾奏邊緣、無起始點的段落、大幅能量跳躍)將曲目切割成影格,並將每個邊界對齊到 audiomap 的錨點。對於每個影格,設定 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 色塊的調色板)。 - 填寫每個影格。 決定其群組,並為每個群組指定處理方式:一個來自信錄的匹配模板(帶有綁定的參數和真實的 audiomap 錨點)、一個來自原語目錄的自由組合、或一個遵循
pacing的素材處理。在您自由組合一個命名外觀之前,先在線上位目錄中搜尋它:對於使用者要求的所有外觀、效果、處理或轉場——「CRT 掃描線」、「故障」、「底片顆粒」、「閃光掃掠」——執行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
您的區塊: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]),以 0 毫秒切換來控制其群組,並寫入一個安全的影格檔案。worker 從不執行 hyperframes CLI——這些命令作用於已組裝的專案,而該專案尚不存在,因此它們會報告錯誤的檔案。worker 僅按照合約寫入檔案並停止;您將在組裝後(步驟 6)進行驗證。當每個 worker 返回時,您可以確認其檔案已存在於磁碟上。
關卡: 每個影格都有其 compositions/frames/NN-*.html 存在於磁碟上。
步驟 5:組裝
目標:將構建的影格 + 背景音樂連接成可播放的 index.html。
assemble-index.mjs 是確定性的——無需子代理,無需判斷。它按其累積的 data-start 引用每個影格檔案,在音軌 11 上掛載 assets/bgm.mp3,並進行硬切影格→影格(影格連續覆蓋曲目,無空隙,因此沒有轉場注入器)。
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 會對…
…(內容因截斷而省略)