HyperFrames CLI
すべての操作は npx hyperframes で実行します。Node.js >= 22 と FFmpeg が必要です。
ワークフロー
- スキャフォールディング —
npx hyperframes init my-video - 作成 — HTMLコンポジションを作成（
hyperframesスキルを参照） - リント —
npx hyperframes lint - プレビュー —
npx hyperframes preview - レンダリング —
npx hyperframes render
プレビューの前にリントを行ってください。data-composition-idの欠落、トラックの重複、未登録のタイムラインを検出します。
スキャフォールディング
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 preview # カレントディレクトリを提供
npx hyperframes preview --port 4567 # カスタムポート（デフォルト3002）
ファイル変更時にホットリロードします。自動的にブラウザでスタジオを開きます。
レンダリング
npx hyperframes render # 標準MP4（自動的にrenders/に出力）
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はレンダリング時間が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 | リントエラーで失敗 |
--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
テキスト読み上げ
npx hyperframes tts "ここにテキスト" --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の欠落、メモリ不足。
落とし穴
--outパスはファイル名ではなくディレクトリである必要があります
npx hyperframes render --out renders/output.mp4 → ✗ エラー: "Not a directory"
npx hyperframes render → ✅ renders/name_timestamp.mp4に自動出力
名前付きファイルパスを指定するには--outではなく--outputを使用します。
index.htmlのルートタイムラインはサブコンポジションのdata-composition-idと一致する必要があります
index.htmlにインラインコンテンツがなくdata-composition-src参照のみ含まれている場合でも、実際のdata-composition-idと一致するwindow.__timelines登録が必要です。ベストプラクティス: window.__timelines['<sub-comp-id>'] = gsap.timeline({paused:true}) を登録します — ただし、サブコンポジションは独自のタイムラインを登録するため、index.htmlのスクリプトブロックはリントを通すためだけに必要です。サブコンポジションのIDを使用します（'root'ではありません）。
サブコンポジションの<div>にはdata-start="0"とdata-durationが必要です
<template>内の<div data-composition-id="...">にはdata-start="0"とdata-duration="N"が必要です。これがないとリントが警告を出し、再生が開始されない可能性があります。
その他
npx hyperframes compositions # プロジェクト内のコンポジションを一覧表示
npx hyperframes docs # ドキュメントを開く
npx hyperframes benchmark . # レンダリングパフォーマンスをベンチマーク