mcpField
H
hyperframes-compose

hyperframes-compose

github.com/heygen-comクリエイティブ・メディア74.7k47 回インストール今日更新
リポジトリ

hyperframes-compose について

HTML で HyperFrames の動画コンポジションを作成・編集するスキルです。data 属性でタイミングを指定し、CSS でスタイルを整え、GSAP でアニメーションを設定します。決定論的なレンダリングを重視し、構造ルールと検証項目を示します。

主な機能

  1. 01クリップのタイミングとトラック属性の定義
  2. 02コンポジションとサブコンポジションの構成
  3. 03GSAP タイムラインとメディア再生の連携
  4. 04決定論的レンダリングのルール
  5. 05lint と検証チェックリスト

活用シーン

  1. 01時間指定のある HTML 動画コンポジションの作成
  2. 02既存プロジェクトのクリップやアニメーションの調整
  3. 03レンダリング前のコンポジション検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/heygen-com/hyperframes --skill hyperframes-compose

インストール後、Claude Code で/hyperframes-composeを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

data-in-motion.md
house-style.md
patterns.md
palettes/
bold-energetic.md
clean-corporate.md
dark-premium.md
jewel-rich.md
monochrome.md
nature-earth.md
neon-electric.md
pastel-soft.md
warm-editorial.md

詳細

動画の構成

動画のソースオブトゥルースは HTML です。構成は、タイミング用の data-* 属性、アニメーション用の GSAP タイムライン、外観用の CSS を含む HTML ファイルです。フレームワークがクリップの表示、メディアの再生、タイムラインの同期を処理します。

アプローチ

HTML を記述する前に、全体像を考えます。

  1. 内容 — 視聴者にどのような体験をしてもらうか。物語の流れ、重要な場面、感情の動きを特定します。
  2. 構成 — 構成はいくつにするか、サブ構成とインラインのどちらにするか、各トラックに何を配置するか（動画、音声、オーバーレイ、キャプション）。
  3. タイミング — どのクリップが長さを決めるか、トランジションをどこに配置するか、テンポをどうするか。
  4. 実装 — その後、以下のルールに従って実装します。

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

visual-style.md やアニメーションの指示がない場合は、モーションのデフォルト、サイズ、カラーパレットについて house-style.md に従ってください。

データ属性

すべてのクリップ
属性必須値
idはい一意の識別子
data-startはい秒数またはクリップ ID 参照（"el-1"、"intro + 2"）
data-durationimg/div/構成では必須秒数。動画と音声は、デフォルトでメディアの長さになります。
data-track-indexはい整数。同じトラック上のクリップは重複できません。
data-media-startいいえソース内のトリミング位置（秒数）
data-volumeいいえ0～1（デフォルトは 1）

data-track-index は視覚的な重ね合わせに影響しません。CSS の z-index を使用してください。

構成クリップ
属性必須値
data-composition-idはい一意の構成 ID
data-durationはいGSAP タイムラインの長さより優先されます
data-width / data-heightはいピクセル寸法（1920x1080 または 1080x1920）
data-composition-srcいいえ外部 HTML ファイルへのパス

構成の構造

すべての構成は、data-composition-id を持つ <div> を囲む <template> です。それぞれに独自の GSAP スクリプトを含め、タイムラインを登録する必要があります。

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </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 });
      // tweens...
      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>

動画と音声

動画には muted playsinline が必要です。音声は必ず独立した <audio> 要素にします。

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

タイムラインの仕様

  • すべてのタイムラインは { paused: true } で開始します。再生はプレーヤーが制御します。
  • すべてのタイムラインを登録します：window.__timelines["<composition-id>"] = tl
  • フレームワークがサブタイムラインを自動でネストします。手動で追加しないでください。
  • 長さは GSAP タイムラインの長さではなく、data-duration で決まります。
  • 長さを設定するために空のトゥイーンを作成しないでください。

ルール（必須）

決定性: Math.random()、Date.now()、または時間ベースのロジックは使用しないでください。レンダラーは毎回同一の出力を生成する必要があります。

GSAP: アニメーションできるのは視覚プロパティ（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、トランスフォーム）のみです。visibility、displayはアニメーションしないでください。また、video.play()／audio.play()も呼び出さないでください。

アニメーションの競合: ヘッドレスレンダリングでちらつきが発生するため、同じ要素の同じプロパティを複数のタイムラインから同時にアニメーションしないでください。

禁止事項:

  1. window.__timelinesへの登録を忘れない
  2. 音声に動画を使用しない — 必ずミュートした動画と個別の<audio>を使用する
  3. タイミング指定されたdiv内に動画をネストしない — タイミング指定のないラッパーを使用する
  4. data-layer（data-track-indexを使用）やdata-end（data-durationを使用）を使用しない
  5. 動画要素の寸法をアニメーションしない — ラッパーのdivをアニメーションする
  6. メディアの再生／一時停止／シークを呼び出さない — 再生はフレームワークが管理する
  7. data-composition-idのないトップレベルコンテナを作成しない

既存のコンポジションの編集

  • まずコンポジション全体を読み、既存のフォント、色、アニメーションのパターンに合わせます
  • 依頼された箇所のみ変更し、変更対象外のセクションを書き換えないでください
  • 小さな変更のためにファイル全体を書き換えないでください
  • 関係のないクリップのタイミングは維持してください

タイポグラフィとアセット

  • 各コンポジションで独自のフォントを読み込みます（<style>内の@importまたは@font-face）
  • ローカルフォントにはfont-display: blockを使用します — キャプチャ前にフォントを読み込む必要があります
  • 外部URLから読み込むメディアにはcrossorigin="anonymous"を追加します
  • 読みやすい文字サイズの最小値は、横向きで20px、縦向きで18pxです
  • コンテナからはみ出す可能性のある動的テキストには、window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })を使用して、1行に収まる最大フォントサイズを計算します。戻り値は{ fontSize, fits }です。オプション：baseFontSize（デフォルトは78）、minFontSize（デフォルトは42）、step（デフォルトは2）。fontFamilyとfontWeightは、要素に適用されるCSSと一致させる必要があります
  • すべてのファイル（動画、音声、フォント、画像）は、index.htmlと同じプロジェクトルートに置きます
  • サブコンポジションからルートファイルを参照するには、../を使用します

PiP、タイトルカード、スライドショーのパターンについては、patterns.mdを参照してください。
データ、統計、インフォグラフィックについては、data-in-motion.mdを参照してください。
タイプライター風テキストやその他のGSAPアニメーション効果については、gsap-effectsスキルを参照してください。
音声駆動のアニメーション（ビート同期、グロー、パルス）については、audio-reactiveスキルを参照してください。

出力チェックリスト

  • すべてのトップレベルコンテナにdata-composition-idがある
  • すべてのコンポジションにdata-width、data-height、data-durationがある
  • 各コンポジションを独立したHTMLファイルに置き、data-composition-src経由で読み込む
  • サブコンポジションに<template>ラッパーがある
  • すべてのコンポジションでwindow.__timelinesに登録されている
  • 100%決定的 — ランダム性なし
  • 各コンポジションにGSAPが含まれている：<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
  • npx hyperframes lintがエラー0件で成功する
  • npx hyperframes validateがエラー0件で成功する（スタジオを開く前に両方を実行する）

コメント

Markdown 対応