Communitygithub.com

KingBridgeSS/sakugacut

HyperFrames HTMLを用いて、ビデオ合成、アニメーション、タイトルカード、オーバーレイ、キャプション、ナレーション、オーディオリアクティブビジュアル、シーントランジションを作成します。確定したSakugaCutタイムラインプランを実装する際に使用します。CLIの初期化、lint、チェック、スナップショット、ドラフトレンダリングにはhyperframes-cliを、プリプロセスにはhyperframes-mediaを読み込みます。

sakugacut とは?

このスキルは、HyperFramesフレームワークを使用してプログラムによるビデオ合成を作成するための包括的なガイドです。主な原則は、HTMLをビデオの唯一の信頼できる情報源とすることであり、タイミング用の`data-*`属性、アニメーション用のGSAPタイムライン、およびスタイリング用のCSSで構成されます。デザインシステムの発見、プロンプトの拡張、構造化された計画など、段階的なアプローチを説明し、レイアウトファースト、アニメーションセカンドの設計原則を強調しています。このスキルは、パラメータ化可能な構成、サブ構成、および様々なビデオ要素のための正確なデータ属性をサポートしており、ビデオ編集エージェント向けに設計されています。さらに、`hyperframes-cli`を使用してレンダリングし、`hyperframes-media`でメディアをプリプロセスするためのCLI統合も含まれています。

対応~Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/KingBridgeSS/sakugacut/tree/HEAD/hyperframes_skills/hyperframes

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

HyperFrames

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

アプローチ

発見(探索的なリクエストのみ)

方向性が決まっていない自由形式のリクエスト(「製品ローンチビデオを作って」、「ブランド用に何か作って」など)の場合、色を決める前に意図を理解します。

  • オーディエンス — 誰が見ますか? 開発者? エグゼクティブ? 一般消費者?
  • プラットフォーム — どこで再生されますか? ソーシャル(15秒)、ウェブサイトヒーロー、製品デモ、社内?
  • 優先順位 — 最も重要なものは? モーションの品質? コンテンツの正確性? ブランドの忠実性? スピード?
  • バリエーション — ユーザーはオプションを望んでいますか、それとも単一のベストショットを望んでいますか?

特定のリクエスト(「タイトルカードを追加」、「シーン3のタイミングを修正」)の場合は、発見をスキップします。

探索的なリクエストの場合は、単なる色の変更ではなく、異なるペーシング、エネルギーレベル、または構造的アプローチなど、意味のある方法で異なる2〜3のバリエーションを検討します。1つは安全/予想通り、1つは野心的です。これを強制しないでください — 適切な場合に利用できるツールです。

ステップ1:デザインシステム

design.mdまたはDESIGN.mdがプロジェクトに存在する場合、まずそれを読みます(両方の大文字小文字を確認してください — Linuxでは別のファイルです)。ブランドカラー、フォント、および制約の唯一の信頼できる情報源です。その正確な値を使用してください — 色を発明したり、フォントを代用したりしないでください。どのような形式でも機能します(YAMLフロントマター、散文、テーブル — 値を抽出するだけです)。

ローカルで見つけられないフォントが指定されている場合(fonts/ディレクトリに.woff2ファイルがない、組み込みフォントではない)、HTMLを作成する前にユーザーに警告します:「design.mdは[フォント名]を指定していますが、フォントファイルが見つかりません。fonts/に.woff2ファイルを追加してください。そうしないと、最も近い組み込みの代替フォントにフォールバックします。」

design.mdが存在しない場合、ユーザーに選択肢を提供します。

  1. ユーザーがスタイルやムードを指定しましたか? → visual-styles.mdを読んで、8つの名前付きプリセットを確認します。最も近いものを選択します。
  2. 視覚的にオプションを閲覧しますか? → デザインピッカーを実行: references/design-picker.mdを読んで、完全なワークフローを確認します。これにより、視覚的なピッカーページが提供されます。ユーザーはブラウザでムード、パレット、タイポグラフィ、モーションを設定し、生成されたdesign.mdをコピーして会話に貼り付けます。
  3. スキップしてすぐに進みますか? → 質問: ムード、ライトまたはダーク、ブランドカラー/フォントはありますか? 次に、house-style.mdからパレットを選択します。

design.mdはブランドを定義します。ビデオ合成ルールを定義しません。 それらはreferences/video-composition.mdとhouse-style.mdにあります。ブランドカラーは、ウェブUIの不透明度ではなく、ビデオに適したスケールで使用します。

ステップ2:プロンプト拡張

すべてのコンポジションで常に実行します(単一シーンの作品や些細な編集を除く)。このステップは、design.mdとhouse-style.mdに対してユーザーの意図を具体化し、下流のすべてのエージェントが同じように読む一貫した中間成果物を生成します。

完全なプロセスと出力形式については、references/prompt-expansion.mdを読んでください。

ステップ3:計画

HTMLを作成する前に、ハイレベルで考えます。

  1. 何を — 視聴者は何を体験すべきですか? 物語の弧、重要な瞬間、感情的なビートを特定します。
  2. 構造 — いくつのコンポジション? どれがサブコンポジションでどれがインラインか? どのトラックが何を運ぶか(ビデオ、オーディオ、オーバーレイ、キャプション)。
  3. リズム — 実装する前にシーンのリズムを宣言します。どのシーンがクイックヒットで、どれがホールドか、シェーダーはどこに配置されるか、エネルギーがどこでピークに達するか。パターンに名前を付けます: fast-fast-SLOW-fast-SHADER-hold。リズムテンプレートについては、references/beat-direction.mdを読んでください。
  4. タイミング — どのクリップが継続時間を決定するか? トランジションはどこに配置されるか? ペーシングはどうか?
  5. レイアウト — まず最終状態を構築します。以下の「アニメーション前のレイアウト」を参照してください。
  6. アニメート — 次に、以下のルールを使用してモーションを追加します。

依頼されたものを構築します。 「タイトルカード」のリクエストは、「タイトルカード + 3つのサポートシーン + 環境音楽 + キャプション」のリクエストではありません。すべてのシーン、すべての要素、すべてのトゥイーンは、その場所に値するものでなければなりません。追加のシーンや要素が作品を真に向上させる場合は、提案してください — 追加しないでください。

小さな編集(色の修正、タイミングの調整、1つの要素の追加)の場合は、ルールに直接スキップします。

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

すべての要素を、最も見える瞬間 — 完全に入ってきて、正しく配置され、まだ退出していないフレーム — にあるべき位置に配置します。これを最初に静的な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位置が信頼できる情報源であり、トゥイーンはそこに到達するまでの経路を記述します。(data-composition-srcを介して読み込まれたサブコンポジションでは、gsap.fromTo()を優先します — references/motion-principles.mdの負荷のかかるGSAPルールを参照してください。)
  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:これらの位置にアニメーション INTO
ll.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-durationimg/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-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ステップパターン:

  1. コンポジションの<html>ルートでdata-composition-variablesを使用して変数を宣言します。各エントリには、id、type(string、number、color、boolean、enumのいずれか)、label、defaultが必要です。Enumエントリにはoptions: [{value, label}, ...]も必要です。
  2. コンポジションのスクリプト内でwindow.__hyperframes.getVariables()を使用して解決された値を読み取ります。宣言されたデフォルト + インスタンスごとのオーバーライド + CLIオーバーライドのマージ結果を返します。
  3. レンダリング時に、npx hyperframes render --variables '{...}'(トップレベル)またはホスト要素のdata-variable-values='{...}'(サブコンプのインスタンスごと)でオーバーライドします。
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Hello"},
  {"id":"theme","type":"enum","label":"Theme","default":"light","options":[
    {"value":"light","label":"Light"},
    {"value":"dark","label":"Dark"}
  ]}
]'
>
  <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 Report","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":"$99"}'
></div>

オーディオリアクティブおよびデータ駆動ビジュアル

オーディオの周波数と振幅に反応するビジュアル、またはJSONデータセットから駆動されるビジュアルを作成します。

オーディオ分析

<canvas>でオーディオ分析を使用するには、<audio>要素にdata-audio-source属性を設定します。

<audio data-audio-source="track-0" src="music.mp3"></audio>
<canvas id="visualizer"></canvas>
<script>
  const audioEl = document.querySelector('[data-audio-source="track-0"]');
  const audioContext = new AudioContext();
  const source = audioContext.createMediaElementSource(audioEl);
  const analyser = audioContext.createAnalyser();
  analyser.fftSize = 256;
  source.connect(analyser);
  source.connect(audioContext.destination);

  const bufferLength = analyser.frequencyBinCount;
  const dataArray = new Uint8Array(bufferLength);

  function draw() {
    requestAnimationFrame(draw);
    analyser.getByteFrequencyData(dataArray);
    const canvas = document.getElementById('visualizer');
    const ctx = canvas.getContext('2d');
    // dataArrayを使用して描画
  }
  draw();
</script>

ビデオフレーム検出

data-video-sourceが設定された<video>要素に対してcanvasを使用して、ビデオフレームに基づいてビジュアルをレンダリングします。

データセット駆動ビジュアル

変数を使用してJSONデータセットをコンポジションに渡し、getVariables()で読み取ります。

<script>
  const data = window.__hyperframes.getVariables().chartData;
  // dataでSVGまたはcanvasに描画
</script>

キャプションと字幕

キャプションを追加するには2つの方法があります:

  1. SRTトラック: <track data-caption-src="captions.srt" kind="captions" srclang="en" label="English">
  2. インラインキャプション: data-captions='[{"start":0, "end":3, "text":"Hello"}]'を任意の要素に設定

インラインキャプションの例:

<div data-captions='[{"start":0,"end":2,"text":"Welcome"},{"start":2,"end":4,"text":"to HyperFrames"}]'>
  <h1>Main Content</h1>
</div>

シーントランジション

トランジションはdata-transition属性を使用して定義します。

<div
  data-start="0"
  data-duration="5"
  data-transition='{"out":"fade","duration":0.5}'
>

利用可能なトランジション:fade、slide-left、slide-right、slide-up、slide-down、zoom-in、zoom-out、crossfade。

CLIリファレンス

# プロジェクトの初期化
npx hyperframes-cli init

# 構文チェック
npx hyperframes-cli lint

# 整合性チェック(重複、ギャップ)
npx hyperframes-cli check

# スナップショットの作成
npx hyperframes-cli snapshot

# ドラフトレンダリング(低品質、高速)
npx hyperframes-cli draft-render

# 高品質レンダリング
npx hyperframes render --output final.mp4

# メディアのプリプロセス
npx hyperframes-media preprocess --input raw/ --output media/

ベストプラクティス

  • すべてのdata-start値を相対時間(例:"prev + 0.5")ではなく絶対秒数で指定します。
  • 可読性のためにタイムラインコードで名前付きの開始時間を使用します:const SCENE_1_START = 0; const SCENE_2_START = 5;
  • すべてのビデオ/オーディオソースが.mp4 / .mp3 / .wav形式であることを確認します。
  • 複雑なプロジェクトではサブコンポジションを好みます。data-composition-srcはモジュール性を強制します。
  • GSAPのpaused: trueでタイムラインを初期化して、手動制御を可能にします。
  • 変数を使用してコンポジションを再利用可能にします — データ駆動型のテンプレートを実現します。

制限事項

  • GSAPタイムラインのみがサポートされています。data-composition-srcを通じてサブコンポジションを読み込むときに、ページ全体のリロードはサポートされていません。
  • オーディオ分析はHTMLの<canvas>でのみ機能します。
  • design.mdが指定するフォントは.woff2形式である必要があります。
  • 絶対配置できるのは装飾要素のみです。コンテンツコンテナはフレックスベースである必要があります。

関連スキル