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は、macOSのsandbox-exec内でBashをラップし、
# その下でpuppeteerのChromeサブプロセスがフレームキャプチャの途中でハングします。
# デーモンプロセスはサンドボックス化されていないため、レンダリングは確実に完了します。)
#
# ディスパッチャーは ~1秒以内に {taskId} を返します。
# `od media wait <taskId>` をループしてレンダリングを完了まで駆動します。
# 各呼び出しは最大25秒間ロングポーリングし(シェルツールのデフォルト30秒の制限を下回ります)、
# 終了コード0/2/5で完了/実行中/失敗を知らせます。
out=$(node "$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=$(node "$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からの進行行(フレーム 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 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つの名前付きプリセットがあるスタイルライブラリです — 別のファイルです。) - ユーザーがスタイルを指定したか(例:「スイスパルス」「ダークでテクニカル」「高級ブランド」)? → visual-styles.md を読み、8つの名前付きプリセットを確認してください。以下の内容で最小限のDESIGN.mdを生成してください:
## Style Prompt(1段落)、## Colors(役割付きで3〜5つの16進数値)、## Typography(1〜2つのフォントファミリー)、## やってはいけないこと(3〜5つのアンチパターン)。 - 上記のいずれでもないか? → HTMLを作成する前に3つの質問をしてください:
- ムードは?(爆発的 / 映画的 / 流動的 / テクニカル / 混沌 / 暖かい)
- 明るいキャンバスか暗いキャンバスか?
- 特定のブランドカラー、フォント、ビジュアルリファレンスはあるか? 次に、回答から最小限のDESIGN.mdを生成してください。
すべてのコンポジションは、そのパレットとタイポグラフィをDESIGN.md、visual-style.md、または明示的なユーザーの指示に遡らなければなりません。#333、#3b82f6、Roboto を使用しようとしている場合 — このステップをスキップしています。
モーションのデフォルト、サイズ設定、エントランスパターン、イージングについては、house-style.md に従ってください。ハウススタイルはものの動き方(HOW)を扱います。DESIGN.mdはものの見た目(WHAT)を扱います。
アニメーションの前にレイアウト
すべての要素を、最も目立つ瞬間 — 完全に進入し、正しく配置され、まだ退出していないフレーム — に配置すべき場所に配置してください。これを最初に静的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:それらの位置にアニメーションで進入
{ /* ... */ }
// ステップ4:それらの位置からアニメーションで退出
{ /* ... */ }
要素が時間を超えてスペースを共有する場合
要素Aが要素Bが同じ領域に進入する前に退出する場合、両方ともそれぞれのヒーローフレームに対して正しいCSS位置を持つ必要があります。タイムラインの順序付けにより、それらが視覚的に共存することは決してありません — しかし、レイアウトステップをスキップすると、タイミングエラーによって誤って重なるケースを見逃します。
意図的な重なりと見なされるもの
レイヤー効果(テキストの背後にあるグロー、シャドウ要素、背景パターン)とzスタックデザイン(カードスタック、深度レイヤー)は意図的です。レイアウトステップは、意図しない重なり — 2つの見出しが互いに重なる、統計がラベルを覆う、コンテンツがフレームからはみ出る — をキャッチするためのものです。
データ属性
すべてのクリップ
| 属性 | 必須 | 値 |
|---|---|---|
id | はい | 一意の識別子 |
data-start | はい | 秒数、またはクリップID参照("el-1"、"intro + 2") |
data-duration | img/div/compositionでは必須 | 秒数。動画/音声はメディアの持続時間がデフォルト。 |
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="10" data-track-index="1"></div>
動画
… [翻訳のため省略]