promoshot

promoshot

查看运行效果： demo.md — 技法提示词和开放式创意简报，分别交给仅获得技能和 MCP 的全新 Agent，展示其结果与手工制作的参考作品。完整示例集位于 demos/。

这是 PromoShot 背后的渲染引擎 （App Store），也是其项目格式的开源实现。.promo 项目是一个文件夹，包含 metadata.json 和媒体文件；本工作区提供了验证、检查和渲染项目所需的一切，可将项目渲染为静帧、图像序列或带混合音频的 mp4：无需附带应用，使用的合成器与应用随附的完全相同，逐字节一致。

设计理念是格式即接口。助手、脚本或用户编写 metadata.json；引擎会在所有环境中以相同方式渲染它——Mac 和 iOS 应用（Metal + VideoToolbox）、本仓库的 CLI，或完全没有 GPU 的无头 Linux 机器（通过 lavapipe 上的 wgpu，以及作为子进程运行的 ffmpeg）。这种格式只有一个事实来源，却有三种形态：包含四种经过验证的配方的创作子集（promo schema）、完整文档（--full），以及根据解析器自身结构体生成的仅含类型的 JSON Schema（--types）。验证器运行的解析器与渲染器使用的解析器相同，因此“通过验证”就意味着“可以渲染”。

不是另一个同名的 PromoShot

这是 Alexander Garmash 开发的开放引擎（及 App Store 应用）PromoShot——一款完整的图层／关键帧／时间线编辑器，可处理屏幕录制、视频和照片（Mac；iPhone 和 iPad 可打开相同的 .promo 项目）。

它不是那些名称相似、能将截图转换成模板视频的 App Store 应用（例如 “PromoShot: Screenshot to Video”）。如果你需要关键帧、蒙版、GPU 合成和开放的 .promo 格式，那么你要找的就是这个： promoshot.app · App Store。

产品信息／PAD

面向消费者的应用：promoshot.app · App Store。软件目录可导入此 PAD 4.0 文件：

https://raw.githubusercontent.com/GarAlex/promoshot/main/promoshot.pad.xml

Crates

Crate	负责内容
promo-model	格式：线格式结构体、迁移、调色板角色、schema.md
promo-timeline	时间线计算：关键帧、裁剪、附件、等待、验证
promo-gpu	wgpu 合成：四边形、边框、遮幅、矢量、颜色转换
promo-text	字幕排版和特效（cosmic-text）
promo-engine	预览／导出编排、帧缓存、内存调控器、PCM 混音器
promo-media	解码器／编码器 trait 注册表；ffmpeg 子进程后端和一致性测试套件
promo-editor	文档的编辑词汇：支持撤销的命令、向导的编排、主题规则——promo_apply 和 promo_slideshow 都基于此构建
promo-cli	promo ——从命令行渲染项目
promoshot-mcp	面向 Agent 的 MCP 服务，通过 stdio 通信

构建和验证

./check-all.sh          # fmt, clippy -D warnings, all tests, release build

渲染视频需要 PATH 中有 ffmpeg（和 ffprobe）——帧会在 GPU 上合成后以原始数据传给它们；ffmpeg 仅负责解码和编码。在无头 Linux 机器上，mesa-vulkan-drivers（lavapipe）就足以提供 GPU 支持。

命令行工具

cargo build --release -p promo-cli     # -> target/release/promo

promo schema                            # authoring subset + recipes; --full, --types
promo validate <project> [--strict]     # "NOT OK" lists what will not render; --strict exits 1 on any finding
promo inspect  <project>                # canvas, layers, missing media, undefined colours
promo upsert-keyframe <project> --args '{"layer":"bg","time":2,"zoom":1.2}'
                                        # the MCP authoring tools as verbs (init, upsert-layer,
                                        # upsert-keyframe, apply, slideshow, explain, diff)
promo still    <project> --out f.png --time 2.5
promo frames   <project> --out frames/ --fps 30 --from 0 --to 4
promo video    <project> --out out.mp4 --fps 30

在任何项目命令后添加 --json，即可输出机器可读内容——在 stdout 上输出一个对象，包括错误信息，退出代码保持不变。

promo video 会像应用一样混合音轨：修剪和媒体剪辑、 定格帧、保留音高的变速、关键帧音量、重点旁白压低其下方的所有声音， 以及仅保留项目所需的音轨。

无头渲染是干净的——没有水印，也绝不会要求提供许可证、序列号或 密钥。（Mac 和 iOS 应用会为免费版渲染添加水印； 这是 App Store Pro 版的功能，仍由它们自行处理。）

MCP 服务

promoshot-mcp 通过 stdio 使用 Model Context Protocol，因此任何 MCP 客户端 都能创作、检查和渲染项目。它不包含任何渲染代码——所有渲染都会调用 promo（从可执行文件旁边、PATH 中查找，或通过 --promo 指定），因此 CLI 始终是唯一的接口契约。

连接 Agent

需要两部分：MCP 服务（工具）和技能（工作流）。 两者都不依赖特定厂商。Agent 不会自行发现此代码库。

从 PromoShot 3.0 开始，应用都能打开此引擎写入的内容。App Store 版 2.3.1 可读取 minReaderVersion 不高于 17 的项目（不支持嵌套合成、 也不支持 3D），且无法通过 --mcp-stdio 启动。

1. 构建——也可以跳过

cargo build --release -p promo-cli -p promoshot-mcp
# binaries: target/release/promo  target/release/promoshot-mcp
scripts/install-local.sh   # …and on PATH, linked from target/release,
                           # so every later build is what runs

没有 Rust 工具链？从 Releases 获取预构建的配套文件（linux-x64、 macos-arm64；每个资源的 sha256 都在发布页面上），或拉取镜像： docker pull ghcr.io/garalex/promoshot-mcp——两者都同时包含 promo 和 promoshot-mcp。

将两者放入 PATH，或向服务传入 --promo。渲染视频还需要 PATH 中有 ffmpeg/ffprobe。随后运行 promo skill install，即可将 Agent 技能安装到机器上所有 Agent 工具都能读取的位置——共享的 ~/.agents/skills（Codex、Gemini CLI、Cursor、GitHub Copilot、Grok Build），以及每个只读取自身目录的工具各自的文件夹 （Claude Code、Antigravity）；运行 promo skill 可打印技能内容。

2. MCP（工具必需）

Claude Code / Cursor / 任何 mcp.json：

{
  "mcpServers": {
    "promoshot-headless": {
      "command": "/ABS/PATH/target/release/promoshot-mcp",
      "args": ["--workspace", "/ABS/PATH/Promo", "--root", "/ABS/PATH/Promo"]
    }
  }
}

--workspace 用于存放新项目；--root 用于限制服务可操作的项目范围—— 将两者都指向同一个文件夹是最简洁的配置。两者均为可选项。--log <file> 会 为每次工具调用追加一行日志——记录时间、工具名称、耗时（毫秒）和结果—— 用于跟踪会话情况；演示页面也由此生成。

客户端一行配置：

# Claude Code
claude mcp add promoshot-headless /ABS/PATH/target/release/promoshot-mcp

# Grok Build
grok mcp add promoshot-headless -- /ABS/PATH/target/release/promoshot-mcp \
  --workspace /ABS/PATH/Promo --root /ABS/PATH/Promo
grok inspect   # confirms the server registered

# Docker — the host needs nothing but docker (details below)
docker build -t promoshot-mcp .
# then command: docker, args: ["run","-i","--rm","-v","/ABS/PATH/Promo:/projects","promoshot-mcp"]

在安装了 PromoShot 3.0 的 Mac 上，应用本身也可以作为服务—— 提供相同的工具，并可访问用户打开的文档、撤销功能和审批。请在 PromoShot 的 Settings 中开启 Automation，然后注册应用本身；客户端启动时，应用也会随之启动：

claude mcp add promoshot -- "/Applications/PromoShot.app/Contents/MacOS/PromoShot" --mcp-stdio

Settings ▸ Automation 会显示该行配置，其中包含这台 Mac 自己的路径， 以及供支持 URL 配置的客户端使用的 URL 形式。promoshot 指应用， promoshot-headless 指二进制文件，因此两者可以并列注册； 如果两者都存在，技能会询问使用哪一个。

3. 技能（工作流）

各处使用同一个文件：skill/SKILL.md。

REPO=https://github.com/GarAlex/promoshot
git clone --depth 1 $REPO /tmp/promoshot

# Claude Code (Grok Build also scans this folder)
mkdir -p ~/.claude/skills/promoshot
cp /tmp/promoshot/skill/SKILL.md ~/.claude/skills/promoshot/SKILL.md

# Grok Build explicit path
mkdir -p ~/.grok/skills/promoshot
cp /tmp/promoshot/skill/SKILL.md ~/.grok/skills/promoshot/SKILL.md

# OpenAI Codex / many others
mkdir -p ~/.agents/skills/promoshot
cp /tmp/promoshot/skill/SKILL.md ~/.agents/skills/promoshot/SKILL.md

# Cursor project (in the repo the user is editing, not this engine repo)
mkdir -p .cursor/rules
cp /tmp/promoshot/skill/SKILL.md .cursor/rules/promoshot.md
# or: mkdir -p .agents/skills/promoshot && cp SKILL.md there

任何能读取指令的 Agent 都可以直接接收此文件；它只依赖这些工具（或 CLI）。

4. 验证——让 Agent 渲染一次：

将 examples/ProductCard.promo 渲染为一张 3s 处的静帧。

执行一次 promo_validate、一次 promo_render_still，即可获得一个带设备边框的应用 演示文件路径。接下来，技能会教你如何循环操作：“为 做一个宣传片”。

工具

工具：promo_schema（创作子集 + 四个已验证配方； promo_schema_full 是完整格式；promo_schema_types 是以生成的 仅含类型的 JSON Schema 表示的格式 — 也签入在 docs/promo.schema.json 中，供 $schema 编辑器 自动补全使用），promo_validate、promo_inspect（列出每个图层及其 id — 编辑工具使用的句柄）、 promo_render_still、promo_render_frames、promo_render_video、 promo_render_gif、promo_proxy、promo_workspace；媒体感知工具 — promo_media_probe、promo_media_turntable（从各个角度查看模型）、 promo_media_filmstrip（SOURCE 剪辑的联系表，每格对应一个时间点）、 promo_media_silences（静音片段及其反向区间）和 promo_media_scenes（场景切换及其间的镜头），让 Agent 在开始组合前 了解素材内容；编辑三件套， promo_init、promo_upsert_layer 和 promo_upsert_keyframe：创建 项目、添加带位置的图像／视频／字幕图层，然后制作动画 — 第二个位置关键帧会产生推近效果，视口关键帧则是 Ken Burns 效果； 短 id 会原样使用，未命名的图层会获得规范 UUID，像素尺寸会被记录， 合成画面会始终覆盖其图层。设备边框也能在无头模式下烘焙 — 与应用绘制的 边框相同。promo_slideshow 是向导：输入图片和剪辑，输出完整的经典、 轮播或商店列表展示；任何幻灯片上的字幕都会成为与图片绑定的图层。 promo_apply 涵盖全部词汇：一批编辑器命令（删除、移动、更新任意图层、 更新任意关键帧、修补资源）以原子方式应用，并同时提供命令架构。 promo_explain 可解释某个图层在特定时间为何位于当前位置，promo_diff 则显示自上次查看项目以来的更改；promo_transcribe 可根据语音草拟字幕。 promo_voices 列出服务提供商的语音，promo_speak 使用个人自己的服务商 密钥合成旁白 — 也可以完全不使用密钥，改用本地语音 — 并通过回执复用未更改的文本。创作工具会以内嵌缩略图的形式返回合成画面， 因此图层放错位置时能立即发现。工具通过格式自带的解析器写入普通的 metadata.json — 架构始终是事实来源，手动编辑也始终受到支持。渲染结果 默认输出到项目旁边的 <Name> Exports/，并返回写入的路径，而非 字节数据。

所有标志均为可选：--workspace <dir>（promo_workspace 指向的位置； 否则使用 $PROMOSHOT_WORKSPACE，再否则使用 XDG 数据目录），--root <dir>（拒绝 此目录树之外的项目），--promo <path>。

旁白密钥

旁白使用个人自己的服务商账户，密钥绝不会经过 Agent：没有工具会接收密钥， 也没有工具会显示密钥。只需在操作系统密钥环中注册一次 — macOS Keychain、 Linux 上的 Secret Service（GNOME Keyring、KWallet）、Windows 上的 Credential Manager：

promoshot-mcp key set openai        # reads the key from stdin: paste, then Ctrl-D
promoshot-mcp key status            # where each provider's key comes from, never the key
promoshot-mcp key remove openai

服务提供商：openai、elevenlabs、google。密钥从标准输入读取，因此不会 进入任何 shell 历史记录、配置文件或参数列表。

没有密钥环的环境 — Docker 镜像、CI 运行器 — 会从密钥文件读取密钥， 这是 Docker、Kubernetes 和 CI 系统传递密钥的方式：/run/secrets/OPENAI_API_KEY （同理还有 ELEVENLABS_API_KEY、GOOGLE_API_KEY），或由 OPENAI_API_KEY_FILE 指定的路径。使用权限为 0400 的文件，绝不使用 环境变量，因为 docker inspect 和所有同一用户下的进程都能读取环境变量：

docker run -i --rm \
  -v "$HOME/.secrets/openai:/run/secrets/OPENAI_API_KEY:ro" \
  -v /path/to/your/projects:/projects promoshot-mcp

Agent 可以在制定计划前先询问：使用 {"check": true} 调用 promo_speak 不会产生费用，并会按服务提供商报告密钥是否存在，以及实际调用会合成什么内容。 实际调用会先检查所有待处理旁白的密钥，再购买任何内容；每笔费用支付后， 都会立即写回对应回执，因此即使中途失败，下次调用也不会重复付费。密钥通过 请求标头传递，绝不会放在 URL 中，也不会被记录到日志。

本地语音——无需密钥

local 提供方使用 local-tts 在本机进行语音合成：其英文语音使用 Apache-2.0 许可的权重，因此音频可供你发布（而 macOS 系统语音等仅许可个人使用）。无需密钥、无需账户，也不花钱；一次性下载后，无需联网。安装一次语音包：

promoshot-mcp voices list                      # packages, sizes, licences, what is installed
promoshot-mcp voices install kokoro-en-q8      # 106 MB: 28 voices, US and UK, the best English
promoshot-mcp voices install kitten-nano-en    # 31 MB, 8 voices

每个文件都来自固定上游 URL（Hugging Face 或固定提交的 GitHub），并会在软件包显示前通过 SHA-256 校验。软件包存放在 macOS 的 ~/Library/Application Support/PromoShot/Voices、Linux 的 ~/.local/share/promoshot/voices，或 PROMOSHOT_VOICES 指定的位置；PROMOSHOT_VOICES_MIRROR 用于指定优先尝试的镜像。

脚本随后会说 "speech": {"text": "…", "provider": "local", "voiceID": "kokoro-en-q8/af_heart"}；promo_voices 配合 local 提供方会按上游的试听评级列出所有 ID，最佳的排在最前（af_heart、af_bella、af_nicole、bf_emma，……）。英式语音会使用美式发音。再次运行安装命令以更新较旧的 Kokoro 软件包时，只会补上缺少的语音，不会重新下载模型。生成的片段为 .wav。英语词典遇到不认识的单词时会拒绝处理，而不是自行猜测——通常是产品名称。可在每个项目的 Resources/pronunciations.dict 中按 CMU 格式添加一次拼写：

PROMOSHOT  P R OW1 M OW0 SH AA2 T

词典中没有的单词会以其他方式猜测：按大写字母拆分为已知单词（YouTube、ChatGPT），遇到首字母缩略词时逐字母拼读（API），或由使用该词典训练的小型模型进行猜测；promo_speak 会将所有猜测列为可直接粘贴的行。在该文件中固定或修正某个条目，然后再次调用 promo_speak：编辑文件会重新生成项目的本地语音片段。

Docker

镜像包含完整的渲染环境——服务、CLI、ffmpeg、软件 Vulkan 和字体——因此客户端无需在主机上安装任何东西：

docker build -t promoshot-mcp .

{
  "mcpServers": {
    "promoshot-headless": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-v", "/path/to/your/projects:/projects",
               "promoshot-mcp"]
    }
  }
}

如需无需密钥的语音合成，请为镜像提供语音卷，并在其中安装一次软件包；之后每次运行都会读取该卷：

docker run --rm -v promoshot-voices:/voices --entrypoint promoshot-mcp \
  promoshot-mcp voices install kokoro-en-q8

并在上述 args 中添加 "-v", "promoshot-voices:/voices"。

项目存放在挂载目录下；promo_workspace 会返回 /projects。所有示例都已打包在镜像中，因此无需任何挂载即可验证镜像——先渲染 ProductCard.promo；带设备边框的应用演示是了解产品宣传工作流的示例。server.json 是已发布镜像（ghcr.io/garalex/promoshot-mcp）的 MCP Registry 清单（io.github.GarAlex/promoshot）。GitHub 的 MCP Registry 会在 mcp-publisher publish 后读取该清单。

mcp-name: io.github.GarAlex/promoshot

该 skill 会通过测试来检测是否偏离：测试会将其固定为服务实际提供的工具列表，因此不会介绍不存在的工具。

Mac 应用内置了自己的 MCP 服务（Settings → Automation），共享核心工具名称，并提供仅应用可用的功能——打开编辑器、语音合成。创作工具组合、感知功能和类型架构均以无头模式为先。

一次会话的示例——发出三个请求，得到经过验证的项目和渲染帧（本页顶部的画面就是这样生成的）：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"promo_validate","arguments":{"project":"examples/LinuxSmoke.promo"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"promo_render_still","arguments":{"project":"examples/LinuxSmoke.promo","time":5.5}}}

{"id":2,"result":{"content":[{"type":"text","text":"ok — nothing the renderer would quietly correct"}]}}
{"id":3,"result":{"content":[{"type":"text","text":"wrote examples/LinuxSmoke Exports/still-5.5s.png (1280x720 at 5.50s)"}]}}

同一引擎，适用于每个平台

同一项目分别在 macOS（Metal、VideoToolbox）和精简的 Linux 容器（lavapipe 软件 Vulkan，无 GPU；ffmpeg）上渲染——完整 240 帧视频的 SSIM 为 0.983。可见差异在于字体：字幕提出问题，两帧画面给出答案。

亲自试试——examples/ 为每种 promo_schema 配方提供了一个可运行项目（每个 metadata.json 本身就是配方，并由测试固定），从带设备边框的产品卡片到 9:16 重制版；此外还有内容齐全的 LinuxSmoke.promo：

promo video examples/ProductCard.promo --out card.mp4

编写项目

从 promo schema 开始。简而言之：项目文件夹包含 metadata.json 和 Resources/；ID 是唯一字符串（短助记符也可以，应用会按原样保留）；图层通过关键帧（先保持后缓动）、放置规则、转场和调色板命名的颜色（@accent）将资源放到时间线上。渲染前先验证——如果某项内容无法渲染或不起作用（某个字段无人读取，且名称本应是另一个名称；某个值在当前位置不起作用；缺少媒体），答案会以 NOT OK 开头，然后列出渲染器会静默调整的内容，也包括未定义的颜色名称。

mkdir -p Demo.promo/Resources
# write Demo.promo/metadata.json, copy media into Resources/
promo validate Demo.promo --strict && promo still Demo.promo --out look.png --time 1

或者让 MCP 服务处理样板代码（promo_init、 promo_upsert_layer），并将 "$schema" 指向 docs/promo.schema.json，为编辑器提供自动补全。

不变量与计划

• SPECS.md — 测试所验证的不变量。

版本

在 1.0 之前，版本号采用 0.MINOR.PATCH。新增格式级别（提高 minReaderVersion）、新增工具，或用户或 Agent 能察觉的行为变更时，递增 MINOR；仅修复问题时，递增 PATCH。每个 GitHub 版本都会附带生成的说明和二进制文件的构建溯源信息，且发布频率最多为每周一次。0.3.0 是遵循此规则的首个版本：读取器处于第 47 级。（0.2.x 在 11 天内发布了 79 个补丁版本，同时新增了第 19 至 47 级——数字毫无意义，而这正是此规则要解决的问题。）

许可证

Apache-2.0。基于此引擎构建的 PromoShot 应用是独立的专有产品。

长素材代理文件

promo proxy <project> 会为每个视频资源构建 tier-1 代理文件（长边为 960 px，每帧均为关键帧），并将其缓存到软件包之外（$PROMO_PROXY_DIR；否则使用平台缓存目录下的 promoshot/proxies）。still、frames、gif 和 video 接受 --proxy auto|on|off：auto（默认）会在输出长边不超过代理文件尺寸时读取已构建的代理文件；on 会先构建缺失的代理文件；off 会读取源文件——全尺寸渲染始终读取源文件。MCP 工具接受相同的 proxy 参数；promo_proxy 用于构建代理文件。

标记与章节

项目可以包含 markers，即输出时间线上的命名时刻。kind: "chapter" 标记会写入导出的 mp4 章节列表（播放器的章节菜单）；inspect 会列出所有标记。

音频效果

视频或音频资源可以包含 audioEffects，其中有 compressor 和单频段 eq 条目，会按列表顺序在混音前应用；还有 normalize，它会将整个资源调整到目标响度（ITU BS.1770 LUFS，暂停片段不计入），并在效果链末尾应用单一静态增益。应用的导出和实时预览使用相同的效果，核心会为每个宿主规划归一化增益。

色度键

视频或图像图层可以包含 chromaKey，指定颜色、容差和柔化度：在合成器中，底板会在图层调色、边框和遮罩之前变为透明，因此绿幕片段可在所有宿主上一致地合成到任意内容之上。

模型

model 类型的资源是 Resources/ 中的 glTF 2.0 二进制文件（.glb）；model 类型的图层会通过轻量 PBR 渲染通道，将它绘制到与图层尺寸相同的纹理中，之后它就和其他图片一样：位置、透明度、转场、遮罩、效果和接触阴影都适用。关键帧包含一个 camera（偏航、俯仰、翻滚、以边界半径为单位的距离、视野）和一个 light；资源上的 materials 将槽位名称绑定到颜色——可以使用调色板名称，因此 @accent 会用主题为主体换肤——而在对象形式中，还可以绑定到一种表面效果：在文件自身数值的基础上设置 metallic 和 roughness（各为 0…1），这样同一个主体在本项目中是镀铬效果，在下一个项目中则是哑光效果（第 32 级）——或者更好地，绑定到一种表面效果词（第 44 级）：chrome、brushed、anodized、gloss、satin、matte、rubber、ceramic、lacquer、paper、glass、frosted；引擎会将每个词展开为其代表的数值、涂层、纹理、透射和折射效果，因此不必再手动调整反射；在屏幕上，这个词代表覆盖图片的涂层，而舞台上的玻璃会折射其后的主体。灯光默认值来自主题；金属反射的是场景 environment（studio、sunset、night；第 35 级——或者在第 46 级中，是一个 resourceID，指向项目中的全景图，也就是主体所映照的世界）；文件中的法线贴图和金属度-粗糙度纹理也会生效。第 29 级。内置设备机身（phone、tablet、tablet-portrait、laptop；promo device）会以生成的 .glb 文件形式提供，并带有 Body 和 Screen 槽位，因此设备画面也是模型。模型也可以是引擎在加载时构建的 recipe，而非文件——首先是作为主体的文字：在 3D 世界中的真实字体，带有 Face 和 Side 槽位，并像其他主体一样接受光照和表面效果处理（第 34 级）；设备机身；以及由部件构成的主体——盒体、球体、圆柱体、圆环、旋转体、拉伸体，每个部件都属于一个槽位，并通过位置、旋转和缩放进行摆放——这是绘图的 3D 对应形式，创作方式与 SVG 相同（第 37 级）。命名同一 stage 的图层会通过同一个摄像机绘制到同一个深度缓冲区中，模型位于各自的 depth 位置，图片则作为公告牌显示，而第一个成员的摆放决定整个场景的位置（第 30 级）。舞台也可以是一个 stage 类型的图层，由它持有自己的 members，并在自身关键帧中设置摄像机和灯光（第 33 级）——画面相同，只是明确记录了舞台的所有权。舞台的 floor 词（第 45 级）——matte、satin、glossy、mirror——会在最低处的主体下方放置一个平面，捕捉主光的阴影、主体接触处的暗部，以及舞台在平面中的倒影，并逐渐减少模糊；舞台图层下方的内容会透出，因此桌面就是项目自身的背景。灯光的关键帧会移动阴影；地面保持不动。

穿在主体上的图片

槽位中的图片默认是屏幕：不受光照、尺寸适配，适合手机上的屏幕截图。在绑定中设置 "mode": "surface"，就会将图片改为贴在表面上——图片或视频会成为槽位在灯光和表面效果作用下的颜色，并由 repeat 平铺、由 offset 偏移；图片透明处会显示槽位自身的颜色——这样标签可以贴在花瓶上，印花可以印在盒子上，视频也可以在光亮的墙面上播放，而主光和环境光仍会对墙面产生明暗效果。第 38 级。

粒子

particles 类型的资源是一份配方，而非文件——发射器、速率或爆发、寿命、速度、重力、风、阻力、湍流、随寿命变化的大小和颜色，以及形状——由绘制层播放。每个粒子都是由其诞生时间和种子决定的封闭形式函数，因此任何帧都能独立渲染，并且在每个宿主上结果一致。第 36 阶。

路径资源可以携带舞台中的路线（第 40 阶）：以舞台半径为单位的 3D 点，供成员或摄像机的 motionPath 跟随；它会像 2D 运动路径一样，在两个关键帧之间进行拟合。摄像机的 target——中心、前方、某个成员或一个点——则指定它沿途注视的位置。一条始终向内注视的螺旋只需一条路线和一个关键帧。

舞台中的粒子是一种变形（第 39 阶）：配方指定两个物体，对第一个物体的表面进行采样；随着绘制成员的 progress 关键帧从 0 增至 1，粒子飞散后聚集到第二个物体上——立方体爆散为点，再汇聚成一个单词。带有 faces: true 的部件盒有六个槽位，每面一张图片，这正是此类立方体的构成方式。

带侧面的文字

旧版：下文的标题 depth 指平面合成器的 2.5D。带有真实侧面的标题是站在舞台中的文字主体（第 34 阶）；验证器会指出旧格式。它仍然可以渲染。

标题样式可以带有 depth：将文字副本堆叠在正面下方，每一层都沿着一个方向再偏移一点，并且颜色更暗，让字体呈现出有侧面的实心字母效果——经典的挤出效果，纯 2D，通过选择偏移量来打光。揭示效果也会以同样的方式挤出每个出现的部分。标题上的 tiltX / tiltY 关键帧会让它产生透视倾斜，使用与设备画面相同的摄像机，侧面也会随正面一同倾斜。揭示效果的 flip、tumble 和 slide 模式会让每个单词沿各自的轴出现——只用一条规则就能实现动态排版，无需关键帧。

跟随指针

Mac 录制器生成的视频会带有 pointer，记录指针移动和点击的位置，使用录制内容自身的时间和坐标。显示它的图层可以设置 follow：其视口会变成源画面中大小为 1/zoom 的窗口，并跟随平滑处理后的指针；每次点击都会绘制一个逐渐扩散并淡出的圆环。这是一条规则，而非关键帧：重新裁剪录制内容后，效果依然准确，且在所有宿主上都一致。

图像效果

图层可以带有 effects：blur（圆形模糊，或沿 blurAngle 方向模糊）、亮部的 glow、朝向图层自身角落的 vignette、胶片 grain 和非锐化 sharpen，这些效果都由合成器处理，仅作用于图层自身的像素。模糊、辉光和暗角也支持关键帧轨道，因此焦点拉动或脉冲辉光都可以像调色效果一样逐渐变化。五种转场使用相同的处理流程——blurDissolve、zoom、flash、glitch 和 dip——与原有的淡入淡出、擦除、滑动、推入和缩放并列，可用于图层边缘，也可用于资源切换。视频图层切换时可以指定一个合成（第 47 阶）：接管画面，让下一段影片通过上述任意一种转场进入，进入位置由其 sourceTime 指定，或从其时钟当前所在的位置开始。相同的关键帧也控制所有带时钟内容的使用者的播放状态——视频、音频、合成、精灵：sourceTime 用于定位，playback 用于暂停和恢复，声音也会随之变化。

来自 .cube 的外观

lut 类型的资源是 Resources/ 中的 .cube 文件；图层的 adjustments.lutResourceID（配合 lutAmount）会在图层自身调色之后，由合成器应用它——采用三线性查找，在所有宿主上效果一致。

ProRes 和 Alpha

promo video … --codec prores422|prores4444 --out x.mov 会写入 ProRes；--alpha 会将项目渲染到透明背景上，并保留帧的 Alpha 通道，输出为 ProRes 4444（对 still / frames 使用 --alpha 会生成透明 PNG）。携带 Alpha 通道的源素材（ProRes 4444、带 Alpha 的 WebM、PNG 序列）会以预乘 Alpha 的方式解码，并以透明方式合成。