LeClap

@leclap/mcp

ffmpeg-video-composer エンジンを エージェントから呼び出せる動画ツール として公開する MCP サーバーです。

AI エージェント（Claude Desktop、Cursor など）が LLM であり、このサーバーは、スキーマから 素敵なエフェクトを備えたカスタマイズ済みテンプレートを作成 し、それを 決定論的に 検証して mp4 にレンダリングするのを支援します。このサーバーには、共有のパッケージ化されたカタログを通じて 50 個のショーケースサンプルが含まれており、クリエイティブディレクション、記述子、必要な入力が付属しています。実行時にアプリや非公開のクリエイティブキットがなくても動作します。Remotion を利用した作成はオプションの経路です。 その結果は エージェントが組み合わせ可能で、決定論的で、再現可能な 動画です。これは、レンダリングではなくサンプリングを行う生成動画モデルとは対照的です。

ツール

ツール	説明
get_samples	id なしの場合: カテゴリ/バックエンド/クエリで絞り込んだサンプルのメタデータと必須入力 → { samples }。id ありの場合: そのサンプルと自己完結型の template JSON
get_template_schema	テンプレート記述子の JSON Schema と簡単な作成ガイド
get_motion_catalog	モーションプリセット、カメラ、グラフィックス、トランジション、イージング/時間文法、テーマ、プラットフォーム、ジャンルのドクトリン、シーンブループリント。{ query, kind? } → ランク付けされた一致（何にも一致しないクエリはカタログギャップログに記録されます）
validate_template	インライン記述子のドライラン（レンダリングなし）→ { valid, sectionCount, orientation, requiredClips, formFields, fields?, geometry?, featureWarnings? }。include: ["resolved"] は resolved（fields/format 用の記述子）を追加し、include: ["timeline"] は timeline（セクション、モーションイベント、ビート、キュー）を追加します
compose_video	インライン記述子を検証してレンダリング（任意でその format の1つを）→ { outputPath, durationSeconds, sizeBytes, videoCodec, audioCodec, renderId }、および mp4 への resource_link
render_frames	ネイティブテンプレートをレンダリングし、静止フレームを PNG 画像 + パスとして返します: at、atTransitions、perSection、sheet、safe、zoom、variants、looks
edit_template	インライン JSON に対して、セクション名ごとの JSON Patch operations および/または登録済みの effectProps を、expectedRevision の下で適用。すべて適用されるか、まったく適用されないか → { template, revision, changedPaths, changedSections? }
probe_media	ローカルメディアファイルを検査 → コーデック、再生時間、サンプルレート、サイズ、および HDR / カラー / ビット深度 / VFR / 回転の特性
extract_style	メディアディレクトリ内の参照画像/クリップ → { theme, styleGuide, confidence }: パレットの役割 + WCAG コントラスト、グレイン、ペーシング（パレットとペーシングのみ）
analyze_music	ローカルの音楽ファイルを計測 → global.beats および cue:drop 用の { bpm, offset, beatsPerBar, confidence, usable, cues, globalBeats }
analyze_sound	sfx[].sound（合成、またはバリエーション付きプリセット）をレンダリング → 長さ、ピーク/RMS dBFS、セントロイド、高/低エネルギー比、アタック、アドバイザリ + スペクトログラムと波形の PNG
transcribe_media	ローカルの音声/動画ファイルの音声を whisper.cpp でローカルに文字起こし → subtitles.words に固定するための { words, srt, language, confidence, advice }
get_capabilities	ローカルの FFmpeg 機能レポート（リスト + 1フレームプローブ）→ 各機能について yes/no/unknown と修正方法
open_in_builder	テンプレート → 人が編集するための leclap.dev/studio/builder#t=… リンク。テンプレートは URL フラグメント内を移動します（サーバーには送信されません）→ { url, length, mediaToRebind, warnings }
render_remotion_clip	（ボーナス、オプトイン） あなた自身の Remotion プロジェクトからコンポジションをレンダリング → project_video セクション用の mp4 クリップ
analyze_sound は、サウンドのノイズとジッターを seed（デフォルトは 0）で初期化します。テンプレートが再生する正確なレンダリングを聴くには、テンプレートの global.seed を seed として渡し、キュー のパスを cue として渡します。例えば、intro という名前のセクションの最初のキューには "sections.intro.sfx[0]"、3 番目のグローバルキューには "global.sfx[2]" を指定します。ツールは、ミックスがそのキューをシードするのと同じ方法でサウンドをシードし、使用した seed を返します。レベルは -120 dBFS で下限が設定されるため、無音のサウンドは -120 と読み取られ、sound_silent が発生します。

典型的なエージェントの流れ: get_samples → get_samples { id } → 要件を確認し、メディア/コピーをカスタマイズ → get_template_schema → validate_template（有効になるまで繰り返す）→ render_frames（結果を確認し、safe でセーフゾーンをチェック）→ compose_video → 返された outputPath を読み取る。適合するサンプルがない場合は、スキーマから新しい記述子を作成します。

render_frames は <output-dir>/.section-cache 配下のセクションごとのキャッシュを通してレンダリングするため、小さな編集後の 2 回目の確認では、変更されたセクションのみが再エンコードされます。これは compose_video と同じメディアディレクトリのチェック、スロット上限、タイムアウト、キャンセル処理の下でレンダーワーカー内で実行され、PNG を <output-dir>/frames-<id>/ に書き出し、最大 8 枚の画像（sheet が設定されている場合はシート）をインライン化します。モーメントは、動画全体に対する秒数または時間参照です: "intro.end"（セクションまたは要素の ID）、"50%"、"beat:8"、"cue:drop + 0.1"。include: ["timeline"] を指定した validate_template は、選択する価値のあるモーメントを一覧表示します。

validate_template はまた、レンダリングなしで、フレームからはみ出したりタイトルセーフから外れたりするテキスト、他のテキストと衝突するテキスト、バンドの下に位置するテキスト、小さすぎるテキスト、コントラストが不足しているテキスト、またはボックス、アウトライン、シャドウなしで映像の上に配置されたテキストを報告します。これらの検出結果はオプションの geometry フィールドに 1 行ずつ届き、何を変更すべきかを示します。修正するものがない場合、このフィールドは完全に存在しません。これらは助言的なものであり、valid は true のままです。(approx: …) で終わる行は、それが推定値である理由を示します: フォントを読み取れなかった、テキストにレンダリング時にのみ解決される {{ variable }} が含まれている、またはセクションが duration を宣言していない、などです。フォントがバンドルされていない場合、サーバーは LeClap アセットカタログから取得します（5 秒のタイムアウト）。オフラインの場合は推定します。

validate_template に render: true を渡すと、テキストを含むセクションもレンダリングし、実際のピクセルからコントラストを測定します。これにより、レンダリングなしのチェックでは unknown としか言えない、画像上のテキスト、グレード、ルックが確定します。数秒かかり（それらのセクションの 2 回のレンダリング）、compose_video と同じメディアディレクトリのサンドボックスを通り、メディアディレクトリからアセットを読み取り、同じタイムアウトの下で同じフォークされたレンダーワーカー内で実行されます。render フィールド（measured、seconds、およびレンダリングできなかった場合は unavailable —drawtext 付きの FFmpeg がない、レンダリングの失敗、またはタイムアウト）が追加されます。レンダリングなしの検出結果はどちらの場合も返されます。

作成前にサンプルを確認する

get_samples は Remotion が無効な場合でも常に利用できます。読み取るのはパッケージ済みデータのみで、メディアのダウンロード、エフェクトの実行、リポジトリへのアクセスは行いません。id を指定しない場合は一覧を返し、任意の category(templates、typography、effects、app-demos、overlays、evidence)、backend(native、remotion)、および大文字小文字を区別しない query(最大 4000 文字)で絞り込めます。id(1〜200 文字)を指定すると、そのサンプルを返します。

{ "name": "get_samples", "arguments": { "category": "app-demos", "backend": "native" } }

{ "name": "get_samples", "arguments": { "id": "web-app-promo" } }

結果には同一の JSON がテキストと structuredContent の両方に含まれます。id を指定した場合、記述子はそのメタデータとともに template に配置されます。不明な ID は、発見のためのヒントとともに isError を返します。必須の入力には、名前付きクリップとデュレーション/キャプチャのヒント、フォームフィールドと制限、変数/デフォルト値/プレースホルダー、アセット、有効なプリセットフォントファイル(source: "preset")、およびバージョン管理されたエフェクトが含まれます。サンプルのコピーを置き換え、クリップは userVideoPaths で、フォームの値は fields で指定し、global.variables をカスタマイズしてから、template を validate_template と compose_video に渡してください。参照されているパーシャルは記述子に埋め込まれます。

25 個のネイティブサンプルは FFmpeg を使用します。登録済みの 10 個のエフェクトサンプルには --allow-remotion、Remotion のピア依存関係、および信頼された --remotion-entry が必要です。customCatalog: true を持つエフェクトには、さらにオペレーターの --effect-catalog と、そのエントリ内の対応するコンポジションが必要です。サンプルの確認だけでは、実行が有効になったり、カタログがインストールされたり、React ソースが提供されたりすることはありません。エフェクトの props を編集する前に、requirements.setup を確認し、オペレーターのセットアップ後は get_effect_schema を確認してください。オペレーターカタログを参照してください。

プレビュー動画/ポスターおよびメディアは同梱されていません。作成したアセット参照とフォントを用意するか置き換えてください。相対参照は、設定されたメディアディレクトリ配下で解決される必要があります。source、showcasePath、preview の値は、作成/ショーケースの場所を表すものであり、インストール済みのローカルファイルではありません。記述子の JSON を MCP の外部に保存するには、leclap samples export <id> --output <new-file> を使用してください。

レシピ: プルリクエストまたはマージリクエスト用の動画エビデンス

コード変更に取り組むエージェントは、レビュー用の視覚的エビデンスをパッケージ化するために LeClap を利用できます。

1. 短い実際の画面録画を収集し、レビュアーが確認すべき点を明示します。
2. examples/agentic-pr-video、またはその evidence-video skill のようなレビューテンプレートを作成または再利用します。これは、計測されたキャプションとともに before/after のカードとパネルをまず合成します。
3. 記述子が有効になるまで validate_template を呼び出します。
4. 録画を userVideoPaths に、レビューコンテキストを fields に指定して compose_video を呼び出します。
5. 返された outputPath を、diff の横に並べて PR または MR に添付します。

MCP サーバーはレンダリングを行い、ローカルの成果物を返します。GitHub や GitLab へのアップロードは行いません。それは周囲のエージェントワークフローにおける明示的なステップのままです。

独自の Remotion を持ち込む(オプション)。 Remotion プロジェクトをお持ちの場合、render_remotion_clip はそのコンポジションの 1 つを mp4 にレンダリングします。これは FFmpeg のフィルターグラフでは表現できない本格的なモーショングラフィックス(スプリング物理、キネティックタイポグラフィ)です。entry(registerRoot を呼び出すモジュール)、またはビルド済みの serveUrl を指定し、さらに compositionId と任意の inputProps を指定します。あるいは --remotion-entry / LECLAP_MCP_REMOTION_ENTRY でデフォルトを設定できます。返されたクリップを project_video クリップとして(userVideoPaths 経由で)compose_video に渡すと、決定論的エンジンがそれをあなたのシーンの手前に合成します。これにはオプションのピア依存関係である @remotion/renderer + @remotion/bundler が必要で、設計時専用(ヘッドレス Chromium)です。MCP のその他のすべては、自己完結かつオンデバイスのままです。

プロンプト

compose-video — ガイド付きのオーサリングプロンプトです（Claude Desktop などのクライアントでは /compose-video として表示されます）。任意の goal、orientation、creativeDirection 引数を受け取り、スキーマ、プレミアムなビルディングブロックレシピ（どのフィルターがどの見た目になるか、バンドルされているフォント一覧、オンデバイスフィルターの許可リスト）、そして validate_template → compose_video のループをエージェントに事前に読み込ませます。

creativeDirection はプレーンテキストのビジュアルブリーフです（1〜4000 文字）。このプロンプトは、エージェントがそれを meta.creativeDirection に保存し、明示的なネイティブ設定または登録済みエフェクトのプロパティに変換し、シーンの目的に応じてレイアウトを変化させ、ブリーフに照らして entrance、settling、ending を検査するよう導きます。get_template_schema はメタデータの契約を公開します。これは参照用の資料であり、レンダラーがその文章を解釈するわけではありません。登録済みシーンでは render_preview を使用し、ネイティブシーンではエンジンのレンダーとフレーム抽出が必要です。これらはプロンプトの引数であり、追加の compose_video 引数ではありません。creative-direction のワークフローと例を参照してください。

実行

# published — no checkout needed
npx -y @leclap/mcp

# or from a checkout: build the engine + this server, then start it over stdio
pnpm --filter ffmpeg-video-composer build
pnpm --filter @leclap/mcp build
node packages/leclap-mcp/dist/index.js

これは stdio 経由で MCP を話します（stdout はプロトコルのチャネルです — すべての診断は stderr に送られます）。公開されている bin は leclap-mcp です。

FFmpeg。 compose_video はエンジンの FFmpeg でレンダリングします。まずシステムの FFmpeg、次にバンドルされている ffmpeg-static を使用します。ffmpeg-static には ffprobe が同梱されていません。トランジション、音楽、動画全体のオーバーレイ、または project_video クリップを含むテンプレートには ffprobe が必要で、probe_media にも必要です。その経路では、レンダリングはエンコードの前に停止し、不足しているバイナリを名指しします。FFmpeg をインストールする（brew install ffmpeg、sudo apt install ffmpeg）と両方が提供されます。サーバーの隣にインストールされるオプションの ffprobe-static パッケージも機能します。

MCP TypeScript SDK（@modelcontextprotocol/server）上に構築されており、現在のプロトコルリビジョンに追随しています。古いリビジョンのクライアントも引き続き動作します — stdio エントリーは同じツール定義から両方の世代にサービスを提供します。

設定

設定	フラグ	環境変数	デフォルト
出力ディレクトリ	--output-dir	LECLAP_MCP_OUTPUT_DIR	~/.leclap/renders
メディア許可リスト / アセットルート	--media-dir	LECLAP_MCP_MEDIA_DIR	~/.leclap/media
テンプレートフォントディレクトリ	--fonts-dir	LECLAP_MCP_FONTS_DIR	未設定。global.fonts はメディアディレクトリから読み込まれます
Remotion オプトイン	--allow-remotion	LECLAP_MCP_ALLOW_REMOTION	オフ
ステージ/ワーカータイムアウト	--render-timeout-ms	LECLAP_MCP_RENDER_TIMEOUT_MS	600000 ms（10 分）
信頼済み Remotion エントリー	--remotion-entry	LECLAP_MCP_REMOTION_ENTRY	未設定
Chrome 実行ファイル	--remotion-browser	LECLAP_MCP_REMOTION_BROWSER	未設定。Remotion が自身のブラウザーを管理します
オペレーターエフェクトカタログ	--effect-catalog	LECLAP_MCP_EFFECT_CATALOG	未設定。組み込みの契約のみ
エフェクトキャッシュバイト数	--effect-cache-max-bytes	LECLAP_MCP_EFFECT_CACHE_MAX_BYTES	536870912（512 MiB）。0 でキャッシュを無効化
カタログギャップログ	--catalog-gap-log	LECLAP_MCP_CATALOG_GAP_LOG	catalog-gaps.jsonl、常に出力ディレクトリ配下
フォントディレクトリは読み取り専用です。テンプレートの global.fonts[].src はまずそこを基準に解決され、次にメディアディレクトリを基準に解決されますが、それ以外の場所では解決されません（realpath でチェックされるため、トラバーサルや外部へのシンボリックリンクは拒否されます）。フォントが取得されることはありません。validate_template と compose_video はどちらも、読み取れない宣言済みフォントで失敗します。

優先順位はフラグ → 環境変数 → デフォルトです。パスはサーバーの作業ディレクトリを基準に解決されます。指定された ~ の値は展開されません。引数なしの --allow-remotion、=true / =1、または環境変数の true / 1 で Remotion が有効になります。明示的な =false / =0 は環境変数を上書きします。カタログの変更には再起動が必要です。ホスト設定、出力の優先順位、ステージの期限、キャッシュの動作については、完全なエンジン設定リファレンスを参照してください。

compose_video は mediaDir をエンジンの assetsDir として使用し、レンダリングごとに 1 つの buildDir を作成します。その fields（文字列、数値、またはブール値: フォームの値と宣言された global.fields で、それぞれの型に変換されます）、userVideoPaths、locale 引数がメディア／コピーをバインドし、format は formats を持つテンプレートの 1 つのコンポジションを選択します。その template.global は向きと fps を制御します。コーデック、品質ティア、FFmpeg のセグメント並行処理のフィールドはライブラリのホスト設定であり、任意の MCP ツール引数ではありません。

テンプレートは global.fields で入力を宣言できます（型付き: text、color、url、media、number、enum、time。テンプレートリファレンスを参照）。validate_template はそれらを fields として一覧表示し、その勧告の中に field_undefined、field_unused、field_type_mismatch、field_missing_required を報告します。compose_video と render_frames は、必須の値が欠落している場合や型に適合しない場合、レンダリング前に拒否します。また、include: ["resolved"] を指定した validate_template は、それらの fields が生成する記述子を表示します。

type: "html" の inputs[] エントリは、HTML と CSS でカード、バッジ、価格タグをレイアウトします（flexbox のサブセット。HTML レイヤーを参照）。compose_video と render_frames はそれを透明な PNG に描画し、画像のように合成します。その画像はメディアディレクトリ配下のテンプレートアセット（または PNG/JPEG データ URI）でなければなりません。リモート URL と絶対パスは拒否されます。validate_template は html_unsupported_css、html_unsupported_markup、html_font_unknown、html_missing_field、html_overflow（レイヤーがそのボックスに対してレイアウトされたこと）を報告し、html_too_large で失敗します。get_template_schema は入力について説明し、get_motion_catalog は CSS サブセットと 4 つのレイアウトレシピを html の下に一覧表示します。

14 個のツールが常に登録されます: get_samples、get_template_schema、get_motion_catalog、validate_template、edit_template、compose_video、render_frames、probe_media、extract_style、analyze_music、analyze_sound、transcribe_media、get_capabilities、open_in_builder です。オプトインで get_effect_schema、render_preview、render_remotion_clip が追加されます。エフェクトプロパティの編集はエフェクトバックエンドの検証を迂回しません。各ツールの名前と説明は毎ターンエージェントに送信されるため、サーフェスは小さく保たれます。0.5.0 では patch_template が edit_template に、list_samples と get_sample が get_samples に統合され、ping が削除されました（MCP にはプロトコルの ping があります）。CHANGELOG の移行表を参照してください。 open_in_builder はテンプレートを人に手渡します。返されるのは https://leclap.dev/studio/builder#t=v1.… (/fr のようなロケール接頭辞やローカル開発サーバー用の baseUrl)、 さらに mediaToRebind と warnings です。テンプレートは URL フラグメント内に圧縮されて乗りますが、ブラウザーが これをサーバーへ送ることはないため、何もアップロードされず、受け取る LeClap サーバーも存在しません。ローカルパスと media:// のアップロードはリンク内を移動できません。ビルダーはそれらのシーンを空の状態で開き、人が再度埋めます。ビルダーが 読み込まない URL スキーム (http(s)、data:、library://、media:// 以外) のメディアは、 理由 unsupported_scheme とともに一覧表示され、同じように破棄されます。https://leclap.dev とは別のオリジンの baseUrl (ローカル開発サーバーを含む) は警告を追加します。そこから配信されるページはフラグメント内のテンプレートを読めるため、 エージェントはリンクを共有する前に、そのリンクがどこを指すのかを伝えるべきです。

edit_template は expectedRevision の下でインラインテンプレート JSON に JSON Patch (RFC 6902) を適用します。 バッチはオール・オア・ナッシングであり、結果は検証に通らなければなりません。effectProps ([{ section, props }]) もまた、 操作の後に、同じバッチ内で、展開されたセクション名によって登録済みのエフェクトプロパティをマージします。Web テンプレート ビルダーは同じ語彙を WebMCP を通じてブラウザー内エージェントに公開します。 get_template_schema、get_motion_catalog、validate_template、edit_template (JSON Patch)、 render_frames はそこでも同じ意味を持ち、両方のサーフェスは同じ JSON に対して同じ revision を計算します。

音声からのキャプション: ピン留めしてから確認します。 transcribe_media はホスト上で whisper.cpp を実行し (音声はそこから出ません)、{ words, srt, language, confidence, advice } を返します。単語の時刻はファイル内の秒単位です。 それらをセクションの subtitles.words にピン留めする (clip.from を減算) か、セクションに subtitles: { transcribe: { from: "self" } } を設定して、compose_video がレンダリング前に文字起こししてピン留めするようにします。 公開する前にユーザーに単語を見せてください。lowConfidence: true は、いくつかが聞き間違えられた可能性が高いことを意味します。 このツールはモデルをダウンロードしません。オペレーターが leclap transcribe --download-model で一度だけ取得します (またはサーバー環境で LECLAP_WHISPER_DOWNLOAD=1 を設定します)。

各レンダリングは <output-dir>/<renderId>/ に書き込みます。ローカル入力ファイル (userVideoPaths、 probe_media、extract_style、analyze_music、transcribe_media) は、メディアディレクトリの内側に解決される必要があります (symlink-safe なコンテインメントチェック)。メディアディレクトリの デフォルトは意図的に狭く設定されています。~ を指すと、どのツール呼び出しでもホームディレクトリ全体を読めてしまいます。 render_remotion_clip はあなたのプロジェクト自身の JS を実行するため、オプトインが設定されている場合 (--allow-remotion または LECLAP_MCP_ALLOW_REMOTION=1) にのみ登録されます。leclap init --remotion はそれが有効化された .mcp.json を生成します。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (絶対パスのみ — 環境変数の値はチルダ展開されません):

{
  "mcpServers": {
    "leclap": {
      "command": "npx",
      "args": ["-y", "@leclap/mcp"],
      "env": {
        "LECLAP_MCP_OUTPUT_DIR": "/abs/path/to/Movies/leclap-renders",
        "LECLAP_MCP_MEDIA_DIR": "/abs/path/to/Movies"
      }
    }
  }
}

チェックアウトから実行する場合は、コマンドを "command": "node" に置き換え、 "args": ["/abs/path/to/ffmpeg-video-composer/packages/leclap-mcp/dist/index.js"] を指定します。

次に、エージェントに 「フェードインと音楽付きの 10 秒の縦型タイトルカードを作成し、レンダリングして」 と依頼します。 エージェントはスキーマを取得し、記述子を作成し、検証して、レンダリングします。返された outputPath を開いてください。 または、ネイティブアプリのデモを一覧表示し、web-app-promo を取得し、コピーを置き換えて画面録画をバインドし、検証してレンダリングするよう依頼します。

Inspector

npx @modelcontextprotocol/inspector node packages/leclap-mcp/dist/index.js

アーキテクチャ

compose_video はコンパイルをサーバープロセス内で実行しません。コアはレンダリング中に stdout へログを出力し（pino が fd 1 に直接書き込む場合も含む）、これが MCP の JSON-RPC ストリームを破壊してしまうためです。そこでレンダリングは フォークされた子ワーカー（dist/render-worker.js）で実行され、結果は IPC チャネルを介して返されます。子プロセスの stdout が使われることはありません。これにより、クリーンなエラーキャプチャ（親プロセスがワーカーのログをバッファリングします）、レンダリングタイムアウト、レンダリング間の DI 状態の分離も実現されます。

compose_video は、数メガバイトの base64 をインライン化するのではなく、レンダリングされたファイルを指す resource_link を返します。クライアントがそれを開くか取得します。レンダリングの進捗は stderr に書き込まれ（[compose_video] render <id> NN%）、プロトコル通知としては送信されません。リクエストごとのログチャネルは現在のリビジョンでは非推奨であり、stdout は JSON-RPC のフレーミング用に予約されているためです。

セキュリティはコアから継承されます。FFmpeg は execFile 経由で実行され（シェルは使用しません）、リモートテンプレート URL は SSRF 対策済みです（プライベート/メタデータ IP とリダイレクトをブロックし、http(s) のみ許可）。ディスクリプタは safeParse で検証され、ローカルファイルパスはメディアディレクトリに対する包含チェックが行われます。http(s) URL でもカタログパス（pictures/…、videos/…）でもないメディアパスは、メディアディレクトリ配下に存在しなければなりません。compose_video、render_frames、render_preview はレンダリング前にそれを拒否し、パスとメディアディレクトリを明示します。また、それはリモートから取得されることはありません。

テスト

pnpm --filter @leclap/mcp test              # vitest unit tests (mocked render)
pnpm --filter @leclap/mcp test:integration  # cucumber BDD over real stdio + a real render

統合テストスイートは、ビルド済みサーバーを stdio 経由で起動し、自己完結型のカラードカードテンプレートをエンドツーエンドでレンダリングします。これは、実際の（pino を多用する）コンパイルを経ても stdio のフレーミングが維持されることを証明するリグレッションガードです。

未実装（今後）

ストリーミング可能な HTTP トランスポート、MCP リソース（leclap://templates/{name}）、クライアントから見える進捗通知、リモート URL のプロービング、非同期ジョブ API。

---

LeClap モノレポの一部です。

JSON ファーストの登録済みエフェクト

オプトインのデスクトップグラフィックスバックエンドは、既存の FFmpeg パイプラインがコンパイルする前に、type: "effect" セクションを JSON から直接解決できます。組み込みのタイトルエフェクトは [email protected] です。LeclapTitle（1280×720、30 fps、300 フレーム）を公開する信頼済みの Remotion エントリを設定してください。実行可能なリファレンスプロジェクトには、コンポーネント、JSON、メディアフィクスチャジェネレーターが含まれています。

• get_effect_schema({ list: true }) は、組み込みおよびオペレーターが登録したアイデンティティ、説明、出力、コントラクトのダイジェストを一覧表示します。id と version を渡すと、厳密な props/assets を検査できます。引数なしの場合も、組み込みのタイトルコントラクトを返します。list: true はアイデンティティフィールドと組み合わせることはできません。
• validate_template は参照/props/assets をチェックし、コンテンツベースの JSON リビジョンを返します。
• render_preview は、エフェクトシーンから選択したフレームまたは包含的なフレーム範囲をレンダリングします。フレーム画像は読み取り可能な MCP 画像コンテンツです。
• edit_template は effectProps を使用して、期待されるリビジョンを用いて選択したエフェクト props をインライン JSON にアトミックに適用します。展開されたセクション名（部分的なプレフィックスを含む）を使用してください。インラインパーシャル内のエフェクトは編集可能です。レジストリパーシャルを編集すると、その参照のみがインラインパーシャルとして実体化され、その変数とプレフィックスは保持されます。他の参照と共有定義は変更されません。
• compose_video はエフェクトクリップを解決し、正規化されたテンプレートを既存のエンジンに送信します。

Remotion は引き続きオプションであり、既存の信頼済みローカルのオプトインが必要です。ブラウザーセットアップのダウンロードを避けたい場合は、LECLAP_MCP_REMOTION_BROWSER / --remotion-browser を互換性のあるインストール済み Chrome 実行ファイルに設定してください。コアの直接コンパイルは、プラットフォームの初期化前に未解決のエフェクトを拒否します。ライブラリの呼び出し元は、エクスポートされた resolveTemplateEffects コールバック API を独自の信頼済みレンダラーとともに使用できます。 登録済みのタイトルエフェクトは不透明なクリップを生成します。バックエンドはスマートフォン上で React シーンを実行したり、汎用のエフェクトマーケットプレイスを提供したりしません。コアの FFmpeg ジオメトリチェックは、テキストの収まりやコントラストについて Remotion グラフィックスを検査しません。再現性のために、JSON、モジュールのソース/依存関係、アセット、レンダリングのプロヴェナンスをまとめて保持してください。

登録済みのジョブは、単一のセットアップ・レンダリング期限の下で別個のワーカー内で実行されます。失敗したジョブは削除されます。完了したプレビューは返されたアーティファクトとプロヴェナンスを保持し、コンポジションは FFmpeg ワーカーが一時的なエフェクトクリップを消費した後もプロヴェナンスを保持します。effectProvenance 内の中間パスは消費された入力を表し、ダウンロード可能な出力アーティファクトではありません。相対的なエフェクトアセットパスは mediaDir の下で解決され、絶対パスはその内部に留まる必要があります。エフェクトのプロパティ/アセットは未解決の {{ placeholders }} ではなく具体的な値を含む必要があります。

アセットのプリフライトはエフェクトワーカーのキューを共有し、動画を順番にプローブし、同一リクエスト内で同じ実ファイルに対するプローブ結果を再利用します。独自の期限には設定されたレンダリングタイムアウトを使用します。リクエストのキャンセルとその期限は、キュースロットを解放する前に、FFprobe の検出を含むアクティブなプローブを停止します。

登録済みの JSON エフェクトプレビューとコンポジションは、レンダリング済みアーティファクトを <mediaDir>/.leclap-effects/cache-v1 で再利用します。検索は、新規のアセットステージング、 バンドル、ブラウザ/コンポジションの識別の後に行われます。正確なスチルフレーム、両端を含む 範囲、完全なクリップにはそれぞれ別のキーが付きます。ソース、依存関係、プロパティ、アセット、 レンダリング/ブラウザ設定がプロヴェナンスに含まれます。ヒットは使用前に検証され、現在の ジョブディレクトリにコピーされます。

デフォルトのキャッシュ予算は 512 MiB で、最大 256 エントリ、最終使用が最も古いものから 追い出されます。大きすぎる出力は登録をバイパスし、キャッシュの I/O 障害はレンダリングに フォールバックします。--effect-cache-max-bytes または LECLAP_MCP_EFFECT_CACHE_MAX_BYTES を、バイト単位の非負の安全な整数に設定してください。 0 は検索と登録を無効にします。無効な値はデフォルトを使用します。CLI の値は環境変数の値より 優先されます。プレビュー結果は cache: {hits, misses, writes} を公開し、コンポジション結果は テンプレートにエフェクトが含まれる場合に集約された effectCache を公開します。個々のエフェクト 結果は metadata.cache（hit、miss、disabled、bypass のいずれか）も持ちます。

各 MCP プロセスは、登録済みエフェクトのプリフライトまたはレンダリングジョブを一度に 1 つだけ 受け入れ、保留中のジョブは最大 8 つです。キューの待機、アセットのプリフライト、ワーカーの セットアップ/レンダリングには、それぞれ別個の renderTimeoutMs 期限があります。これは エンドツーエンドのリクエスト予算ではありません。エフェクトキューには 1..2147483647 ミリ秒を 使用してください。最終的な FFmpeg ワーカーには独自のレンダリング期限があります。独立した MCP プロセスはディスクキャッシュを再利用できますが、レンダリングジョブを統合することは ありません。スタンドアロンの probe_media には固定の 30 秒のプロセスタイムアウトがあり、 リクエストのキャンセルをサポートします。

Web アプリプロモのリファレンス

静的エフェクトカタログには [email protected]（LeclapWebAppPromo、1280×720、30 fps、10 秒）も含まれます。その厳密なコピー、パレット、タイミング、カメラの制御は get_effect_schema を通じて確認できます。そのローカルアセットスロットは screenshot、logo、font です。このコンポジションと既存のタイトルの両方を example Root が登録するため、テンプレートを混在させることができます。リファレンス作成ガイドとプロモ JSONを参照してください。

このガイドでは、スクリーンショットを背景にしたモーション、信頼できる React/SVG レイアウトをフレームの進行に適応させる方法、プレビュー/リビジョン/パッチ/コンポーズ/キャッシュ、および提供された非公開の LeClap フィルムソースへのオプションの無視されるスナップショットブリッジについて説明します。そのブリッジは、選択されたシネマティックエフェクトを 10 秒のプロモで再利用しますが、エフェクト JSON を通じて全編フィルムの再生や任意のソース選択を公開することはありません。

オペレーター向けカスタムエフェクトカタログ

既存の信頼できる Remotion エントリからコンポジションを登録するには、--effect-catalog /absolute/path/effect-catalog.json または LECLAP_MCP_EFFECT_CATALOG を使用します（CLI が優先されます）。サーバーは起動時にカタログを一度だけ読み込んで検証し、不変の JSON スナップショットを保持します。無効な入力の場合は、対処可能な effect_catalog_invalid エラーで起動に失敗します。変更後は再起動してください。実行中にファイルを編集または削除しても、検出や準備済みジョブは変わりません。テンプレート JSON はカタログ、エントリ、ソースコード、出力形式を選択できません。

アセット不要のカタログ例とカスタムテンプレートを参照してください。各 schemaVersion: 1 カタログには effects が含まれ、それぞれに一意でバージョン付きの id、version、compositionId、任意の description、厳密な propsSchema、および assets があります。組み込みの識別子は上書きできません。オペレーターは、設定されたエントリに対応するコンポジションを登録する必要があります。JSON はそのコントラクトを記述し、React がそのジオメトリとアニメーションを実装します。

サポートされる JSON Schema のサブセットは、厳密なオブジェクト（properties、required、additionalProperties: false）、境界付き文字列、上限と下限を含む有限の数値/整数、ブール値、プリミティブの enum、1 つの items スキーマと必須の maxItems を持つ配列、説明、および検証済みのデフォルトです。サポートされていないキーワードはフェイルクローズされ、参照、ユニオン/コンビネータ、パターン、フォーマット、条件分岐などが含まれます。制限: 正規化されたデフォルトを含めてカタログは 256 KiB、カスタムエフェクトは 64 個、スキーマ深さは 16、スキーマノードの総数は 1024。配列の maxItems は最大 1000 です。JSON の走査は深さ 64、ノード数 20000 に制限されます。オブジェクト/プロパティ/アセットのキーは安全な識別子でなければならず、プロトタイプに関連する名前は使用できず、props/asset 名は重複できません。

各アセットはサポートされる extensions、任意の required（デフォルトは true）、および動画専用拡張子向けの任意の minVideoDurationSeconds を宣言します。アセットは mediaDir 内の realpath に含まれる通常のローカルファイルでなければならず、指定された任意のファイルも同じチェックを受けます。動画の最小再生時間はキーごとに明示されます。正確な get_effect_schema レスポンスには assetExtensions と assetVideoPolicies が含まれ、アセットスキーマには必須スロットが一覧表示されます。アセットは生成されたステージングファイル名を使用するため、大文字小文字を区別しないファイルシステム上でも Logo と logo のような大文字小文字が異なるキーが別々に保たれます。組み込みのタイトル背景は 10 秒の最小値を維持します。出力は不透明な H.264、ランドスケープ 1280×720、30 fps、300 フレーム / 10 秒のままです。

get_effect_schema({ list: true }) を使用し、選択した id/version を確認し、インラインテンプレートを検証し、実際のフレームをプレビューし、返されたリビジョンで境界付きの props をパッチしてから、コンポーズします。同じキュー、キャンセル/デッドライン、永続キャッシュがカスタムエフェクトを処理します。準備済みジョブは、解決されたコンポジション ID と正規のコントラクトダイジェストを IPC 経由で運びます。ワーカーがカタログファイルを再読み込みすることはありません。キャッシュのプロベナンスには、ソース、アセット、props、ブラウザの識別子とともに両方の値が含まれます。実用的なプレビューワークフローを参照してください。