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 を追加すると、警告でも失敗します。繰り返し発生する静的な問題はデフォルトで折りたたまれ、JSON 出力は LLM のコンテキストウィンドウに対してコンパクトに保たれます。オーバーフローが出入りアニメーションのために意図的である場合は、要素または祖先に data-layout-allow-overflow をマークします。装飾要素を監査する必要がない場合は、data-layout-ignore をマークします。
互換性エイリアスとして、npx hyperframes layout も同じビジュアルインスペクションパスで使用可能です。
プレビュー
npx hyperframes preview # カレントディレクトリを配信
npx hyperframes preview --port 4567 # カスタムポート（デフォルトは 3002）
ファイル変更時にホットリロードします。ブラウザでスタジオを自動的に開きます。
プロジェクトをユーザーに渡すときは、ソースの 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/name_timestamp.mp4 | 出力パス |
--fps | 24, 30, 60 | 30 | 60fps はレンダリング時間が倍増 |
--quality | draft, standard, high | standard | draft はイテレーション用 |
--format | mp4, webm | mp4 | WebM は透明度をサポート |
--workers | 1-8 または auto | auto | 各ワーカーが Chrome を起動 |
--docker | フラグ | off | 再現可能な出力 |
--gpu | フラグ | off | GPU アクセラレーションエンコード |
--strict | フラグ | off | lint エラーで失敗 |
--strict-all | フラグ | off | エラーと警告の両方で失敗 |
--variables | JSON オブジェクト | — | data-composition-variables で宣言された変数値を上書き |
--variables-file | パス | — | 変数値の JSON ファイル（--variables の代替） |
--strict-variables | フラグ | off | --variables で宣言されていないキーや型の不一致でレンダリングを失敗 |
品質ガイダンス: イテレーション中は draft、レビュー用は standard、最終納品は high。
パラメータ化されたレンダリング: コンポジションは <html> ルートに data-composition-variables で変数を宣言します — スキーマを定義する JSON 宣言の配列（エントリごとに {id, type, label, default}）です。内部のスクリプトは window.__hyperframes.getVariables() で解決された値を読み取ります。CLI の --variables '{"title":"Q4 Report"}' は id をキーとする JSON オブジェクト で、宣言されたデフォルトをそのレンダリングで上書きします。欠落したキーはそのままフォールスルーされるため、同じコンポジションが開発プレビューと本番の両方で変更なく動作します。（サブコンポジションホストは data-variable-values でインスタンスごとに上書きすることもできます — 同じオブジェクト形状で、サブコンポジションの1つのマウントにスコープされます。完全なパターンについては hyperframes スキルを参照してください。）
アセット前処理
npx hyperframes tts, transcribe, remove-background はアセット（ナレーション音声、ワードレベルのトランスクリプト、透明動画）を生成し、コンポジションにドロップします。それぞれ初回実行時にモデルをダウンロードします。音声選択、Whisper モデルのルール（非英語を .en が翻訳する落とし穴）、出力形式の選択（VP9 アルファ WebM と 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 . # レンダリングパフォーマンスのベンチマーク