HyperFrames 登錄表
登錄表提供可透過 hyperframes add <name> 安裝的可重複使用區塊與元件。
- 區塊 — 獨立的子合成(擁有自己的維度、持續時間、時間軸)。透過宿主合成中的
data-composition-src引入。 - 元件 — 效果片段(無自身維度)。直接貼入宿主合成的 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 屬性。
位置參數首先被解析為確切的項目名稱。如果沒有相符項目且該值是一個標籤,則命令會安裝所有具有該標籤的區塊。登錄表依賴項會在請求的項目之前安裝。hyperframes add 僅適用於區塊和元件;對於範例,請改用 hyperframes init <dir> --example <name>。
安裝位置
區塊預設安裝到 compositions/<name>.html。元件預設安裝到 compositions/components/<name>.html。
這些路徑可在 hyperframes.json 中配置:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
接線區塊
區塊是獨立的合成——透過宿主 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 時間軸整合(請參見片段中的註解區塊),將這些調用添加到你的時間軸中
探索
使用 CLI 作為主要的探索介面。在瀏覽之前先根據意圖搜尋: 登錄表包含的項目多到無法用肉眼掃描,因此列出它們並根據名稱或標籤進行匹配是慢速路徑,並且當作者的用詞與你的不同時會失敗。
# 對整個目錄進行排序,針對節拍應做之事
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
搜尋在本機進行,不發送任何資料。預設情況下,它根據與項目名稱、標題和描述共享的詞彙進行排序,因此它只能找到重複你詞語的項目;--on-device 則根據意義進行排序,但需要一次性模型下載。使用 --json 時,信封會指明是哪個層次回答的,因此請檢查該資訊,而不是假設已進行排序。
無論影片使用何種語言,始終用英文查詢。 目錄是用英文編寫的,兩個層次都以這種方式索引(本機裝置模型也是僅限英文)。使用其他語言的查詢不會產生可搜尋的詞語,並且會返回空結果。在日本或中文專案中很容易出錯,在這種情況下,簡報、字幕和旁白都是該語言,查詢自然會跟隨:用英文描述 動作,然後用影片所需的任何語言編寫螢幕上的文字。如果查詢返回 No searchable words in query,這是規則問題,而不是缺少元件,也不值得提交缺口報告。
可安裝性在排序之後應用,而非之前:向量攜帶但此登錄表無法提供的名稱會從結果中刪除並計入 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 <name> 安裝選定的名稱。--human-friendly 會打開一個互動式選擇器並立即安裝選定的項目。在 CI 或代理工作流程中,建議使用 --json 後跟明確的 add。
報告目錄中缺少的內容
當搜尋結果出來後,其中沒有任何內容能滿足需求時,請在手工製作該動作之前說明:
npx hyperframes feedback --search-miss "<你執行的查詢>" --wanted "<你需要的動畫>" --tier on-device
catalog --query 會為你列印此行,並預先填寫好,而 --json 則將其作為 report_gap 攜帶——因此在你決定沒有任何內容適合時,它已經準備就緒。
每當結果中的任何內容都無法滿足工作需求時,請報告,無論是哪個層次。 不要等待本機裝置層次回答:它需要一個經同意的 33 MB 下載,因此代理運行時除非明確選擇加入,否則處於 words 層次,而依賴 on-device 會使幾乎所有報告都保持沉默。--tier 值會隨附,以便在閱讀這些報告時,詞彙缺失與意義缺失之間保持可區分性。描述你需要的效果,而不是你想像中的項目名稱:返回的是一個值得建構的動作列表,而一個命名了不存在項目的報告什麼也教不會。這是唯一一個將查詢發送到任何地方的路徑,這正是它作為一個單獨的故意命令而非搜尋自行執行的原因。它不攜帶任何評級,也永遠不會進入評級指標。
這是整個目錄的需求訊號。跳過它意味著你遇到的缺口只能從安裝計數中推測,而安裝計數無法看到一個任何人都無法安裝的動作。
如果 CLI 無法連接到配置的登錄表,請檢查原始清單作為後備:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
CLI 無法連接的登錄表不會清空探索的目錄:只要重新驗證失敗,之前擷取的清單會在 24 小時刷新視窗之外繼續提供服務,因此 catalog 和 catalog --query 仍然會對磁碟上的最後一個副本進行列出和排序。
add 仍然需要網路,即使是你昨天安裝的項目也是如此。 只有清單會被快取;項目的實際檔案在每次安裝時都會重新擷取。因此,離線時你可以搜尋,也可以查看項目的內容,但安裝會在檔案擷取時失敗。不要向使用者承諾離線安裝。
每個項目的 registry-item.json 包含:名稱、類型、標題、描述、標籤、尺寸(僅限區塊)、持續時間(僅限區塊)和檔案列表。
詳見 discovery.md 以了解按類型和標籤篩選的詳細資訊。
貢獻新的區塊或元件
要創作一個新的登錄表項目(字幕樣式、VFX 區塊、轉場、下三分之一或可重複使用的元件)並將其作為上游 PR 提交——而非安裝現有項目——請遵循 contributing.md 中的完整工作流程:構想 → 搭建 → 建構 → 驗證 → 預覽 → 提交。可複製貼上的入門範本(字幕 / VFX / 元件 / registry-item.json)位於 templates.md。