HyperFrames CLI

プラグインインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルが HyperFrames プラグイン内にある場合は、プラグイン実行ルール に従ってください。スタンドアロンインストールの場合は、以下の更新手順をそのまま使用します。

HyperFrames CLI は何をしますか？

プロジェクトの指示がラッパーを提供しない限り、コマンドは npx hyperframes ... として実行します。ラッパーがある場合はそれに従います。CLI には Node.js 22 以降と FFmpeg が必要です。

開発ループ

1. スキャフォールド: npx hyperframes init <プロジェクト> (中央揃えの空白)。またはサイトをキャプチャします。名前付きの例から始める場合のみ --example=<名前> を渡します。
2. 動きを見つける: リクエストがアセット、サウンド、画像、音声、または高速ビジュアル編集を指定している場合は、計画を提案する前に /media-use を通じて解決します。それ以外の場合、手動でモーションを作成する前に、既にそれを行うプリミティブを検索します: npx hyperframes catalog --query "見出しを一行ずつ表示する"。頭にある仕組みではなく、希望するエフェクトを指定してください。npx hyperframes add <名前> でインストールします (/hyperframes-registry を参照)。何も適合しない場合のみ手動で作成します。
3. 作成: /hyperframes-core を使用してコンポジションを作成します。プロジェクトのタイムライン（トラック、クリップ、開始、終了、再生内容）を確認するには、index.html とすべてのサブコンポジションファイルを読む代わりに、npx hyperframes timeline --json を実行します。ネストされた行は、ローカルなサブコンポジション時間だけでなく、絶対的なメインタイムラインの absStart/absEnd とそれらを所有する file を運びます。テキスト形式よりも --json を優先します。同程度以上の正確性で、トークン消費が少なくなります。一般的な質問に答えるワンライナーについては、references/upgrade-info-misc.md を参照してください。出力全体を読む必要はありません。
4. 編集時に迅速なフィードバックを得る: 最初の HTML パス後および構造変更後に npx hyperframes lint を実行します。
5. 最終ゲートを実行する: npx hyperframes check を実行します。ブラウザを開く前に lint を再実行します。冗長なスタンドアロン lint 呼び出しを前置しないでください。注釈付きの概要フレームとクロップを見つけるには --snapshots を追加します。
6. サブコンポジションを検査する: index.html が data-composition-src をマウントしている場合、中間点のスナップショットをキャプチャし、マウントされた各シーンを検査します。
7. 最終 Studio プレビューを開く: npx hyperframes preview --background を実行し、URL が HTTP 200 を返すことを確認し、タイムラインプロジェクト URL をユーザーに渡し、修正するかレンダリングするかを尋ねます。レビューが終了するまでアクティブに保ちます。
8. 承認後にのみレンダリング: 反復中は --quality draft を使用し、最初の実際のエンコードには --quality looks (CLI デフォルト)、最終納品には --quality delivery を使用します。
9. 出力を確認する: ファイルが存在し、空でないことを確認します。レンダリングサマリーの 2 行目 (beginframe vs screenshot、GPU、ステージタイミング) を読みます。Linux での screenshot + software gpu は低速パスです。ffprobe -v error -show_format -show_streams を実行し、ルートの data-duration と比較します（および、ブリーフで設定されている場合は fps も）。

あなたのターンでのプロジェクト履歴

プロジェクトへのすべての書き込みは、元に戻せるエントリとして保持されます。毎ステップではなく、以下の2つのタイミングでのみ使用します:

• ターンの開始: npx hyperframes history begin --who <あなたの名前> --label "<これから行うこと>" を実行し、次に npx hyperframes history --since mine --who <あなたの名前> を実行して、最後のターン以降にその人が変更した内容を確認します。あなたの編集を構築し、上書きしないでください。
• チェックが失敗した、またはユーザーが状況が悪化したと言った場合: npx hyperframes history undo --who <あなたの名前> は最新のターンを元に戻し、その人の編集はそのままにします。手動で戻さないでください。競合が発生した場合は終了コード 2 で終了し、両方の選択肢を表示します。

各ターンを npx hyperframes history end で終了すると、書き込みが「アプリ外で変更」ではなく、あなたのものとして読み取られます。ターンが開いている間は、プロジェクトへのすべての書き込みは、10分間書き込みがないまであなたのものとしてカウントされ、その後ターンは自動的に終了します。

必須の作成者-編集相互参照

• ズーム、パンチイン/パンチアウト、リフレーム、カメラムーブ、またはキーフレームモーションを作成または診断する前に、最初に /hyperframes-keyframes を読んでください。
• hyperframes keyframes の前に、/hyperframes-keyframes を読んでください。このコマンドはアニメーションの軌跡を表示し、クリップカットを診断しません。
• カット、トリム、スプライス、並べ替え、またはソースタイミング編集については、/hyperframes-core を読み、そのクリップ/タイムライン契約を使用します。
• フェードイン/フェードアウト、クロスフェード、トラックゲイン、ボリュームオートメーション、ダッキング、ボイスオーバーカーブ、または配置されたオーディオへの FX については、/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 looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4

check は最初に lint を実行し、次に1つのブラウザセッションと1つのシークパスを使用して、ランタイムエラー、失敗したリクエスト、レイアウト、*.motion.json アサーション、および WCAG コントラストを監査します。永続的な発見は終了コードをゲートし、一時的な開始/終了発見は情報提供です。警告をゲートするには --strict を使用します。validate、inspect、layout は互換性のためにエイリアスとして残りますが、新しい指示やスクリプトに含めてはいけません。

レンダリング前のプレビュー

check が合格した後、最終コンポジションプレビュー (#project/<名前>) を開き、組み立てられたタイムラインをレビューします。チャット内の計画と storyboard.html スケッチシートは、最終ビデオの承認ではありません。レンダリングには常に、hyperframes/references/review-loop.md で定義された最終承認が必要です。

サブコンポジションのスモークテスト

静的監査ではすべてのマウント失敗をキャッチできません。プロジェクトがサブコンポジションを使用する場合、各ホストスロットに対して少なくとも1つの可視中間点をキャプチャします:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

小さなスタイル未適用のコンテンツ、キャンバスサイズのアイコン、欠落したヒーロー要素、またはタイムライン登録のタイムアウトを、レンダリングをブロックするマウント欠陥として扱います。対応する修正については、hyperframes-core/references/sub-compositions.md を参照してください。

エージェント規約

• モーションを手動で作成する前にカタログを検索します。 npx hyperframes catalog --query "<ビートを平易な英語で>"。検索は完全にローカルです。ホスト型階層はなく、アカウントも不要で、クエリテキストが送信されることはありません。デフォルトでは、アイテムの名前、タイトル、説明、タグと共有される語彙でランク付けされるため、カタログ自身の表現を再利用しないフレーズは見逃されます。代わりに意味でランク付けするには、--on-device を追加します（以下のオフラインティアを参照）。

• ビデオが英語でなくても、クエリは英語で行います。 両方のティアが英語のカタログをインデックスするため、異なるスクリプトでのクエリは検索可能な用語を生成せず、何も返しません。動きを英語で説明してください。画面上のコピーは、ビデオが必要とする言語のままです。クエリに検索可能な単語がありません はまさにこれを意味し、コンポーネントの欠落ではありませんので、カタログのギャップとして報告しないでください。

• どのティアが回答したかを読み取り、結果が現れたことから推測しないでください。 --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 で再実行するとそのインデックスが再フェッチされるため、それがユーザーに提供する救済策です。純粋な過カバレッジの歪み (unindexed がゼロで dropped がゼロより大きい) は再フェッチをトリガーしません。~/.hyperframes/catalog/ をクリアするのが唯一の脱出方法です。どちらのカウントも結果の名前ではなく名前のカウントであるため、どちらも total を超える可能性があります。

• 検索がインストールする価値のあるものを何も返さなかった場合は、そう伝えます。 npx hyperframes feedback --search-miss "<実行したクエリ>" --wanted "<必要な動き>" --tier <回答したティア>。この行を組み立てる必要はありません。catalog --query は事前に入力されたものを出力し、すべての --json 検索エンベロープは report_gap としてクエリとティアがすでに正しい状態でそれを運びます。--wanted を入力して送信します。これがクエリをどこかに送信する唯一のパスであり、catalog --query が何も送信しないという約束を正確に守るための、別個の意図的なコマンドです。いずれかのティアで報告します。結果が目的の動作をしない場合は常に、オンデバイスティアを待たないでください。オンデバイスティアは同意が必要な33 MBのダウンロードが必要であり、ほとんどのエージェント実行ではオフになっています。待つことは決して報告しないことを意味します。ティアはレポートに含まれるため、語彙ミスと意味ミスは、どちらに当たったかを自分で判断する必要なく区別できます。返ってくるのは、カタログがまだ持っていない動きのリストであり、インストール数から推測されるのではなく直接読み取られるため、重要なのは想像したアイテム名ではなく、望んだ効果です。評価は含まれず、評価指標に届くことはありません。

• オフラインティアを提供しますが、静かに有効にしないでください。 一回限りの約33 MBのダウンロード (量子化された ONNX ビルドの bge-small-en-v1.5 とそのトークナイザー、固定リビジョンにピン留め) とレジストリからのカタログベクターで、両方とも ~/.hyperframes/ にキャッシュされ、プロジェクトやパッケージには追加されません。キャッシュされると、何も送信せずに意味でランク付けします。サイズを声に出して伝え、ユーザーに決定させ、同意が得られたら --on-device (プロンプトをスキップするために -y を付けて) を渡します。インタラクティブな提供は TTY でのみ発動します。--json の下ではプロンプトはありませんが、何も見つからなかった検索は同じ要求を warnings に配置するため、その配列を読んで、ユーザーに自分で決定を委ねてください。ユーザーがダウンロード内容、このモデルが選ばれた理由、またはマシンから何が送信されるかを尋ねた場合は、https://hyperframes.heygen.com/developers/catalog-search を参照するよう指示してください。

• エージェントと CI 呼び出しには --json を優先します。サーバーモードの render、preview、play は通常の JSON 出力を提供しません。preview --selection --json と preview --context --json はクエリモードの例外です。

• doctor --json は常に終了コード 0 で終了します。そのペイロードでゲートします:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• 非 TTY モードは自動で、中央揃えの空白をスキャフォールドします。名前付きの例から始める場合のみ --example を渡します。TTY でフラグのみのモードを強制するには --non-interactive を使用します。

• 同じ検証ループ内のすべてのコマンドには1つの HYPERFRAMES_RUN_ID を使用します。

• ディスク容量が逼迫している場合、npx hyperframes clean を実行します (--dry-run で最初にリスト表示)。これにより、死んだレンダリングが残したものと、自己再構築するアイドルキャッシュが削除されますが、出力、ソース、または実行中のレンダリングが使用するものは決して削除されません。QC フレームはプロジェクトではなく一時ディレクトリに書き込みます。

• 対応する警告、変数、または 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 looks --output out.mp4
最終ローカル納品	npx hyperframes render --quality delivery --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 ...
サーバーレス Google Cloud Run レンダリング	npx hyperframes cloudrun ...

診断とトラブルシューティング

ビルドやレンダリングの失敗を診断するには:

npx hyperframes doctor --json

jq -e '.ok' でゲートします。出力が ok: false を示す場合、errors 配列とシステム構成の提案を確認してください。

• npx hyperframes info は、システム、プロジェクト、プラグインの完全な診断ダンプを提供します。
• npx hyperframes browser は、診断のためにさまざまなブラウザを開くことができます。
• npx hyperframes upgrade は、CLI とプラグインを確認して更新します。
• npx hyperframes skills は、利用可能なスキルとそのバージョンをリストします。

その他のコマンド

• npx hyperframes beats: ビデオにビートマーカーを追加します。
• npx hyperframes keyframes: キーフレームアニメーションを管理します。
• npx hyperframes single: 単一フレームをレンダリングします。
• npx hyperframes batch: バッチレンダリングを実行します。
• npx hyperframes publish: プロジェクトを公開します。
• npx hyperframes cloud: クラウド操作を管理します。
• npx hyperframes cloudrun: Google Cloud Run の操作。
• npx hyperframes feedback: フィードバックを送信します。
• npx hyperframes transcribe: ビデオ/オーディオを文字起こしします。
• npx hyperframes auth: 認証を管理します。
• npx hyperframes tts: テキスト読み上げ。
• npx hyperframes remove-background: 画像/ビデオから背景を削除します。
• npx hyperframes composer: 構成を管理します。
• npx hyperframes benchmark: パフォーマンスベンチマーク。
• npx hyperframes telemetry: テレメトリ。
• npx hyperframes docs: ドキュメントを開きます。
• npx hyperframes clean: キャッシュと孤立したレンダリングアーティファクトをクリーンアップします。

validate、inspect、layout は非推奨のエイリアスです。代わりに check を使用してください。