HyperFrames
HTMLはビデオの真実のソースです。コンポジションは、タイミング用のdata-*属性、アニメーション用のGSAPタイムライン、および外観用のCSSを持つHTMLファイルです。フレームワークは、クリップの可視性、メディア再生、およびタイムライン同期を処理します。
Open Design統合(このサーフェスにとって重要な要素)
このスキルがOpen Design内で実行される場合(つまり$OD_PROJECT_DIRが設定されている場合)、出力フローは固定されています:レンダリングされた.mp4のみがプロジェクトルートに配置されるべきです。コンポジションソースファイル(hyperframes.json、meta.json、index.html、アセット)は、ユーザーのFileViewerやチャットの「生成ファイル」チップを散らかさないように、隠しキャッシュディレクトリ内に属します。
OD内のレンダリングワークフロー - 高速パス:
ほとんどのODリクエスト(「テストビデオ」、「5秒プロダクトリビール」、「デモクリップ」)では、コンポジションHTMLをゼロから作成しないでください。HyperFramesの組み込みスキャフォールドを使用し、プロンプトが実際に変更するものだけを編集してください。「ゼロからの作成」パスは、モデル出力とサイレントチャットツール時間に数分かかりますが、スキャフォールドパスは数秒で済みます。
# 1. 隠しキャッシュスロットを選択します。ドットファイルのプレフィックスにより、ODのプロジェクトファイル
# リストはそれをスキップするため、ソースファイルがチャットを散らかすことはありません。
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. すぐにレンダリング可能なスキャフォールドを取得します(hyperframes.json、
# meta.json、GSAP CDN + すでに登録されているwindow.__timelines.mainを含むindex.html)。
# これはシェル内で実行されます - 純粋なファイルコピーで、
# Chromeは不要で、npxキャッシュを超えるネットワークもありません。
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. $COMP/index.htmlのみを編集します - 非デフォルトの長さが必要な場合はルートの`data-duration`を変更し、
# <style>内のプレースホルダーパレットを置き換え、テキスト/画像用の1〜3つのクリップ<div>を追加し、
# 既存の`window.__timelines["main"] = gsap.timeline({paused:true})`ブロック内に
# 対応するGSAPトゥイーンを追加します。
# 編集は最小限に抑えてください。スキャフォールドはすでに有効なHFです。
# 4. ODデーモンを介してレンダリングをディスパッチします。このシェルから`npx hyperframes
# render`を実行しないでください。デーモンが代わりにアンサンドボックス化されたプロセスで実行します。
# (多くのエージェントCLI、特にClaude Codeは、BashをmacOSのsandbox-execでラップし、
# その下でpuppeteerのChromeサブプロセスがフレームキャプチャの途中でハングします。
# デーモンプロセスはアンサンドボックス化されているため、レンダリングは確実に完了します。)
#
# ディスパッチャーは約1秒以内に{taskId}を返します。ループで`"$OD_NODE_BIN" "$OD_BIN" media wait <taskId>`呼び出しを行って
# レンダリングを完了させます。
# 各呼び出しは最大25秒間ロングポーリングし(シェルツールのデフォルト30秒制限を十分下回ります)、
# 完了/実行中/失敗を示すために0/2/5で終了します。
out=$("$OD_NODE_BIN" "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<descriptive-name>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$("$OD_NODE_BIN" "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
各generateと各wait呼び出しは最大約25秒であり、エージェントシェルツールのデフォルト約30秒の制限がトリガーされることはありません。HFからの進行状況行(Capturing frame N/M)は、ループ中にstderrにライブでストリーミングされます。レンダリングが完了すると、最後のstdout行は{"file": { "name": "<output>", "size": …, "kind": "video", … }}になります。返信でfile.nameを引用して、ユーザーに何が生成されたかを知らせてください。
OD内のVisual Identity Gateをスキップします。 以下の「アプローチ」セクションのHARD-GATEセクションでは、コンポジションを作成する前に、DESIGN.md / visual-style.mdを読むか、3つのムードに関する質問をして停止するように指示されています。このゲートはスタンドアロンのHFプロジェクト用です。ODプロジェクトにはすでに独自のデザインシステムレイヤーがあります - ユーザーはプロジェクト作成時にビジュアルの方向性を選択しました。ODテストレンダリングでは、デフォルトで:ダークキャンバス(#0b0b0f)、1つのウォームアクセント(#ffb76b)、1つのクールアクセント(#7da4ff)、控えめなモーションを使用します。ユーザーのプロンプトが主題すら選ぶのに曖昧すぎる場合にのみ、スタイルの入力を求めてください(非常にまれです)。
スキャフォールドをスキップしてゼロから作成する場合:ユーザーが明示的にブランクテンプレートで明らかにホストできないものを要求した場合のみ(例:マルチコンポジションタイムライン、オーディオリアクティブオーバーレイ、すでに生成したTTSトラックに同期されたキャプション)。それ以外の場合は、init + 編集がデフォルトのパスです。
独自のシェルから引き続き実行できる軽量のHFサブコマンド(Chromeを起動する必要はありません):
npx hyperframes lint "$COMP"- ディスパッチ前にコンポジションを検証npx hyperframes transcribe <audio>- キャプションを生成npx hyperframes tts <text>- ナレーションを生成
デーモンディスパッチはrender/inspect/preview用に予約します(Chromeに依存するものすべて)。
呼び出さないでください:"$OD_NODE_BIN" "$OD_BIN" media generate --model hyperframes-html — そのディスパッチャーパスは意図的に400 (AGENT_RENDERED) を返します。HyperFramesはnpxを介して直接レンダリングされます。
配置しないでください:hyperframes.json / meta.json / index.html をプロジェクトルートに配置しないでください。ODのファイルリストは再帰的にスキャンされ、ユーザーはチャットに3つの無関係なファイルが表示されます。
render以外のCLIオプション(lint、preview、transcribe、tts、inspect、benchmark)は、タスクに適している場合(例:コンポジションから参照する前にTTSオーディオをキャッシュに生成する)、シェルツールから直接呼び出してください。
アプローチ
HTMLを作成する前に、高いレベルで考えてください:
- 何 - 視聴者は何を体験すべきか? 物語のアーク、重要な瞬間、感情的なビートを特定します。
- 構造 - いくつのコンポジションか、どれがサブコンポジションかインラインか、どのトラックが何を伝えるか(ビデオ、オーディオ、オーバーレイ、キャプション)。
- タイミング - どのクリップが期間を決定するか、トランジションはどこに配置されるか、ペーシングはどうか。
- レイアウト - 最初に最終状態を構築します。以下の「アニメーションの前にレイアウト」を参照してください。
- アニメート - 次に、以下のルールを使用してモーションを追加します。
小さな編集(色の修正、タイミングの調整、1つの要素の追加)の場合は、ルールに直接スキップします。
Visual Identity Gate
次の順序で確認してください:
- DESIGN.mdがプロジェクトに存在するか? → それを読んでください。その正確な色、フォント、モーションルール、および「やってはいけないこと」の制約を使用します。
- visual-style.mdが存在するか? → それを読んでください。その
style_prompt_fullと構造化フィールドを適用します。(注:visual-style.mdはプロジェクト固有のファイルです。visual-styles.mdは8つの名前付きプリセットを持つスタイルライブラリです — 異なるファイルです。) - ユーザーがスタイルを指定したか(例:「Swiss Pulse」、「ダークでテクニカル」、「ラグジュアリーブランド」)? → visual-styles.mdを読んで8つの名前付きプリセットを確認します。最小限のDESIGN.mdを生成します:
## Style Prompt(1段落)、## Colors(役割付きの3〜5つの16進数値)、## Typography(1〜2のフォントファミリー)、## What NOT to Do(3〜5のアンチパターン)。 - 上記のいずれでもないか? → HTMLを作成する前に3つの質問をします:
- ムードは何ですか?(爆発的 / シネマティック / 流動的 / テクニカル / カオス / ウォーム)
- 明るいキャンバス or 暗いキャンバス?
- 特定のブランドカラー、フォント、またはビジュアルリファレンスはありますか? 次に、回答から最小限のDESIGN.mdを生成します。
すべてのコンポジションは、そのパレットとタイポグラフィをDESIGN.md、visual-style.md、または明示的なユーザーの指示に遡ってトレース可能でなければなりません。#333、#3b82f6、またはRobotoに手を伸ばしている場合 — このステップをスキップしています。
モーションのデフォルト、サイズ設定、エントランスパターン、およびイージングについては、house-style.mdに従ってください。ハウススタイルは物事がどのように動くかを扱います。DESIGN.mdは物事がどのように見えるかを扱います。
アニメーションの前にレイアウト
すべての要素を、最も見える瞬間に配置します。つまり、完全に進入し、正しく配置され、まだ退出していないフレームです。これを最初に静的HTML+CSSとして記述します。まだGSAPは使用しません。
これが重要な理由: 要素をアニメーションの開始状態(画面外、0にスケーリング、不透明度0)に配置し、それらが着地すると思われる場所にトゥイーンすると、最終的なレイアウトを推測していることになります。オーバーラップはビデオがレンダリングされるまで見えません。最初に最終状態を構築することで、モーションを追加する前にレイアウトの問題を確認して修正できます。
プロセス
- 各シーンのヒーローフレームを特定します — 最も多くの要素が同時に表示される瞬間です。これが構築するレイアウトです。
- そのフレームの静的CSSを記述します。
.scene-contentコンテナは、width: 100%; height: 100%; padding: Npx;を使用してシーン全体を埋め、display: flex; flex-direction: column; gap: Npx; box-sizing: border-boxを使用します。パディングを使用してコンテンツを内側に押し込みます — コンテンツコンテナには決してposition: absolute; top: Npxを使用しないでください。絶対配置されたコンテンツコンテナは、コンテンツが残りのスペースよりも高い場合にオーバーフローします。position: absoluteは装飾用のみに予約します。 gsap.from()でエントランスを追加します — 画面外/非表示からCSSの位置へアニメーションします。CSSの位置がグラウンドトゥルースです。トゥイーンはそこに到達するための旅を説明します。gsap.to()でイグジットを追加します — CSSの位置から画面外/非表示へアニメーションします。
例
/* scene-contentはシーンを埋め、パディングでコンテンツを配置 */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* コンテナは任意のシーンサイズ(1920x1080、1080x1920など)を埋めます。
パディングでコンテンツを配置。Flex + gapでスペーシングを処理。 */
誤り — ハードコードされた寸法と絶対配置:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// ステップ3:それらの位置にアニメーションIN
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// ステップ4:それらの位置からアニメーションOUT
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
要素が時間の経過とともにスペースを共有する場合
要素Aが要素Bが同じエリアに入る前に退出する場合、両方ともそれぞれのヒーローフレームに対して正しいCSS位置を持つ必要があります。タイムラインの順序により、それらが視覚的に共存することは決してありません — しかし、レイアウトステップをスキップすると、タイミングエラーによって誤って重なるケースを見逃します。
意図的なオーバーラップと見なされるもの
レイヤード効果(テキストの後ろのグロー、シャドウ要素、背景パターン)とzスタックデザイン(カードスタック、深度レイヤー)は意図的です。レイアウトステップは、意図しないオーバーラップを捕捉することです — 2つの見出しが互いの上に重なる、統計がラベルを覆う、コンテンツがフレームからはみ出るなど。
データ属性
すべてのクリップ
| 属性 | 必須 | 値 |
|---|---|---|
id | はい | 一意の識別子 |
data-start | はい | 秒数またはクリップID参照("el-1"、"intro + 2") |
data-duration | img/div/コンポジションに必須 | 秒数。ビデオ/オーディオはメディア時間にデフォルト設定。 |
data-track-index | はい | 整数。同じトラックのクリップは重複できません。 |
data-media-start | いいえ | ソースへのトリムオフセット(秒) |
data-volume | いいえ | 0-1(デフォルト1) |
data-track-indexは視覚的なレイヤリングには影響しません — CSSのz-indexを使用してください。
コンポジションクリップ
| 属性 | 必須 | 値 |
|---|---|---|
data-composition-id | はい | 一意のコンポジションID |
data-start | はい | 開始時間(ルートコンポジション:"0"を使用) |
data-duration | はい | GSAPタイムラインの期間よりも優先されます |
data-width / data-height | はい | ピクセル寸法(1920x1080または1080x1920) |
data-composition-src | いいえ | 外部HTMLファイルへのパス |
コンポジション構造
data-composition-srcを介して読み込まれたサブコンポジションは、<template>ラッパーを使用します。スタンドアロンコンポジション(メインのindex.html)は<template>を使用しません — data-composition-id divを直接<body>に配置します。スタンドアロンファイルで<template>を使用すると、ブラウザからすべてのコンテンツが非表示になり、レンダリングが壊れます。
サブコンポジション構造:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- コンテンツ -->
<style>
[data-composition-id="my-comp"] {
/* スコープ付きスタイル */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// トゥイーン...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
ルートに読み込む:<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="5"></div>
タイムラインルール
GSAPのベストプラクティス
tl.from()をエントランスに、tl.to()をイグジットに使用します。 CSSで決定された最終状態から開始し、アニメーションがそこに到達する方法を説明します。- 絶対時間をラベルの代わりに使用します。 ラベルは読みにくくなります。
tl.from(..., 0.5)(「開始後0.5秒」)の方がtl.from(..., "label")よりも優れています。 - イージングルールに従います。 エントランスには
power3.out、イグジットにはpower2.in、ハイライトにはback.out(1.7)、連続アニメーションにはlinear。 durationにデフォルト値を使用します。 0.5秒は瞬きのような感覚、0.8秒は快適、1.2秒はゆったり。positionパラメータを効果的に使用します。0は前のトゥイーンと同時に開始、0.5は前のトゥイーン開始後0.5秒、-=0.3は前のトゥイーンの終了前に0.3秒オーバーラップ。
オーディオリアクティブアニメーション
背景色をビートにパルスさせたり、テキストをリズムに合わせて拡大縮小したりするには、data-audio-reactive属性を持つクリップを使用します。
<div id="beat-box" class="beat-box" data-audio-reactive data-track-index="0" data-start="0" data-duration="5">
<div class="pulse-ring"></div>
</div>
// オーディオ分析データにアクセス
const audioData = window.__audioData;
// audioData.frequencies、audioData.magnitude、audioData.beatを使用して
// requestAnimationFrameループで視覚要素を駆動
tl.to(".beat-box", {
scale: 1.05,
duration: 0.1,
repeat: -1,
yoyo: true,
ease: "power1.inOut",
});
テキストハイライトアニメーション
マーカースイープ、手描き円、バースト線、スケッチ、スケッチアウトを実現するには、data-text-highlight属性とそれぞれの効果クラスを使用します。
<p data-text-highlight="sweep" class="highlight-sweep">このテキストはマーカーでハイライトされます</p>
<p data-text-highlight="circle" class="highlight-circle">このテキストの周りに円が描かれます</p>
<p data-text-highlight="scribble" class="highlight-scribble">このテキストはスケッチスタイルでハイライトされます</p>
シーントランジション
利用可能なトランジションタイプ
- クロスフェード:
fade— 前のシーンをフェードアウトし、次のシーンをフェードイン - ワイプ:
wipe-left、wipe-right、wipe-up、wipe-down— 方向性ワイプ効果 - リビール:
reveal— 次のシーンが前のシーンを覆うように表示 - シェーダートランジション:
shader— カスタムシェーダー効果用
トランジションの実装
<div class="transition" data-transition="fade" data-duration="0.5">
<div class="transition-content">
<!-- トランジション要素 -->
</div>
</div>
// トランジションアニメーション
tl.to(".transition", { opacity: 1, duration: 0.5, ease: "power2.out" });
CLIコマンド
HyperFramesは、ビデオ制作ワークフローを自動化するためのいくつかのCLIコマンドを提供します。
init:新しいコンポジションをスキャフォールドします。lint:コンポジションのエラーを検証します。preview:ブラウザでコンポジションをプレビューします。render:コンポジションをビデオファイルにレンダリングします。transcribe:オーディオファイルからキャプションを生成します。tts:テキストからナレーションオーディオを生成します。
使用法の詳細と例については、hyperframes-cliスキルを参照してください。