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"
}
}
詳細は 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を主要な検出手段として使用します。意図で検索してからブラウズしてください: レジストリには目でスキャンできる以上のアイテムが含まれているため、名前やタグで一覧表示して一致させるのは遅い方法であり、作成者の表現があなたの表現と異なる場合に失敗します。
# カタログ全体をビートが行うべきことに対してランク付け
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
検索はローカルで行われ、何も送信しません。デフォルトでは、アイテムの名前、タイトル、説明と共有される語彙でランク付けされるため、あなたの言葉を再利用するアイテムのみが見つかります。--on-device を使用すると、1回限りのモデルダウンロード後に、意味でランク付けされます。--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 には、name、type、title、description、tags、dimensions (ブロックのみ)、duration (ブロックのみ)、file list が含まれています。
タイプとタグによるフィルタリングの詳細については、discovery.md を参照してください。
新しいブロックまたはコンポーネントの貢献
新しいレジストリアイテム(キャプションスタイル、VFXブロック、トランジション、ローワーサード、または再利用可能なコンポーネント)を作成し、アップストリームPRとして出荷するには — 既存のものをインストールするのではなく — contributing.md にある完全なアイデア → スキャフォールド → ビルド → 検証 → プレビュー → 出荷ワークフローに従ってください。コピー&ペースト可能なスターターテンプレート(caption / VFX / component / registry-item.json)は templates.md にあります。