Communitygithub.com

HyperFrame 註冊表搜尋與安裝工具

在 HyperFrames 合成中搜尋、安裝並整合註冊表中的區塊與元件。在手工建構任何具名視覺效果前,先使用此工具,因為約有 400 個託管項目已涵蓋許多常見效果。

HyperFrame 註冊表搜尋與安裝工具 是什麼?

這個技能為 AI 代理(如 Claude Code、Cursor 或 Codex)提供 HyperFrames 註冊表的完整存取能力。它讓代理能夠搜尋、安裝並連接超過 400 個預先建立的區塊(獨立的子合成)與元件(效果片段)。主要的使用時機是在開始手工製作任何具名視覺效果(如 CRT 掃描線、故障效果、色差、膠卷顆粒、微光掃掠、圖表、程式碼視窗、地圖或五彩紙屑爆發)之前進行搜尋,因為這些效果大多已有現成項目。該技能支援 `hyperframes add` 命令用於安裝(透過名稱或標籤),以及 `hyperframes catalog --query` 命令用於語意搜尋。`--on-device` 標記能在下載模型後進行基於意義的排名,而預設的 `words` 層級則是基於詞彙重疊。若要回報目錄中缺少的效果,可使用 `hyperframes feedback` 命令。此技能處理發現、安裝位置設定、區塊子合成連接(使用 `data-composition-src`)、元件片段合併,以及貢獻新的區塊或元件(從構想到 PR 的完整工作流程)。搜尋是本機進行的,不會發送任何資料,但若要進行意圖式查詢,則必須使用英文。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/samyakiasonline-ctrl/hyperframe/tree/HEAD/.claude/skills/hyperframes-registry

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

外掛安裝: 在執行設定或更新命令之前,請先遵循外掛執行規則(當此技能位於 HyperFrames 外掛內部時)。獨立安裝則保留下方的更新說明。

HyperFrames 註冊表

此註冊表提供可透過 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 屬性。

位置參數會先嘗試解析為確切的項目名稱。如果沒有匹配的項目且該值是一個標籤,則命令會安裝所有帶有該標籤的區塊。註冊表依賴項會在請求的項目之前安裝。hyperframes add 僅適用於區塊和元件;如需範例,請使用 hyperframes init <dir> --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 — 工作室時間軸行號;僅為顯示用途。圖層疊加請使用 CSS z-index

詳情請參閱 wiring-blocks.md。

連接元件

元件是程式碼片段 — 將其 HTML 貼入合成標記、CSS 貼入樣式區塊、JS 貼入腳本(如果有的話):

  1. 讀取已安裝的檔案(例如 compositions/components/grain-overlay.html)
  2. 將 HTML 元素複製到合成的 <div data-composition-id="..."> 中
  3. 將 <style> 區塊複製到合成的樣式中
  4. 將任何 <script> 內容複製到合成的腳本中(在時間軸程式碼之前)
  5. 如果元件暴露了 GSAP 時間軸整合(請參閱代碼片段中的註解區塊),將這些呼叫加入你的時間軸

詳情請參閱 wiring-components.md。

發現 (Discovery)

使用 CLI 作為主要的發現界面。先根據意圖搜尋,再瀏覽: 註冊表中的項目數量超過肉眼可掃描的範圍,因此列出所有項目並根據名稱或標籤進行比對是較慢的路徑,而且當作者的用詞與你的不同時,這種方法會失效。

# 根據節拍應執行的動作對整個目錄進行排名
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,這就是這個規則造成的,而不是缺少元件,也不值得回報為缺口。

可安裝性是在排名之後應用的,而不是之前:向量承載但此註冊表無法提供的項目名稱會從結果中刪除,並計入 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 <回應的層級>

catalog --query 會印出這行命令(已預先填好),而 --json 會將其作為 report_gap 攜帶——因此在你決定沒有任何項目符合需求時,這行命令已準備就緒。

只要結果中沒有任何項目符合需求,無論是哪個層級回應,都請回報。 不要等到 on-device 層級回應:它需要一個已同意的 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 中。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

samyakiasonline-ctrl/hyperframe

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

samyakiasonline-ctrl/hyperframe

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

samyakiasonline-ctrl/hyperframe

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

samyakiasonline-ctrl/hyperframe

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

samyakiasonline-ctrl/hyperframe

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

samyakiasonline-ctrl/hyperframe

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, history, clean, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

samyakiasonline-ctrl/hyperframe

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

samyakiasonline-ctrl/hyperframe

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

samyakiasonline-ctrl/hyperframe

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

samyakiasonline-ctrl/hyperframe

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

samyakiasonline-ctrl/hyperframe

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

samyakiasonline-ctrl/hyperframe

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

samyakiasonline-ctrl/hyperframe

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

相關技能