HyperFrames CLI
すべての操作は、プロジェクトの指示でローカルラッパーが指定されていない限り、npx hyperframes を通じて実行します。ローカルラッパーが指定されている場合は、それを正確に従ってください。Node.js >= 22 と FFmpeg が必要です。
ワークフロー
- スキャフォールド —
npx hyperframes init my-video(または URL からのcapture)。initはインストールされているスキルを GitHub 上の最新版と照合し、古いものがあればグローバルセットを更新します。--skip-skillsフラグは現在無効化されています(一時的。skills.sh レジストリが追いつくまでの措置)。そのため、すべてのinitでこのチェックが実行され、最新のスキルが常に取り込まれます。 - 記述 — HTML コンポジションを作成します(
hyperframes-coreスキルを参照) - リント —
npx hyperframes lint - 検証 —
npx hyperframes validate(ランタイムエラー + コントラスト) - 視覚的検査 —
npx hyperframes inspect - プレビュー —
npx hyperframes previewで Studio(タイムラインエディター)が開きます。ユーザーはここで視聴するだけでなく、手動ですべてを編集できます。そこで確認し、レンダリングの前にユーザーに確認を取ってください。 - レンダリング — 以下のバリアントから選択:
- イテレーション:
npx hyperframes render --quality draft - 本番出力:
npx hyperframes render --quality high --output out.mp4 - CI / クロスホスト再現:
npx hyperframes render --docker --strict --output out.mp4 - クラウド(長時間 / 大規模):
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(以下の Lambda を参照)
- イテレーション:
プレビューの前に、lint、validate、inspect を実行してください。lint は、data-composition-id の欠落、重複トラック、未登録のタイムラインを検出します。validate はヘッドレス Chrome でコンポジションを読み込み、ランタイムコンソールエラーと WCAG コントラストの問題を報告します。inspect はタイムラインをシークし、バブル/コンテナからはみ出したりキャンバス外に出たテキストを報告します。さらに、*.motion.json サイドカーが存在する場合、同じシークされたタイムラインに対してモーションインテント(シーク時の出現、スタガー順序、フレーム内、ライブネス)を検証します。
モーション量の多い作業では、スナップショット駆動のイテレーションと *.motion.json サイドカーを推奨します。詳細な規律とモーション検証仕様については references/lint-validate-inspect.md を参照してください。
エージェント規約
すべてのコマンドに適用される横断的ルール:
--jsonは、render、preview、playを除くすべてのコマンドで使用可能です。 サポートされているコマンドのエージェント / CI 呼び出しにはこれを使用してください。出力には_metaエンベロープ(CLI バージョン、利用可能な最新バージョン、アップデートアドバイス)が含まれます。renderは stdout + 終了コードのみでステータスを報告します。以下のレンダリング後チェックで成功を確認してください。preview/playはサーバーであり、JSON 出力はありません。doctor --jsonは、環境が壊れていても常に 0 で終了します。 ペイロードのokフィールドで判定してください:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。これにより、パイプラインが CLI リリースの変動から保護されます。- 非 TTY モードは自動検出されます。 stdout が TTY でない場合(CI、エージェント、パイプ出力)、CLI は自動的に非対話モードに切り替わります。その場合、
initは--exampleを必須とします。TTY 上でもこのモードを強制するには--non-interactiveを渡してください。 - レンダリングの CI ゲーティング:
--strictはリントエラーで失敗し、--strict-allは警告でも失敗し、--strict-variablesは未宣言の--variablesキーで失敗します。 --json内のパスは難読化されます —$HOMEはリテラル$HOMEになるため、出力をバグレポートやエージェントコンテキストに安全に貼り付けることができます。- レンダリングはユーザー承認が必要です。 チェックが通ったら自動レンダリングは絶対に行わないでください。
previewで一時停止し、ビデオが Studio で編集可能であることをユーザーに伝え、ユーザーが承認した場合のみレンダリングしてください。 - レンダリング後検証。
renderが終了コード 0 を返した後、出力ファイルが存在し、妥当なサイズであることを確認してから成功を報告してください:[ -s "$OUTPUT" ] || echo "render produced no output"。CLI は成功時に◇ <path>を出力します。長時間のレンダリングでは、ffprobe -i "$OUTPUT" -show_format -v errorで再生時間も確認してください。
ルーティング
| 目的 | 参照先 |
|---|---|
プロジェクトのスキャフォールド(init、capture、skills) | references/init-and-scaffold.md |
正確性の確認(lint、validate、inspect、snapshot) | references/lint-validate-inspect.md |
プレビューまたはレンダリング(preview、play、render、publish) | references/preview-render.md |
環境の診断(doctor、browser) | references/doctor-browser.md |
AWS Lambda でのクラウドレンダリング(lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
その他(info、upgrade、compositions、docs、benchmark、telemetry、アセット前処理) | references/upgrade-info-misc.md |
スキル間連携
- Tailwind プロジェクト(
init --tailwind)→ クラスやテーマトークンを編集する前に、hyperframes-core(Tailwind リファレンス)を使用してください。 - レジストリブロック/コンポーネント(
hyperframes add、hyperframes catalog)→ インストールパス、サブコンポジションワイヤリング、スニペットマージにはhyperframes-registryを使用してください。 - アセット前処理(
tts、transcribe、remove-background)→ 音声選択、Whisper モデルルール、キャプション、TTS→キャプションチェーンにはhyperframes-mediaを使用してください。 - パラメータ化レンダリング(
--variables)→<html>にdata-composition-variablesとして宣言します。完全なスキーマはhyperframes-coreを参照してください。
Lambda(クラウドレンダリング)
hyperframes lambda は分散レンダリングを AWS Lambda にデプロイし、ラップトップまたは CI からレンダリングを駆動します。エンドツーエンドは 3 つのコマンドです:
npx hyperframes lambda deploy # SAM スタックをプロビジョニング(Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # 破棄(S3 バケットは保持されます)
レンダリングが 1 台のホストでは時間がかかりすぎる / 大きすぎる場合(数分の動画、4K、大規模な並列バッチ)、AWS 認証情報が設定されている場合に Lambda を使用してください。開発ループのイテレーションでは、ローカルの render を使い続けてください。
前提条件、6 つのサブコマンドすべて(deploy、sites create、render、progress、destroy、policies)、IAM ポリシー検証、ステートファイル、およびコスト / クリーンアップルールについては references/lambda.md を参照してください。
最小完了ゲート
静的ゲート
npx hyperframes lint
npx hyperframes validate
レイアウトに関わる作業には inspect を、CI でリントエラー時に失敗させるには render --strict を追加してください。
ビジュアルスモークテスト — プロジェクトがサブコンポジションを使用する場合に必須
lint / validate / inspect は各コンポジションを単独で評価します。これらは index.html を読み込んで data-composition-src を介してサブコンポジションをマウントすることはないため、ファイル間のマウント障害を捕捉できません(hyperframes-core → references/sub-compositions.md の「よくある落とし穴」を参照)。それらを捕捉できる唯一のゲートは、実際に index.html を読み込んでタイムラインをシークするものです。
hyperframes snapshot を使用してください。これは render と同じ方法でプロジェクトを読み込み(したがって同じマウントパスを実行します)、要求したタイムスタンプのみをキャプチャするため、フルレンダリングではなく数秒で完了します:
# 各サブコンポジションの中間点で 1 フレームをキャプチャ。
# 中間点 = index.html の各ホストスロットの data-start + data-duration/2。
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...
# または、シーンごとのターゲット設定が不要な場合、等間隔サンプル:
npx hyperframes snapshot --frames 9
出力は snapshots/frame-NN-at-Xs.png に保存されます。各フレームをシーンプランと照らし合わせて目視確認してください。
フレームごとのレッドフラグ(それぞれ、静的ゲートが見逃す特定の障害モードに対応):
| 見られる状態 | 根本原因 |
|---|---|
| テキストが左上隅に小さくスタイルなしで表示される | <style> ブロックが <template> 外の <head> に残っている(落とし穴 1)— CSS がライブ DOM に到達していない |
| SVG/アイコン要素がキャンバスサイズまで拡大される | 同上 — 幅/高さの制約が適用されていない |
| シーンのヒーロー要素が完全に欠落し、背景と透かしだけが見える | ホスト ID ≠ テンプレート ID(落とし穴 2)— タイムラインが実行されず、初期状態でフレームがキャプチャされた |
スナップショットコマンドが Sub-composition timelines not registered after 45000ms とログ出力 | 落とし穴 2 — 直接的な確認 |
snapshots/ は目視確認後に削除して構いません。最終的なユーザー向けレンダリングは、npx hyperframes render を使用した別のパスです。