HyperFrames CLI
すべての操作は npx hyperframes で実行します。Node.js >= 22 と FFmpeg が必要です。
ワークフロー
- スキャフォールディング —
npx hyperframes init my-video - 作成 — HTML コンポジションを記述 (
hyperframesスキルを参照) - リント —
npx hyperframes lint - ビジュアルインスペクト —
npx hyperframes inspect - プレビュー —
npx hyperframes preview - レンダリング —
npx hyperframes render
プレビューの前に lint と inspect を実行してください。lint は不足している data-composition-id、重複トラック、未登録タイムラインを検出します。inspect はヘッドレス Chrome でレンダリングコンポジションを開き、タイムラインをスキャンし、吹き出しやコンテナの外、またはキャンバスからはみ出したテキストを報告します。
スキャフォールディング
npx hyperframes init my-video # 対話型ウィザード
npx hyperframes init my-video --example warm-grain # サンプルを選択
npx hyperframes init my-video --video clip.mp4 # 動画ファイルを指定
npx hyperframes init my-video --audio track.mp3 # 音声ファイルを指定
npx hyperframes init my-video --example blank --tailwind # Tailwind v4 ブラウザランタイムを指定
npx hyperframes init my-video --non-interactive # プロンプトをスキップ (CI/エージェント)
テンプレート: blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。
init は適切なファイル構造を作成し、メディアをコピーし、Whisper で音声を文字起こしし、AI コーディングスキルをインストールします。手動でファイルを作成する代わりにこれを使用してください。
--tailwind を使用する場合は、クラスやテーマトークンを編集する前に tailwind スキルを呼び出してください。スキャフォールディングは Studio の Tailwind v3 セットアップではなく、ブラウザランタイムを介した Tailwind v4.2 を使用します。
リント
npx hyperframes lint # カレントディレクトリ
npx hyperframes lint ./my-project # 特定のプロジェクト
npx hyperframes lint --verbose # 情報レベルの検出結果
npx hyperframes lint --json # 機械可読形式
index.html と compositions/ 内のすべてのファイルをリントします。エラー (修正必須)、警告 (修正推奨)、および情報 (--verbose 使用時) を報告します。
ビジュアルインスペクト
npx hyperframes inspect # レンダリングレイアウトをタイムライン上で検査
npx hyperframes inspect ./my-project # 特定のプロジェクト
npx hyperframes inspect --json # エージェント可読の検出結果
npx hyperframes inspect --samples 15 # より密なタイムラインスキャン
npx hyperframes inspect --at 1.5,4,7.25 # 明示的なヒーローフレームのタイムスタンプ
lint と validate の後、特に吹き出し、カード、キャプション、タイトなタイポグラフィが含まれるコンポジションで使用します。以下を報告します。
- 最も近いビジュアルコンテナまたは吹き出しの外側に延びているテキスト
- 自身の固定幅/固定高さのボックスでクリップされているテキスト
- コンポジションキャンバスの外側に延びているテキスト
- クリッピングコンテナからエスケープしている子要素
エラーはレンダリング前に修正する必要があります。警告はエージェントによるレビューのために表示されます。警告でも失敗させるには --strict を追加します。繰り返し発生する静的問題はデフォルトで折りたたまれ、LLM のコンテキストウィンドウのために JSON 出力をコンパクトに保ちます。オーバーフローがエントランス/イグジットアニメーションで意図的である場合は、要素または祖先に data-layout-allow-overflow をマークします。装飾要素を監査対象から除外するには、data-layout-ignore をマークします。
npx hyperframes layout は、同じビジュアルインスペクションパスの互換性エイリアスとして引き続き使用できます。
プレビュー
npx hyperframes preview # カレントディレクトリを提供
npx hyperframes preview --port 4567 # カスタムポート (デフォルト 3002)
ファイルの変更時にホットリロードします。ブラウザで Studio が自動的に開きます。
プロジェクトをユーザーに引き渡すときは、ソースの index.html パスではなく、Studio プロジェクト URL を使用してください。
http://localhost:<port>/#project/<project-name>
プレビュー出力の実際のポートとプロジェクトディレクトリ名を使用します。たとえば、codex-openai-video で npx hyperframes preview --port 3017 を実行した後、http://localhost:3017/#project/codex-openai-video を報告します。
index.html はソースコードのコンテキストとしてのみ扱います。実装ファイルとしてリンクすることは問題ありませんが、プロジェクトやプレビュー画面としてラベル付けしないでください。
レンダリング
npx hyperframes render # 標準 MP4
npx hyperframes render --output final.mp4 # 名前付き出力
npx hyperframes render --quality draft # 高速イテレーション
npx hyperframes render --fps 60 --quality high # 最終納品
npx hyperframes render --format webm # 透明 WebM
npx hyperframes render --docker # バイト同一
| フラグ | オプション | デフォルト | 備考 |
|---|---|---|---|
--output | パス | renders/名前_タイムスタンプ.mp4 | 出力パス |
--fps | 24, 30, 60 | 30 | 60fps はレンダリング時間が 2 倍になります |
--quality | draft, standard, high | standard | draft はイテレーション用 |
--format | mp4, webm | mp4 | WebM は透明度をサポート |
--workers | 1-8 または auto | auto | 各ワーカーは Chrome を起動します |
--docker | フラグ | オフ | 再現可能な出力 |
--gpu | フラグ | オフ | GPU アクセラレーションによるエンコーディング |
--strict | フラグ | オフ | リントエラーで失敗 |
--strict-all | フラグ | オフ | エラーと警告の両方で失敗 |
--variables | JSON オブジェクト | — | data-composition-variables で宣言された変数値を上書き |
--variables-file | パス | — | 変数値を含む JSON ファイル (--variables の代替) |
--strict-variables | フラグ | オフ | --variables で未宣言のキーや型の不一致がある場合にレンダリングを失敗 |
品質ガイダンス: イテレーション中は draft、レビュー用は standard、最終納品用は high。
パラメトリックレンダリング: コンポジションは <html> ルートで data-composition-variables を使用して変数を宣言します。これは宣言の JSON 配列 ({id, type, label, default} をエントリごとに) であり、スキーマを定義します。内部のスクリプトは window.__hyperframes.getVariables() を介して解決された値を読み取ります。CLI の --variables '{"title":"Q4 レポート"}' は id をキーとする JSON オブジェクト で、1 回のレンダリングのために宣言されたデフォルトを上書きします。欠落したキーはそのままになるため、同じコンポジションが開発プレビューと本番の両方で変更なしで実行されます。(サブコンポジションホストは、data-variable-values を使用してインスタンスごとに上書きすることもできます。これは同じオブジェクト形状で、サブコンポジションの 1 つのマウントにスコープされます。完全なパターンについては hyperframes スキルを参照してください。)
アセット前処理
npx hyperframes tts、transcribe、remove-background はアセット (ナレーション音声、単語レベルのトランスクリプト、透明動画) を生成し、コンポジションにドロップされます。各コマンドは初回実行時に独自のモデルをダウンロードします。音声選択、Whisper モデルのルール (.en が非英語を翻訳するという落とし穴)、出力形式の選択 (VP9 アルファ WebM vs ProRes)、TTS → 文字起こし → キャプションのチェーンについては、hyperframes-media スキルを呼び出してください。
トラブルシューティング
npx hyperframes doctor # 環境をチェック (Chrome, FFmpeg, Node, メモリ)
npx hyperframes browser # バンドルされた Chrome を管理
npx hyperframes info # バージョンと環境の詳細
npx hyperframes upgrade # アップデートを確認
レンダリングに失敗した場合は、最初に doctor を実行してください。一般的な問題: FFmpeg の欠落、Chrome の欠落、メモリ不足。
その他
npx hyperframes compositions # プロジェクト内のコンポジションを一覧表示
npx hyperframes docs # ドキュメントを開く
npx hyperframes benchmark . # レンダリングパフォーマンスのベンチマーク