HyperFrames Registry
此 Registry 提供可複用的區塊與元件,可透過 hyperframes add <名稱> 安裝。
- 區塊 (Blocks) — 獨立的子合成(擁有自己的尺寸、持續時間、時間軸)。在主合成中透過
data-composition-src引入。 - 元件 (Components) — 效果片段(無獨立尺寸)。直接貼入主合成的 HTML 中。
快速參考
hyperframes add data-chart # 安裝一個區塊
hyperframes add grain-overlay # 安裝一個元件
hyperframes add captions # 安裝所有標記為 captions 的區塊
hyperframes add shimmer-sweep --dir . # 指定目標專案
hyperframes add data-chart --json # 機器可讀輸出
hyperframes add data-chart --no-clipboard # 跳過剪貼簿(適用於 CI/無頭模式)
安裝完成後,CLI 會顯示寫入了哪些檔案,以及可供貼入主合成的程式碼片段。該片段是起點——在配線區塊時,你需要自行加入 data-composition-id(必須與區塊內部的合成 ID 相符)、data-start 和 data-track-index 屬性。
位置參數會先被解析為精確的項目名稱。如果沒有相符的項目,該值會被視為標籤,並安裝所有帶有該標籤的區塊。Registry 相依項目會在請求的項目之前先行安裝。hyperframes add 僅適用於區塊與元件;若要安裝範例,請使用 hyperframes init <目錄> --example <名稱>。
安裝位置
區塊預設安裝至 compositions/<名稱>.html。元件預設安裝至 compositions/components/<名稱>.html。
這些路徑可在 hyperframes.json 中設定:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
詳細資訊請參閱 install-locations.md。
配線區塊
區塊是獨立的合成——在主 index.html 中透過 data-composition-src 引入:
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
關鍵屬性:
data-composition-src— 區塊 HTML 檔案的路徑data-composition-id— 必須與區塊內部的 ID 相符data-start— 區塊在主時間軸中出現的時間(秒)data-duration— 區塊播放的持續時間data-width/data-height— 區塊畫布尺寸data-track-index— 圖層順序(數值越高越靠前)
詳細資訊請參閱 wiring-blocks.md。
配線元件
元件是片段——將它們的 HTML 貼入合成標記、CSS 貼入樣式區塊、JS 貼入腳本區塊(如果有的話):
- 讀取安裝的檔案(例如
compositions/components/grain-overlay.html) - 將 HTML 元素複製到合成的
<div data-composition-id="...">中 - 將
<style>區塊複製到合成的樣式中 - 將任何
<script>內容複製到合成的腳本中(在時間軸程式碼之前) - 如果元件提供了 GSAP 時間軸整合(請參閱片段中的註解區塊),將這些呼叫加入時間軸
詳細資訊請參閱 wiring-components.md。
探索
將 CLI 當作主要的探索介面。先以意圖搜尋,再瀏覽: Registry 中的項目數量遠超過肉眼可掃描的範圍,因此僅列出並比對名稱或標籤是慢速方法,且當作者的用詞與你的用詞不同時就會失敗。
# 將整個目錄與效果的目標進行排序
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
搜尋為本地端執行,不會傳送任何資料。預設情況下,它會根據與項目名稱、標題和描述共享的詞彙進行排序,因此只會找到包含你的詞彙的項目;--on-device 則根據語意排序(需一次性下載模型)。使用 --json 時,信封會標明回答的是哪個層級,因此請檢查這個標記,而不是假設已進行排序。
無論影片使用何種語言,請一律使用英文查詢。 目錄是以英文撰寫,兩個層級都以此進行索引(on-device 模型也只支援英文)。使用其他語言的查詢不會產生任何可搜尋的詞彙,而且不會傳回任何結果。在日文或中文專案中,由於簡報、字幕和旁白都是該語言,而查詢自然會順應使用該語言,因此很容易出錯:請用英文描述 動作,然後再以影片所需的語言撰寫畫面上的文字。如果查詢結果顯示 No searchable words in query,這就是這個規則所致,而不是缺少元件,因此不值得撰寫缺口報告。
可安裝性是在排序之後才套用,而不是之前:向量攜帶但此 Registry 無法提供的名稱會從結果中移除,並計入 dropped,因此非零的 dropped 表示兩者屬於不同世代。請參閱 /hyperframes-cli 了解離線層級、同意授權機制,以及如何重新整理過期的索引。
如果希望瀏覽或篩選而非搜尋:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
一般表格模式和 --json 模式只會列出相符的項目;使用 hyperframes add <名稱> 安裝選中的項目。--human-friendly 會開啟互動式選取器並立即安裝選中的項目。在 CI 或代理工作流程中,建議優先使用 --json 後再執行明確的 add。
回報目錄中缺少的內容
當搜尋結果中沒有任何項目符合需求時,請在自行手動製作效果之前先回報:
npx hyperframes feedback --search-miss "<你執行的查詢>" --wanted "<你需要的效果>" --tier on-device
catalog --query 會預先填好這行並印出,而 --json 會將其作為 report_gap 攜帶——因此在你決定沒有任何項目符合需求時,這個資訊已經在你手邊。
只要結果中沒有任何項目符合需求,無論是哪個層級,都請回報。 不要等到 on-device 層級回答:它需要經過同意的 33 MB 下載,因此除非明確選擇啟用,否則代理執行將使用 words 層級,而僅限於 on-device 會讓幾乎所有的回報都無法發出。--tier 數值會一併攜帶,因此在讀取時可以區分詞彙遺漏與語意遺漏。請描述你想要的效果,而不是你想像的項目名稱:回傳的是值得建立的效果列表,而回報一個不存在的項目名稱無法提供任何資訊。這是唯一會將查詢傳送到任何地方的路徑,也正是它是一個獨立、有意的指令而非搜尋自動執行的事項的原因。它不攜帶評分,也絕不會進入評分指標。
這是目錄的整個需求訊號。跳過它意味著您遇到的缺口只能透過安裝次數來推測,而安裝次數無法看出沒有人能安裝的效果。
如果 CLI 無法連線到設定的 Registry,請檢查原始清單作為備案:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
CLI 無法連線的 Registry 並不會讓目錄在探索時變成空的:只要重新驗證失敗,先前擷取的清單會繼續在 24 小時的重新整理視窗之外提供服務,因此 catalog 和 catalog --query 仍會針對磁碟上的最後一個副本進行列出和排序。
即使是你昨天安裝過的項目,add 仍然需要網路。 只有清單會被快取;項目本身的檔案會在每次安裝時重新擷取。因此,你可以在離線狀態下搜尋,也可以查看項目的說明,但安裝會因為無法取得檔案而失敗。請不要向使用者承諾可以離線安裝。
每個項目的 registry-item.json 包含:名稱、類型、標題、描述、標籤、尺寸(僅限區塊)、持續時間(僅限區塊)以及檔案列表。
依類型和標籤篩選的詳細資訊請參閱 discovery.md。
貢獻新的區塊或元件
若要創作一個新的 Registry 項目(字幕樣式、VFX 區塊、轉場、下三分之一或可複用的元件)並以上游 PR 的形式送出——而非安裝現有項目——請遵循 contributing.md 中的完整構想 → 建立骨架 → 建置 → 驗證 → 預覽 → 發布工作流程。複製貼上用的入門範本(字幕 / VFX / 元件 / registry-item.json)位於 templates.md。