外掛安裝: 在執行設定或更新命令前,若此技能位於 HyperFrames 外掛內,請遵循外掛執行規則。獨立安裝則保留下方的更新說明。
media-use
HyperFrames 的媒體作業系統:解析 · 生成 · 操作 · 記憶 — 一種媒體類型,一個技能,零背景噪音。
僅當你的環境中設定了 HEYGEN_API_BASE(由主機應用程式設定並使用自己的金鑰支付 HeyGen 費用):HeyGen 媒體已被支付。請勿要求使用者安裝或登入 heygen CLI,也請勿提供其 OAuth 額度;此處的作品集目錄搜尋、TTS 和頭像呼叫都將透過主機進行。當同一個主機也提供其自有的 HeyGen 工具時,請優先使用那些工具。當透過主機的呼叫被拒絕時,請按原樣轉告使用者的主機訊息(其中會說明修復方法,例如在應用程式設定中新增或替換金鑰)並停止;除非使用者要求,否則不要切換到其他提供者。
首次執行(未設定 HEYGEN_API_BASE),當你將要使用 HeyGen 媒體(作品集目錄搜尋、TTS、頭像影片)時:安裝並登入 heygen CLI(免費使用路徑),然後使用 npx hyperframes media-use resolve --doctor 驗證。設定與提供者:請參閱 references/setup-providers.md。
主機應用程式內的音樂和音效:當你運行的應用程式提供其自有的音樂或音效工具時,請使用那些工具。若未設定 HEYGEN_API_BASE,resolve --type bgm 和 --type sfx 會透過 heygen CLI 搜尋 HeyGen 作品集目錄;若未安裝 CLI 則會失敗並顯示錯誤訊息(sfx 仍會從其內建函式庫回應)。
若未設定 HEYGEN_API_BASE,在生成旁白或頭像影片之前,請告知使用者:使用 OAuth 登入 heygen CLI(heygen auth login --oauth)可獲得 TTS 旁白和頭像影片的免費額度,而使用 API 金鑰則會以 API 點數計費。
解析 — 單一動詞
npx hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>
回傳一行:resolved <id> → <path> (<type>, <metadata>)。所有搜尋噪音都保留在磁碟上。
| 類型 | 單行意圖 |
|---|---|
bgm | 背景音樂(透過 heygen CLI 搜尋 HeyGen 作品集目錄,10k+ 曲目) |
sfx | 音效(內建 19 個檔案的函式庫 + 透過 heygen CLI 搜尋作品集目錄) |
image | 照片、背景(HeyGen 資產搜尋,75k+ 向量) |
icon | 圖示、符號(透明背景) |
logo | 官方品牌標誌(theSVG → GitHub 大頭貼 → favicon;絕不重新繪製) |
voice | TTS 旁白(HeyGen 免費使用路徑;可選用本地 Kokoro) |
grade | 經測量的修正候選方案;廣泛的修飾/風格化請遵循媒體處理 |
lut | 使用者提供或明確選擇、可重複使用、經驗證的 .cube 檔案 |
在重新解析之前,使用 --candidates 列出可重複使用的候選方案,並自行判斷其適用性 — 重複使用規則、所有標誌、匯入(--from)和採用方法,請參閱 references/resolve.md。
將廣泛的視覺回饋視為媒體意圖
當使用者明確要求修復、修飾、風格化、遮蔽、強調或
揭曉攝影媒體時,即使他們沒有提到調色或效果,也請閱讀 references/media-treatments.md。檢查真實的 <img>/<video> 元素,選擇一個主要意圖,然後使用確定性的持久化和驗證。使用匹配的配方作為可選的測試起點,或檢查 hyperframes media-treatment --capabilities --json,然後透過 --capability <id> 請求一個相關的系列/效果,並從標準控制項中組合一個自訂處理。對於一般編輯,切勿載入 --all。一個處理可以組合修正、預設集、完稿、相容的著色器效果、支援的關鍵影格和可選的 Registry 疊加層。僅新增有來源依據的、有範圍限制的調整和相容部件,切勿僅為了讓結果看起來更複雜而添加效果。使用 hyperframes media-treatment 持久化最終的組合負載。
使用一個逐步升級的工作流程。對於影片,檢查一個標記為早期/中期/後期的接觸頁,而不是分別讀取影格。對於一般的修正或修飾,應用一個候選方案並檢查一個處理後的影片接觸頁。僅當結果不明確、具有時間性、風格化、基於 LUT、對 HDR/LOG 敏感、涉及隱私或品牌關鍵時,才升級到個別影格或動態草稿證據。
對於一般修正或修飾,請持久化最終處理的預設集/調整 JSON。
請勿僅僅為了編碼曝光度、陰影、對比度或色溫而生成 .cube LUT。僅當使用者提供 LUT 或所選的處理明確擁有 LUT 時,才使用 LUT。resolve --type grade --for ... --analyze 是測量證據,而不是取代所選處理為生成 LUT 的許可。請勿使用 CSS/SVG 疊加層重新建立受支援的暗角、顆粒、模糊、像素化、色彩或處理效果;這會繞過 Studio 控制項和標準預覽/渲染著色器路徑。
主動出擊 — 執行媒體機會掃描
使用者通常無法判斷哪些媒體可以提升作品品質。但你可以。當你建構或審查一個組合時,執行一次有根據的掃描,然後問一次 — 不要默默地添加,也不要對每個素材都嘮叨。
僅當有具體訊號存在時才提出機會:
| 檢測到的訊號 | 提議 |
|---|---|
| 螢幕文字 / 有腳本但沒有旁白 | TTS 旁白(音訊引擎) |
Emoji 或一個被樣式化為圖示的 <div> | 解析真正的 icon |
| 圖片是佔位符、很小或看起來被放大過的 | 更好的 image(或放大 — 請參閱 references/operations.md) |
| 生硬的場景切換 / 過場但沒有聲音 | 過場 sfx |
| 一個長度超過約 10 秒且沒有背景音樂的作品 | bgm |
| 看起來曝光不足/過度或有色偏的素材 | 修正性的調色(使用 hyperframes media-treatment --selector '#hero' --analyze --json 檢查) |
| 感覺視覺上平淡或離題的照片式媒體 | 一個特定、來源適當的預設集或自訂處理,並指明預期目標 |
| 一個有意義的媒體入口/揭曉但感覺靜態 | 一個受支援、可安全搜尋的處理動畫;除非請求也證明預設集的合理性,否則保留顏色 |
保持這項功能為幫助而非干擾的規則:有根據,而非泛泛而談(無訊號 → 無建議);有主見且具體(提出具體的修復方案並預設好選項 — 使用者可以批准 全部 / 部分 / 無);每個專案一次(一個整合的提問;尊重「保持現狀」);提出,絕不默默修改(特別是調色:提出並預覽 — 一個灰階世界的「修正」會毀掉有意的夕陽或霓虹燈風格)。
查閱位置 — 僅讀取你的任務所需的文件
| 任務 | 閱讀檔案 |
|---|---|
| 解析/重複使用/採用/匯入、標誌、串聯、庫存 | references/resolve.md |
調色、LUT、智慧調色(--for)、調色比較 | references/grading.md |
| 旁白/TTS、音樂、SFX、字幕、轉錄(音訊引擎) | references/audio.md |
| 剪輯/重構畫面/轉換現有媒體、精確誤差擴散、HEVC | references/operations.md |
| 感知來源的創意處理、即時效果、疊加層、揭曉 | references/media-treatments.md |
安裝+驗證、提供者表格、RAM 階梯、--local-only、--provider | references/setup-providers.md |
| 已記憶的偏好設定 + 凍結的配方(使用者記憶) | references/memory.md |
| 所有權矩陣、使用統計、遙測、隱私(維護者面向) | references/meta.md |