shader-gen

シェーダージェネレーター

submit_shader または inspect_item がまだ読み込まれていない場合は、呼び出す前に ToolSearch で読み込み、推測ではなく実際のパラメーターを使用してください。

送信のみ：バックエンドの生成ジョブを作成し、jobId を返します。送信後のジョブのライフサイクル管理には、track_progress ツールを使用してください。

新しいシェーダーには必ず generate.ts を使用してください。 手動での作成は、既存アセットのコードを編集する場合に限ります。生成に失敗したときの代替手段として使用してはいけません。

カタログ優先のルール — 生成前に既存アセットを試してください

ユーザーが browse_assets にすでに表示されている正確なアセット ID を指定している場合を除き、シェーダーを生成する前に browse_library を呼び出してください。

browse_library は、組み込みエフェクト、組み込みトランジション、プロジェクトのエフェクト／トランジションアセットの信頼できる情報源です。組み込みアセットは安定したグローバルアセット ID であり、プロジェクトごとの DB アセットではないため、browse_assets に表示されない場合があります。

カタログの項目を適用するには edit_item を使用し、submit_shader は呼び出さないでください。

適切なカタログ検索の例：

browse_library(query: "zoom")
browse_library(category: "transitions", query: "dissolve")
browse_library(category: "audio-fx")

ユーザーの意図に十分近いカタログ項目がない場合に限り、生成してください。

builtin:zoom でも、ほかのエフェクトと同じトラックに紐づく配置を使用します

エフェクトには常にタイムライン上の範囲があります。クリップ全体にエフェクトを適用する場合は targetItemId を指定してください。ChatCut がそのクリップを基準にした範囲へ解決します。タイムライン上の範囲を明示する場合は、trackId + trackBoundFrom + trackBoundDurationInFrames を指定してください。

# Zoom on the entire video clip
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","targetItemId":"<clip-id>","propertyOverrides":{"magnification":1.5,"shape":"hold"}}]}')

# Zoom on a sub-range of the clip (e.g. frames 90–150 only, a punch zoom on a beat)
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<trackId>","trackBoundFrom":90,"trackBoundDurationInFrames":60,"propertyOverrides":{"magnification":2,"shape":"punch"}}]}')

トラック項目の ID とタイムラインフレーム範囲を取得するには、preview_timeline({views:["timeline"],tracks:["V1"]}) を使用してください。正確な項目の詳細が必要な場合は、inspect_item({itemId:"..."}) を使用してください。

キー	型	範囲／値	デフォルト	備考
magnification	数値	1–4	1.5	ズーム倍率。1 = ズームなし、2 = 2 倍に拡大
focalPointX	数値	0–1	0.5	水平方向の焦点（0 = 左、1 = 右）
focalPointY	数値	0–1	0.5	垂直方向の焦点（0 = 上、1 = 下）
shape	選択式	punch / hold / slow-push / instant	hold	アニメーションカーブ
focalMode	選択式	auto / manual	auto	auto は被写体を選択し、manual は焦点を使用
easeInFrames	数値	0–60	8	徐々に拡大するフレーム数
easeOutFrames	数値	0–60	8	徐々に縮小するフレーム数

デフォルトのズームでは propertyOverrides 全体を省略してください。変更するキーのみを送信します。これはパッチセマンティクスです。

クリップ基準と調整トラック

エフェクト項目には、どちらも具体的な時間範囲を持つ配置方法が 2 つあります。

• クリップ基準：クリップ全体に適用する場合は targetItemId を指定するか、クリップと交差する範囲を明示します。保存された範囲はそのクリップ内で相対的に扱われ、クリップを移動すると追従します。
• 調整トラック：トラック上の空き領域に範囲を設定する場合は、trackId + trackBoundFrom + trackBoundDurationInFrames を指定します。この範囲はタイムライン上で絶対的に設定されます。

クリップ全体にエフェクトを適用する場合は targetItemId を使用してください。指定する範囲がクリップの全長と異なる場合に限り、明示的なトラックジオメトリを使用してください。

組み込み 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 アセットも、assetId だけが異なる同じ形式です。詳しくは、以下の「既存の LUT アセットを適用する」を参照してください。

対応する対象

エフェクトとトランジションは、video、image、gif 項目に適用できます。

種類の振り分け

何かを生成する前に、まず生成以外の次の 2 つの方法を確認してください。

1. カタログのエントリー — 組み込みのエフェクトやトランジションには browse_library を使用します。
2. プロジェクトライブラリにすでにあるユーザーがアップロードした .cube LUT アセット — 生成する代わりにバインドします。詳しくは、以下の「既存の LUT アセットを適用する」を参照してください。browse_assets では、type: effect で editableProperties に lut 型のエントリーがあるものとして表示されます。

ユーザーの要望	--type
動画の外観（色、ぼかし、グロー、粒子、歪み）	effect
カラーグレーディング／ルック（ティール＆オレンジ、シネマティック、ビンテージ、LUT 風）	effect
表示の制御（マスク、表示、ワイプ、図形による切り抜き、グラデーションフェード）	effect
クリップ間のブレンド（クロスフェード、ディゾルブ、スライド、3D キューブ／ページめくり）	transition

表の「LUT 風」とは、LUT に似た新しい GLSL カラーグレーディングを生成することを意味します。これは、ユーザーが新しいものを求めている場合に限ります。ライブラリにある .cube ファイルを適用したい場合は、生成せず、既存のアセットをバインドしてください。

生成する場合に、LUT やマスク専用のジェネレーターはありません。いずれも effect です。

既存の LUT アセットを適用する

デフォルトの対象はタイムラインです。「この LUT を適用して」は、クリップに edit_item エフェクトを適用することを意味します。edit_asset sourceLut を使用するのは、ユーザーがソース自体に、それが使われているすべての場所で適用するよう求めた場合に限ります。たとえば、そのアセットから切り出されたすべてのクリップに適用する場合や、映像をログから Rec.709 に正規化する場合です。これはすべてのタイムライン上にあるアセットの全インスタンスを変更するためです。

ユーザーがアップロードした .cube ファイルは、category: "lut" のエフェクトアセットになります。クリップへの適用は生成ではありません。組み込み LUT と同じ edit_item エフェクト形式で、そのアセット固有の ID を assetId に指定します。

edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"<lut-effect-asset-id>","propertyOverrides":{"intensity":1}}]}')

重要な点：

• assetId は LUT エフェクトアセットの実際の ID です。文字列 "lut" を assetId に指定することはできません。また、propertyOverrides の中に LUT バインディングをネストすることもできません。
• propertyOverrides に含めるのは intensity（0–1、デフォルトは 1）のみです。.cube のバインディングはエフェクト項目ではなく、アセットにあります。
• ID は browse_assets type:"effect" で確認します。editableProperties に lut 型のキーがあるものが LUT アセットです。組み込み LUT は browse_library category:"luts" から取得します。
• targetItemType のデフォルトは video です。image と gif にも対応しています。
• 置き換えるには、エフェクトを削除し、もう一方の LUT の assetId を指定して再追加します。削除するには、エフェクト項目を削除します。
• 1 つのタイムライン項目だけでなく、ソースクリップが使われているすべての場所でグレーディングするには、動画／画像／GIF アセットに対して edit_asset の update を使用し、{"sourceLut":{"assetId":"<lut-effect-asset-id>"}} を指定します。{"sourceLut":null} で削除できます。
• .cube がまだプロジェクトにない場合、この手段では取り込めません。この機能には LUT のインポート経路がなく、.cube はチャット添付ファイルとしても受け付けられないため、ファイルを送るようユーザーに求めないでください。代わりに、エディターのメディアプールにドラッグするよう案内してください。エディターが LUT アセットとして登録し、その後 browse_assets に表示されます。ChatCut は .cube を扱えないと伝えないでください。エディターでは扱えます。

この経路では submit_shader を呼び出さないでください。

適用後、preview_timeline で対象クリップのトラックにエフェクトが表示されていることを確認してください。edit_item の応答だけで成功を報告しないでください。

使用方法

submit_shader を呼び出す前に、ユーザーの意図を具体的な一文で言い換えてから、すぐに処理を進めてください。track_progress が返された後は、生成されたものを一行で伝えてください。「このまま使いますか、それとも再生成しますか？」とは尋ねないでください。

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 のみであることを説明しています。モーショングラフィックスのプロパティも配列ですが、使用する型の種類は異なります。

パラメーター

Param	Description	Default
type	"effect" または "transition"（必須）	—
prompt	シェーダーの説明（必須）	—
name	ライブラリーに表示されるアセット名	—
referenceAssetIds	アセット ID。画像 ID → 視覚的な着想を得るためにモデルが参照します。エフェクト／トランジション ID → スタイルの基準としてコードを再利用します（送信ごとに最大 1 つ。type と種類が一致している必要があります）。	—

出力

{ success, job: { jobId, status }, manage: { status, wait, watch } } を返します。

タイムラインへの適用

ユーザーから明示的に依頼された場合に限ります。影響を受けるタイムラインを view:"timeline" で更新し、適切な場合は track を指定して読み取り対象を絞り込んでください。

エフェクト

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 も読んでください。

一般的なワークフローは次のとおりです。

1. シェーダーの assetId と includeCode: true を指定して inspect_asset を実行し、現在のソースを読み取ります。
2. 自分のコンテキスト内でソースを編集します。
3. action=update と同じ assetId を指定して edit_asset を実行し、完全な置換用ソースを json.code にインラインで渡します。更新時に検証が自動実行され、コードが無効な場合は、エラーの詳細とともに更新が拒否されます。