HyperFrames CLI
npx hyperframes ... としてコマンドを実行します。プロジェクトの指示でラッパーが指定されている場合は、それに従ってください。ラッパーが存在する場合は、そちらを優先します。CLI には Node.js 22 以降と FFmpeg が必要です。
開発ループ
- スキャフォールド:
npx hyperframes init <project>またはサイトをキャプチャします。非 TTY モードでは、--non-interactive --example=<name>を渡します。 - 動きを見つける: 手作業でモーションを作成する前に、すでにその動きを実現するプリミティブがないかを検索します:
npx hyperframes catalog --query "一行ずつ見出しを表示する"。思い浮かべた仕組みではなく、実現したい効果を指定してください。npx hyperframes add <name>でインストールします (/hyperframes-registryを参照)。何も適合しない場合にのみ、手作業で作成します。 - 作成:
/hyperframes-coreを使用してコンポジションを記述します。 - 編集時の高速フィードバック: 最初の HTML パス後、および構造変更後に
npx hyperframes lintを実行します。 - 最終ゲートを実行:
npx hyperframes checkを実行します。lint が再実行されてからブラウザが開きます。冗長な独立した lint 呼び出しを前置しないでください。注釈付きの概要フレームとクロップ領域を見つけるには--snapshotsを追加します。 - サブコンポジションの検査:
index.htmlがdata-composition-srcをマウントする場合、中間点のスナップショットをキャプチャし、マウントされた各シーンを検査します。 - 最終 Studio プレビューを開く:
npx hyperframes preview --backgroundを実行し、URL が HTTP 200 を返すことを確認し、タイムラインプロジェクトの URL をユーザーに渡し、修正するかレンダリングするかを尋ねます。レビューが終了するまでプレビューを開いたままにします。 - 承認後にのみレンダリング: イテレーションにはドラフト品質、納品には高品質を使用します。
- 出力を検証: ファイルが存在し、空でなく、妥当な長さであることを確認します。
必須のクリエイター編集クロスリファレンス
- ズーム、パンチイン/パンチアウト、リフレーム、カメラ移動、またはキーフレームモーションの作成や診断を行う前に、
/hyperframes-keyframesを読んでください。 hyperframes keyframesの前に/hyperframes-keyframesを読んでください。このコマンドはアニメーションの軌跡を表示し、クリップカットの診断は行いません。- カット、トリム、スプライス、並べ替え、またはソースタイミングの編集には、
/hyperframes-coreを読み、そのクリップ/タイムラインのコントラクトを使用してください。 - フェードイン/フェードアウト、クロスフェード、トラックゲイン、ボリュームオートメーション、ダッキング、ナレーションのカーブ、または配置されたオーディオへのエフェクトには、
/hyperframes-audioを読んでください。クリップの配置やピクチャタイミングも変更する場合は、これと一緒にコアもロードしてください。 - メディアのソース/生成または派生アセットの前処理には
/media-useを使用してください。クリエイター編集マークアップは/hyperframes-core→references/creator-editing-recipes.mdからコピーしてください。
# 高速イテレーションチェック。作成中に必要に応じて繰り返します。
npx hyperframes lint
# 必須の最終ゲート。lint を含みます。
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check は最初に lint を実行し、次に1つのブラウザセッションと1つのシークパスを使用して、ランタイムエラー、失敗したリクエスト、レイアウト、*.motion.json のアサーション、WCAG のコントラストを監査します。永続的な問題は終了コードをゲートします。一過性の開始または終了の問題は情報提供のみです。警告をゲートするには --strict を使用します。互換性のために validate、inspect、layout はエイリアスとして残りますが、新しい指示やスクリプトには使用しないでください。
2つの異なるプレビュー画面
これらの状態を混同しないでください:
| 画面 | 開かれるタイミング | 目的 |
|---|---|---|
| ストーリーボード | コンポジションチェック前、storyboard: yes の場合のみ | プランカードとワイヤーフレームスケッチをレビューします。?view=storyboard#project/<name> を開きます。 |
| 最終コンポジションプレビュー | check が成功した後 | レンダリング前にアセンブルされたタイムラインをレビューします。#project/<name> を開きます。 |
初期のボードは最終ビデオの承認ではありません。レンダリングには常に hyperframes-core/references/review-loop.md で定義された最終承認が必要です。
サブコンポジションのスモークテスト
静的監査ではすべてのマウント障害をキャッチできません。プロジェクトがサブコンポジションを使用する場合、各ホストスロットの少なくとも1つの中間点の可視スナップショットをキャプチャしてください:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
極小のスタイルなしコンテンツ、キャンバスサイズのアイコン、欠落したヒーロー要素、またはタイムライン登録のタイムアウトは、レンダリングをブロックするマウント欠陥として扱います。対応する修正については hyperframes-core/references/sub-compositions.md を参照してください。
エージェントの規約
-
モーションを手作業で作成する前に、カタログを検索してください。
npx hyperframes catalog --query "<平易な英語でのビート>"。検索は完全にローカルで行われます。ホステッドティア、アカウントはなく、クエリテキストが外部に送信されることもありません。デフォルトでは、アイテムの名前、タイトル、説明と共有される語彙でランク付けされるため、カタログ自身の表現を再利用しないフレーズは見逃されます。代わりに意味でランク付けするには--on-deviceを追加してください（以下のオフラインティアを参照）。 -
ビデオが英語でなくても、クエリは英語で記述してください。 両方のティアは英語のカタログをインデックスしているため、他のスクリプトでのクエリは検索可能な用語を生成せず、何も返しません。動きを英語で説明してください。画面上のコピーは、ビデオが必要とする言語のままです。
No searchable words in queryはまさにこの状態を意味し、コンポーネントの欠落ではありません。カタログのギャップとして報告しないでください。 -
どのティアが応答したかを読み取ってください。結果が表示されたからといって推測しないでください。
--jsonを使用すると、エンベロープにはquery、tier(on-deviceまたはwords)、tier_detail、dropped、unindexed、shown、total、results、および応答ティアが生成する場合はtop_score、ティアが要求されたが実行できなかった場合はwarningsが含まれます。wordsでの弱い結果は予想通りです。同じ結果がon-deviceで出た場合はバグです。top_scoreは on-device のみであり、その背後にしきい値はありません。ランカーはすべてのクエリに対してカタログ全体を何らかの順序で返すため、それを合格または不合格としてではなく、証拠として読んでください。 -
droppedとunindexedは、レジストリとオンデバイスインデックス間の逆の偏りであり、クエリを言い換えてもどちらも修正されません。droppedは、このレジストリがインストールできないランク付けされた名前をカウントするため、最も強い一致が失われています。unindexedは、インデックスがまったく認識できないレジストリの動きをカウントし、どのクエリでも返すことはできません。どちらに対しても、レジストリのリフレッシュは解決策ではありません。そのマニフェストには24時間のTTLがあり、自己修復します。ベクトルは別途公開されたアーティファクトであり、~/.hyperframes/catalog/にフェッチされます。unindexedがゼロより大きい場合、--on-deviceを再実行するとそのインデックスが再フェッチされるため、それがユーザーに提供する救済策です。純粋な過カバレッジの偏り（droppedがゼロより大きく、unindexedがゼロ）は再フェッチをトリガーしません。その場合は~/.hyperframes/catalog/をクリアするしかありません。両方のカウントは結果ではなく名前のカウントであるため、どちらもtotalを超える可能性があります。 -
検索でインストールする価値のあるものが何も返ってこなかった場合は、その旨を伝えてください。
npx hyperframes feedback --search-miss "<実行したクエリ>" --wanted "<必要だった動き>" --tier <応答したティア>。この行を自分で組み立てる必要はありません。catalog --queryは事前に入力された状態でこれを出力し、すべての--json検索エンベロープはreport_gapとしてクエリとティアがすでに正しい状態でそれを保持しています。--wantedを入力して送信してください。これがクエリをどこかに送信する唯一のパスであり、単純なcatalog --queryが何も送信しないという約束を守るために、これは別個の意図的なコマンドです。いずれかのティアで報告してください。 結果が目的の動作をしないときはいつでも、です。オンデバイスティアを待つ必要はありません。オンデバイスティアは同意が必要な33 MBのダウンロードを必要とし、そのためほとんどのエージェント実行ではオフになっています。それを待つことは、決して報告しないことを意味します。ティアはレポートに含まれるため、語彙のミスと意味のミスは、どちらに該当するかをユーザーが判断しなくても区別可能です。返ってくるのは、カタログにまだない動きのリストであり、インストール数から推測されるのではなく直接読み取られるため、重要なのは、あなたが想像したアイテム名ではなく、必要だったエフェクトの表現です。評価は含まれず、評価指標に届くこともありません。 -
オフラインティアを提供してください。静かに有効にしないでください。 約33 MBの1回限りのダウンロード（
bge-small-en-v1.5の量子化ONNXビルドとそのトークナイザー、固定リビジョンにピン留め）とレジストリからのカタログベクトル。どちらも~/.hyperframes/の下にキャッシュされ、プロジェクトやパッケージには追加されません。一度キャッシュされると、何も送信せずに意味でランク付けされます。サイズを声に出してユーザーに決定させ、同意が得られたら--on-device（プロンプトをスキップするために-yを付けて）を渡してください。インタラクティブなオファーはTTYでのみ発動し、--jsonの下では何も印刷されないため、エージェント実行ではユーザー自身に提起する必要があります。 -
エージェントおよびCI呼び出しには
--jsonを優先してください。サーバーモードのrender、preview、playは通常のJSON出力を提供しません。preview --selection --jsonおよびpreview --context --jsonはクエリモードの例外です。 -
doctor --jsonは常にゼロで終了します。そのペイロードでゲートしてください:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非TTYモードは自動です。
initではそこで--exampleが必要です。TTYで決定論的な動作を強制するには--non-interactiveを使用してください。 -
同じ検証ループ内のすべてのコマンドに1つの
HYPERFRAMES_RUN_IDを使用してください。 -
対応する警告、変数、またはCI条件がレンダリングをゲートする必要がある場合は、
--strict、--strict-all、--strict-variablesを使用してください。 -
JSONパスはホームディレクトリを
$HOMEとして難読化します。難読化を元に戻そうとしないでください。 -
ホステッドクラウドプロジェクトが200 MBのアップロード制限に近づいているか超えている場合は、
cloud render --dry-run --jsonを使用し、references/cloud.mdの.hyperframesignore調査に従ってください。アセットが大きいという理由だけで無視しないでください。 -
チェックが成功したからといってレンダリングしないでください。最終プレビューで一時停止し、承認を待ってください。
Studio による編集
ユーザーが「この要素」や現在の選択について言及した場合、推測する代わりに Studio にクエリを実行してください:
npx hyperframes preview --context --json --context-fields selection
selection.target.hfId が利用可能な場合はそれを使用し、それ以外の場合はそのセレクタとソースファイルを使用します。結果が no-selection を報告した場合、ユーザーに要素をクリックして再実行するように依頼してください。必要なコンテキストスライスのみを要求してください。計算されたスタイルや編集可能なテキストメタデータには --context-detail full のみを使用してください。完全な動作と障害コードは references/preview-render.md にあります。
レンダリングの選択肢
| ニーズ | コマンド |
|---|---|
| 高速ローカルイテレーション | npx hyperframes render --quality draft |
| 最終ローカル納品 | npx hyperframes render --quality high --output out.mp4 |
| 再現可能なコンテナレンダリング | npx hyperframes render --docker --strict --output out.mp4 |
| ローカル変数駆動バッチレンダリング | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen ホステッドゼロインフラレンダリング | npx hyperframes cloud render |
| 自己管理分散 AWS レンダリング | npx hyperframes lambda render <project> --width 1920 --height 1080 --wait |
| 自己管理分散 GCP レンダリング | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
スキル属性は自動的に行われます。上記の例では --skill は必要ありません。ワークフローによってスキャフォールドされたプロジェクト (hyperframes init --skill=<workflow>) は、その所有スキルを hyperframes.json に記録し、その後のすべてのレンダリングは匿名テレメトリでそれを継承します: 再レンダリング、npm run render、--batch も同様です。ワークフローを通じて作成されなかったプロジェクトにスタンプする場合にのみ、明示的に --skill=<slug> を渡してください（最初のレンダリングでそれが永続化されます）。
ユーザーがローカルの Chrome、FFmpeg、AWS なしでホステッドレンダリングを希望する場合は、クラウドレンダリングを使用してください。AWS の所有権が要件である場合にのみ Lambda を使用してください。GCP の所有権が要件である場合にのみ Cloud Run を使用してください。クラウドパスを実行する前に、対応するリファレンスを読んでください。
レンダリングの成功を確認した後、テレメトリが無効になっているかユーザーがオプトアウトしていない限り、1つのフィードバックレポートを送信してください:
npx hyperframes feedback --rating <0-10> --comment "<具体的な結果または摩擦>"
クリーンランは簡潔にフィードバックしてください。バグや摩擦については、症状の要約のみを送信せず、提出前に再現パケットをキャプチャしてください。これには、再実行可能なコマンド（プロジェクトディレクトリからの相対パス — フィードバックは公開チャネルに送信されるため、絶対パス、ホームディレクトリのプレフィックス、ユーザー/マシン識別子は貼り付けないでください）、期待される動作と実際の動作、正確なエラー（スタックトレースからも絶対パスを取り除いてください — ベース名 + 行番号を保持し、先頭のディレクトリを削除）、出力が完了したか/フォールバックしたか/失敗したか、回避策、再現プロジェクトのステータスを含めてください。レーティング ≤ 7 で視覚的な欠陥（黒フレーム、フリッカー、破損した出力、間違ったフレーム、空白の出力、その他の視覚的な異常）を説明する場合は、COMPOSITION_STRUCTURE: ブロックも含めてください。これはプライバシーを保護する構造的な解剖（要素の構成 + 属性の存在 + タイムラインの形状）であり、メンテナがコンポジションZIPなしで既知のバグファミリーとパターンマッチングできるようにします。エージェントは composition-census ヘルパーを介してこれを自動入力します。人間のユーザーは手動で入力しません。問題が再現しなかった場合は、その旨を述べ、それでも最後に失敗したコマンドとログを含めてください。同意がある場合にのみ --file-issue を使用してください。これは最小限の再現を公開URLに公開します。必要なパケット形式とプライバシー警告は references/preview-render.md にあります。
コマンドを実行する前に対応するリファレンスを読んでください
...