media-use:在取得音訊/圖片前,請呼叫
/media-use從 HeyGen 目錄中解析 BGM/SFX/圖片。先執行--adopt以註冊現有資產。詳見/media-use技能。
產品發布到 HyperFrames
使用此技能來了解產品、理解其品牌、規劃發布影片,並在 HyperFrames 中逐影格建立影片。
在步驟 0 之前確認路線。 您是協調者。執行每個步驟,驗證其檢查點,然後才繼續下一步。此技能適用於正在被行銷、發布、推廣或揭露的產品,包括如「為我們的網站製作宣傳影片」等請求,但前提是目的為宣傳。將其他意圖導向別處:一般的非發布網站導覽 ->
/website-to-video;不含產品的專題解說 ->/faceless-explainer;GitHub PR ->/pr-to-video;為現有影片加上字幕 ->/embedded-captions;簡短無旁白動態圖形 ->/motion-graphics。如果使用者只說「製作影片」或路線不確定,請先閱讀/hyperframes。
您是協調者。在 videos/<project>/ 中工作。依序執行步驟,並在繼續前通過每個檢查點。需要使用者批准的步驟為步驟 0、步驟 3 和步驟 6。除了步驟 5(您為每個影格派發一個子代理程式)外,所有步驟均由您親自完成。請勿在此處放置設計或動態規則;這些規則存在於影格工作者子代理程式、此技能的本地 ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ 以及 hyperframes-creative 中。
工作流程:步驟 0 設定 -> hyperframes.json;步驟 1 擷取 -> capture/;步驟 2 設計系統 -> frame.md;步驟 3 故事板/腳本 -> STORYBOARD.md 和 SCRIPT.md;步驟 3.1 音訊 -> audio_meta.json;步驟 4 視覺設計 -> 豐富的 STORYBOARD.md;步驟 5 影格 -> compositions/frames/NN-*.html 和 index.html;步驟 6 最終渲染 -> renders/video.mp4。
步驟 0:設定與簡報
目標:鎖定核心影片簡報,並在需要時建立 HyperFrames 專案。
僅在缺少 hyperframes.json 時初始化。根據品牌或網域以 kebab-case 命名 <project>,例如 acme-promo;切勿使用工作區名稱或時間戳。
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init 會檢查已安裝的技能與 GitHub 上的最新版本,若任何技能過時則更新全域技能集。
在簡報前顯示登入狀態 — 執行 npx hyperframes auth status 並逐字轉述其輸出(不要改寫或重新編寫)。 它會報告語音/BGM 將使用 HeyGen 或本地引擎,以及未登入時的登入方式。如果未登入,請停止並等待使用者選擇——登入,或說「go」/「offline」以使用本地引擎繼續——然後再詢問簡報或其他事項。 將其視為一個真實的決策點,而非隨口一提;不要將選擇摺疊進簡報問題中,也不要將金鑰寫入每個儲存庫的 .env 中。(在自主模式下,記錄狀態並以離線模式繼續。)參見 ../hyperframes-media → Preflight 以取得標準指引。
檢查點: hyperframes.json 存在,且角度、長度、長寬比和語言已鎖定;已顯示登入狀態(已登入,或繼續離線模式)。
步驟 1:擷取素材
目標:收集影片所需的原始素材、品牌訊號和可用資產。
分類輸入並選擇路徑。明確的網址 -> 擷取它,並使用該網站進行旁白和素材。貼上的腳本/簡報 -> 逐字儲存為 user_script.txt,詢問一次「照原樣使用或重新架構?」,將答案儲存為 VO_MODE,然後解析擷取目標:文字中的網址 -> 使用它;僅有品牌名稱 -> WebSearch,在一行中確認網址,然後爬取;無網址/網站 -> 無擷取路徑。
使用以下指令執行擷取:npx hyperframes capture "<URL>" -o ./capture
如果存在 GEMINI_API_KEY、GOOGLE_API_KEY 或 OpenRouter 金鑰,擷取會自動將素材加上標題,放入 capture/extracted/asset-descriptions.md。這不是審查檢查點。沒有視覺金鑰時,使用 DOM 上下文並繼續。
無擷取路徑:手動建立 capture/extracted/tokens.json、capture/extracted/visible-text.txt、capture/extracted/asset-descriptions.md 和 capture/assets/。tokens.json 應為 { "title": "", "description": "", "colors": [], "fonts": [] };盡可能從簡報填入標題/描述。visible-text.txt 包含完整的簡報或腳本。asset-descriptions.md 應說明未擷取任何資產,除非使用者提供了資產說明。
檢查點: capture/extracted/tokens.json、capture/extracted/visible-text.txt、capture/extracted/asset-descriptions.md 和 capture/assets/ 存在;您可以用一句清晰的句子說明該品牌。將 asset-descriptions.md 視為主要資產清單。如果在實際擷取後它遺失了,請停止並報告擷取不完整。如果存在 capture/BLOCKED.md,請遵循它。
步驟 2:設計系統
目標:選擇一個已提供的影格預設;一個腳本會將其轉換為此影片的 frame.md + 字幕皮膚。
您需要做出一個判斷——選擇哪個預設。閱讀 ../hyperframes-creative/references/design-spec.md 並選擇外觀最符合品牌和簡報的預設。然後執行:
node <SKILL_DIR>/scripts/build-frame.mjs --preset <name> --hyperframes .
腳本會確定性地完成其餘工作:將預設的 FRAME.md 複製為 frame.md 並重新混合到 capture/extracted/tokens.json 中的品牌代幣上(品牌顏色依角色——墨水、畫布、強調色——映射到預設的顏色鍵上,保留鍵/結構/元件;以品牌的顯示+正文字型取代預設的),將預設的字幕皮膚複製到 .hyperframes/caption-skin.html,並自我驗證(映射錯誤時退出碼為 1)。當它退出碼為 0 時,立即進行下一步——不要手動編輯規格。
tokens.json 中沒有品牌顏色/字型(例如無擷取)時 -> 腳本會保留預設自己的調色盤,這是一個完整的可出貨設計。如果簡報提到了擷取遺漏的品牌顏色/字型,請在執行前將它們加入 capture/extracted/tokens.json(或使用使用者的 design.md 來填入);之後只有在映射確實需要時才手動調整 frame.md。
檢查點: build-frame.mjs 退出碼為 0 —— frame.md 來自命名的預設,並且(當預設提供時).hyperframes/caption-skin.html 作為字幕皮膚來源存在。
步驟 3:故事板與腳本
目標:將簡報和擷取的素材轉換為已批准的逐影格故事計劃。
閱讀 references/story-design.md、../hyperframes-animation/blueprints-index.md、../hyperframes-core/references/storyboard-format.md 和 ../hyperframes-core/references/script-format.md。使用它們來撰寫 STORYBOARD.md,並在需要旁白時撰寫 SCRIPT.md。
使用 story-design.md 作為故事藍圖、鉤子、說服邏輯、節拍、VO_MODE 和資產選擇。作為軟性指引,參考 ../hyperframes-animation/blueprints-index.md 中的角色→藍圖選單:對於每個節拍,如果某個藍圖 ID 合適,請記下一個候選藍圖 ID。故事的真實性仍然決定哪些節拍存在——永遠不要強迫節拍去符合藍圖,也永遠不要僅僅因為有可用的既定形狀而發明節拍。從 capture/extracted/asset-descriptions.md(標準清單)中選擇每個視覺影格的 asset_candidates——不要瀏覽原始的 capture/assets/。除非該清單遺失或無法使用,否則不要要求使用者選擇資產。使用故事板和腳本參考中的確切必填欄位。
草擬完成後,顯示逐影格摘要。在同一則訊息中詢問使用者兩件事:(a) 批准或要求修改,以及 (b) 是否想要故事板框架的即時預覽(npx hyperframes preview)——只有在得到肯定答覆時才開啟它。反覆進行直到獲得批准,並將預覽選擇帶到步驟 6。
檢查點: STORYBOARD.md 存在,每個視覺影格都有 asset_candidates,在需要旁白時 SCRIPT.md 存在,且使用者已批准逐影格計劃。
步驟 3.1:音訊
目標:從已批准的腳本生成旁白、單字時間、音樂和音訊元資料。
在步驟 3 批准後開始音訊處理。在背景執行它,然後繼續進行步驟 4。
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
音訊腳本處理旁白、單字時間、從 HeyGen 音樂庫查詢 BGM 以及時間元資料。BGM 情緒來自故事板的 music: 欄位。這使用 HeyGen 音訊 API 進行檢索,而非生成,並使用與 TTS 相同的 ~/.heygen 憑證。有關提供者詳細資訊,請閱讀 ../hyperframes-media/references/tts.md。
如果沒有旁白且沒有 SCRIPT.md,則跳過語音生成。如果故事板有音樂情緒,BGM 仍可能執行。
檢查點: 音訊任務已開始,或專案標記為無聲。
步驟 4:影格視覺設計
目標:為每個故事板影格添加視覺方向、版面意圖和動態選擇。
就地編輯 STORYBOARD.md。不要建立另一個故事板。使用 frame.md 作為顏色、字體、版面感覺和風格的真相來源。
閱讀 references/visual-design.md、../hyperframes-animation/blueprints-index.md、references/motion-language.md 和 ../hyperframes-animation/rules-index.md。使用 visual-design.md 來獲得方法(時間編碼鏡頭序列、內嵌的 Layout 詞彙以及必備的 ## Video direction 區塊)。使用 ../hyperframes-animation/blueprints-index.md 來選擇每個影格的鏡頭形狀。使用 motion-language.md(動態詞彙 + 動態原則)和 ../hyperframes-animation/rules-index.md(有效的規則名稱)來處理動態——不要發明動態名稱。
對於每個視覺影格,根據 visual-design.md 的方法在 STORYBOARD.md 中撰寫一個時間編碼鏡頭序列:選擇影格的藍圖(或自行組合),用此產品的內容實例化它,並根據旁白調整每個場景的揭示節奏,使影格在其整個持續時間內發展,而不是在前面加載然後靜止。根據場景內嵌陳述版面配置和動態(詞彙在 visual-design.md 和 motion-language.md 中)。添加一個涵蓋整個影片的 ## Video direction 區塊。
請勿更改故事、腳本、資產選擇、asset_candidates、transition_in 或擷取的原始素材。請勿在此步驟中撰寫 HTML。
在視覺設計鎖定後,暫存命名的資產:
node <SKILL_DIR>/scripts/stage-assets.mjs --storyboard ./STORYBOARD.md --hyperframes .
檢查點: 每個視覺影格都有一個時間編碼鏡頭序列,其揭示節奏與旁白同步(無前置加載);存在 ## Video direction;assets/ 包含命名的資產。
步驟 5:建立影格
目標:將每個故事板影格建立為 HTML 組合,並組裝可播放的影片。
如果音訊已開始,請等待步驟 3.1 的音訊完成。然後同步持續時間並擷取 SFX;如果專案為無聲,則跳過這兩項。
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
持續時間同步是機械性的:真實的語音持續時間優先;無聲影格保留估計值;切勿手動編輯同步後的持續時間。
在派發之前,閱讀 sub-agents/frame-worker.md 和 ../hyperframes-core/references/subagent-dispatch.md。為每個影格派發一個子代理程式,如果可能則並行處理;否則以批次方式執行工作者。每個工作者只處理一個影格。
每個工作者的上下文必須包含 PROJECT_DIR、frame_id、畫布大小、字幕狀態和啟用字幕時的保留區帶,以及 RULES_DIR,其為此技能 ../hyperframes-animation/rules/ 的絕對路徑。每個工作者讀取 frame.md、來自 STORYBOARD.md 的其專屬 ## Frame N 區塊、每個引用動態的本地規則配方(../hyperframes-animation/rules/<id>.md)以及影格的藍圖範本(../hyperframes-animation/blueprints/<id>.md)。每個工作者只寫入 compositions/frames/NN-*.html。工作者絕不能編輯 STORYBOARD.md。
當每個工作者返回時,協調者在 STORYBOARD.md 中將該影格標記為 animated。
在音訊時間存在後,在背景建立字幕並組裝索引:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs 使用專案的 .hyperframes/caption-skin.html(在步驟 2 中複製)作為字幕外觀,從 frame.md 注入品牌代幣;如果沒有皮膚,則渲染內建的預設藥丸形狀。captions: skipped (<reason>) 是有效的。當明確跳過時,繼續進行而不使用字幕。
檢查點: 每個影格都標記為 animated、index.html 存在,且字幕已建立或明確跳過。
步驟 6:完成
目標:驗證組裝後的影片,取得使用者批准,並渲染最終的 MP4。
注入轉場,執行檢查,暫停以進行審查,然後渲染。
node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .
node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html
npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
npx hyperframes snapshot --at <frame-midpoints>
snapshot 將擷取的影格拼接成一張連絡表(snapshots/contact-sheet.jpg)。快速瀏覽一下;如果沒有明顯問題,就繼續——不要在此停留。
如果某個指令失敗,請顯示 stderr 並停止——不要堆疊恢復指令。自行修復:對 compositions/frames/NN-*.html 進行最安全的編輯,然後重新執行失敗的檢查。
檢查通過後,暫停以進行使用者審查。影片已組裝完成,可在 Studio 中檢視和編輯。僅在步驟 3 和步驟 6 各管理一次預覽:如果使用者先前要求過則開啟,如果先前拒絕則提供,如果他們已在 Studio 中審查則不要再詢問。
預覽:npx hyperframes preview
渲染