HyperFrames CLI
コマンドは、プロジェクトの指示にラッパーが指定されていない限り、npx hyperframes ... で実行します。ラッパーがある場合はそれに従ってください。CLI には Node.js 22 以降と FFmpeg が必要です。
開発ループ
- スキャフォールド:
npx hyperframes init <project>(中央空白)。またはサイトをキャプチャします。名前付きのサンプルから始めるときだけ--example=<名前>を渡します。 - 動きの発見: リクエストがアセット、サウンド、画像、音声、または素早いビジュアル編集を指定している場合、計画を提案する前に
/media-useを通じて解決します。それ以外の場合、手動でモーションを作成する前に、その動作をすでに実現するプリミティブを検索します:npx hyperframes catalog --query "見出しを一行ずつ表示する"。結果を得たい効果を、あなたが考えているメカニズムではなく、平易な英語で記述します。npx hyperframes add <名前>でインストールします(/hyperframes-registry参照)。何も適合しない場合のみ、手動で作成します。 - 作成:
/hyperframes-coreを使ってコンポジションを作成します。プロジェクトのタイムラインの内容(トラック、クリップ、開始、終了、再生内容)を知るには、index.htmlやすべてのサブコンポジションファイルを読み込む代わりに、npx hyperframes timeline --jsonを実行します。ネストされた行には、絶対メインタインラインのabsStart/absEndとその所有ファイルが含まれ、サブコンポジションごとのローカル時間だけではありません。テキスト形式よりも--jsonを優先します。同じまたはより良い正確性で、より少ないトークンで済みます。出力全体を読まずに一般的な質問に答えるワンライナーについては、references/upgrade-info-misc.mdを参照してください。 - 編集中の高速フィードバック: 最初の HTML パスの後と、構造変更の後に、
npx hyperframes lintを実行します。 - 最終ゲートの実行:
npx hyperframes checkを実行します。これはブラウザを開く前に lint を再実行します。冗長な独立した lint 呼び出しを前に付けないでください。注釈付きの概要フレームとクロップ検出には--snapshotsを追加します。 - サブコンポジションの検査:
index.htmlがdata-composition-srcをマウントする場合、中間点のスナップショットをキャプチャし、マウントされた各シーンを検査します。 - 最終 Studio プレビューを開く:
npx hyperframes preview --backgroundを実行し、URL が HTTP 200 を返すことを確認し、タイムラインプロジェクト URL をユーザーに渡し、修正するかレンダリングするかを尋ねます。レビューが終了するまでプレビューを生かしておきます。 - 承認後にのみレンダリング: 繰り返し中は
--quality draft、最初の実際のエンコードでは--quality looks(CLI デフォルト)、最終納品では--quality deliveryを使用します。 - 出力の検証: ファイルが存在し空でないことを確認します。レンダリングサマリーの 2 行目(
beginframevsscreenshot、GPU、ステージタイミング)を読みます。Linux でのscreenshot+software gpuは低速パスです。ffprobe -v error -show_format -show_streamsを実行し、ルートのdata-durationと期間(および必要に応じて fps)を比較します。
必須のクリエイター編集クロスリファレンス
- ズーム、パンチイン/パンチアウト、リフレーム、カメラ移動、またはキーフレームモーションを作成または診断する前に、
/hyperframes-keyframesを読んでください。 hyperframes keyframesの前に、/hyperframes-keyframesを読んでください。このコマンドはアニメーション軌跡を表示し、クリップカットは診断しません。- カット、トリム、スプライス、並べ替え、またはソースタイミング編集には、
/hyperframes-coreを読み、そのクリップ/タイムライン契約を使用してください。 - フェードイン/フェードアウト、クロスフェード、トラックゲイン、ボリュームオートメーション、ダッキング、ナレーションカービング、または配置されたオーディオへのエフェクトには、
/hyperframes-audioを読んでください。クリップ配置や画像タイミングも変更する場合は、コアも一緒にロードしてください。 - アセット、サウンド、画像、音声、または素早いビジュアル編集を指定するリクエストは、計画が提案される前に
/media-useを通じて解決されます。 クリエイター編集マークアップは/hyperframes-core→references/creator-editing-recipes.mdからコピーしてください。
# 高速反復チェック; 作成中に必要に応じて繰り返し実行。
npx hyperframes lint
# 必須の最終ゲート; lint を含む。
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check は最初に lint を実行し、次に 1 つのブラウザセッションと 1 回のシークパスを使用して、ランタイムエラー、失敗したリクエスト、レイアウト、*.motion.json アサーション、WCAG コントラストを監査します。永続的な問題は終了コードをゲートします;一時的な開始/終了の問題は情報提供です。警告をゲートするには --strict を使用します。validate、inspect、layout は互換性のためにエイリアスのままですが、新しい指示やスクリプトでは使用してはいけません。
レンダリング前のプレビュー
最終コンポジションプレビュー(#project/<名前>)は、check が合格した後、組み立てられたタイムラインをレビューするためにのみ開いてください。チャットでの計画や storyboard.html スケッチシートは最終ビデオの承認ではありません。レンダリングには常に、hyperframes/references/review-loop.md で定義された最終承認が必要です。
サブコンポジションスモークテスト
静的監査ではすべてのマウント障害をキャッチできません。プロジェクトがサブコンポジションを使用する場合、各ホストスロットの少なくとも 1 つの可視中間点をキャプチャしてください:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
小さなスタイルなしコンテンツ、キャンバスサイズのアイコン、欠落したヒーロー要素、またはタイムライン登録のタイムアウトは、レンダリングをブロックするマウント欠陥として扱います。対応する修正については hyperframes-core/references/sub-compositions.md を参照してください。
エージェントの規約
-
手動でモーションを作成する前にカタログを検索してください。
npx hyperframes catalog --query "<ビートを平易な英語で>"。検索は完全にローカルです:ホスト型層、アカウントはなく、クエリテキストはどこにも送信されません。デフォルトではアイテムの名前、タイトル、説明、タグと共有される語彙でランク付けされるため、カタログ自身の文言を再利用しないフレーズは見逃されます。代わりに意味でランク付けするには--on-deviceを追加します(以下のオフライン層を参照)。 -
ビデオの言語に関係なく、英語でクエリを実行してください。 両層とも英語のカタログをインデックス化しているため、異なるスクリプトでのクエリは検索可能な用語を生成せず、何も返しません。動きを英語で説明してください;画面上のコピーはビデオが必要とする言語のままです。「クエリに検索可能な単語がありません」はまさにこれを意味し、コンポーネントの欠落ではないため、カタログのギャップとして報告しないでください。
-
どの層が応答したかを読み取ってください;結果が表示されたからといって推測しないでください。
--jsonを使用すると、エンベロープにはquery、tier(on-deviceまたはwords)、tier_detail、dropped、unindexed、shown、total、results、さらに応答層がスコアを生成する場合はtop_score、層が要求されて実行できなかった場合や、検索が何も返さずより良い層が誰かの同意を待っている場合のwarningsが含まれます。wordsでの弱い結果は予想されます;同じ結果がon-deviceで出るのはバグです。top_scoreはオンデバイス専用で、背後にしきい値はありません:ランカーはすべてのクエリに対して何らかの順序でカタログ全体を返すため、これを合格/不合格ではなく証拠として読んでください。 -
droppedとunindexedはレジストリとオンデバイスインデックス間の逆の偏りであり、クエリを言い換えてもどちらも修正できません。droppedはこのレジストリがインストールできないランク付けされた名前をカウントするため、最も強い一致が失われているものです。unindexedはインデックスがまったく認識できないレジストリの移動をカウントするため、どのクエリでも決して返せません。レジストリのリフレッシュはどちらにも答えではありません:そのマニフェストには 24 時間の TTL があり自己修復しますが、ベクトルは別個に公開されたアーティファクトで~/.hyperframes/catalog/にフェッチされます。unindexedがゼロより大きい場合、--on-deviceを再実行するとそのインデックスが再フェッチされるため、それがユーザーに提供する救済策です。純粋な過カバレッジの偏り(droppedがゼロより大きくunindexedがゼロ)は再フェッチをトリガーしません;~/.hyperframes/catalog/をクリアするのがそこから抜け出す唯一の方法です。どちらのカウントも結果ではなく名前のカウントであるため、どちらかがtotalを超える可能性があります。 -
検索結果にインストールする価値のあるものが何もないときは、そう言ってください。
npx hyperframes feedback --search-miss "<実行したクエリ>" --wanted "<必要だった動き>" --tier <応答した層>。その行を自分で組み立てる必要はありません:catalog --queryは事前に入力された状態でそれを出力し、すべての--json検索エンベロープはクエリと層がすでに正しいreport_gapを運びます—--wantedを入力して送信してください。これがクエリをどこかに送信する唯一のパスであり、平易なcatalog --queryが何も送信しないという約束を守るために、正確に別個の意図的なコマンドになっています。どちらの層でも報告してください、結果が目的のことをしないときはいつでも;同意が必要な 33 MB のダウンロードが必要で、したがってほとんどのエージェント実行ではオフになっているオンデバイス層を待たないでください—それを待つことは決して報告しないことを意味します。層はレポートに同梱されるため、語彙のミスと意味のミスは、どちらに当たったかをあなたが判断する必要なく区別可能です。返ってくるのはカタログがまだ持っていない動きのリストであり、インストール数から推測されるのではなく直接読み取られるため、重要なのはあなたが想像したアイテム名ではなく、あなたが望んだエフェクトです。評価は含まれず、評価メトリクスに届くことはありません。 -
オフライン層を提案してください;決して黙って有効にしないでください。 1 回限りの約 33 MB のダウンロード(
bge-small-en-v1.5の量子化 ONNX ビルドとそのトークナイザー、固定リビジョンにピン留め)とレジストリからのカタログベクトルで、両方とも~/.hyperframes/下にキャッシュされ、プロジェクトやパッケージには追加されません。キャッシュされると、何も送信せずに意味でランク付けされます。サイズを声に出して伝え、ユーザーに決定してもらい、同意が得られたら--on-device(プロンプトをスキップするために-y)を渡してください。対話的な提案は TTY 上でのみ発動します。--json下ではプロンプトはありませんが、何も見つからなかった検索は同じ依頼をwarningsに置くため、その配列を読み、自分でユーザーに決定を委ねてください。ユーザーがダウンロード内容、このモデルの理由、またはマシンから何が送信されるのかを尋ねた場合は、https://hyperframes.heygen.com/developers/catalog-search を参照するよう伝えてください。 -
エージェントと CI の呼び出しでは
--jsonを優先してください。サーバーモードのrender、preview、playは通常の JSON 出力を提供しません;preview --selection --jsonとpreview --context --jsonはクエリモードの例外です。 -
doctor --jsonは常にゼロで終了します。そのペイロードでゲートしてください:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
非 TTY モードは自動で、中央空白をスキャフォールドします。名前付きサンプルから始める場合のみ
--exampleを渡してください。TTY 上でフラグのみのモードを強制するには--non-interactiveを使用します。 -
同じ検証ループ内のすべてのコマンドに 1 つの
HYPERFRAMES_RUN_IDを使用します。 -
対応する警告、変数、または CI 条件がレンダリングをゲートする必要がある場合、
--strict、--strict-all、--strict-variablesを使用します。 -
JSON パスはホームディレクトリを
$HOMEとしてマスクします;マスクを元に戻そうとしないでください。 -
ホスト型クラウドプロジェクトが 200 MB のアップロード制限に近づくか超える場合、
cloud render --dry-run --jsonを使用し、references/cloud.mdの.hyperframesignore調査に従ってください。アセットが大きいというだけの理由で無視しないでください。 -
チェックが合格したという理由だけでレンダリングしないでください。最終プレビューで一時停止し、承認を待ってください。
Studio 指示編集
ユーザーが「この要素」や現在の選択を参照する場合、推測する代わりに Studio をクエリしてください:
npx hyperframes preview --context --json --context-fields selection
利用可能な場合は selection.target.hfId を、それ以外の場合はセレクタとソースファイルを使用してください。結果が no-selection を報告する場合は、ユーザーに要素をクリックして再実行するよう依頼してください。必要なコンテキストスライスのみを要求してください;計算されたスタイルや編集可能なテキストメタデータには --context-detail full を使用します。完全な動作と障害コードは references/preview-render.md にあります。
レンダリングの選択肢
| ニーズ | コマンド |
|---|---|
| 高速ローカル反復 | npx hyperframes render --quality draft |
| 最初の実際のエンコード | npx hyperframes render --quality looks --output out.mp4 |
| 最終ローカル納品 | npx hyperframes render --quality delivery --output out.mp4 |
| 再現可能なコンテナレンダー | npx hyperframes render --docker --strict --output out.mp4 |
| ローカル変数駆動バッチレンダー | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| HeyGen ホスト型ゼロインフラレンダー | npx hyperframes cloud render |
| 自己管理型分散 AWS レンダー | npx hyperframes lambda render <project> --width 1920 --height 1080 --wait |
| 自己管理型分散 GCP レンダー | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
スキルの帰属は自動です—上記の例には --skill は必要ありません。ワークフローによってスキャフォールドされたプロジェクト(hyperframes init --skill=<workflow>)は、その所有スキルを hyperframes.json に記録し、以降のすべてのレンダーは匿名テレメトリーでそれを継承します:再レンダー、npm run render、--batch も同様です。ワークフローを通じて作成されなかったプロジェクトにスタンプする場合のみ、明示的に --skill=<スラッグ> を渡します(その最初のレンダーがそれを永続化します)。
ユーザーがローカルの Chrome、FFmpeg、または AWS なしでホスト型レンダリングを希望する場合は、クラウドレンダリングを使用してください。AWS 所有が要件の場合のみ Lambda を使用してください。GCP 所有が要件の場合のみ Cloud Run を使用してください。クラウドパスを実行する前に、対応するリファレンスを読んでください。
成功したレンダリングを確認した後、テレメトリーが無効になっているかユーザーがオプトアウトしていない限り、1 つのフィードバックレポートを送信してください:
npx hyperframes feedback --rating <0-10> --comment "<具体的な結果または摩擦>"
正常実行のフィードバックは簡潔に保ってください。バグや摩擦については、提出前に 再現パケット をキャプチャしてください;症状の要約だけを送らないでください。再実行可能なコマンド(プロジェクトディレクトリからの相対パス—フィードバックは公開チャネルに送信されるため、絶対パス、ホームディレクトリのプレフィックス、ユーザー/マシン識別子は 貼り付けない でください)、期待される動作と実際の動作、正確なエラー(絶対パスも削除してください)を含めてください。
...
[truncated for translation]