HyperFrames
HTML が動画の信頼できる情報源 (source of truth) です。コンポジションは、タイミング用の data-* 属性、アニメーション用の GSAP タイムライン、および外観用の CSS を備えた HTML ファイルです。フレームワークは、クリップの可視性、メディア再生、タイムライン同期を処理します。
アプローチ
発見 (探索的リクエストのみ)
「製品ローンチ動画を作って」「ブランド用に何か作って」といった、ユーザーが方向性を確定していないオープンエンドなリクエストについては、色を選ぶ前に意図を理解します。
- オーディエンス — 誰が見るのか? 開発者? 経営幹部? 一般消費者?
- プラットフォーム — どこで再生されるのか? ソーシャル (15秒)、Webサイトヒーロー、製品デモ、社内用?
- 優先事項 — 何が最も重要か? モーションの品質? コンテンツの正確性? ブランドの忠実性? スピード?
- バリエーション — ユーザーは選択肢を希望しているか、それとも単一のベストな成果物を希望しているか?
「タイトルカードを追加して」「シーン3のタイミングを修正して」といった具体的なリクエストについては、発見ステップをスキップします。
探索的リクエストの場合は、単なる色の変更ではなく、ペース、エネルギーレベル、構造的アプローチが異なる、意味のある2〜3のバリエーションを提供することを検討します。1つは安全/予想通り、もう1つは意欲的に。これを必須としないでください — 適切な場合に利用可能なツールです。
ステップ 1: デザインシステム
design.md または DESIGN.md がプロジェクトに存在する場合、最初にそれを読みます (Linux では大文字小文字が異なるファイルとして扱われるため、両方のケースを確認します)。これがブランドカラー、フォント、制約の信頼できる情報源です。その正確な値を使用します — 色を発明したり、フォントを代用したりしないでください。どのような形式でも機能します (YAML フロントマター、散文、表 — 値を抽出するだけです)。
ローカルに見つからないフォントが指定されている場合 (fonts/ ディレクトリに .woff2 ファイルがなく、組み込みフォントでもない場合)、HTML を書く前にユーザーに警告します。「design.md で [フォント名] が指定されていますが、フォントファイルが見つかりません。fonts/ に .woff2 ファイルを追加してください。見つからない場合は、最も近い組み込み代替フォント [最も近い組み込み代替フォント] を使用します。」
design.md が存在しない場合は、ユーザーに選択肢を提供します。
- ユーザーがスタイルやムードを指定した場合 → visual-styles.md を読み、8つの名前付きプリセットから最も近いものを選択します。
- 視覚的にオプションを閲覧したい場合 → デザインピッカーを実行します。references/design-picker.md で完全なワークフローを読んでください。これにより、視覚的なピッカーページが提供されます。ユーザーはブラウザ内でムード、パレット、タイポグラフィ、モーションを設定し、生成された
design.mdをコピーして会話に貼り付けます。 - スキップして早く進みたい場合 → ムード、ライト/ダーク、ブランドカラー/フォントを尋ねます。その後、house-style.md からパレットを選択します。
design.md はブランドを定義します。動画コンポジションのルールを定義するわけではありません。 それらは references/video-composition.md と house-style.md から来ます。ブランドカラーは、Web UI の不透明度ではなく、動画に適したスケールで使用します。
ステップ 2: プロンプト拡張
常にすべてのコンポジションで実行します (単一シーンの作品と些細な編集を除く)。このステップは、ユーザーの意図を design.md と house-style.md に照らして具体化し、すべてのダウンストリームエージェントが同じように読む一貫した中間成果物を生成します。
完全なプロセスと出力形式については、references/prompt-expansion.md を読んでください。
ステップ 3: 計画
HTML を書く前に、高いレベルで考えます。
- 何を — 視聴者は何を体験すべきか? 物語の流れ、重要な瞬間、感情的なビートを特定します。
- 構造 — いくつのコンポジションがあるか、どれがサブコンポジションでどれがインラインか、どのトラックが何を運ぶか (ビデオ、オーディオ、オーバーレイ、キャプション)。
- リズム — 実装前にシーンリズムを宣言します。どのシーンがクイックヒットか、どれがホールドか、シェーダーはどこに置くか、エネルギーはどこでピークになるか。パターンに名前を付けます: fast-fast-SLOW-fast-SHADER-hold。リズムテンプレートについては references/beat-direction.md を読んでください。
- タイミング — どのクリップが持続時間を決定するか、トランジションはどこに配置されるか、ペースはどうか。
- レイアウト — 最初に最終状態を構築します。以下の「レイアウトを先に、アニメーションを後に」を参照してください。
- アニメーション — 次に、以下のルールを使用してモーションを追加します。
リクエストされたものを構築します。 「タイトルカード」のリクエストは、「タイトルカード + 3つのサポートシーン + アンビエント音楽 + キャプション」のリクエストではありません。すべてのシーン、すべての要素、すべてのトゥイーンは、その場所に値するものでなければなりません。追加のシーンや要素が作品を真に向上させる場合は、それらを提案します — 追加しないでください。
小さな編集 (色の修正、タイミングの調整、要素の追加) の場合は、ルールに直接スキップします。
レイアウトを先に、アニメーションを後に
すべての要素を、最も見える瞬間 — 完全に入力され、正しく配置され、まだ終了していないフレーム — に配置します。これを最初に静的な 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 位置が信頼できる情報源であり、トゥイーンはそこに到達するための経路を記述します。(data-composition-srcを介して読み込まれたサブコンポジションでは、gsap.fromTo()を優先します — references/motion-principles.md の耐荷重 GSAP ルールを参照)。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: それらの位置にアニメーションで移動
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: それらの位置からアニメーションで退出
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/compositions に必須 | 秒数。ビデオ/オーディオはメディアの長さをデフォルトとします。 |
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-variable-values | いいえ | サブコンポジションホスト上のインスタンスごとの変数オーバーライドの JSON オブジェクト |
ルート <html> 要素上:
| 属性 | 必須 | 値 |
|---|---|---|
data-composition-variables | いいえ | 宣言された変数の JSON 配列 (id/type/label/default) — Studio 編集 UI を駆動し、getVariables() のデフォルトを提供します |
コンポジション構造
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>
変数 (パラメータ化されたコンポジション)
ソース HTML を編集せずに、同じコンポジションを異なるコンテンツ (タイトル、テーマカラー、価格、キャプション) でレンダリングします。
3 ステップパターン:
- 宣言 コンポジションの
<html>ルートでdata-composition-variablesを使用して変数を宣言します。各エントリには、id、type(string、number、color、boolean、enumのいずれか)、label、defaultが必要です。列挙型エントリにはoptions: [{value, label}, ...]も必要です。 - 読み取り コンポジションのスクリプト内で
window.__hyperframes.getVariables()を使用して解決された値を読み取ります。宣言されたデフォルト + インスタンスごとのオーバーライド + CLI オーバーライドのマージ結果を返します。 - オーバーライド レンダリング時に
npx hyperframes render --variables '{...}'(トップレベル) またはホスト要素のdata-variable-values='{...}'(サブコンポジションのインスタンスごと) を使用してオーバーライドします。
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"タイトル","default":"こんにちは"},
{"id":"theme","type":"enum","label":"テーマ","default":"light","options":[
{"value":"light","label":"ライト"},
{"value":"dark","label":"ダーク"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# 開発プレビューは宣言されたデフォルトを使用します
npx hyperframes preview
# オーバーライド付きでレンダリング
npx hyperframes render --variables '{"title":"Q4 レポート","theme":"dark"}' --output q4.mp4
# または JSON ファイルから
npx hyperframes render --variables-file ./vars.json
サブコンポジションのインスタンスごとの値: data-composition-src を介して読み込まれたサブコンポジション内部でも同じ getVariables() が機能します。各ホスト要素は独自の値を渡します:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Enterprise","price":"お問い合わせください"}'
></div>
トランジション (シーン間のブリッジ)
data-transition 属性を使用して、シーンクリップ間のトランジションを定義します。data-duration を持つ親シーンでトランジションを宣言します。
<div data-composition-id="transition-demo" data-width="1920" data-height="1080">
<div id="scene1" class="scene clip" data-start="0" data-duration="5" data-track-index="0">
<!-- シーン 1 のコンテンツ -->
</div>
<div id="scene2" class="scene clip" data-start="5" data-duration="5" data-track-index="1"
data-transition="crossfade" data-transition-duration="1">
<!-- シーン 2 のコンテンツ -->
</div>
</div>
内蔵トランジション
crossfade— 1 つ前のシーンにクロスフェードしますslide-left— 新しいコンテンツが左からスライドインしますslide-right— 新しいコンテンツが右からスライドインしますslide-up— 新しいコンテンツが下からスライドインしますslide-down— 新しいコンテンツが上からスライドインしますwhip-left— 高速で歪んだスライドwhip-right— 高速で歪んだスライドzoom-in— 新しいシーンにズームインしますzoom-out— 新しいシーンにズームアウトしますmask-wipe— マスクベースのワイプ
data-transition-duration (秒、デフォルト 0.5) でトランジションの長さを制御します。
オーディオリアクティブアニメーション
音声駆動のアニメーションには、オーディオ分析スクリプト audio-reactive.js を含めます。これにより、window.__hyperframes.getAudioData() が提供され、現在のビート、エネルギー、周波数帯域が返されます。
<script src="https://cdn.hyperframes.dev/audio-reactive.js"></script>
<script>
const tl = gsap.timeline({ paused: true });
// ビートに同期したパルス
tl.to(".pulse-element", {
scale: 1.2,
duration: 0.1,
repeat: -1,
repeatRefresh: true,
onRepeat: function() {
const data = window.__hyperframes.getAudioData();
if (data.isBeat) {
gsap.to(this.targets(), { scale: 1.2, duration: 0.05 });
gsap.to(this.targets(), { scale: 1, duration: 0.15, delay: 0.05 });
}
}
});
// エネルギー駆動のグロー
tl.to(".glow-element", {
opacity: 1,
duration: 0.1,
repeat: -1,
repeatRefresh: true,
onRepeat: function() {
const data = window.__hyperframes.getAudioData();
const energy = data.energy || 0;
gsap.to(this.targets(), {
filter: `brightness(${1 + energy * 2}) drop-shadow(0 0 ${10 + energy * 20}px rgba(255,100,50,${energy}))`,
duration: 0.05
});
}
});
</script>
テキストハイライトアニメーション
アニメーションテキストハイライトには、text-highlight.js スクリプトを使用します。これにより、highlightText() 関数が提供され、テキスト要素にマーカースイープ、手書きサークル、バースト線、スケッチアウト効果を適用できます。
<script src="https://cdn.hyperframes.dev/text-highlight.js"></script>
<script>
// "重要なポイント" というテキストをマーカーでハイライト
highlightText(document.querySelector(".highlight-target"), {
type: "marker-sweep",
color: "rgba(255, 200, 0, 0.4)",
duration: 0.3
});
</script>
キャプションと字幕
captions ライブラリを使用して、音声に同期したキャプションと字幕を追加します。
<script src="https://cdn.hyperframes.dev/captions.js"></script>
<script>
// キャプションデータを定義 (各エントリは start、end、text を持つ)
const captionsData = [
{ start: 0.5, end: 2.0, text: "HyperFrames へようこそ" },
{ start: 2.5, end: 4.0, text: "これは HTML ベースの動画ツールです" }
];
// キャプショントラックを初期化
const captions = new Captions({
data: captionsData,
container: "#captions-container",
style: {
fontFamily: "sans-serif",
fontSize: "32px",
color: "white",
textShadow: "2px 2px 4px rgba(0,0,0,0.8)"
}
});
// タイムラインにキャプション更新を統合
tl.call(function() { captions.update(tl.time()); }, [], null, 0);
</script>
テキスト読み上げ (TTS) ナレーション
TTS ナレーションを生成するには、hyperframes-media スキルの tts コマンドを使用します。このマークダウンでは、design.md で指定された音声を使用するものとします。
# ナレーションを生成
npx hyperframes-media tts --text "製品のご紹介をいたします。" --voice "ja-JP-Wavenet-D" --output narration.mp3
生成されたオーディオファイルは、通常のメディアクリップとしてコンポジションに含めることができます。
動画制作ワークフロー
完全な動画制作ワークフローは以下を含みます:
- コンポジションの作成 — 上記のように HTML 構造を記述します。
- プレビュー —
npx hyperframes previewを使用して開発サーバーでプレビューします。 - レンダリング —
npx hyperframes renderを使用して最終動画を出力します。 - メディアアセットの前処理 —
npx hyperframes-media tts(TTS)、npx hyperframes-media transcribe(文字起こし)、npx hyperframes-media remove-background(背景除去) を使用します。 - リンティングと検査 —
npx hyperframes lintとnpx hyperframes inspectを使用して問題をチェックします。
これらの CLI コマンドの詳細については、それぞれ hyperframes-cli および hyperframes-media スキルを参照してください。
ミニマルコンポジションの例
以下は、開始するための完全なミニマルコンポジションです:
<!doctype html>
<html data-composition-variables='[]'>
<head>
<style>
body { margin: 0; overflow: hidden; }
.scene-content {
width: 100%; height: 100%; padding: 40px;
display: flex; flex-direction: column; justify-content: center; align-items: center;
box-sizing: border-box;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
h1 { font-size: 72px; color: white; margin: 0; }
p { font-size: 24px; color: rgba(255,255,255,0.8); }
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
</head>
<body>
<div data-composition-id="my-video" data-width="1920" data-height="1080">
<div id="scene" class="clip" data-start="0" data-duration="10" data-track-index="0">
<div class="scene-content">
<h1 id="title">ようこそ</h1>
<p id="subtitle">HyperFrames へ</p>
</div>
</div>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["my-video"] = (function() {
const tl = gsap.timeline({ paused: true });
tl.from("#title", { y: -50, opacity: 0, duration: 1, ease: "power3.out" }, 0);
tl.from("#subtitle", { y: 30, opacity: 0, duration: 0.8, ease: "power2.out" }, 0.3);
tl.to(".scene-content", { opacity: 0, duration: 0.5 }, 9);
return tl;
})();
</script>
</div>
</body>
</html>
重要な注意事項:
- スタンドアロンコンポジションでは
<template>を使用しないでください。 - HTML を書く前に常に
design.mdを確認するか、デザイン選択肢を求めます。 - アニメーションを追加する前に、静的な CSS でレイアウトを構築します。
data-track-indexを使用してタイムラインの競合を防ぎます。- 変数を使用して再利用可能なコンポジションを作成します。
- 複雑なプロジェクトではサブコンポジションを使用します。