HyperFrames / HyperFrames

HyperFrames

初めてですか？ 開始前に環境チェックを実行してください：

python3 /var/minis/skills/hyperframes-cli/scripts/check-env.py

これにより、minis-browser-use、ffmpeg、および必要なスキルがインストールされているか確認します。 hyperframes-cli スキルが不足している場合は、以下をインストールしてください：

python3 /var/minis/skills/hyperframes-cli/scripts/install-skill.py \
  hyperframes-cli --repo heygen-com/hyperframes --subdir skills

HTMLは動画の信頼できる情報源です。コンポジションとは、タイミング用の data-* 属性、アニメーション用のGSAPタイムライン、および外観用のCSSを持つHTMLファイルです。フレームワークは、クリップの可視性、メディア再生、およびタイムラインの同期を処理します。

アプローチ

HTMLを書く前に、高いレベルで考えてください：

1. 何を — 視聴者は何を体験すべきか？ 物語の流れ、重要な瞬間、感情的な盛り上がりを特定します。
2. 構造 — いくつのコンポジションがあるか、どれがサブコンポジションでどれがインラインか、どのトラックが何（ビデオ、オーディオ、オーバーレイ、キャプション）を運ぶか。
3. タイミング — どのクリップが持続時間を決めるか、トランジションはどこに配置されるか、ペーシングはどうか。
4. レイアウト — 最初に最終状態を構築します。以下の「アニメーション前のレイアウト」を参照してください。
5. アニメーション — 次に、以下のルールを使用してモーションを追加します。

小さな編集（色の修正、タイミングの調整、1つの要素の追加）の場合は、ルールに直接進んでください。

ビジュアルアイデンティティゲート

次の順序で確認してください：

1. プロジェクトにDESIGN.mdが存在しますか？ → それを読んでください。その正確な色、フォント、モーションルール、「やってはいけないこと」の制約を使用します。
2. visual-style.mdが存在しますか？ → それを読んでください。その style_prompt_full と構造化フィールドを適用します。（注：visual-style.md はプロジェクト固有のファイルです。visual-styles.md は8つの名前付きプリセットを持つスタイルライブラリです — 別のファイルです。）
3. ユーザーがスタイルを指定しましたか（例：「スイスパルス」、「ダークでテクニカル」、「ラグジュアリーブランド」）？ → visual-styles.md を読んで8つの名前付きプリセットを確認します。最小限のDESIGN.mdを生成します：## スタイルプロンプト（1段落）、## カラー（3～5つの16進数カラーとその役割）、## タイポグラフィ（1～2つのフォントファミリー）、## やってはいけないこと（3～5つのアンチパターン）。
4. 上記のいずれでもない場合？ → HTMLを書く前に3つの質問をしてください：
   • ムードは？ （爆発的 / 映画的 / 流動的 / テクニカル / 混沌 / 温かみ）
   • ライトキャンバスかダークキャンバスか？
   • 特定のブランドカラー、フォント、またはビジュアルリファレンスはありますか？ 次に、回答から最小限のDESIGN.mdを生成します。

すべてのコンポジションは、そのパレットとタイポグラフィをDESIGN.md、visual-style.md、または明示的なユーザーの指示にまでさかのぼる必要があります。#333、#3b82f6、または Roboto に手を伸ばしている場合 — このステップをスキップしています。

モーションのデフォルト、サイジング、エントランスパターン、イージングについては、house-style.md に従ってください。ハウススタイルは物事がどのように動くかを扱います。DESIGN.mdは物事がどのように見えるかを扱います。

アニメーション前のレイアウト

すべての要素を、最も見える瞬間（完全に入力され、正しく配置され、まだ退出していないフレーム）に配置すべき場所に配置します。これを最初に静的なHTML+CSSとして記述します。まだGSAPは使わないでください。

なぜこれが重要なのか： 要素をアニメーションの開始状態（画面外、0にスケール、不透明度0）に配置し、そこから着地すると思われる場所にトゥイーンする場合、最終的なレイアウトを推測していることになります。重なりは、ビデオがレンダリングされるまで見えません。最初に最終状態を構築することで、モーションを追加する前にレイアウトの問題を確認して修正できます。

プロセス

1. 各シーンのヒーローフレームを特定します — 最も多くの要素が同時に表示される瞬間。これが構築するレイアウトです。
2. そのフレームの静的な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 は装飾用のみに予約してください。
3. gsap.from() でエントランスを追加 — 画面外/非表示からCSSの位置へアニメーションします。CSSの位置が真実であり、トゥイーンはそこに到達するための経路を説明します。
4. 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
// ステップ　（．タイトル、｛y：60、不透明度：0、持続時間：0．6、イーズ：”power3．out”｝、0）；
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);

マルチシーンコンポジション：シーンごとに1つのコンテナ

コンポジションに複数のシーンが順次表示される場合（Aが終了してからBが開始する）、すべてのシーンの要素を1つの共有Flexコンテナに絶対に配置しないでください。 各要素が opacity: 0 で始まるとしても、flexはすべての子要素に高さを割り当てます。1つのコンテナに5シーン分のコンテンツがある場合、コンテナの合計高さはステージの高さをはるかに超えます — flex justify-content: center はその特大のコンテナに対してコンテンツを中央揃えにし、表示可能なコンテンツをスクリーンショットのクロップの外側に押し出します。

間違い — すべてのシーンが1つのflexコンテナ内にある：

<div class="scene-content"> <!-- flex column, height:100% -->
  <!-- シーンAの要素 -->
  <div id="title-a" style="opacity:0">タイトルA</div>
  <div id="body-a"  style="opacity:0">本文A</div>
  <!-- シーンBの要素 — 見えなくてもflexの高さを取る -->
  <div id="title-b" style="opacity:0">タイトルB</div>
  <div id="body-b"  style="opacity:0">本文B</div>
  <!-- シーンC ... -->
</div>

正しい — 各シーンが独自の絶対レイヤーである：

<!-- シーンA -->
<div class="scene" id="scene-a">
  <div id="title-a" style="opacity:0">タイトルA</div>
  <div id="body-a"  style="opacity:0">本文A</div>
</div>
<!-- シーンB — シーンAへの高さの影響はゼロ -->
<div class="scene" id="scene-b">
  <div id="title-b" style="opacity:0">タイトルB</div>
  <div id="body-b"  style="opacity:0">本文B</div>
</div>

/* 各シーンが独立してステージを埋める */
.scene {
  position: absolute;
  inset: 0;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  padding: 80px 120px;
  box-sizing: border-box;
  z-index: 2;
  gap: 24px;
}

これが順次シーンに対する唯一の正しいパターンです。各シーンコンテナの position: absolute; inset: 0 は「アニメーション前のレイアウト」ガイドラインと競合しません — そのガイドラインは、コンテンツ要素（タイトル、カード、統計）をハードコードされたピクセルオフセットで絶対配置することを禁止しています。inset: 0 でステージ全体を埋めるシーンコンテナは正しく、必須です。

要素が時間を超えてスペースを共有する場合

要素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-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 =