LeClap

@leclap/mcp

一个 MCP 服务，将 ffmpeg-video-composer 引擎作为可由 Agent 调用的视频工具提供。

AI Agent（Claude Desktop、Cursor，……）负责提供大模型；此服务可帮助它根据架构创作带有精美效果的定制模板，然后对模板进行验证，并以确定性方式渲染为 mp4。此服务通过共享的打包目录提供 50 个展示样例，其中包含创意方向、描述符和必需的输入。运行时无需应用或私有 creative-kit。Remotion 辅助创作是一种可选方式。 最终视频可由 Agent 组合、具有确定性且可复现，与生成式视频模型截然相反；后者通过采样而非渲染生成视频。

工具

工具	描述
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）→ { 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 对比度、颗粒感、节奏（仅提取色板和节奏）
extract_structure	将参考视频片段的格式（镜头、节奏、转场、背景、布局）提取为模板的约束规则。仅提取格式；最多 2 分钟，每 0.25 秒采样一次。
extract_brand	将网站的品牌套件（名称、颜色、字体、标志）提取为主题和约束规则，并保存到 <media-dir>/brand-kits/<host>/。需要 --allow-network。
analyze_music	分析本地音乐文件 → { bpm, offset, beatsPerBar, confidence, usable, cues, globalBeats }，用于 global.beats 和 cue:drop
analyze_sound	渲染 sfx[].sound（合成音效，或带变体的预设）→ 时长、峰值／RMS dBFS、质心、高／低频能量占比、起音、建议，以及频谱图和波形 PNG
transcribe_media	使用 whisper.cpp 在本地转录本地音频／视频文件中的语音 → { words, srt, language, confidence, advice }，以便写入 subtitles.words
get_capabilities	本地 FFmpeg 功能报告（列表 + 单帧探测）→ 每项功能的状态为是／否／未知，并附带修复方法
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 传入："sections.intro.sfx[0]" 表示名为 intro 的区段中的第一个提示音，"global.sfx[2]" 表示第三个全局提示音。随后，工具会像混音器为该提示音设定种子一样为声音设定种子，并返回它使用的 seed。电平最低为 -120 dBFS，因此静音会显示为 -120，并触发 sound_silent。

典型的 Agent 流程：get_samples → get_samples { id } → 检查需求并自定义媒体/文案 → get_template_schema → validate_template（反复迭代，直到有效）→ render_frames（查看结果；使用 safe 检查安全区域）→ compose_video → 读取返回的 outputPath。如果没有合适的示例，请根据架构创建新的描述文件。

render_frames 会通过 <output-dir>/.section-cache 下的区段缓存进行渲染，因此小幅修改后再次查看时，只会重新编码发生变化的区段。它会在渲染工作进程中运行，并遵循与 compose_video 相同的媒体目录检查、插槽上限、超时和取消规则；它会将 PNG 写入 <output-dir>/frames-<id>/，并内联最多八张图片（设置 sheet 时则内联图像表）。时刻可以是视频全程中的秒数或时间引用："intro.end"（区段或元素 ID）、"50%"、"beat:8"、"cue:drop + 0.1"。使用 validate_template 并设置 include: ["timeline"]，即可列出值得挑选的时刻。

validate_template 还会报告无需渲染即可检测的问题：文本超出画面或标题安全区域、与其他文本重叠、位于色带下方、字号过小、对比度不足，或叠加在既没有底框也没有描边或阴影的素材上。这些结果会显示在可选的 geometry 字段中，每行说明一项需要修改的内容；如果没有需要修复的问题，则完全不会出现该字段。这些结果仅供参考：valid 仍为 true。行末的 (approx: …) 会说明为何结果是估算值：无法读取字体、文本包含仅在渲染时才会解析的 {{ variable }}，或区段未声明时长。若字体未随附，服务会从 LeClap 资源目录获取字体（超时为 5s）；离线时则会进行估算。

在 validate_template 中传入 render: true，还会渲染包含文本的区段，并根据实际像素测量对比度——它会处理图片上的文本、色彩分级和外观效果，而无需渲染的检查只能将这些情况标记为未知。此操作耗时数秒（会渲染这些区段两次），使用与 compose_video 相同的媒体目录沙箱，从媒体目录读取资源，并在遵循相同超时设置的分叉渲染工作进程中运行。它会添加一个 render 字段（包含 measured、seconds，以及无法渲染时的 unavailable——例如缺少带 drawtext 的 FFmpeg、渲染失败或超时）；无论结果如何，都会返回无需渲染即可得到的检查结果。

编写前先发现示例

即使禁用了 Remotion，get_samples 也始终可用。它只读取打包的数据：不会下载媒体、执行效果或访问代码仓库。不提供 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" } }

结果会在文本和 structuredContent 中包含相同的 JSON；提供 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 源码。编辑效果属性前，请检查 requirements.setup，并在操作员完成设置后调用 get_effect_schema。请参阅操作员效果目录。

不会打包预览视频／海报和媒体。请提供或替换编写时使用的资源引用和字体；相对引用必须解析到已配置的媒体目录之下。source、showcasePath 和 preview 的值描述的是编写／展示位置，而非已安装的本地文件。要在 MCP 之外保存描述符 JSON，请使用 leclap samples export <id> --output <new-file>。

配方：为拉取请求或合并请求准备视频证据

处理代码更改的 Agent 可以使用 LeClap 打包视觉证据，供评审：

1. 录制一段简短的真实屏幕录像，并说明评审者应检查什么。
2. 编写或复用评审模板，例如 examples/agentic-pr-video，或其证据视频技能，该模板会先组合带有测量说明文字的前后对比卡片和面板。
3. 反复调用 validate_template，直至描述符有效。
4. 使用 compose_video，将录像放入 userVideoPaths，将评审背景信息放入 fields。
5. 将返回的 outputPath 与差异内容一并附加到 PR 或 MR。

MCP 服务会渲染并返回本地制品。它不会上传到 GitHub 或 GitLab；上传仍是周边 Agent 工作流中的明确步骤。

自带 Remotion（可选）。 如果你有 Remotion 项目，render_remotion_clip 可以将其中一个合成渲染为 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 参数，并为 Agent 提供架构、优质构建模块配方（哪些滤镜对应哪些效果、内置字体列表、设备端滤镜允许列表），以及 validate_template → compose_video 工作流。

creativeDirection 是纯文本视觉简报（1–4000 个字符）。该提示词会引导 Agent 将其存储在 meta.creativeDirection 中，将其转化为明确的原生设置或已注册效果属性，根据场景用途调整布局，并参照简报检查入场、过渡稳定和结尾效果。get_template_schema 会公开元数据契约。这是参考资料；渲染器不会解读其中的文字说明。已注册场景使用 render_preview；原生场景则需要引擎渲染和帧提取。这些是提示词参数，并非额外的 compose_video 参数。请参阅创意方向工作流和示例。

运行

# 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	关闭
原始滤镜显式启用	--allow-raw-filters	LECLAP_MCP_ALLOW_RAW_FILTERS	关闭；原始 filters 受允许列表限制
网络显式启用	--allow-network	LECLAP_MCP_ALLOW_NETWORK	关闭
阶段／工作进程超时	--render-timeout-ms	LECLAP_MCP_RENDER_TIMEOUT_MS	600000 毫秒（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，始终位于输出目录下

--allow-network 允许 extract_brand 通过 HTTPS 从公共主机获取网站内容（拒绝私有、环回和链路本地地址、URL 中的凭据以及非 HTTPS 重定向；大小和耗时均有限制）。默认关闭，且未启用时不会注册该工具。

字体目录为只读：模板的 global.fonts[].src 会优先从该目录解析，其次从媒体目录解析，不会从其他位置解析（会检查真实路径，因此拒绝路径遍历或指向目录外部的符号链接）；绝不会获取字体。validate_template 和 compose_video 遇到无法读取的已声明字体时都会失败。

Agent 模板中的原始 filters 会根据引擎的原始滤镜允许列表进行检查：不在列表中的滤镜会导致验证错误 filter_not_allowed，而 get_capabilities 会报告模式（rawFilters）。原始滤镜显式启用后，仅可信本地模板可恢复原始透传，服务器会在启动时通过 stderr 说明这一点。渲染时的拒绝列表仍然生效，但只能尽力而为：可信模板仍可能写入文件（包括通过拒绝列表无法识别的选项写入绝对路径），也可能访问网络。drawtext 的 fontfile 必须是纯字体名称（媒体目录中的字体通过 global.fonts 使用）。

优先级为标志 → 环境变量 → 默认值。路径相对于服务器的工作目录解析；提供的 ~ 值不会展开。单独使用 --allow-remotion、=true／=1 或环境变量 true／1 均可启用 Remotion；显式设置 =false／=0 会覆盖环境变量。目录更改需要重启。有关主机配置、输出优先级、阶段时限和缓存行为，请参阅完整的引擎配置参考。 compose_video 使用 mediaDir 作为引擎的 assetsDir，并为每次渲染创建一个 buildDir。 它的 fields（字符串、数字或布尔值：表单值和声明的 global.fields，每个值都会转换为对应类型）、userVideoPaths 和 locale 参数用于绑定媒体和文案，而 format 则从模板的 formats 中选择一种合成方式；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 会列出 html 下支持的 CSS 子集 和四种布局方案。

始终会注册 15 个工具：get_samples、get_template_schema、get_motion_catalog、 validate_template、edit_template、compose_video、render_frames、probe_media、extract_style、 extract_structure、analyze_music、analyze_sound、transcribe_media、get_capabilities 和 open_in_builder。选择启用后会添加 get_effect_schema、render_preview 和 render_remotion_clip；--allow-network 会添加 extract_brand。编辑效果属性不会绕过 效果后端验证。每轮都会向 Agent 发送每个工具的名称和描述，因此工具面保持精简：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.…（baseUrl 可用于指定区域前缀，例如 /fr，或本地开发服务器）， 以及 mediaToRebind 和 warnings。模板会压缩后放在 URL 片段中，浏览器绝不会将其发送到服务器，因此不会上传任何内容，也没有 LeClap 服务器可以接收模板。本地路径和 media:// 上传内容无法通过链接传递；构建器会以空场景打开这些场景，供用户重新填充。如果媒体使用构建器无法加载的 URL 方案（除 http(s)、data:、library:// 和 media:// 之外的任何方案），则会列出并标记原因为 unsupported_scheme，并以相同方式丢弃。如果 baseUrl 与 https://leclap.dev 不同源（包括本地开发服务器），则会添加警告：该地址提供的页面可以读取片段中的模板，因此 Agent 在分享链接前应说明链接指向何处。 edit_template 会在 expectedRevision 下对内联模板 JSON 应用 JSON Patch（RFC 6902）：整个批次要么全部成功，要么全部失败，且结果必须通过验证。effectProps（[{ section, props }]）也会在所有操作完成后，按展开后的片段名称合并已注册的效果属性，并纳入同一批次。网页模板构建器通过 WebMCP 向浏览器内的 Agent 提供相同的词汇：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）必须解析到 media-dir 内部（检查时会安全处理符号链接）。media-dir 的默认范围刻意设得很窄——如果将其指向 ~，任何工具调用都可以读取整个主目录。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"]。

然后让 Agent “制作一张带淡入效果和音乐的 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 会返回指向渲染文件的 resource_link，而不会内联数 MB 的 base64——客户端会打开或获取该文件。渲染进度会写入 stderr（[compose_video] render <id> NN%），而不会作为协议通知发送：当前修订中已弃用每请求日志通道，stdout 则保留用于 JSON-RPC 帧传输。

安全保障继承自核心：FFmpeg 通过 execFile 运行（不使用 shell）；远程模板 URL 受 SSRF 防护（禁止私有/元数据 IP 和重定向，仅允许 http(s)）；描述符通过 safeParse 验证；本地文件路径会检查是否位于 media dir 内。既不是 http(s) URL、也不是目录路径（pictures/…、videos/…）的媒体路径，必须存在于 media dir 下：compose_video、render_frames 和 render_preview 会在渲染前拒绝此类路径，并指出路径及 media dir，且绝不会从远程获取它。

测试

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 启动已构建的服务，并端到端渲染一个自包含的彩色卡片模板——这是回归保护措施，用于证明 stdio 分帧在真实（大量使用 pino）的编译过程中仍能正常工作。

尚未实现（未来计划）

Streamable HTTP 传输、MCP 资源（leclap://templates/{name}）、客户端可见的进度通知、远程 URL 探测、异步作业 API。

---

属于 LeClap monorepo。

JSON 优先的注册效果

选择启用的桌面图形后端可在现有 FFmpeg 管线编译之前，直接从 JSON 解析 type: "effect" 节。内置标题效果为 [email protected]；配置一个可信的 Remotion 入口以公开 LeclapTitle（1280×720、30 fps、300 帧）。可运行的参考项目包含组件、JSON 和媒体素材生成器。

• get_effect_schema({ list: true }) 会列出内置和由操作员注册的标识、说明、输出及合约摘要。传入 id 和 version 可查看严格的属性/素材；不传参数仍会返回内置标题合约。list: true 不能与标识字段同时使用。
• validate_template 会检查引用/属性/素材，并返回基于内容的 JSON 修订版本。
• render_preview 会从效果场景渲染选定帧或包含首尾帧的帧范围；帧图像会作为可读取的 MCP 图像内容返回。
• edit_template 配合 effectProps，会根据预期修订版本，将选定的效果属性以原子方式应用到内联 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 进程一次仅允许一个已注册效果的预检或渲染作业，最多可有八个待处理作业。队列等待、素材预检以及工作进程设置／渲染各自有独立的 renderTimeoutMs 时限；这不是端到端请求时限。效果队列的有效值为 1..2147483647 毫秒。最终 FFmpeg 工作进程有自己的渲染时限。独立的 MCP 进程可以复用磁盘缓存，但不会合并渲染作业。独立的 probe_media 具有固定的 30 秒进程超时，并支持请求取消。

Web 应用宣传片参考

静态效果目录还包含 [email protected]（LeclapWebAppPromo，1280×720，30 fps，十秒）。通过 get_effect_schema 查看其严格的文案、配色、时间安排和摄像机控制项；其本地素材槽位为 screenshot、logo 和 font。示例 Root 会注册此合成以及现有标题，从而允许混合模板。参见参考创作指南和 promo JSON。

本指南介绍以截图为基础的动态效果、如何根据帧进度调整可信的 React/SVG 布局、预览／修订／补丁／合成／缓存，以及一个可选的、默认忽略的快照桥接方案，用于访问提供的 LeClap 私有影片源。该桥接方案会在十秒宣传片中复用选定的电影效果；它不会通过效果 JSON 暴露完整影片回放或任意来源选择。

运营方自定义特效目录

使用 --effect-catalog /absolute/path/effect-catalog.json 或 LECLAP_MCP_EFFECT_CATALOG，从现有的可信 Remotion 入口注册合成（CLI 优先）。服务会在启动时读取并验证目录，保留不可变的 JSON 快照；如果输入无效，则以可操作的 effect_catalog_invalid 错误终止启动。更改后请重启。服务运行期间编辑或删除文件，不会改变发现结果或已准备的任务。模板 JSON 无法选择目录、入口、源代码或输出格式。

参见无资源目录示例和自定义模板。每个 schemaVersion: 1 目录都包含 effects，其中包含唯一的版本化 id、version、compositionId、可选的 description、严格的 propsSchema 和 assets。内置标识不可覆盖。运营方必须在配置的入口中注册匹配的合成：JSON 描述其契约，React 则实现其几何效果和动画。

支持的 JSON Schema 子集包括：严格对象（properties、required、additionalProperties: false）、有界字符串、带包含边界的有限数值/整数、布尔值、基本类型枚举、具有单个 items 架构且必须指定 maxItems 的数组、描述和经过验证的默认值。不支持的关键字会导致验证失败，包括引用、联合/组合、模式、格式和条件语句。限制：目录最大为 256 KiB（包括规范化后的默认值），最多 64 个自定义特效，架构深度最多为 16，总架构节点数最多为 1024；数组的 maxItems 最大为 1000。JSON 遍历限制为深度 64、节点数 20000。对象/属性/资源键必须是安全标识符，不能使用与原型相关的名称，且属性名称不得与资源名称重叠。

每项资源都声明支持的 extensions、可选的 required（默认为 true），以及仅适用于视频扩展名的可选 minVideoDurationSeconds。资源必须是位于 mediaDir 内（按 realpath 判断）的本地常规文件；提供的可选文件也必须通过相同检查。每个键的视频最短时长都需显式指定。get_effect_schema 的确切响应包含 assetExtensions 和 assetVideoPolicies；资源架构会列出必需的槽位。资源使用生成的暂存文件名，因此在大小写不敏感的文件系统中，Logo 和 logo 这类大小写不同的键仍会保持独立。内置标题背景仍保留十秒的最短时长。输出仍为不透明 H.264、横向 1280×720、30 fps、300 帧 / 十秒。

使用 get_effect_schema({ list: true })，检查所选的 id/version，验证内联模板，预览实际帧，使用返回的修订版本修补有界属性，然后进行合成。自定义特效使用相同的队列、取消/截止时间机制和持久缓存。已准备的任务会通过 IPC 携带已解析的合成 ID 和规范化契约摘要；工作进程不会重新读取目录文件。缓存来源信息包含这两个值，以及源代码、资源、属性和浏览器标识。参见预览工作流示例。