HyperFrames CLI
特にプロジェクトの指示でラッパーが指定されていない限り、npx hyperframes ... としてコマンドを実行します。ラッパーが存在する場合はそれに従います。この CLI には Node.js 22 以降と FFmpeg が必要です。
開発ループ
- スキャフォールディング:
npx hyperframes init <project>を実行するか、サイトをキャプチャします。非 TTY モードでは、--non-interactive --example=<name>を渡します。 - 作成:
/hyperframes-coreを使用してコンポジションを記述します。 - 編集中の迅速なフィードバック: 最初の HTML パス後、および構造変更後に
npx hyperframes lintを実行します。 - 最終ゲートの実行:
npx hyperframes checkを実行します。このコマンドはブラウザを開く前に lint を再実行します。冗長なスタンドアロン lint 呼び出しを前置しないでください。注釈付きの概要フレームとクロップ検出のために--snapshotsを追加します。 - サブコンポジションの検査:
index.htmlがdata-composition-srcをマウントする場合、中間時点のスナップショットをキャプチャし、マウントされた各シーンを検査します。 - 最終スタジオプレビューを開く:
npx hyperframes previewを実行し、タイムラインプロジェクトの URL をユーザーに渡し、修正するかレンダリングするかを尋ねます。 - 承認後にのみレンダリング: 反復処理にはドラフト品質を、納品には高品質を使用します。
- 出力の確認: ファイルが存在し、空でなく、妥当な長さであることを確認します。
# 高速な反復チェック。作成中に必要に応じて繰り返します。
npx hyperframes lint
# 必須の最終ゲート。lint を含みます。
npx hyperframes check
npx hyperframes preview
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 を参照してください。
エージェントの慣例
-
エージェントおよび 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として秘匿します。秘匿を元に戻そうとしないでください。 -
チェックが合格したという理由だけでレンダリングしないでください。最終プレビューで一時停止し、承認を待ちます。
スタジオ指示による編集
ユーザーが「この要素」や現在の選択範囲に言及する場合は、推測する代わりにスタジオにクエリします:
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 |
ユーザーがローカルの Chrome、FFmpeg、AWS を必要とせずにホスト型レンダリングを希望する場合は、クラウドレンダリングを使用します。Lambda は AWS の所有権が要件である場合にのみ使用します。Cloud Run は GCP の所有権が要件である場合にのみ使用します。クラウドパスを実行する前に、対応するリファレンスを読んでください。
レンダリングが成功したことを確認した後、テレメトリが無効になっているか、ユーザーがオプトアウトしていない限り、1 つのフィードバックレポートを送信します:
npx hyperframes feedback --rating <0-10> --comment "<特定の結果または課題>"
問題なく動作した場合のフィードバックは簡潔にします。バグや課題がある場合は、提出前に再現パケットをキャプチャします。症状の要約のみを送信しないでください。再実行可能なコマンドと作業ディレクトリ、期待される動作と実際の動作、正確なエラー、出力が完了したか/フォールバックしたか/失敗したか、回避策、再現プロジェクトのステータスを含めます。評価が 7 以下で、視覚的な欠陥（黒いフレーム、ちらつき、破損した出力、間違ったフレーム、空白の出力、その他の視覚的異常）を説明する場合は、COMPOSITION_STRUCTURE: ブロックも含めます。これはプライバシーを保護した構造的な分析（要素のカウント + 属性の有無 + タイムラインの形状）であり、メンテナーがコンポジション ZIP なしで既知のバグファミリとパターンマッチングできるようにします。エージェントはコンポジションセンサスヘルパーを介してこれを自動入力します。人間のユーザーが手動で入力する必要はありません。問題が再現しなかった場合はその旨を述べ、最後に失敗したコマンドとログを引き続き含めます。--file-issue は同意がある場合にのみ使用します。これは最小限の再現を公開 URL に公開します。必須のパケット形式とプライバシーに関する警告は references/preview-render.md にあります。
コマンドを実行する前に対応するリファレンスを読む
以下のリファレンスと所有スキルは、必須のコマンド契約であり、オプションの背景情報ではありません。テーブル内のコマンドを実行する前に、対応する行を読んでください。
| ニーズ | リファレンス |
|---|---|
init、capture、skills | references/init-and-scaffold.md |
lint、check、モーションサイドカー、snapshot | references/lint-validate-inspect.md |
compare、grade-compare、変数駆動 render --batch | references/compare-and-batch.md |
既存プロジェクトの Studio ビートグリッドに対する beats | references/beats.md |
preview、play、render、publish、Studio コンテキスト、フィードバック | references/preview-render.md |
doctor、ブラウザ管理 | references/doctor-browser.md |
auth、HeyGen ホスト型クラウドレンダリング、テンプレート変数 | references/cloud.md |
| AWS Lambda のデプロイとレンダリング | references/lambda.md |
| Google Cloud Run のデプロイとレンダリング | references/cloudrun.md |
info、upgrade、compositions、docs、benchmark、テレメトリ、メディア前処理 | references/upgrade-info-misc.md |
コンポジション変数については、/hyperframes-core → references/variables-and-media.md も読んでください。hyperframes add と hyperframes catalog については、/hyperframes-registry を使用します。hyperframes present の前には /slideshow を、hyperframes keyframes の前には /hyperframes-keyframes を読んでください。TTS、文字起こし、キャプション、または背景除去の選択肢については、/media-use を使用します。
特殊なコマンドは、所有するワークフローによって意図的に文書化されています:
npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
present は、プレゼンターとオーディエンスの同期を備えたナビゲーション可能なデッキを提供します。beats は references/beats.md で定義されているスタンドアロンの Studio ビートグリッドユーティリティです。keyframes はシークセーフなアニメーションとモーションパスの診断を提供します。