effectcraft

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EffectCraft

EffectCraft

Operate EffectCraft through its structured automation interfaces, using the user's intended project and session.
通过EffectCraft的结构化自动化接口操作该应用,使用用户指定的项目与会话。

References

参考文档

Read the relevant sections of references/control-protocol.md before constructing desktop calls. This is an unmodified snapshot downloaded on 2026-10-08 from the upstream control protocol. The upstream MIT license is included in references/LICENSE-MIT.
Search the reference for
Engine
,
UI state
,
Input
,
Locating things
, or
Screenshots
. Relative documentation links resolve against
https://github.com/storytold/effectcraft/blob/main/docs/
.
For MCP tool schemas, CLI syntax, scripting, tracking, rotoscoping, and export workflows, consult the upstream agent guide when needed. Discover schemas from the installed application if behavior differs; do not reuse parameters from other ArtCraft applications or assume complete After Effects compatibility.
构建桌面调用前,请阅读references/control-protocol.md的相关章节。这是2026年10月8日从上游控制协议下载的未修改快照。上游MIT许可证包含在references/LICENSE-MIT中。
在参考文档中搜索
Engine
、
UI state
、
Input
、
Locating things
或
Screenshots
相关内容。相对文档链接基于
https://github.com/storytold/effectcraft/blob/main/docs/
解析。
如需了解MCP工具schema、CLI语法、脚本编写、tracking、rotoscoping以及导出工作流,请在需要时查阅上游Agent指南。如果行为存在差异,请从已安装的应用中发现schema;不要复用其他ArtCraft应用的参数,也不要假设完全兼容After Effects。

Choose the session

选择会话

Discover available EffectCraft tools, installed executables, and existing sessions. Prefer an available MCP connection targeting the intended session.
  • For a running desktop project, use its control channel or
    effectcraft-cli mcp --bridge 9877
    . A needed desktop session can be started with
    effectcraft --control 9877
    or
    EFFECTCRAFT_CONTROL_PORT=9877
    ; adapt executable paths and port to the environment.
  • For independent work,
    effectcraft-cli mcp --project /absolute/path/project.ecproj
    opens a headless session;
    effectcraft-cli mcp
    starts without content, while
    --demo
    loads demonstration content. Headless rendering defaults to CPU;
    --gpu
    requests a separate GPU compositor and fails if no adapter is usable.
  • One-shot CLI invocations use separate headless engines and default to the demo project. Supply the intended project or
    --empty
    , and use
    --save
    or
    --save-as
    to persist edits. A CLI call supports
    --bridge 9877
    when it should act on the live app instead.
Reuse an appropriate session. Do not open a separate headless project expecting edits to appear in the desktop app. Report a missing executable or connection when unavailable; this skill does not install EffectCraft or configure MCP servers.
发现可用的EffectCraft工具、已安装的可执行文件以及现有会话。优先使用面向目标会话的可用MCP连接。
  • 对于正在运行的桌面项目,使用其控制通道或
    effectcraft-cli mcp --bridge 9877
    。可通过
    effectcraft --control 9877
    或
    EFFECTCRAFT_CONTROL_PORT=9877
    启动所需的桌面会话;请根据环境调整可执行文件路径和端口。
  • 对于独立工作,
    effectcraft-cli mcp --project /absolute/path/project.ecproj
    会打开一个无头会话;
    effectcraft-cli mcp
    会在无内容的情况下启动,而
    --demo
    会加载演示内容。无头渲染默认使用CPU;
    --gpu
    会请求独立的GPU合成器,若无可用适配器则会失败。
  • 一次性CLI调用使用独立的无头引擎,默认使用演示项目。请提供目标项目或
    --empty
    参数,并使用
    --save
    或
    --save-as
    来保存编辑内容。如果CLI调用需要作用于正在运行的应用,可支持
    --bridge 9877
    参数。
请复用合适的会话。不要打开单独的无头项目并期望编辑内容会显示在桌面应用中。如果缺少可执行文件或无法连接,请报告;本技能不会安装EffectCraft或配置MCP服务器。

Discover commands and transport

发现命令与传输方式

The desktop channel is raw TCP on
127.0.0.1
, not HTTP or MCP JSON-RPC. Send UTF-8 JSON objects with a string
method
, optional
params
, and distinct request IDs, one per newline. Read one reply per request, match IDs, and check
ok
before dependent actions:
json
{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.execute","params":{"command":"project.summary"}}
{"id":3,"method":"engine.execute","params":{"command":"command.describe","params":{"command":"comp.new"}}}
Connections are persistent and replies are ordered. Requests run between UI frames with a 60-second timeout. Invalid request lines, invalid UTF-8, or lines over 4 MiB close the connection; at most 16 connections are served. The port has no authentication, so enable it only while needed. After a timeout or lost mutation reply, inspect state before replaying; stop and report uncertainty if the result cannot be established safely.
Use
engine.commands
, or engine commands
command.list
and
command.describe
, for IDs, schemas, enablement, and disabled reasons. Execute edits with
engine.execute {command, params}
. It runs engine commands without opening dialogs;
ui.menu.invoke {id, params}
behaves like a menu click and may open a dialog when params are empty.
MCP uses
list_commands
,
describe_command
, and
execute_command {command, params}
, plus helper tools such as
get_comp
,
get_layer
, and
set_property
. Use the actual connected tool schemas; MCP helpers and desktop methods have different names and parameter casing. For CLI discovery, use
effectcraft-cli commands
or
effectcraft-cli exec --list --schemas --json
.
桌面通道是运行在
127.0.0.1
上的原始TCP连接,而非HTTP或MCP JSON-RPC。发送包含字符串类型
method
、可选
params
以及唯一请求ID的UTF-8 JSON对象,每行一个请求。每个请求对应一个回复,匹配ID后,在执行依赖操作前检查
ok
字段:
json
{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.execute","params":{"command":"project.summary"}}
{"id":3,"method":"engine.execute","params":{"command":"command.describe","params":{"command":"comp.new"}}}
连接是持久化的,回复按顺序返回。请求在UI帧之间执行,超时时间为60秒。无效的请求行、无效的UTF-8或超过4 MiB的行会导致连接关闭;最多同时服务16个连接。该端口没有身份验证,因此仅在需要时启用。超时或丢失变更回复后,请先检查状态再重放操作;如果无法安全确认结果,请停止并报告不确定性。
使用
engine.commands
,或引擎命令
command.list
和
command.describe
,来获取ID、schema、启用状态和禁用原因。使用
engine.execute {command, params}
执行编辑。它会运行引擎命令而不打开对话框;
ui.menu.invoke {id, params}
的行为类似于菜单点击,当参数为空时可能会打开对话框。
MCP使用
list_commands
、
describe_command
和
execute_command {command, params}
,以及辅助工具如
get_comp
、
get_layer
和
set_property
。请使用实际连接的工具schema;MCP辅助工具和桌面方法具有不同的名称和参数大小写。对于CLI发现,请使用
effectcraft-cli commands
或
effectcraft-cli exec --list --schemas --json
。

Inspect and edit compositions

查看与编辑合成

Inspect project items, active comp, selection, time, dirty state, and background jobs before editing. Desktop queries include
project.summary
,
comp.info
,
editor.state
,
app.capabilities
, and
jobs.list
through
engine.execute
; MCP exposes
get_state
,
get_project
, and
get_comp
.
Obtain actual comp and layer IDs from queries. Layers can also be addressed by name or
#n
(1-based from the top), but indices can change after reordering. Pass an explicit comp where supported, and set selection deliberately for commands acting on selected objects. Do not unlock or edit locked layers incidentally.
Read property trees with
layer.tree
/ MCP
get_layer
and use returned paths or UIDs. Read values with
prop.get
/
get_property
; discover effect IDs and parameters before applying them. Returned effect and shape paths identify the newly created instances, avoiding accidental edits to another effect of the same type.
MCP
set_property
without
time
sets a static value; with
time
it creates a keyframe; with
expression
it sets an expression. Times are seconds. Keyframe times use layer time, which differs from comp time for offset or stretched layers. Inspect interpolation and values at relevant times. Expression replies distinguish
value
from
evaluated
and report
expressionError
; a syntax error can leave the expression stored but disabled.
For related multi-step edits, consider MCP
batch
or
engine.batch
after reading its schema: steps can reference prior results with
$N.key
, and failed batches roll back. For procedural construction,
run_script
supports the application's After Effects-style object model. Inspect script errors and any
waiting
result; ScriptUI dialogs require interaction before a script finishes. Preserve the application's scripting file/network restrictions.
Opening, replacing, reverting, or closing a project through engine/MCP commands does not ask to save. Inspect dirty state and save the user's work before such a transition when needed. Do not use
app.quit {force: true}
to bypass unsaved work.
在编辑前,请查看项目项、当前活动合成、选中项、时间、脏状态和后台任务。桌面查询包括通过
engine.execute
调用的
project.summary
、
comp.info
、
editor.state
、
app.capabilities
和
jobs.list
;MCP提供
get_state
、
get_project
和
get_comp
。
从查询中获取实际的合成和图层ID。图层也可以通过名称或
#n
(从顶部开始的1-based索引)来寻址,但索引在重新排序后会发生变化。在支持的地方请传入明确的合成,并为作用于选中对象的命令主动设置选区。不要意外解锁或编辑已锁定的图层。
使用
layer.tree
/ MCP
get_layer
读取属性树,并使用返回的路径或UID。使用
prop.get
/
get_property
读取值;在应用效果前先发现效果ID和参数。返回的效果和形状路径可标识新创建的实例,避免意外编辑同类型的另一个效果。
不带
time
参数的MCP
set_property
会设置静态值;带
time
参数会创建关键帧;带
expression
参数会设置表达式。时间单位为秒。关键帧时间使用图层时间,对于偏移或拉伸的图层,这与合成时间不同。请查看相关时间点的插值和值。表达式回复会区分
value
和
evaluated
,并报告
expressionError
;语法错误可能导致表达式被存储但被禁用。
对于相关的多步骤编辑,在阅读完schema后可考虑使用MCP
batch
或
engine.batch
:步骤可以通过
$N.key
引用先前的结果,失败的批量操作会回滚。对于程序化构建,
run_script
支持应用的After Effects风格对象模型。请检查脚本错误和任何
waiting
结果;ScriptUI对话框需要交互才能让脚本完成。请遵守应用的脚本文件/网络限制。
通过引擎/MCP命令打开、替换、还原或关闭项目时,不会提示保存。在进行此类切换前,如有需要请检查脏状态并保存用户的工作。不要使用
app.quit {force: true}
来绕过未保存的工作提示。

Operate the UI when needed

按需操作UI

Use
ui.inspect
and
ui.elements {prefix?}
to discover drawn widgets and stable IDs. Refresh elements after layout changes. Coordinates and widget rectangles are logical window points;
ui.viewer.locate
converts comp pixels to window points, and
ui.timeline.locate
locates a layer at a time. Prefer discovered IDs over guessed coordinates.
ui.type
acts on the focused field.
Use
ui.set
for documented viewer/timeline state or
ui.panel.show
to expose the needed panel. Avoid stealing focus with
ui.focus
unless interaction requires it. UI gestures reply after synthetic input is processed; inspect their result before dependent edits.
使用
ui.inspect
和
ui.elements {prefix?}
来发现已绘制的控件和稳定ID。布局变化后请刷新控件列表。坐标和控件矩形是窗口逻辑坐标点;
ui.viewer.locate
可将合成像素转换为窗口坐标点,
ui.timeline.locate
可定位某一时间点的图层。优先使用发现的ID,而非猜测的坐标。
ui.type
作用于当前聚焦的输入框。
使用
ui.set
设置已记录的查看器/时间轴状态,或使用
ui.panel.show
显示所需的面板。除非交互需要,否则避免使用
ui.focus
抢占焦点。UI手势会在模拟输入处理完成后回复;在进行依赖编辑前请检查其结果。

Save, render, and verify

保存、渲染与验证

Save the editable
.ecproj
separately from exported media. MCP provides
save_project {path?}
; discover the corresponding engine save command and CLI flags for the chosen interface. Verify the save result and resulting file, and check dirty state where available.
Use
render.frame
(desktop) or
render_frame
(MCP) to inspect frames at representative times, including animation boundaries and transitions. Desktop frames are independent of viewer zoom/resolution;
max_side: 0
gives full size. MCP
transparent: true
preserves alpha for inspection. Use
ui.screenshot
for panel or UI evidence. A frame preview is not a finished video export.
Discover render queue/export schemas and supported formats with command discovery and capabilities. Set the intended comp, output path, time range, dimensions, and alpha requirements explicitly. Wait for
renderQueue.render {wait: true}
where supported, or poll the relevant job/status until completion; likewise inspect status for tracking or roto jobs before saving or applying results. Check background footage validation after opening a project and report missing media affecting the result.
Verify exported files exist, are readable, and match the requested format and duration; inspect representative frames and alpha when relevant. Review warnings for Lottie or timeline interchange rather than treating an existing file as proof of fidelity. Report actual saved/exported paths and any unfinished jobs, missing media, or unsupported features.
将可编辑的
.ecproj
文件与导出的媒体分开保存。MCP提供
save_project {path?}
;请为所选接口查找对应的引擎保存命令和CLI标志。验证保存结果和生成的文件,并在可用时检查脏状态。
使用
render.frame
(桌面端)或
render_frame
(MCP)查看代表性时间点的帧,包括动画边界和过渡效果。桌面端帧不受查看器缩放/分辨率影响;
max_side: 0
可获得完整尺寸。MCP的
transparent: true
可保留Alpha通道以供查看。使用
ui.screenshot
获取面板或UI的证据。帧预览不是最终的视频导出。
通过命令发现和能力查询,发现渲染队列/导出schema和支持的格式。明确设置目标合成、输出路径、时间范围、尺寸和Alpha要求。在支持的地方等待
renderQueue.render {wait: true}
完成,或轮询相关任务/状态直至完成;同样,在保存或应用结果前,请检查跟踪或rotoscoping任务的状态。打开项目后请检查后台素材验证情况,并报告影响结果的缺失媒体文件。
验证导出的文件存在、可读,且符合请求的格式和时长;在相关情况下检查代表性帧和Alpha通道。请查看Lottie或时间轴交换的警告,不要认为文件存在就代表保真度合格。报告实际保存/导出的路径,以及任何未完成的任务、缺失的媒体或不支持的功能。