HyperFrames CLI
マーケティングエンジンパイプライン向けの npx hyperframes ラッパー。Node.js 22 以上と FFmpeg が PATH に必要です(npx hyperframes doctor で確認)。すべてのコマンドはデフォルトで DRY_RUN セーフモードで実行されます。lint/inspect パスは外部呼び出しを行いません。render のみ MP4 を書き込みます。
呼び出しタイミング
hyperframes-prompt-builderがoutputs/<client>/<date>/<piece-id>/以下にプロジェクトを生成した直後。- コンポジションを公開前に検証する必要がある場合(
lint+inspect)。 - 作品の反復作業中にローカルプレビューを行う場合(
preview)。 - 公開ステップで受け取る成果物を生成する最終レンダリング時(
render)。 - レンダリングが失敗した場合の環境トラブルシューティング時(
doctor、browser、info)。
入力
project_path: 文字列。HyperFrames プロジェクトへのパス(index.htmlとcomposition.jsonが含まれている必要があります)。mode:"lint" | "inspect" | "preview" | "render" | "doctor"。render_opts: オブジェクト、オプション、mode = "render"の場合のみ。認識されるキー:fps: 24 | 30 | 60(デフォルト 30)。quality:"draft" | "standard" | "high"(デフォルト"standard"。反復作業中は"draft"を使用)。format:"mp4" | "webm"(デフォルト"mp4")。variables: オブジェクト。変数 ID をキーとする JSON オブジェクトで、data-composition-variablesのデフォルトを上書きします。strict: ブール値。--strictにマッピング。パイプラインではデフォルトtrue— lint エラーでレンダリングを失敗させます。strict_variables: ブール値。--strict-variablesにマッピング。作品実行ではデフォルトtrue。workers: 整数 1〜8 または"auto"。デフォルト"auto"。output: 文字列。outputs/<client>/<date>/<piece-id>/内の出力ファイルパス。
処理手順
- 環境確認 セッションの初回実行時:
npx hyperframes doctor。FFmpeg または Chrome が不足している場合はハードブロックとして表示 — レンダリングを試行しない。 - Lint。
npx hyperframes lint <project_path> --json。errorレベルのすべての検出結果をブロッカーとして扱う。警告はオーケストレーターに通知;オペレーターに判断させる。 - Inspect。
npx hyperframes inspect <project_path> --json。レンダリング前に、報告されたテキストあふれやキャンバスエスケープを解決する。あふれが要素の出入りの意図的なものである場合、その要素にdata-layout-allow-overflowを(または装飾要素の場合は祖先にdata-layout-ignoreを)マークする — ルールをグローバルに抑制しない。 - プレビュー(オペレーターのみ)。
npx hyperframes preview <project_path> --port <port>。Studio プロジェクト URL(http://localhost:<port>/#project/<project-name>)を返す。ソースのindex.htmlパスではない。 - レンダリング。
npx hyperframes render <project_path>をrender_optsから解決されたフラグとともに実行。render_opts.variablesから--variables引数を単一行 JSON 文字列で構築する。作品実行では常に--strictと--strict-variablesを渡す。 - 出力確認。 レンダリング後、MP4 が存在し、サイズがゼロでないことを確認する。
data/video-usage.jsonlに{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }の形式でログを記録する。
出力
lint:{ pass: ブール値, errors: [...], warnings: [...] }。inspect:{ pass: ブール値, findings: [...] }。render:{ artifact_path: 文字列, duration_s: 数値, file_bytes: 数値, render_ms: 数値 }。preview:{ url: 文字列 }。
コマンドチートシート
npx hyperframes init <name> # スキャフォールディング(プロンプトビルダーが各作品で1回使用)
npx hyperframes lint <path> # マークアップの検証
npx hyperframes inspect <path> # レイアウト/あふれの監査
npx hyperframes preview <path> --port 3017 # ローカル開発
npx hyperframes render <path> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<client>/<date>/<piece-id>/final.mp4
npx hyperframes doctor # 環境チェック
npx hyperframes info # バージョン/環境詳細
非交渉ルール
lintとinspectのパスが合格していない状態でレンダリングを行わないこと。パイプラインには、不正な構成に対する回復パスはない。- lint または inspect の検出結果をグローバルに抑制しないこと — マークアップを修正するか、特定の要素を
data-layout-allow-overflow/data-layout-ignoreで許可リストに追加する。 - 変数が宣言されている作品では、常に
--strict-variablesを渡すこと。変数 ID のタイプミスは静かにデフォルトにフォールスルーするのではなく、明確に失敗しなければならない。 - 最終納品用レンダリングでは
--quality high。反復ループでは--quality draftを使用して計算リソースを節約する。 - アセットの前処理(
tts、transcribe、remove-background)はこのスキルの範囲外 — 将来のhyperframes-mediaスキルを通じて呼び出し、ここにインライン化しない。
障害モード
doctorが FFmpeg または Chrome の不足を報告:プロジェクトのセットアップ手順に従ってインストールする;回避策をとらない。renderがunknown variableで失敗:--variablesで渡されたキーがdata-composition-variablesで宣言されていない。マークアップを修正するか、上書きを削除する。renderが壁時間予算を超過:--qualityをstandardに下げるか、コンポジションをサブコンポジションに分割し、--workersで並列化する。- 出力 MP4 のサイズがゼロ:
doctorを再実行;ほとんどの場合、キャプチャ中の Chrome クラッシュが原因。
関連スキル
hyperframes: コンポジション作成ルール;このスキルが検証・レンダリングするプロジェクトを生成する。hyperframes-prompt-builder: ブリーフ → コンポジション仕様;このスキルの前に実行される。qa-tech-specs: このスキルの後に、レンダリングされた MP4 に対して実行され、プラットフォーム仕様を検証する。
アップストリームリファレンス
すべてのフラグ、トラブルシューティングマトリックス、パラメータ化レンダリングを含む完全なアップストリームスキル:https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli