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 を使用すると、エンベロープはどの階層が回答したかを示すので、ランク付けが行われたと想定するのではなく、それを確認してください。
ビデオの言語に関わらず、常に英語でクエリを実行してください。 カタログは英語で書かれており、両方の階層がそのようにインデックスします(オンデバイスモデルも英語のみです)。他の文字体系でのクエリは検索可能な用語を生成せず、何も返しません。これは日本語や中国語のプロジェクトで間違いやすい点です。そのようなプロジェクトでは、ブリーフ、キャプション、ナレーションがすべてその言語であり、クエリも自然にその言語になります。動き(move)を英語で説明し、画面上のコピーはビデオが必要とする任意の言語で記述してください。クエリが 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 にあります。