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スキルを参照) - Lint —
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はlintエラーで失敗、--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バケットは保持)
Lambdaは、レンダリングが1台のホストでは長時間/大規模すぎる場合(数分の動画、4K、大規模な並列バッチ)で、AWS認証情報が設定されている場合に使用します。開発ループの反復作業はローカルの render を継続してください。
前提条件、6つすべてのサブコマンド(deploy、sites create、render、progress、destroy、policies)、IAMポリシーの検証、ステートファイル、コスト/クリーンアップルールについては references/lambda.md を参照してください。
最小完了ゲート
静的ゲート
npx hyperframes lint
npx hyperframes validate
レイアウトに影響する作業には inspect を追加し、CIでは lint エラー時に失敗させるために 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> ブロックが <head> に残り <template> の外にある(落とし穴1)— CSSがライブDOMに到達していない |
| SVG/アイコン要素がキャンバスサイズに拡大表示される | 同上 — 幅/高さの制約が適用されていない |
| シーンの主要要素が完全に欠落し、背景とウォーターマークのみ表示される | Host-id ≠ テンプレートid(落とし穴2)— タイムラインが実行されず、初期状態のフレームがキャプチャされた |
スナップショットコマンドが Sub-composition timelines not registered after 45000ms とログ出力 | 落とし穴2 — 直接的な確認 |
snapshots/ は目視確認後に削除して構いません。最終的なユーザー向けレンダリングは npx hyperframes render で別途実行します。