シェーダージェネレーター
送信専用:バックエンド生成ジョブを作成し、jobIdを返します。ジョブのライフサイクル管理には、送信後にtrack_progressツールを使用してください。
新しいシェーダーには必ず generate.ts を使用してください。 手動でのコード作成は、既存アセットコードの編集のみに許可されており、生成に失敗した場合のフォールバックとしては絶対に使用しないでください。
カタログ優先ルール — 生成前に既存アセットを試す
シェーダーを生成する前に、ユーザーが read_project で既に表示されている正確なアセットIDを指定していない限り、browse_library を呼び出してください。
browse_library は、組み込みエフェクト、組み込みトランジション、およびプロジェクトのエフェクト/トランジションアセットに関する信頼できる情報源です。組み込みアセットは安定したグローバルアセットIDであり、プロジェクトごとのDBアセットではないため、read_project のアセットリストに表示されない場合があります。
カタログエントリは edit_item で適用してください。submit_shader は呼び出さないでください。
適切なカタログ検索の例:
browse_library(query: "zoom")
browse_library(category: "transitions", query: "dissolve")
browse_library(category: "audio-fx")
カタログにユーザーの意図に十分に合致するエントリがない場合にのみ生成してください。
builtin:zoom はトラックバウンドのみ — アイテムバウンドでは使用しないでください
デフォルトのエフェクトモードは "item-bound" です(targetItemId を介して単一アイテムにアタッチ)。builtin:zoom はアイテムバウンドモードではレンダリングされません — レンダラーはトラックバウンドのエフェクトアイテムからのみズームデータを読み取ります。アイテムバウンドのズームはDBに挿入されますが、プレビューには何も表示されません。
mode: "track-bound" を trackId + trackBoundFrom + trackBoundDurationInFrames と共に使用してください。これら3つのフィールドは必須です。
# ビデオクリップ全体にズーム
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<clip-trackId>","trackBoundFrom":<clip-fromFrame>,"trackBoundDurationInFrames":<clip-durationInFrames>,"propertyOverrides":{"magnification":1.5,"shape":"hold"}}]}')
# クリップの一部範囲にズーム(例:フレーム90〜150のみ、ビートに合わせたパンチズーム)
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<trackId>","trackBoundFrom":90,"trackBoundDurationInFrames":60,"propertyOverrides":{"magnification":2,"shape":"punch"}}]}')
trackId / fromFrame / durationInFrames は read_project から取得します(各ビデオ/画像アイテムは、そのtrackIdとタイムラインフレーム範囲をリスト表示します)。
| キー | タイプ | 範囲 / 値 | デフォルト | 備考 |
|---|---|---|---|---|
magnification | number | 1–4 | 1.5 | ズーム倍率; 1=ズームなし, 2=2倍 |
focalPointX | number | 0–1 | 0.5 | 水平フォーカルポイント(0=左, 1=右) |
focalPointY | number | 0–1 | 0.5 | 垂直フォーカルポイント(0=上, 1=下) |
shape | select | punch / hold / slow-push / instant | hold | アニメーションカーブ |
focalMode | select | auto / manual | auto | autoは被写体を選択; manualはfocalPoint使用 |
easeInFrames | number | 0–60 | 8 | フェードインのフレーム数 |
easeOutFrames | number | 0–60 | 8 | フェードアウトのフレーム数 |
デフォルトのズームを使用する場合は、propertyOverrides 全体を省略してください。変更したいキーのみを送信してください — パッチセマンティクスです。
トラックバウンド vs アイテムバウンド — より広範なルール
スキーマ内のエフェクトアイテムには2つのモードがあります:
item-bound(デフォルト):targetItemIdのみ。エフェクトはターゲットアイテムの再生全体をカバーします。シェーダーエフェクト、LUT、カラーグレード、ブラーで機能します。track-bound:trackId+trackBoundFrom+trackBoundDurationInFrames。エフェクトはトラック上のタイムライン範囲をカバーし、アイテムから独立しています。builtin:zoomで必須。また、特定のタイムライン範囲をカバーしたい場合(例:2つのクリップの境界をまたぐトランジションのようなカラーシフト)は、任意のシェーダーエフェクトでも有効です。
シェーダーエフェクトではデフォルトでアイテムバウンドを使用します。トラックバウンドは、(a) アセットがそれを要求する場合(ズーム)、または (b) エフェクトが単一のアイテムに一致しないタイムライン範囲をカバーする必要がある場合に使用します。
組み込みLUTプロパティ
edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"builtin:slog3-s709","propertyOverrides":{"intensity":1}}]}')
| キー | タイプ | 範囲 | デフォルト | 備考 |
|---|---|---|---|---|
intensity | number | 0–1 | 1 | LUT強度; 1=完全適用 |
交換するには:エフェクトを削除し、異なる assetId で再追加します。削除するには:エフェクトアイテムを削除します。
これらは、ユーザーがアップロードした .cube LUTアセット(以下の「既存LUTアセットの適用」を参照)とは別物です。これらは assetId:"lut" を使用する異なるコードパスを使用します。
ベータステータスゲート
新しいシェーダー生成はベータ版です。生成する前に、ユーザーに警告し、明示的な確認を待ってください。
ユーザーの言語を使用してください。日本語:「新しいエフェクト/トランジションの生成は現在ベータ版であり、不安定な問題が発生する可能性があります。それでも実行したい場合は、対応します。」ユーザーが同じリクエスト内で既に認識している場合はスキップします。
サポート対象
エフェクトとトランジションは、video、image、gif アイテムに適用されます。
タイプルーティング
生成を行う前に、まず2つの非生成パスを確認します:
- カタログエントリ — 組み込みおよびプロジェクトのエフェクト/トランジションには
browse_libraryを使用します。 - ユーザーがアップロードした既存の
.cubeLUTアセット — プロジェクトライブラリに既に存在する場合。別のコードパスです。以下の「既存LUTアセットの適用」を参照してください。アセットはread_projectにtype: lutとして表示されます。
| ユーザーが希望するもの | --type |
|---|---|
| ビデオの外観(色、ブラー、グロー、グレイン、ディストーション) | effect |
| カラーグレード/ルック(ティールオレンジ、シネマティック、ビンテージ、LUTスタイル) | effect |
| 可視性制御(マスク、リビール、ワイプ、シェイプカットアウト、グラデーションフェード) | effect |
| クリップ間のブレンド(クロスフェード、ディゾルブ、スライド、3Dキューブ/ページフリップ) | transition |
表の「LUTスタイル」は、ユーザーが新しいものを望む場合にのみ、LUTに似た新しいGLSLカラーグレードを生成することを意味します。ライブラリに既に存在する .cube ファイルを適用したい場合は、生成せずに既存のアセットをバインドします。
生成パスに別個のLUTまたはマスクジェネレーターはありません — これらはすべて effect です。
既存LUTアセットの適用
ユーザーがアップロードした .cube ファイルは lut アセットになります。クリップに適用することは生成ではありません — これは単一の edit_item 呼び出しで、assetId がリテラル文字列 "lut" であり、propertyOverrides.lut が実際のLUTアセットIDをバインドするエフェクトアイテムをアタッチします。(レガシー契約; 統合LUT APIはLUTエフェクトアセットIDを直接バインドします — edit_item の説明を参照してください。)
edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"lut","propertyOverrides":{"intensity":1,"lut":{"assetId":"<lut-asset-id>","assetType":"lut","type":"asset"}}}]}')
重要なポイント:
assetIdはリテラル文字列"lut"であり、LUTアセットのIDではありません。実際のLUTアセットIDはpropertyOverrides.lut.assetId内に配置します。intensityは0–1; デフォルトは1(完全強度)。targetItemTypeのデフォルトはvideo;image、gifもサポートしています。- 既存のエフェクトでLUTを交換するには:
propertyOverrides.lut.assetIdを新しいLUTアセットIDに更新します。 - 削除するには: エフェクトアイテムを削除します。
このパスでは generate.ts を呼び出さないでください。実際のLUTアセットIDを assetId として渡さないでください — エディターは assetId === "lut" をチェックしてLUTレンダラーにルーティングします。UUIDを渡すと、何もレンダリングされずに黙って失敗します。
使用方法
submit_shader を呼び出す前に、ユーザーの意図を具体的な一文で言い換えてから、すぐに続行します。track_progress が戻った後、生成されたものを1行で述べてください — 「保持しますか、それとも再生成しますか」とは尋ねないでください。
submit_shader({
type: "effect",
prompt: "Chromatic aberration with RGB split",
name: "Chromatic Aberration",
});
submit_shader({
type: "transition",
prompt: "Smooth crossfade with soft edge",
name: "Crossfade",
});
submit_shader({
type: "effect",
prompt: "Cinematic teal-orange color grade",
});
submit_shader({
type: "effect",
prompt: "Stronger version",
referenceAssetIds: ["effect_asset_id"],
});
戦略
- 送信して停止します。ジョブが作成されたことをユーザーに伝えます。
- 送信後のステータス/待機には
track_progressツールを使用します。 - 生成は常にライブラリアセットを生成します — タイムラインの準備ができていないことを理由に拒否しないでください。
- 適用は別個のオプションです。 ユーザーが明示的に要求した場合のみ適用します("加到视频"、"apply"、"用到第一段")。曖昧な場合は、デフォルトでライブラリのみとします。
既存プロパティの編集
シェーダー asset.properties、適用されたエフェクト/トランジション item.propertyOverrides を編集したり、ハードコードされたシェーダー値をプロモートしたりする場合は、まず references/property-changes.md を読んでください。
これにより、シェーダー properties は配列であるが、許可されるシェーダープロパティタイプは number、boolean、color、select、vec2 のみであることが再確認されます。モーショングラフィックプロパティも配列ですが、異なるタイプセットを使用します。
パラメータ
| パラメータ | 説明 | デフォルト |
|---|---|---|
type | "effect" または "transition"(必須) | — |
prompt | シェーダーの説明(必須) | — |
name | ライブラリに表示されるアセット名 | — |
referenceAssetIds | アセットID。画像ID → モデルはそれを視覚的なインスピレーションとして見ます。エフェクト/トランジションID → そのコードをスタイルアンカーとして再利用します(送信あたり最大1つ、type と一致する必要があります)。 | — |
出力
{ success, job: { jobId, status }, manage: { status, wait, watch } } を返します。
タイムラインへの適用
ユーザーが明示的に要求した場合のみ。最初に read_project を呼び出して最新のタイムライン状態を取得します。
エフェクト
edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<id>","assetId":"<id>","enabled":true,"propertyOverrides":{}}]}')
トランジション
隣接する同じトラック上の2つのエンドポイントが必要です。edit_item はライブシームの実現可能性を検証し、フリーズフレームや隣接トランジションのオーバーラップを必要とする期間を拒否します。追加に失敗した場合は、提案された durationInFrames で再試行するか、クリップをトリミングしてハンドルを露出させるか、隣接トランジションを削除/短縮するか、またはハードカットを維持します。
edit_item(json: '{"adds":[{"type":"transition","assetId":"<id>","outgoingItemId":"<id1>","incomingItemId":"<id2>","durationInFrames":30}]}')
検証と確認
バックエンド検証
generate.ts を介して生成する場合、バックエンドが自動的に検証を処理します(トランスパイル、ASTセキュリティ、クラス構造、失敗時の再試行)。
手動コード検証
シェーダーコードをゼロから書かないでください。 新しいシェーダーには常に generate.ts を使用してください。このセクションは、既に生成された既存のシェーダーコードを変更する場合のみのためのものです。
シェーダーコードを手動で記述する場合は、最初に ${CLAUDE_SKILL_DIR}/references/design-principles.md を読んでください。変更が編集可能なプロパティに影響する場合は、${CLAUDE_SKILL_DIR}/references/property-changes.md も読んでください。
典型的なワークフロー:
read_projectをshader assetIdおよびcode: trueで呼び出します — 現在のソースを読み取ります。- 自分のコンテキストでソースを編集します。
edit_assetをaction=update、同じassetId、および完全な置換ソースをjson.codeにインラインで指定して呼び出します。検証は更新時に自動的に実行されます — コードが無効な場合、更新はエラー詳細とともに拒否されます。