Communitygithub.com

sq-cm/claude-template

HyperFrames CLI 開発ループ — `npx hyperframes` によるスキャフォールディング(init)、検証(lint、validate、inspect)、プレビュー、レンダリング、環境トラブルシューティング(doctor、browser、info、upgrade)。これらのコマンドを実行するとき、または HyperFrames のビルド/レンダリング環境のトラブルシューティングを行うときに使用します。アセット前処理コマンド(`tts`、`transcribe`、`remove-background`)の場合は、代わりに `hyperframes-media` スキルを呼び出してください。

claude-template とは?

このスキルは、HyperFrames CLI の完全な開発ループを提供します。`npx hyperframes` を通じて、プロジェクトのスキャフォールディング(`init`)、静的解析(`lint`)、ランタイム検証(`validate`)、ビジュアルインスペクション(`inspect`)、プレビュー(`preview`)、レンダリング(`render`)をカバーします。Node.js >= 22 と FFmpeg が必要です。 主な機能は以下の通りです。 - スキャフォールディング: `init` でプロジェクト構造、メディアファイル、AI コーディングスキルを自動生成。複数のテンプレートと Tailwind v4 サポートがあります。 - 静的解析: `lint` で `data-composition-id` の欠落、トラックの重複、未登録のタイムラインを検出。 - ランタイム検証: `validate` でヘッドレス Chrome 上で JS コンソールエラー、アセット欠落、WCAG コントラスト問題を報告。 - ビジュアルインスペクション: `inspect` でテキストのはみ出しやクリッピングを検出。 - レンダリング: `render` で様々な品質、FPS、フォーマット(MP4/WebM)に対応。Docker による再現可能な出力、GPU アクセラレーション、パラメータ化レンダリングもサポート。 - トラブルシューティング: `doctor` で Chrome、FFmpeg、Node、メモリをチェック。 Claude Code、Cursor、Codex などの AI エージェントが HyperFrames プロジェクトを効率的に操作できるよう設計されており、各コマンドの実行順序や注意点が詳細に記述されています。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sq-cm/claude-template/tree/HEAD/.claude/skills/hyperframes-cli

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

HyperFrames CLI

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

ワークフロー

  1. スキャフォールディング — npx hyperframes init my-video
  2. 作成 — HTML コンポジションを作成(hyperframes スキルを参照)
  3. リンタ — npx hyperframes lint
  4. ランタイム検証 — npx hyperframes validate
  5. ビジュアルインスペクション — npx hyperframes inspect
  6. プレビュー — npx hyperframes preview
  7. レンダリング — npx hyperframes render

プレビューの前にリンタとインスペクションを実行してください。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 を使用する場合、スキャフォールドは Studio の Tailwind v3 セットではなく、ブラウザランタイムを介した Tailwind v4.2 を使用することに注意してください — 編集前にクラスとテーマトークンの構文を v4 のドキュメントで確認してください。

リンタ

npx hyperframes lint                  # カレントディレクトリ
npx hyperframes lint ./my-project     # 特定のプロジェクト
npx hyperframes lint --verbose        # 情報レベルの検出結果
npx hyperframes lint --json           # 機械可読

index.html と compositions/ 内のすべてのファイルを lint します。エラー(修正必須)、警告(修正推奨)、情報(--verbose で表示)を報告します。

ランタイム検証

npx hyperframes validate                  # カレントディレクトリ
npx hyperframes validate ./my-project     # 特定のプロジェクト
npx hyperframes validate --json           # 機械可読
npx hyperframes validate --timeout 5000   # スクリプト/メディアが遅い場合 (デフォルト 3000 ms)

コンポジションをヘッドレス Chrome で読み込み、JS コンソールエラー、アセット欠落、WCAG コントラスト問題を報告します(コントラストパスをスキップするには --no-contrast)。lint の後、inspect の前に実行してください。

validate は上流で非推奨となり、代わりに npx hyperframes check を使用します。これは lint、ランタイム、レイアウト、モーション、コントラストの検証を1つのブラウザセッションで実行します。どちらでも「lint と validate」チェックリスト項目を満たします。

ビジュアルインスペクション

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)

ファイル変更時にホットリロードされます。ブラウザでスタジオが自動的に開きます。

プロジェクトをユーザーに戻すときは、ソースの 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出力パス
--fps24, 30, 603060fps はレンダリング時間が2倍になります
--qualitydraft, standard, highstandardイテレーション中は draft
--formatmp4, webmmp4WebM は透明度をサポート
--workers1-8 or autoauto各ワーカーが Chrome を起動します
--dockerフラグoff再現可能な出力
--gpuフラグoffGPU アクセラレーションによるエンコード
--strictフラグofflint エラーで失敗
--strict-allフラグoffエラーと警告の両方で失敗
--variablesJSON オブジェクト—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 オブジェクトで、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 .    # レンダリングパフォーマンスをベンチマーク

関連スキル