Hyperframes Bridge
オーケストレーション元: SKILL 外部依存ラッパー. 実際のHyperframesモノレポは
../../external/hyperframes/にあります(/amw-initステップ6でユーザーがオプトインした場合にクローンされるか、このスキルが初回レンダリング時にフォールバックとしてクローンします)。このスキルはシェルアウトパターンを文書化するものであり、モノレポをベンダリングしません。
概要
外部のHyperframesモノレポ(external/hyperframes/)にシェルアウトすることで、HTMLコンポジションをMP4ビデオにレンダリングします。単一のHTMLシーンファイル、または完全なHyperframesプロジェクトディレクトリを受け入れます。npx hyperframes render --output <mp4>を呼び出す前に、必須のプリレンダリングゲート(lint → validate → inspect → render)を実行します。MP4のパスとジョブ完了レポートを返します。プラグイン内でHyperframesのパイプラインを再実装することはありません。シェルアウトのみです。
指示
- 2つのチェックで外部リポジトリを確認します:
external/hyperframes/package.jsonが存在すること、およびnpx hyperframes render --helpが応答すること。いずれかのチェックが失敗した場合は即座に失敗します。 - プロジェクトディレクトリを解決します。
project_dirが提供されている場合はそれを使用し、html_scene_pathが提供されている場合は一時プロジェクトをスキャフォールディングします。どちらも提供されていない場合は即座に失敗します。 - プリレンダリングゲートシーケンスを順番に実行します:
lint → validate → inspect → render(いずれかのステップが非ゼロを返した場合は中止)。 cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>を実行し、出力パスを収集します。- MP4ファイルが存在し、空でないことを確認します。出力パスと
inspectの警告を報告します。 - 以下の
## 呼び出しパターンセクションを参照して、正式な実行手順を確認します。
アクティベーション
専用のスラッシュコマンドはありません — このスキルには対応する/amw-*ショートカットはありません。design-principlesオーケストレーターによって、承認された設計がMP4ビデオ出力を必要とする場合に、メインエージェントモードの最終フェーズBステップとして呼び出されます。オーケストレーターは、コマンド層の制限なしに、このスキルからの完全なHyperframesシェルアウトパイプラインとコンポジション手法を適用できます。
このスキルは自律的かつ自己完結型です — どのエージェント(メインエージェント、サブエージェント、または外部オーケストレーター)でも、このSKILL.mdとその参照を読むことで使用できます。このスキルの手法は、一致するコマンドが公開するものに限定されません。
フロー内の位置
出力(フェーズB — 終端)。HTMLからMP4ビデオへのレンダリングパイプライン。ユーザーが明示的にHTMLコンポジションのビデオファイルへのラスタライズを希望する場合にのみトリガーされます。コンポジション作成が完了した後に、最後に実行されます。
トリガー条件
リクエストが以下のいずれかに一致する場合のみ、このスキルを呼び出します:
- 「このHTMLをビデオとしてレンダリング」/「MP4にレンダリング」
- 「HTML to MP4」/「ウェブサイトをビデオに」/「ページをビデオに」
- 「このHTMLコンポジションからビデオを作成」
- 「コンポジションをビデオにラスタライズ」
- Hyperframes /
hyperframes render/.hf.htmlへの明示的な言及
「アニメーション」「モーション」「ビデオ再生」「アニメーションコンポーネント」などの一般的な言及では呼び出さないでください。これらは以下に属します:
../amw-design-principles/starter-components/animations.html(ブラウザ内Stage + Spriteタイムライン)../amw-pretext/(タイポグラフィックモーション —pretext-art/は非推奨のリダイレクト)- ユーザー自身のパイプライン
前提条件
-
ランタイムバイナリ(システム前提条件): Node.js >= 22, git
-
ランタイムバイナリ(
/amw-initでインストール): Bun(Hyperframesのパッケージマネージャー)、FFmpeg。ChromeはHyperframes自身がhyperframes browser ensureで管理します(内部的にPuppeteer +@puppeteer/browsersを使用 — Playwrightではありません)。 -
外部ソース:
../../external/hyperframes/—https://github.com/heygen-com/hyperframesからクローンされたHyperframesモノレポ。inspect、--hdr、data-variable-valuesサポートのためにv0.4.30以降にピン留めします。フォルダが存在しない場合、/amw-initまたはこのスキルは続行前にクローンする必要があります:git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes cd external/hyperframes && bun install
入力契約
このブリッジは、相互に排他的な2つの入力を受け入れます。正確に1つを提供してください:
| フィールド | 型 | 説明 |
|---|---|---|
html_scene_path | string (optional) | 単一のHTMLファイルへの絶対パス。ブリッジはmktemp -d -t hf-XXXXXX(POSIX互換)を使用して一時的なhyperframesプロジェクトディレクトリをスキャフォールディングし、HTMLをindex.htmlとして書き込み、レンダリングし、レポートが書き込まれた後にクリーンアップします。 |
project_dir | string (optional) | 既存のhyperframesプロジェクトディレクトリ(index.htmlとオプションでcompositions/、assets/を含む)への絶対パス。ブリッジは直接cdします — スキャフォールディングは不要です。サブコンポジション、オーディオ、外部アセットをサポートします。 |
両方が提供された場合、project_dirが優先されます。どちらも提供されない場合は、即座に失敗します。
呼び出しパターン
-
外部リポジトリを確認 — 2つのチェックが必要:
# チェック1 — package.jsonが存在する(モノレポがクローンされている) test -f "external/hyperframes/package.json" || exit-fail "monorepo not found" # チェック2 — CLIが応答する(インストールが機能している) # @hyperframes/cliはnpmに公開されていません — モノレポのワークスペース内から実行する必要があります (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "hyperframes CLI not functional — run bun install inside external/hyperframes/"いずれかのチェックが失敗した場合は、即座に失敗します。続行しないでください。
-
プロジェクトディレクトリを解決します。
project_dirが提供されている場合:直接使用します。HF_PROJ_DIR="$project_dir"を設定します。html_scene_pathが提供されている場合:一時プロジェクトをスキャフォールディングします:HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)" cp "$html_scene_path" "$HF_PROJ_DIR/index.html"- それ以外の場合:即座に失敗します。
-
プリレンダリングゲートシーケンスを実行:
lint → validate → inspect → render。cd "$HF_PROJ_DIR" npx hyperframes lint npx hyperframes validate npx hyperframes inspect --json # エラーがある場合は中止(--strictで非ゼロ終了)TECH-hyperframes-cli-lint、TECH-hyperframes-cli-validate、TECH-hyperframes-cli-inspectを参照してください。
[TECH-hyperframes-cli-inspect.md] 機能・使用タイミング・動作方法・フラグ・出力(JSONモード)・最小限の例・オプトアウト属性・落とし穴・相互参照 [TECH-hyperframes-cli-validate.md] 機能・使用タイミング・動作方法・出力・警告が表示されるタイミング・最小限の例・落とし穴・相互参照 [TECH-hyperframes-cli-lint.md] 機能・使用タイミング・動作方法・最小限の例・落とし穴・相互参照
ゲートシーケンス注記: ブリッジのシーケンス(
lint → validate → inspect → render)は、アップストリームのシーケンス(lint → inspect → preview → render— ベンダリングされたexternal/hyperframes/モノレポ内のアップストリームHyperframes CLI SKILL.mdを参照)より意図的に拡張されており、無人フェーズBパイプラインのためにvalidateを追加し、preview(開発者ループプリミティブ)を削除しています。 -
レンダリング。 解決されたプロジェクトディレクトリ内から:
cd "$HF_PROJ_DIR" npx hyperframes render --output <abs-mp4-path>必要に応じて追加フラグ(
--fps、--quality、--format、--hdrなど)— TECH-hyperframes-cli-renderを参照してください。[TECH-hyperframes-cli-render.md] 機能・使用タイミング・動作方法・フラグ・品質ガイダンス・透明ビデオ・最小限の例・ワーカーチューニング・落とし穴・相互参照
-
MP4パスを呼び出し元に返します。 プロジェクトディレクトリが一時スキャフォールド(
html_scene_pathパス)であった場合、レポートが書き込まれた後に削除します。
HTMLコンポジションルール(Hyperframes固有)
コンポジションは、#stageルートとその子要素(トラック/クリップ/オーバーレイ)にdata-*タイムライン属性を持つプレーンHTMLを使用します。これは../amw-design-principles/starter-components/animations.htmlと同じStage + Spriteメンタルモデルです — Hyperframesはそれをマルチトラックオーディオ/ビデオミキシングとオフスクリーン確定レンダリングで拡張します。
主要な属性(公式スキーマは、クローン後にexternal/hyperframes/packages/core/にあります):
data-composition-id— ステージレベルの識別子data-start、data-duration— 秒単位、クリップごとdata-track-index— レイヤー順序(ビデオ/オーバーレイ/オーディオトラック)data-width、data-height— ステージレベルのキャンバスサイズ
ブリッジにFramer Motion、GSAP-as-dependency、またはサードパーティのアニメーションランタイムを導入しないでください。Hyperframesには独自のFrame Adapterパターンがあります。ユーザーがコンポジション内でGSAPを希望する場合、それはHyperframesの関心事であり、ブリッジの関心事ではありません。
参考文献
完全な参照インデックス:INDEX.md — 32個のTECH-*.mdファイル。Captureパイプライン(7ステップ)、CLIコマンド(12個)、コンポジション作成(7個)、レジストリ(4個)でグループ化されています。各ファイルには独自の目次があります。必要なものだけをロードしてください。
例題
ステップごとの参照ファイル./references/TECH-hyperframes-capture-step-*.md(7ステップのウェブサイトからビデオへのパイプライン)およびコンポジション作成ガイドTECH-hyperframes-composition-coreにある実際の例を参照してください。
[TECH-hyperframes-composition-core.md] 機能・使用タイミング・動作方法・アプローチ(ナラティブ順)・単一ファイルスケルトン・ビジュアルアイデンティティゲート(必須 — HTMLを書く前に)・落とし穴・相互参照
出力
レンダリングされたMP4ビデオファイルとジョブ完了レポート。MP4は、解決されたプロジェクトディレクトリからnpx hyperframes render --output <mp4>によって生成されます。ブリッジは、成功を報告する前にファイルが存在し空でないことを確認します。完全な契約は以下を参照してください。
出力と完了チェックリスト
完全な出力契約(アーティファクトパス推論ルール、ジョブ完了レポートの形式、必須チェックリスト)はTECH-output-contractにあります。2つの出力が必須です:
- アーティファクト — hyperframesプロジェクトフォルダ + レンダリングされたMP4。パスはプロジェクトから推論されます(ユーザーパス → フレームワークの慣例 →
./design/<subtype>/→ フォールバック./design/videos/)。 - ジョブ完了レポートは
$MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.mdにあり、すべてのアーティファクトとアイテムごとのチェックリスト判定をリストします。
完了を報告する前に:TECH-output-contractのすべてのチェックリスト項目がPASSまたはN/Aである必要があります。FAILがある場合は、修正ループがトリガーされます。
リソース
../amw-design-principles/starter-components/animations.html— ブラウザ内プレビューに使用される約50行のStage + Spriteタイムラインエンジン。Hyperframesも同じリズムを共有しています。../../bin/amw-html-export.py— 代替ではありません。html-exportは単一フレームをPNG/PDFにレンダリングします。HyperframesはPuppeteer + Chrome(hyperframes browser ensureで管理)+ FFmpegを使用してマルチフレームMP4をレンダリングします。../amw-dev-browser/— 代替ではありません。dev-browserは入力/自動化用です。Hyperframesは出力ラスタライザーです。/amw-init— Bun、FFmpegをインストールし、初回使用時にexternal/hyperframes/をクローンします。レンダリング用のChromeは、Hyperframes自身がhyperframes browser ensureを介してプロビジョニングします。- 外部リポジトリ:
https://github.com/heygen-com/hyperframes
非妥協事項
- 外部モノレポをシェルアウト経由で使用します。そのパイプラインをプラグイン内で再実装しないでください。
- Hyperframesのソースを
skills/にベンダリングしないでください — 500以上のファイルはスキルの範囲として適切ではありません。 dev-browserをHyperframesの代わりに使用しないでください — これらは逆の問題を解決します(入力対出力)。html-export.pyを代わりに使用しないでください — 単一フレームのPNGはビデオではありません。- ユーザーは初回使用前に
/amw-initを実行してBun + FFmpegをインストールし、外部リポジトリをクローンする必要があります。Chromeは、クローン後に(cd external/hyperframes && npx hyperframes browser ensure)を1回実行することでプロビジョニングされます。
エラー処理
一般的な障害モードと修復手順はTECH-error-handlingにあります。内容:外部リポジトリの欠落、Bun / FFmpeg / Chromeのプロビジョニング、HTML属性の解析エラー、ビデオエンコードの失敗、古いクローン。