hyperframes-cli

HyperFrames CLI

すべての操作は npx hyperframes で実行します。Node.js >= 22 と FFmpeg が必要です。

ワークフロー

1. スキャフォールド — npx hyperframes init my-video
2. 作成 — HTML コンポジションを作成します（hyperframes スキルを参照）
3. Lint — npx hyperframes lint
4. 目視検査 — npx hyperframes inspect
5. プレビュー — npx hyperframes preview
6. レンダリング — npx hyperframes render

プレビューの前に lint と inspect を実行してください。lint は、data-composition-id の不足、トラックの重複、未登録のタイムラインを検出します。inspect は、ヘッドレス Chrome でレンダリング済みのコンポジションを開き、タイムラインをシークして、吹き出しやコンテナからテキストがはみ出していないか、またはキャンバス外にはみ出していないかを報告します。

スキャフォールディング

npx hyperframes init my-video                        # interactive wizard
npx hyperframes init my-video --example warm-grain   # pick an example
npx hyperframes init my-video --video clip.mp4        # with video file
npx hyperframes init my-video --audio track.mp3       # with audio file
npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)

テンプレート：blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。

init は適切なファイル構成を作成し、メディアをコピーし、Whisper で音声を書き起こして、AI コーディングスキルをインストールします。ファイルを手作業で作成するのではなく、init を使用してください。

--tailwind を使用する場合は、クラスやテーマトークンを編集する前に tailwind スキルを実行してください。スキャフォールドでは Studio の Tailwind v3 構成ではなく、ブラウザーランタイム経由で Tailwind v4.2 を使用します。

Lint

npx hyperframes lint                  # current directory
npx hyperframes lint ./my-project     # specific project
npx hyperframes lint --verbose        # info-level findings
npx hyperframes lint --json           # machine-readable

index.html と compositions/ 内のすべてのファイルを lint します。エラー（必ず修正）、警告（修正を推奨）、情報（--verbose を指定した場合）を報告します。

目視検査

npx hyperframes inspect                 # inspect rendered layout over the timeline
npx hyperframes inspect ./my-project    # specific project
npx hyperframes inspect --json          # agent-readable findings
npx hyperframes inspect --samples 15    # denser timeline sweep
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps

lint と validate の後に実行してください。特に、吹き出し、カード、キャプション、または文字組みが詰まったコンポジションで有用です。次の内容を報告します。

• テキストが最も近い視覚的コンテナまたは吹き出しの外にはみ出している
• テキストが固定幅または固定高さのボックス内で切れている
• テキストがコンポジションのキャンバス外にはみ出している
• 子要素がクリッピングコンテナからはみ出している

レンダリング前にエラーを修正してください。警告はエージェントによる確認用に表示されます。警告でも失敗させるには --strict を追加してください。LLM のコンテキストウィンドウで JSON 出力が簡潔に保たれるよう、繰り返し発生する静的な問題はデフォルトでまとめられます。出入りのアニメーションで意図的にはみ出させる場合は、要素または祖先要素に data-layout-allow-overflow を指定してください。装飾要素を監査対象から除外するには、data-layout-ignore を指定してください。

npx hyperframes layout は、同じ目視検査を実行する互換性エイリアスとして引き続き使用できます。

プレビュー

npx hyperframes preview                   # serve current directory
npx hyperframes preview --port 4567       # custom port (default 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                                # standard MP4
npx hyperframes render --output final.mp4             # named output
npx hyperframes render --quality draft                # fast iteration
npx hyperframes render --fps 60 --quality high        # final delivery
npx hyperframes render --format webm                  # transparent WebM
npx hyperframes render --docker                       # byte-identical

フラグ	オプション	デフォルト	備考
--output	パス	renders/name_timestamp.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	フラグ	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"}'は、1回のレンダリングで宣言済みのデフォルト値を上書きする、idをキーとするJSONのオブジェクトです。指定されていないキーはデフォルト値が使われるため、同じコンポジションを変更せずに開発プレビューと本番環境の両方で実行できます。（サブコンポジションのホストでは、data-variable-values**を使用してインスタンスごとに上書きすることもできます。オブジェクトの形式は同じで、サブコンポジションのマウントごとに適用されます。詳しくはhyperframesスキルをご覧ください。）

アセットの前処理

npx hyperframes tts、transcribe、remove-backgroundは、コンポジションに追加するアセット（ナレーション音声、単語レベルのトランスクリプト、背景を透明化した動画）を生成します。初回実行時には、それぞれ独自のモデルをダウンロードします。音声の選択、Whisperのモデルに関する注意点（.enが英語以外を翻訳してしまう問題）、出力形式の選択（VP9アルファWebMとProRes）、およびTTS → 文字起こし → キャプションの一連の流れについては、hyperframes-mediaスキルを呼び出してください。

トラブルシューティング

npx hyperframes doctor       # check environment (Chrome, FFmpeg, Node, memory)
npx hyperframes browser      # manage bundled Chrome
npx hyperframes info         # version and environment details
npx hyperframes upgrade      # check for updates

レンダリングに失敗した場合は、まずdoctorを実行してください。よくある問題：FFmpegがない、Chromeがない、メモリ不足。

その他

npx hyperframes compositions   # list compositions in project
npx hyperframes docs           # open documentation
npx hyperframes benchmark .    # benchmark render performance