HyperFrames
概要
HyperFramesは、HeyGenが提供するオープンソース(Apache-2.0)のフレームワークで、HTML、CSS、メディア、アニメーションから決定論的なMP4動画を生成します。同じ入力からは常に同じ出力が得られます。data-*タイミング属性で注釈されたHTMLを解析し、ヘッドレスChromeで各フレームをシーク&キャプチャ、FFmpegでエンコードします。ビルド工程もReactも不要で、レンダリングごとの課金もありません。エージェントフレンドリーに設計されており、CLIはデフォルトで非インタラクティブなので、自動化されたコンテンツパイプラインに簡単に組み込めます。
このスキルを使用して、プロジェクトのスキャフォールディング、HTMLコンポジションの作成、ライブリロード付きプレビュー、そしてGSAP、CSS、Lottie、Three.js、Anime.js、Web Animations APIなどによるアニメーションを含むフレーム精度の動画レンダリングまで行えます。
手順
前提条件
作業を始める前に、環境を確認してください:
- Node.js 22以上(
node --version) - FFmpegがPATHに含まれていること(
ffmpeg -version) - ヘッドレスChrome/Chromiumは初回実行時にエンジンが自動的にダウンロードします。
プロジェクトのスキャフォールディング
npx hyperframes init my-video # プロジェクトをスキャフォールディング(index.html + package.jsonを作成)
cd my-video
AIエージェントのワークスペース内でスキルをセットアップする場合は、npx skills add heygen-com/hyperframesでインストールできます。
コンポジションの作成
コンポジションはプレーンなindex.htmlファイルです。ルートのステージ要素がキャンバスとコンポジションIDを宣言し、子要素がdata-*属性を使って出現タイミングと継続時間を指定します。時間値は秒単位です。
| 属性 | 目的 |
|---|---|
data-composition-id | コンポジションに名前を付ける(レンダリング/インスペクトのターゲット) |
data-start | 要素がタイムラインに現れるタイミング(秒) |
data-duration | 要素がタイムライン上に留まる時間(秒) |
data-width / data-height | キャンバスのサイズ(ピクセル、ステージ要素に指定) |
data-track-index | 重なり合うオーディオやビデオのレイヤー/トラック順序 |
data-volume | オーディオレベル、0.0〜1.0 |
プレビューとレンダリング
npx hyperframes preview # ライブリロード付きのブラウザプレビュー(作成中に使用)
npx hyperframes render # ヘッドレスChromeですべてのフレームをシークし、FFmpegでMP4にエンコード
npx hyperframes lint # レンダリング前にコンポジション構造を検証
npx hyperframes inspect # コンポジションのメタデータ(時間、トラック、サイズ)を表示
解像度はステージ要素のdata-width/data-heightから取得します。フレームレート、出力パス、コーデックはレンダリングパラメータです(インストールされたバージョンの正確なフラグはnpx hyperframes render --helpで確認してください。フラグ名は進化するため)。出力は決定論的なので、変更のない入力を再レンダリングしても安全にキャッシュできます。
コンポーネントカタログの使用
トランジション、オーバーレイ、キャプション、アニメーションチャート、マップ、エフェクトなどの既製ブロックをプロジェクトにインストールできます:
npx hyperframes add flash-through-white # トランジション
npx hyperframes add data-chart # アニメーションチャートブロック
npx hyperframes add instagram-follow # ソーシャルオーバーレイ
フルカタログはhyperframes.heygen.com/catalogで閲覧し、ブロック名を指定してaddします。
アニメーション
エンジンは各タイムライン位置を決定論的にシークし、リアルタイム録画は行わないため、シーク可能でフレーム精度の高いアニメーションであれば問題なく動作します。サポートされているアダプター:GSAP、CSSアニメーション、Lottie、Three.js、Anime.js、WAAPI、およびカスタムフレームアダプター。時間ベースのランダム性やDate.now()/壁時計駆動のモーションは避け、アニメーションの進行をコンポジションのタイムラインにバインドしてください。そうすればシークが再現可能になります。
エージェント / CI パイプライン
CLIは非インタラクティブなので、典型的な自動化フローは次のようになります:HTMLの生成/テンプレート化 → hyperframes lint → hyperframes render → MP4を収集。スケールアップには、@hyperframes/aws-lambdaパッケージを使用してLambda全体に分散レンダリングを実行できます。
例
例1:プロダクトローンチのコンポジションをレンダリング
index.html:
<div id="stage" data-composition-id="launch"
data-start="0" data-width="1920" data-height="1080">
<video data-start="0" data-duration="6" src="intro.mp4"></video>
<h1 id="title" data-start="1" data-duration="4">Launch day</h1>
<audio data-start="0" data-duration="6" data-volume="0.8" src="music.wav"></audio>
</div>
npx hyperframes inspect # 確認:launch、6秒、1920x1080
npx hyperframes lint # レンダリング前に検証
npx hyperframes render # 1080pのMP4を生成
例2:シーク可能なGSAPタイトルアニメーション
<div id="stage" data-composition-id="title-card"
data-start="0" data-width="1080" data-height="1080">
<h1 id="headline" data-start="0" data-duration="3">Q3 Results</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// 進行をタイムラインにバインド(エンジンがシークする一時停止トゥイーン)、実時間にはバインドしない
const tl = gsap.timeline({ paused: true });
tl.from("#headline", { y: 80, opacity: 0, duration: 1 })
.to("#headline", { scale: 1.05, duration: 2 });
window.__seek = (t) => tl.seek(t); // エンジンがフレームごとに呼び出す
</script>
</div>
npx hyperframes preview # ライブで反復、その後:
npx hyperframes render
ガイドライン
- 決定論を第一に。 すべてのモーションをコンポジションのタイムラインにバインドしてください。
Math.random()、Date.now()、リアルタイムループ、レンダリング中のネットワーク呼び出しは避けてください。これらは再現性を損なわせます。 - レンダリング前に必ず lint を。
hyperframes lintは構造/タイミングのミスを低コストで検出します。レンダリングは高コストなステップです。 - キャンバスはステージに設定。
data-width/data-heightはルートのコンポジション要素に、子要素のタイミング(data-start/data-duration)は各要素に秒単位で指定します。 - ツールチェーンを確認。 ほとんどの失敗はFFmpegの欠如、Node < 22、またはファイアウォールによるChromiumダウンロードのブロックが原因です。
- 正確なフラグは
--helpで。render/addのオプションはバージョンによって異なります。fps/出力/コーデックのフラグは、インストールされたCLIで確認してください。 - カタログブロックを優先。
hyperframes addでメンテナンス済みでシーク可能なコンポーネントを取得し、トランジションやチャートを手作業で作成する代わりに使いましょう。 - Lambdaでスケール。 バッチ/大規模ジョブには、長時間のローカルジョブではなく
@hyperframes/aws-lambdaを使用してレンダリングしてください。 - メディアはローカルに保管し、コミットする。 アセットは安定したパスで参照してください。レンダリング中のリモートフェッチは決定論と再現性を損なわせます。