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 は、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 --non-interactive # プロンプトをスキップ(CI/エージェント向け)
テンプレート: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph。
init は正しいファイル構造を作成し、メディアをコピーし、Whisperで音声を文字起こしし、AIコーディングスキルをインストールします。ファイルを手動で作成する代わりに使用してください。
リンティング
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)
ファイル変更時にホットリロードされます。ブラウザで自動的にスタジオが開きます。
プロジェクトをユーザーに引き継ぐ際は、ソースの index.html パスではなく、スタジオのプロジェクト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はレンダリング時間が倍増 |
--quality | draft, standard, high | standard | draftはイテレーション用 |
--format | mp4, webm | mp4 | WebMは透明度をサポート |
--workers | 1-8 または auto | auto | 各ワーカーがChromeを起動 |
--docker | フラグ | off | 再現可能な出力 |
--gpu | フラグ | off | GPUアクセラレーションエンコード |
--strict | フラグ | off | リントエラーで失敗 |
--strict-all | フラグ | off | エラーと警告で失敗 |
品質ガイダンス: イテレーション中は draft、レビュー用は standard、最終納品用は high を使用してください。
文字起こし
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # 既存の字幕をインポート
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
テキスト読み上げ(TTS)
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # 全ボイスを表示
トラブルシューティング
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 . # レンダリングパフォーマンスをベンチマーク