mcpField
A
aip-composition

aip-composition

github.com/opus-proクリエイティブ・メディア7127 回インストール4 日前に更新
リポジトリ

aip-composition について

aip-compositionは、AI Producerの動画プロジェクトでHTMLコンポジションを作成するスキルです。編集可能なモーショングラフィックスを作り、エディターと書き出し機能が認識する構造に沿って、編集可能な要素とコード描画レイヤーを区別します。

主な機能

  1. 01HTMLで動画コンポジションを定義
  2. 02GSAPタイムラインでアニメーションを駆動
  3. 03DOMとCanvasレイヤーの組み合わせ
  4. 04話者クリップとビジュアルクリップの設定
  5. 05エディターが認識する構造に準拠

活用シーン

  1. 01タイトルカードやモーショングラフィックスの制作
  2. 02編集可能なテキストやラベルの重ね合わせ
  3. 03コンポジションへのCanvas描画3Dコンテンツの追加

インストール

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

$npx skills add https://github.com/opus-pro/ai-producer-plugin --skill aip-composition

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

同梱ファイル

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

agents/
openai.yaml
references/
code-drawn.md
motion-recipes.md
pip-transition.md
text-treatments.md

詳細

AI Producer プロジェクト向け HyperFrames

Copyright 2026 HeyGen, Inc. Modifications Copyright 2026 OpusClip. AIP 向けに OpusClip が変更しました。ソースの帰属、ライセンス、変更内容をご覧ください。

HTML が動画です。コンポジションは data-* のタイミング属性を持つ HTML 要素であり、プレーヤーが駆動する一時停止状態の GSAP タイムラインを 1 つ持ちます。AI Producer のエディターは独自のプレーヤーで HTML を再生し、エクスポートでは AI Producer 独自の固定バージョンの HyperFrames を使ってレンダリングします。これらは再生と編集の仕様が別々の 2 つのプログラムです。このページは、その 2 つが読み取るインターフェースにすぎません。何を描くか、どう動かすか、キャプションをどこに配置するか、各場面をどのように見せるかは、あなたが決めます。

AI Producer が受け入れるもの

  • プロジェクトは render-engine/ の下に置きます。index.html、compositions/*.html、および public/ の下にあるアセットです。AI Producer は public/source.mp4(録画)と public/source.mp3(その音声)を配置し、GSAP を public/vendor/gsap.min.js に置きます。GSAP はそのパスから読み込んでください。このコンピューターで確認するページでは、このプロジェクトにあるファイルが読み込まれます。詳しくはメインのスキルをご覧ください。
  • 受け入れ可能なファイルとアップロード制限については、AI Producer ワークスペース形式で説明しています。プロジェクト外のスクリプトは拒否されるため、コンポジションのロジックはインラインで記述します。
  • 各場面は、描画するものに応じて分けてください。テキスト、ラベル、カード、カウンターなど、ユーザーがテキストを入力し直したりスタイルを変更したりする可能性があるものは、GSAP でアニメーションする DOM 要素にします。平面的に配置するのではなく、CSS 3D(perspective、3D 回転、translateZ による重ね合わせ)で実際の奥行きを与えます。3D オブジェクトや空間、シェーダー駆動の面、DOM では扱うには密度が高すぎるデータは、コード描画レイヤーの規則に従って、スクリプトから <canvas> に描画します。3D には Three.js を使います。このコミットでは、独自のクロックで動作するキャンバスや、表示領域の外で WebGL コンテキストを保持するキャンバスは拒否されます。1 つの場面に両方を組み合わせ、DOM ラベルを重ねたキャンバスシーンにすることもできます。エディターはキャンバスを単一のリーフとして扱うため、ユーザーはキャンバスが描画するものを選択したりスタイル変更したりできません。ユーザーが編集する可能性があるものは、DOM に配置してください。
  • ユーザーの画像は public/images/<name> に、ユーザーのクリップは public/videos/<stem>.mp4 に配置されます。<name> はファイル名から ASCII の英字、数字、-、_、. 以外を取り除いたものです(空白は - に変換され、それ以外の文字は削除されます)。その他の文字を使うと、ブラウザーが要求する URL が変わるためです。引き渡し時のチェックでは、コンポジションが src または href を通じて参照する各ファイルがツリー内にあることを確認します。別の方法(data-pip-src、CSS の url(...) など)で参照するファイルはチェックされません。そのため、コンポジションと同じアップロードバッチで配置し、コミット後に一覧で確認してください。

エディターが index.html で認識するもの

  • ルート要素:<div id="stage" data-composition-id="finecut-root" data-start="0" data-duration="<total s>" data-width="W" data-height="H">。このルートは <template> の中ではなく、ドキュメントの body に直接配置してください。ID は固定です。エディターはルートのタイムラインを window.__timelines["finecut-root"] としてシークするため、ルートのトランジションはそのタイムライン上に配置します。また、ルートはどのコンポジションが登録されるよりも前にレジストリを作成します。
<script>
  window.__timelines = window.__timelines || {};
  const rootTl = gsap.timeline({ paused: true });
  ...root tweens (never a speaker zoom or filter; see below)...
  window.__timelines["finecut-root"] = rootTl;
</script>
  • 話者:<video id="speaker" class="clip" src="public/source.mp4" muted playsinline data-volume="0"> と <audio id="speaker-audio" class="clip" src="public/source.mp3" data-volume="1">。メディア ID は一意にしてください。話者の映像は無音で、音声が主音源です。一般的な追加の <audio class="clip"> タグは、AI Producer の効果音トラックではありません。AI Producer の音声トラックには、その編集ドキュメントと派生した track-audio 要素が必要です。カット後は、同じ 2 つのファイルを参照する N 個の動画/音声ペアを使います。各要素には class="clip speaker-clip"、preload="none"、一意の id、および data-start、data-duration、data-media-start、data-track-index を指定します。プレーヤーはアクティブなペアを読み込み、次のペアを先読みします。先行読み込みを急ぐと、同じソースへのリクエストが繰り返されます。ペア内の data-hf-id とタイミングは共通にし、各ペアには異なる data-hf-id を割り当てます。最初のペアには speaker と speaker-audio を使います。各話者トラックの出力順は DOM 順なので、再生順に連続する出力開始時刻を指定して各区間を記述します。EditingScript の AV トラックには同じクリップ ID とソース/出力時刻を設定します。ワークスペースヘルパーが、公開前にその情報と字幕のタイミングを同期します。
  • ビジュアルモーメント:各モーメントにつき、<div class="visual-host clip" data-composition-id="<id>" data-title="<short name>" data-composition-src="compositions/<file>.html" data-start data-duration data-track-index data-width data-height> を 1 つ指定します。ホストの div がエディターに表示され、ユーザーが移動できるモーメントです。ルートに直接書かれたコンテンツはモーメントではありません。モーメントは映像の上に独立したレイヤーとして配置されます。そのコンポジションが描画する内容には、下にある映像は見えません。したがって、mix-blend-mode のように下の要素と合成する効果は、index.html のホスト div に指定します。これにより、エディターでも書き出しでもモーメント全体に適用されます。data-title には効果を表す短い名前(例:Commute title card)を指定します。エディターのタイムラインでは、この名前がモーメントのラベルとして表示され、指定がない場合はコンポジション ID が表示されます。これはレンダリングにも書き出しにも影響しません。サービスが字幕を生成したプロジェクトでは、ホストに、その表示時間内の字幕ポリシーを指定できます。data-hide-captions="false" を設定すると、モーメントの下でも現在の字幕を表示し続けます(属性がない場合、または "true" の場合は非表示で、これがデフォルトです)。data-caption-position="<integer percent of frame height>" は、その表示時間内における字幕帯の基準位置を移動し、data-caption-ink="#<six hex digits>" は、コンポジションが明るい背景として描画した場合などに、そのモーメントの下で字幕文字に使う色を指定します。エディター、サービスの編集処理、および書き出しは、これらの属性から字幕レイヤーの表示時間を再導出するため、モーメントを移動または削除すると、そのポリシーも一緒に移動します。自分で作成する字幕モーメントでは、これらの属性は無視されます。各キューの配置と色は、それぞれのコンポジションで指定します。
  • 字幕:字幕モーメントは、通常のビジュアルモーメントで、ID は captions-<n> です。発話のまとまりごとに 1 つ作り、各キューはコンポジション内に静的テキストとして配置します。タイミング、見た目、マウント方法は動的字幕スキルが管理します。narrator-captions という ID、compositions/narrator_captions.html、compositions/transcript-src.json はサービスの字幕レイヤーです。エディターと書き出しは ID を使ってこのレイヤーを特定し、インラインの const WORDS = [...]; 配列から字幕の語句を読み取ります。ID を宣言していても配列がないファイルはコミット時に拒否され、語句を書き込むのはサービスのみです。このレイヤーを自分で作成したり、その ID を再利用したりしないでください。字幕レイヤーが既にあるプロジェクトでは、マウントされた状態のまま維持し、ホストや index.html の .caption-band にオフセットを設定しないでください。これらを設定すると、全画面サイズの帯全体が移動し、すべての語句が画面外に出てしまいます。字幕のない編集では、これらのファイルは必要ありません。
  • 編集可能なビジュアルモーメントに属する話者の配置や PIP は、そのモーメント内に置きます。<div class="speaker-pip-frame" data-aip-editable="speaker-pip-frame"><video id="<unique>" data-pip-src="public/source.mp4" data-start="<the host's data-start>" data-duration="<the host's data-duration>" data-media-start="<source seconds at that start>" muted playsinline data-volume="0"></video></div> のように指定し、src は付けません。ルートの話者映像の上に不透明なモーメント背景を描画します。フレームを全画面から配置場所へ移動させる場合は、子のタイムライン内でアニメーションさせます。タイミング表の規則に対する唯一の例外として、この動画の data-start には 0 ではなくホストのグローバル開始時刻を指定します。これは書き出し時、カットのあるプロジェクトではその値をメディアオフセットとして設定し、動画の位置を合わせるためです。エディターはカットを通じて位置をマッピングします。映像とペイロードを同じホストの下に置くことで、タイムライン上で移動または削除したとき、両方にその変更が適用されます。サービスが frame_speaker を使って用意した話者の切り抜き(ウィンドウに合わせて切り出されたアルファチャンネル付き動画 public/speaker_<slug>.webm)も、data-media-start="0" を指定し、同じウィンドウを同一のジオメトリで表示する public/source.mp4 の映像を重ねて、同じ方法で接続します。タイミングと位置はフレーミングスキルが管理します。
  • 録画以外の映像(ユーザーのクリップ、ストック映像):PIP と分割表示のどちらも、index.html の専用トラックにルート動画クリップを置く方法をデフォルトにします。<video id="<unique>" class="clip" data-track-index="<n>" src="public/videos/<stem>.mp4" data-start data-duration data-media-start muted playsinline data-volume="0"> のように指定し、その映像をフレームに収めるモーメント(マスク、フレーム、タイトルなど)を上に描画します。別の方法として、同じタグをモーメントのコンポジション内に置くこともできます。<video id="<unique>" class="clip" src="public/videos/<stem>.mp4" data-start="<the host's data-start>" data-duration data-media-start muted playsinline data-volume="0"> のように指定し、PIP と同様にホストの時刻を基準にします。ルートクリップはユーザーがタイムライン上で移動でき、入れ子のクリップはモーメントと一緒に移動します。
  • 話者のズームまたはカラーフィルター:コンポジションファイルを持たない空のホストを使います。ズームの場合は、<div class="visual-host clip" data-composition-id="<id>" data-aip-effect="zoom" data-no-timeline data-start data-duration data-src-anchor data-track-index="20" data-hide-captions="false" data-effect-scale="<above 1, at most 3>" data-effect-origin="<x% y%>" data-effect-in="<s>" data-effect-out="<s>"></div> とします。フィルターの場合は、data-track-index="21" に data-aip-effect="filter" を指定し、スケールと原点の代わりに data-effect-filter="<grayscale, sepia, saturate, contrast, brightness, invert, hue-rotate, or blur functions>" を指定します。効果は data-effect-in 秒かけて徐々に適用され、維持された後、data-effect-out 秒かけて徐々に解除されます。すべてホストの表示時間内で行われ、ホストの表示時間外では話者映像は通常の状態になります。data-src-anchor は data-start におけるソース時刻です(話者クリップの data-media-start に、そのクリップ内のオフセットを加えた値)。そのため、カットを行っても、効果は対象の語句と一緒に移動します。ズーム同士、またはフィルター同士は重ねられませんが、ズームとフィルター、またはモーメントは重ねられます。ルートスクリプトの後にエンジンを読み込みます:<script src="public/vendor/speaker-effects.js"></script>。サービスは、このファイルを初めて読み込むコミット時に書き込むため、アップロードしないでください。エディターでは各ホストがタイムラインに表示され、ユーザーは移動、トリミング、削除、効果の調整ができます。ルートタイムライン上で話者の scale または filter をトゥイーンしてもエディターには表示されません。そのため、ズームやフィルターをその方法で記述してはいけません。
  • ズームやフィルター以外のカメラ処理(衝撃的な揺れ、白いフラッシュ、素早いパン、押し出し、手持ちカメラ風の揺れ):モーションホスト <div class="visual-host clip" data-composition-id="<id>" data-aip-effect="motion" data-no-timeline data-start data-duration data-src-anchor data-track-index="<900 to 907>" data-hide-captions="false" data-effect-motion="<name>" data-effect-params='{"<param>":<number>}'></div> と、index.html 内のインライン <script data-aip-motion="<name>"> を 1 つ使います。このスクリプトで window.__aipMotions["<name>"] = { label, params: { <param>: { min, max, default, label, unit } }, frame(t, d, p, rand) } を割り当てます。frame は x と y(ピクセル)、scale(1 から 3)、rotate(度)、および overlay: { color: "#rrggbb", opacity }(字幕を含む全画面を覆う色)のいずれかを返します。値は引数のみから計算します。t はホスト内の経過秒数、d はホストの長さ、p はパラメーター値、rand(i) はホストごとに固定された位相です。スクリプト内のどこでも Math.random、Date、performance、crypto、Intl、タイマーを読み込んではいけません。また、別の名前のエントリーを設定してはいけません。いずれかに違反すると、プレビュー、書き出し、各レンダーウィンドウで異なるフレームが描画されるため、サービスに拒否されます。時間的に重なるモーションは別々のトラックに配置し、効果を加算します。オフセットの合計は 160 px 以内、回転の合計は 8 度以内にします。サービスは、映像の端が見えないように必要最小限の範囲で映像を拡大します。または、2 倍の拡大でも覆えない場合はモーションを弱めます。ユーザーが調整できる値はすべてパラメーターとして宣言します(最大 8 個。それぞれ lower camel case で 16 文字以内の名前を付け、値を +/-1,000,000 の範囲内にします)。エディターでは各パラメーターがフィールドとして表示されます。実装例:モーションレシピ。
  • ユーザーが 1 つのオブジェクトとして移動およびスタイル変更する要素には、data-aip-editable="<token>" を指定します。ここで、トークンはその要素自身のクラスのいずれかです。エディターは .list-item、.glass-card、.media-card、.speaker-pip-frame、.item-bar も同様のオブジェクトとして扱います。モーメント内にあるその他の要素には、テキストまたは画像のリーフとしてしかアクセスできません。 ビジュアルモーメントが所有するシートやPIPを、ルートスピーカー上の絶対時間ジオメトリトゥイーンとして実装しないでください。ホストを移動または削除しても、ルートタイムライン上の任意のトゥイーンは書き換えられないため、その形状は元の時間のまま残ります。ルートスピーカーのジオメトリは、独立して編集可能なビジュアルモーメントが所有していないカメラ演出に限り使用してください。また、スケール、フィルター、フレームごとのカメラ移動には決して使用しないでください。スピーカーのズームやカラーフィルターはエフェクトホストであり、シェイク、フラッシュ、ウィップ、プッシュはモーションホストです。オプションのPIPの例では、エフェクトが所有するフルフレーム/PIPトランジションを紹介しています。

サブコンポジションファイル

<template>
  <div data-composition-id="<id>" data-width="W" data-height="H">
    ...content, with its <style> and <script> inside the template...
    <script>
      const root = document.querySelector('[data-composition-id="<id>"]');
      const tl = gsap.timeline({ paused: true });
      ...tweens on root.querySelector(...) targets...
      window.__timelines["<id>"] = tl;
    </script>
  </div>
</template>

内側のdivのdata-composition-idはホストのものと一致します。スニペットと同じように、[data-composition-id="<id>"]だけをセレクターに指定してルートをバインドし、そのルートに対する子孫クエリを通じてすべての要素にアクセスしてください。エクスポートマウントでは、内側のdivからdata-composition-idとその他のdata-*属性が取り除かれるため、エクスポート時にIDを持つ要素はホストだけになります。同じ要素にクラス、ID、属性、または:not(.visual-host)も要求するセレクターや、:scope >子セレクターはエクスポート時に何にも一致せず、スクリプトは登録前にエラーをスローし、エクスポートはそのモーメントを拒否します。エクスポート時にスニペットがバインドするrootはこのホストです。一方、ルートルール[data-composition-id="<id>"] { ... }は、その中にあるテンプレート自身のルート要素だけをスタイルするため、rootからスタイルを読み取ったり、テンプレートのルートに書き込んだ属性を読み取ったりしないでください。ルートルールで宣言したカスタムプロパティをrootから読み取ると""になり(parseFloatの結果はNaNになり、そこから計算される値は破棄されます)、その属性もホストにはありません。そのような値は、カスタムプロパティが継承されるルート内の要素から読み取るか、スクリプト定数として保持してください。複数のモーメントが同じドキュメント内で共存できるよう、スタイルと要素のクエリはコンポジションのコンテンツにスコープしてください。コンポジションのルートはベースポーズで表示された状態に保ち、アニメーションはコンポジションのルートやホストではなく、内側のラッパーまたはその子要素に適用してください。エディターがマウントするのは<template>内の内容だけで、エクスポートがマウントするのはテンプレート自体です。したがって、</template>の後に記述した<script>はどちらでもモーメントの一部にならないため、</template>の後には何も記述しないでください。このファイルに独自のマウントスクリプトは必要ありません。タイムラインの時刻0はホストのdata-startであり、プレーヤーはタイムラインを再生するのではなくシークします。DOMが存在した後、同期的に一時停止状態のタイムラインを作成して登録してください。レンダリングに不可欠な変更は、タイマー、requestAnimationFrameループ、再生コールバック、CSSアニメーションではなく、そのタイムラインに記述してください。tl.play()を呼び出したり、自分でメディア再生を開始したりしないでください。クロックはプレーヤーが管理します。アニメーションのリピートは有限にし、シークで決定論的な状態に到達できるよう乱数にはシードを指定してください。連続した移動は、そのスパン全体にわたるトゥイーンにしてください。数フレームずつ各ポーズを保持した後にジャンプするtl.setステップの連続にしてはいけません。その上に重ねるジッターは、トゥイーンするxやyとは別のチャネル(たとえばxPercentやyPercent)に適用してください。filterのトゥイーンは要素全体のフィルターを置き換えるため、filter: url(#...)で見た目を作る要素では、そのフィルターを内側の要素に適用し、ラッパーにトゥイーンを適用してください。ホスト属性が長さとアクティブウィンドウを管理するため、長さを設定するための空のトゥイーンを追加したり、子タイムラインをルートタイムラインに手動でネストしたりしないでください。

タイミング属性

属性対象値
data-startすべてのクリップ秒単位。親コンポジションからの相対値です(コンポジション内の PIP またはフッテージクリップの場合:ホストのグローバル開始位置。上記を参照)
data-durationすべてのクリップ秒単位。クリップ自体の長さです
data-track-indexすべてのクリップ整数。同じトラック上のクリップは重ねられません
data-media-startビデオとオーディオ秒単位のソースファイル内オフセットです
data-volume登録済みメディア再生ゲイン。0〜1 の範囲です。任意のオーディオが AI Producer のミキシングに追加されるわけではありません
data-width、data-heightコンポジションキャンバスの幅と高さ(px)です

プレビューの受け入れ

納品と、検査を行わずに停止する条件は AI Producer スキル が定めています。この契約はクリエイティブディレクションとは分けてください。ローカルのアニメーションサンプルが成功したり、アップロードが受け入れられたりしても、AI Producer のエディターやエクスポートが正しく動作することの証明にはなりません。

コメント