hyperframes-cli

プラグインのインストール： このスキルが HyperFrames プラグイン内にある場合、セットアップまたは最新状態の確認コマンドを実行する前に、プラグイン実行ルールに従ってください。

HyperFrames CLI

プロジェクトにラッパーが用意されていない限り、npx hyperframes <command> を実行してください。ラッパーがある場合は、そちらを使用してください。Node.js 22+ と FFmpeg が必要です。すべてのコマンドで --help が利用でき、ほとんどのコマンドでは --json を指定できます。失敗すると ✗ … と Fix: の行が出力され、ゼロ以外の終了コードで終了します。

用途別コマンド

用途	コマンド
開始する	init <dir>（空の状態で開始。依頼された場合のみ --example <name> を指定）、capture <url>
プロジェクトを読む	info、compositions、timeline --json、docs <topic>
チェックする	作成中は lint、ゲートには check --json（lint、ランタイム、レイアウト、コントラスト）
確認する	snapshot（--at <t,…>、--range START,END、--composition <id>、--zoom、--angle、--against <video>）、keyframes、compare、audio
タイムラインを編集する	move、trim、split、set、duplicate、delete、apply、undo、ids を指定した timeline
再利用する	catalog、add（/hyperframes-registry）
メディアとサウンド	media-treatment、grade-compare、remove-background、tts、transcribe、beats、normalize-audio（/media-use）
表示して納品する	preview、present（/slideshow）、render、publish、cloud、lambda、cloudrun
デスクトップアプリ	open、catch-up
メンテナンス	doctor、browser、upgrade、skills、usage、clean、feedback

validate、inspect、layout は check の非推奨エイリアスです。events はスキル独自のスクリプト用テレメトリです。これらは実行しないでください。

作業の流れ

1. 作成したら、最初のパスの後と構造を変更した後に npx hyperframes lint を実行します。
2. npx hyperframes check --json を実行し、すべてのエラーを修正します。lint エラーが残っている間はレイアウト監査とコントラスト監査が実行されません。「0 samples」は何もチェックされていないことを意味します。コントラストの失敗には suggestedColor が付属します。単一のサンプル（アニメーション中の登場）での指摘は情報です。3 秒以上の動画で視覚的な変化がない場合は sweep_static に失敗します。
3. npx hyperframes snapshot を実行し、PNG（.hyperframes/artifacts/snapshots/ 内）を確認します。動画を見るにはこれが必要です。サブコンポジションがある場合は、各シーンの中間地点をスナップショットします。スタイルが適用されていない小さなコンテンツやヒーローの欠落は、マウントの不具合です（../hyperframes/references/format.md）。
4. npx hyperframes preview --background を実行し、URL が 200 を返すことを確認して、プロジェクトの URL を相手に伝えて返答を待ちます。ただし、ファイルを求められた場合や、停止せず進めるよう求められた場合は除きます。チェックに合格しただけでは、レンダリングする理由にはなりません。
5. レンダリングする段階になったら（ステップ 4）：npx hyperframes render --quality looks --output out.mp4 を実行します（反復中は draft、最終版には delivery を指定します）。ファイルが空でないこと、その ffprobe の再生時間がルートの data-duration と一致することを確認し、デコードしたフレームを確認します。

「この要素」または現在の選択項目を確認するには、npx hyperframes preview --context --json --context-fields selection を実行します。no-selection と表示された場合は、選択項目をクリックするよう相手に依頼してください。

タイムラインを編集する

これらは Studio 自体が行う編集であり、結果は Studio の形式に保たれます。

• timeline --json は、絶対位置の absStart／absEnd、所有する file、編集コマンドが受け取る #id 参照を持つクリップを一覧表示します（timeline ids は不足している ID を付与します）。
• timeline move|trim|split|set|duplicate|delete <ref> … --plan --json は編集内容をプレビューします。実際に編集するには、--plan なしでもう一度実行します。--start、--end、--duration は、それぞれ一方の端または長さを設定します。
• クリップが隣接クリップと重なる場合（--overwrite を指定するか、先に隣接クリップを移動してください）、またはコンポジションの末尾を超える場合、編集は拒否されます。先にルートの data-duration を増やしてください。どのコマンドも data-duration は変更しません。
• 複数の編集をまとめて行うには、[{"verb": "move", "ref": "#outro", "time": "9"}] のような JSON ファイルを作成し、timeline apply plan.json --json を実行します。各実行では receipt が出力されます。これを保存し、timeline undo receipt.json を実行すると元に戻せます。

プロジェクト履歴

すべての書き込みは保存され、元に戻すことができます。ターンの開始時に npx hyperframes history begin --who <you> --label "<plan>" を実行し、続けて history --since mine --who <you> を実行して、相手が変更した内容を確認してください。その編集を基に作業を進めます。チェックに失敗した場合や、悪化したと言われた場合は、history undo --who <you> を実行してください。手作業で元に戻してはいけません。ターンの最後に history end を実行してください。

レンダリング方法

必要なもの	コマンド
ローカル	render --quality looks --output out.mp4（draft、delivery）
再現可能なコンテナ	render --docker --strict --output out.mp4
変数を使った一括処理	render --batch rows.json --output "renders/{name}.mp4"
ローカルの Chrome や FFmpeg が不要なホスト型	cloud render（references/cloud.md）
独自の AWS または GCP	lambda render、cloudrun render（references/lambda.md、references/cloudrun.md）

30 秒の映像は 1〜2 分でレンダリングできます。フォアグラウンドで実行してください。ツールのタイムアウトを超えるレンダリングの場合に限り、デタッチしてください（HYPERFRAMES_RENDER_DETACHED=1、専用のグループを使用し、ログに出力）。その場合は until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done で完了を待ってください。pgrep -f は自分自身のループにも一致し、ツールがタイムアウトするまで待ち続けるため、使用しないでください。

レンダリングの検証後、テレメトリーがオフでない限り、feedback --rating を 1 回送信してください。また、HyperFrames では対応できない依頼があった場合は、その内容も報告してください。詳細は references/feedback.md を参照してください。

コマンドが失敗した場合

症状	対処方法
Chrome が見つからない、または起動しない	npx hyperframes browser ensure を実行してください。doctor --json は常に 0 で終了するため、.ok で判定してください
重いページの準備が時間内に終わらない	check または snapshot の --timeout を大きくしてください
一般的でないコーデックで画面が真っ白になる	--proxy を有効にしたままにしてください（デフォルト）
Linux でレンダリングが遅い	サマリーの 2 行目に screenshot と software gpu と表示されている場合は、低速な処理経路です
capture が失敗する、または BLOCKED.md を書き出す	不完全なファイルは使わず、新しい -o フォルダーに再試行してください
ディスクの空き容量が少ない	clean --dry-run を実行してから clean を実行してください。履歴が保存されている .hyperframes は削除しないでください

リファレンス

コマンドを実行する前に、該当する行を確認してください。

コマンド	参照先
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
beats	references/beats.md
preview、play、render、publish、Studio コンテキスト	references/preview-render.md
doctor、browser	references/doctor-browser.md
auth、cloud、テンプレート変数	references/cloud.md
lambda、cloudrun	references/lambda.md、references/cloudrun.md
info、upgrade、compositions、timeline、docs、usage、テレメトリー	references/upgrade-info-misc.md
--strict フラグ、実行 ID、clean、シェーダーの lint、JSON パス	references/conventions.md
keyframes	../hyperframes/references/motion.md（モーションを見る）