After Effects CC SDK 使用指南（二）—— 第一章 介绍 （上）

其他文章链接

序

第一章 介绍-上

第一章 介绍-下

---

第一章 介绍

欢迎使用Adobe®After Effects®CC软件开发工具包!这是一个全新的文档，并不断更新。SDK的最新公共版本地址：https://www.adobe.io/apis/creativecloud/aftereffects.html

虽然我们试图按逻辑顺序组织这个文档并提供大量的交叉引用，但您的实际需求可能会有所不同。可以在文档中通过搜索可以解决大部分的问题。如果你需要更多的信息，在After Effects SDK论坛上可能已经有人回答你的问题了，如果你的问题还没有被回答，可以去发布一个新问题。

我可以通过这个SDK做什么？

这个SDK描述了开发人员用来构建插件的应用程序编程接口(API)。这些插件可以扩展After Effects和其他支持After Effects API的应用程序的功能。插件也可以用来在After Effects和其他应用程序之间架起桥梁。

我可以用这个SDK构建哪些插件？

Effect特效插件 可以应用于合成中的视频或音频，以处理视频或音频数据。一些内置效果的例子是亮度和对比度，色调/饱和度，高斯模糊，和Warp稳定器。Effect效果插件可以为用户提供一组参数控件来微调效果。这些参数值可以随时间变化，并且effects可以在不同的时间使用其他层和参数来计算输出。人们通常认为所有的插件都是特效。但是effects只是After effects使用的一种插件。

查看在macOS上关于构建Effect效果的快速入门视频：adobe.ly/2sjMDwM

After Effects通用插件(AEGPs) 几乎可以读取和修改After Effects项目和首选项里的每个元素。 他们可以添加菜单项，“挂钩”（注册自己以进行接收）并触发After Effects的内部命令，并添加可以在After Effects UI中停靠并调整大小的新面板。 他们可以使用标记和关键帧，并管理渲染队列。 他们甚至可以运行脚本。 内置AEGP的一些示例是AAF导入工具和SWF导出工具。 Auto Duck Pro Import AE 是另一个著名的AEGP。

After Effects输入/输出(AEIO) 插件支持新媒体文件类型。 除非需要自定义设置对话框来指定解释设置，当然Premiere Pro 导入 API 也提供类似的功能，并且在许多情况下更可取。 AEIO将AEGP API以及某些特定于AEIO的API一起使用。尽管After Effects仍支持Photoshop格式的插件和滤镜以及“外国项目格式”（FPF）插件，但长期以来不推荐使用这些API，而推荐使用AEIO API。

BlitHook插件 将视频输出到外部硬件，以监视广播质量并播放到磁带。 EMP示例项目提供了一个起点。 在After Effects CC 2014和更高版本中，建议使用 Mercury Transmit API。

Artisans 提供3D图层的渲染输出，接管After Effects的3D渲染（After Effects仍处理2D图层的所有渲染）。 Artisans 使用AEGP API以及特定于 Artisans 的某些API。

没看到上面需要的集成类型吗？ After Effects非常灵活，还有其他几种与After Effects集成的方式。

插件出现在After Effects 的什么地方？

Effects效果插件同时出现在“效果”菜单和“效果和预设”面板中，位于其PiPL中指定的效果类别中。使用该用效果后，Effects效果的参数控件（滑块，弹出窗口等）将显示在效果控制面板（ECP）中。

After Effects通用插件（AEGP）可以将项目添加到任何After Effects菜单以及“窗口”菜单中列出的其他面板。 这些菜单项与After Effects自己的菜单项没有区别。

AEIO和Photoshop Format插件可以显示在“文件”>“导入”菜单中，或者在“文件类型”下拉列表的“导入文件”对话框中，具体取决于导入的类型。 AEIO和Photoshop Format插件也可以作为可用输出格式显示在渲染队列中。

BlitHook插件由AE自动加载和使用，但不会出现在任何菜单或对话框中。该插件可以选择提供一个菜单项，以打开其自己的自定义设置对话框。它将使用AEGP API注册并更新菜单项。 它的注册由After Effects调用，可以使用AEGP_RegisterUpdateMenuHook() 更新菜单，并且可以使用AEGP_EnableCommand()/DisableCommand()激活或使菜单项失效。

Artisans 会出现在“合成设置”对话框的“高级”选项卡中的“渲染插件”下拉列表中。

After Effects 如何与插件交互？

插件用C或C ++编写，在macOS是捆绑包，而在Windows上是DLL文件。 它们必须在两个平台上都包含一个插件属性列表（PiPL）资源。插件必须位于几个特定的文件夹之一中，以便由After Effects加载和使用。

对于effects效果插件，After Effects将命令选择器（和相关信息）发送到effects效果的PiPL资源中指定的插件入口点功能。 发送选择器是为了响应用户采取的操作：应用效果或更改参数，在时间轴中滚动查看帧以及呈现所有提示不同选择器序列的操作。 After Effects创建效果的多个实例，每个序列具有唯一的设置和输入数据。 所有实例共享相同的全局数据，并且可以在其序列中的所有帧之间共享数据。用户应用效果后，After Effects不会处理所有图像数据；它仅在需要输出效果时才调用效果。

After Effects通用插件（AEGP）在应用程序启动期间调用了它们的入口点方法，并注册了当时所需的任何信息。 AEGP的进一步调用是由用户操作发起的，作为插件对菜单命令或UI事件的响应的一部分。根据插件的功能，插件可能还需要响应特定于OS的入口点，以进行UI工作和线程管理。

对于BlitHook插件，将按显示在“合成”面板中的框架进行推送。 用户可以在时间轴的某个区域上启动RAM预览，以便将其呈现到RAM中，然后全速播放。

SDK 目录

SDK包含定义After Effects API的头文件，演示集成功能的示例项目以及此SDK指南。

它们与SDK头文件一起编译，这些头文件公开了插件要使用的各种After Effects功能。

其他整合可能性

尽管此SDK描述了大多数与After Effects集成的可能性，但还有其他可能性不容忽视。

脚本

脚本是一种使用After Effects执行自动化任务的相对灵活和轻巧的方法。 ScriptUI是您可以提供与自定义对话框和面板进行UI集成的一种方法（也请参见HTML5面板）。在通过脚本而不是通过本文档中介绍的C API提供某些功能的情况下，脚本可与插件开发一起使用。

After Effects中的脚本是使用基于JavaScript的ExtendScript完成的。 After Effects包含ExtendScript ToolKit，这是用于创建和测试自己的脚本的便捷界面。也可以将脚本编译成.jsxbin二进制文件，以保护知识产权。

您可以在Adobe I/O网站上访问《After Effects脚本指南》，并找到指向脚本论坛的链接，网址为：https://www.adobe.io/apis/creativecloud/aftereffects.html

可以通过从命令行执行脚本来驱动After Effects。在脚本中，您可以打开项目并在其上运行脚本操作。例如，您可以执行以下语句从命令行直接运行脚本：

AfterFX -s "app.quit()"

或者，您可以执行以下语句来运行.jsx脚本，该脚本在结尾处包含退出标识：

AfterFX -r

在Windows上，AfterFX.com 是将命令行反馈给控制台的方法，因为 AfterFX.com 是命令行应用程序。

HTML5 PANELS

在CC 2014及更高版本中，After Effects支持HTML5面板。可在After Effects中的“窗口”>“扩展”>（您的面板名称）中访问它们。可以像After Effects中的任何其他面板一样停靠和调整面板的大小。使用HTML5，After Effects脚本和JavaScript构建面板。 您可以从Adobe I/O网站上下载After Effects Panel SDK，网址为：https://www.adobe.io/apis/creativecloud/aftereffects.html

AERENDER

aerender提供的命令行界面与脚本紧密结合。aerender主要适合于允许自动渲染，但可用于从命令行执行任何序列的脚本命令。 此处的After Effects帮助文档中提供了概述：https://helpx.adobe.com/zh-cn/after-effects/using/automated-rendering-network-rendering.html

PREMIERE PRO IMPORTERS

Premiere Pro importers 支持将媒体导入到Adobe Creative Cloud中大多数的应用程序中，包括Premiere Pro，Media Encoder，Prelude和Audition。 由于这种广泛的兼容性，除非您需要与只能通过此SDK中的AEIO API提供的After Effects进行非常特定的集成，否则我们建议您开发Premiere Pro importers。 可通过以下网址获得Premiere Pro SDK：https://www.adobe.io/apis/creativecloud/premierepro.html

MediaCore导入程序插件相对于AEIO的一个优势是其优先级系统：最高优先级的导入程序在导入文件时会首先遇到问题，如果不支持特定的导入文件，则次高优先级的导入程序将有机会进行以下操作： 尝试导入它，依此类推。

MERCURY TRANSMIT

Mercury Transmit插件用于将视频发送到输出硬件，以进行广播质量监视。 发射器在Adobe Creative Cloud中的大多数应用程序中受支持，包括Premiere Pro，After Effects，Prelude和Character Animator。 Premiere Pro SDK中记录了Mercury Transmit API，网址为：https://www.adobe.io/apis/creativecloud/premierepro.html

SDK 受众

您必须是精通C/C ++的程序员才能编写After Effects插件。尽管我们将帮助解决After Effects API特有的问题，但我们无法帮助您学习IDE或基本编程概念。

本SDK指南假定您从用户的角度了解After Effects，并了解基本的运动图形术语。 如果不是这样，请以书本形式或市场上任何其他精美的教学书本形式使用Adobe After Effects课堂。 它将帮助您了解After Effects的必要主题，例如Alpha通道，像素长宽比，隔行扫描，色彩空间等。

开发要求

After Effects的系统要求在这里：https://helpx.adobe.com/zh-cn/after-effects/system-requirements.html

如果您需要支持过时的应用程序或API版本，请使用旧的SDK（我们不维护或提供）。 当前版本发布六个月后，我们将不再提供或支持旧版本的SDK。

SDK示例是在macOS 10.11上针对Xcode 7.3创建的，而Windows 7 64或Windows 10则是针对Microsoft Visual Studio 2015 Update 3创建的。是的，我们在使用必需的IDE方面非常严格。迁移到新的编译器永远不会令人愉快，但是我们不会继续为旧的构建环境提供帮助。

为了使用Visual Studio，您可能需要调整一些安装设置来安装用于编译64位插件的组件。 可以使用Visual Studio Express，但还需要进行其他安装才能编译64位插件，如此处所述：http://msdn.microsoft.com/zh-cn/library/9yb4317s.aspx

要在更新版本的macOS上使用更新版本的Xcode进行编译，通常所需要做的只是在Build Settings（构建设置）中更新Base SDK。

如何开始创建插件

玩！

在编写一行代码之前，请花费大量时间与After Effects和示例项目一起玩。 将插件构建到正确的文件夹中。 设置许多断点，阅读有趣且内容丰富的注释。

计划！

请明确您的插件将尝试执行的操作。

HACK!

在对样本进行实验之后，找到一个可以完成您想要做的事情的样本。从头开始的诱惑可能很强烈。跟它对干！ 要获得效果，请使用 Skeleton 模板项目。通过将代码移植到现有项目中，可以避免重建项目的麻烦（包括麻烦的Windows PiPL资源生成的自定义生成步骤）。

偷！

要制作自己的 Skeleton 示例，请复制整个 \Skeleton 目录，并将其重命名为（例如）\WhizBang。 使用您选择的文本编辑器，搜索 \WhizBang\*.*（是，包括.NET和Xcode项目文件）以查找 Skeleton 和 SKELETON 的出现，并将其替换为 WhizBang 和 WHIZBANG

现在，您有了一个可编译并运行的插件，该插件可响应常见命令，处理8和16-bpc颜色，使用我们的AEGP_SuiteHandler 实用程序代码，并响应3D灯光和相机信息。 所以，真的那么难吗？

AEGP开发人员将从 Projector（用于After Effects项目创建支持），Easy Cheese（用于关键帧助手），IO （用于媒体文件格式支持）以及 Persisto （用于简单的菜单命令并使用首选项）开始做起。

测试！

如果只是为了测试方便，您应该保存一个应用了效果的项目，并且其所有参数的关键帧都设置为奇数值。 在强调插件的这些项目与开发环境提供的工具之间，您可以顺利地交付一些经过测试的代码。

责任！

如果遇到似乎错误的行为，请查看是否可以使用未修改的示例项目之一来重现该行为。如果您可以确定错误行为是由您的修改引起的，还是从一开始就已经存在，则可以节省大量时间。

开发者课题

第三方开发人员推动API和SDK的改进和扩展。 您的产品使After Effects能够执行我们从未考虑过的事情。 您的努力将使After Effects更好； 继续努力吧！

我们正在努力开发SDK，并欢迎您提出意见和反馈。 我们对API所做的几乎所有更改都是像您这样的开发人员建议的。 欢迎与我们交谈。

原文

Welcome to the Adobe® After Effects® CC Software Development Kit! This is a living document, and is constantly being updated and edited. The latest public version of the SDK is available at: https://www.adobe.io/apis/creativecloud/aftereffects.html

While we’ve tried to organize this document in a logical order and provide plenty of cross references, your specific needs may vary. Searching through this document based on keywords will often lead you to your answer. If you need more information, your question may already be answered on the After Effects SDK forum: http://forums.adobe.com/community/aftereffects_general_discussion/aftereffects_sdk. Use the search box there, and post a new question if your question hasn’t already been answered.

This SDK describes the Application Programming Interface (API) that developers use to build plug-ins. These plug-ins can extend the capabilities of After Effects and other applications that support the After Effects API. Plug-ins may also be used to bridge the gap between After Effects and another application.

Effect plug-ins can be applied to video or audio in a composition, to process video and/or audio data. Some examples of built-in effects are Brightness and Contast, Hue/Saturation, Gaussian Blur, and Warp Stabilizer. Effect plug-ins can provide a set of parameter controls for the user to fine-tune the effect. These parameter values can vary over time, and effects may use other layers and parameters at different times to calculate the output. It’s often thought that all plug-ins are effects. But effects are just one type of plug-in used by After Effects.

See a quickstart video on building an effect (on macOS): adobe.ly/2sjMDwM

After Effects General Plug-ins (AEGPs) can read and modify nearly every element of After Effects projects and preferences. They can add menu items, ‘hook’ (register themselves to receive) and trigger After Effects’ internal commands, and add new panels that dock and resize within the After Effects UI. They can work with markers and keyframes, and manage the render queue. They can even run scripts. Some examples of built-in AEGPs are the AAF importer, and the SWF exporter. Automatic Duck Pro Import AE is another well-known AEGP.

After Effects Input/Output (AEIO) plug-ins provide support for new media file types. Unless you need a custom setup dialog to specify interpretation settings, the Premiere Pro importer API provides similar functionality, and is preferable in many cases. AEIOs use the AEGP API along with certain APIs specific to AEIOs. While After Effects still supports Photoshop format plug-ins and filters, as well as Foreign Project Format (FPF) plug-ins, these APIs have been long deprecated in favor of the AEIO API.

BlitHook plug-ins output video to external hardware for broadcast quality monitoring and playback to tape. The EMP sample project provides a starting point. In After Effects CC 2014 and later, Mercury Transmit is the recommended API.

Artisans provide rendered output of 3D layers, taking over 3D rendering from After Effects (which still handles all rendering of 2D layers). Artisans use the AEGP API along with certain APIs specific to Artisans.

Didn’t see the type of integration you need described above? After Effects is very flexible, and there are several other ways to integrate with After Effects.

Effects plug-ins appear in both the Effect menu and the Effects & Presets panel, in the effect category specified in their PiPL. Once they’re applied, the effect’s parameter controls (sliders, pop-ups, etc.) appear in the Effect Controls panel (ECP).

After Effects General Plug-ins (AEGPs) can add items to any After Effects menu, and additional panels listed in the Window menu. These menu items are indistinguishable from After Effects’ own menu items.

AEIOs and Photoshop Format plug-ins can appear in the File > Import menu, or in the Import File dialog in the Files of type drop-down, depending on the type of importer. AEIOs and Format plug-ins can also appear as available output formats in the render queue.

BlitHook plug-ins are automatically loaded and used by AE, but do not appear in any menu or dialog. The plug-in may optionally provide a menu item that opens it’s own custom settings dialog. It would register and update the menu item using the AEGP API. It can registered to be called by After Effects to update the menu with AEGP_RegisterUpdateMenuHook(), and it can dim/activate the menu item using AEGP_EnableCommand()/DisableCommand().

Artisans appear in the Rendering Plug-in drop-down in the Advanced tab of the Composition Settings dialog.

Plug-ins, written in C or C++, are bundle packages on macOS and DLLs on Windows. They must contain a Plug-in Property List (PiPL) resource on both platforms. The plug-ins must be located in one of a few specific folders in order to be loaded and used by After Effects.

For effects plug-ins, After Effects sends command selectors (and relevant information) to the plug-in entry point function designated in the effects’ PiPL resource. Selectors are sent in response to actions the user takes—applying the effect, changing parameters, scrubbing through frames in the timeline, and rendering all prompt different sequences of selectors. After Effects creates multiple instances of effects, with settings and input data unique to each sequence. All instances share the same global data, and can share data between all frames within their sequence. After Effects doesn’t process all image data as soon as the user applies an effect; it invokes effects only when their output is required.

After Effects General Plug-ins (AEGPs) have their entry point function called during application launch, and register for whatever messaging they need at that time. Further calls to the AEGP are initiated by user actions, as part of the plug-in’s response to menu commands or UI events. Depending on their features, plug-ins may need to respond to OS-specific entrypoints as well, for UI work and thread management.

For BlitHook plug-ins, frames are pushed as they’re displayed in the Composition panel. Users can initiate a RAM preview on an area of the timeline so that it is rendered to RAM, and then it all gets played out at full speed.

The SDK contains headers defining the After Effects APIs, sample projects demonstrating integration features, and this SDK Guide.

They are compiled with the SDK header files, which expose various After Effects functionality to be used by the plug-in.

Although this SDK describes the majority of integration possibilities with After Effects, there are other possibilities not to be overlooked.

Scripting is a relatively nimble and lightweight means to perform automated tasks with After Effects. ScriptUI is one way you can provide UI integration with custom dialogs and panels (see HTML5 panels too). And scripting may be used in tandem with plug-in development, in the cases where a certain function is made available via scripting and not via the C APIs described in this document.

Scripting in After Effects is done using ExtendScript, based on JavaScript. After Effects includes the ExtendScript ToolKit, a convenient interface for creating and testing your own scripts. Scripts may be compiled into .jsxbin binary files, to protect intellectual property.

You can access the After Effects Scripting Guide, and find a link to the scripting forums, on the Adobe I/O website at: https://www.adobe.io/apis/creativecloud/aftereffects.html

After Effects can be driven by executing scripts from the commandline. In your script, you can open the project and run script actions on it. So for example, you can execute the following statement to run a script from the command line directly:

Or you can execute this statement to run a .jsx script that includes a quit at the end:

On Windows, AfterFX.com is the way to get feedback to the console, because AfterFX.com is a command line application.

In CC 2014 and later, After Effects supports HTML5 panels. They are accessed in After Effects from Window > Extensions > (your panel name). Panels can be resized and docked just like any other panel in After Effects. Panels are built using HTML5, After Effects Scripting, and JavaScript. You may download the After Effects Panel SDK from the the Adobe I/O website at: https://www.adobe.io/apis/creativecloud/aftereffects.html

Closely coupled with scripting is the command line interface offered by aerender. aerender is primarily suited to allow automated renders, but can be used to execute any sequence of scripting commands from the command line. An overview is available in the After Effects help documents here: https://helpx.adobe.com/after-effects/using/automated-rendering-network-rendering.html

Premiere Pro importers provide support for importing media into applications across most applications in the Adobe Creative Cloud, including Premiere Pro, Media Encoder, Prelude, and Audition. Because of this broader compatibility, unless you need very specific integration with After Effects only available via the AEIO API in this SDK, we recommend developing a Premiere Pro importer. The Premiere Pro SDK is available at: https://www.adobe.io/apis/creativecloud/premierepro.html

One advantage of MediaCore importer plug-ins over AEIOs is its priority system: The highest priority importer gets first crack at importing a file, and if the particular imported file isn’t supported, the next-highest priority importer will then have the opportunity to try importing it, and so on.

Mercury Transmit plug-ins are used for sending video to output hardware for broadcast-quality monitoring. Transmitters are supported across most applications in the Adobe Creative Cloud, including Premiere Pro, After Effects, Prelude, and Character Animator. The Mercury Transmit API is documented in the Premiere Pro SDK, available at: https://www.adobe.io/apis/creativecloud/premierepro.html

You must be a proficient C/C++ programmer to write After Effects plug-ins. While we’ll help with issues specific to the After Effects API, we can’t help you learn your IDE or basic programming concepts.

This SDK guide assumes you understand After Effects from a user’s perspective, and basic motion graphics terminology. If you don’t, get the Adobe After Effects Classroom in a Book, or any of the other fine instructional books on the market. It will help you understand necessary topics such as alpha channels, pixel aspect ratio, interlacing, color spaces, and more for After Effects.

The system requirements for After Effects are here: https://helpx.adobe.com/after-effects/system-requirements.html

If you require support for obsolete versions of the application or API, use an old SDK (which we don’t maintain or provide). Six months after the current version is released, we will no longer provide or support the previous version’s SDK.

The SDK samples are created for Xcode 7.3 on macOS 10.11, and Microsoft Visual Studio 2015 update 3 on Windows 7 64 or Windows 10. Yes, we’re being pretty stringent about using the required IDE. No, it’s never pleasant to move to a new compiler, but no, we’re not going to continue to help with older build environments.

In order to use Visual Studio, you may need to adjust some installation settings to install the components for compiling 64-bit plug-ins. Visual Studio Express may be used, but will also require an additional installation to compile 64-bit plug-ins, as described here: http://msdn.microsoft.com/en-us/library/9yb4317s.aspx

To compile using newer versions of Xcode on newer versions of macOS, often all that is required is to update the Base SDK in the Build Settings.

Before you write a line of code, Spend some significant time playing with After Effects, and with the sample projects. Build the plug-ins into the right folder. Set lots of breakpoints, read the amusing and informative comments.

Be clear on what your plug-in will attempt to do.

After experimenting with the samples, find one that does something like what you want to do. The temptation to start from scratch may be strong; fight it! For effects, use the Skeleton template project. Avoid the headache of reconstructing projects (including the troublesome custom build steps for Windows PiPL resource generation) by grafting your code into an existing project.

To make the Skeleton sample your own, copy the entire \Skeleton directory, renaming it to (for example) \WhizBang. Using your text editor of choice, search \WhizBang*.* (yes, that includes .NET and Xcode project files) for occurrences of Skeleton and SKELETON, and replace them with WhizBang and WHIZBANG.

You now have a compiling and running plug-in that responds to common commands, handles 8 and 16-bpc color, uses our AEGP_SuiteHandler utility code, and responds to 3D light and camera information. There, was that so hard?

AEGP developers will do well to start with Projector (for After Effects project creation support), Easy Cheese for a keyframe assistant, IO for media file format support, and Persisto for a simple menu command and working with preferences.

If only for testing convenience, you should have a project saved with your effect applied, and all its parameters keyframed to strange values. Between these projects which stress your plug-in, and the tools provided by your development environment, you’re well on your way to shipping some tested code.

If you run into behavior that seems wrong, see if you can reproduce the behavior using one of the unmodified sample projects. This can save you a lot of time, if you can determine whether the bug behavior was introduced by your modifications, or was already there to begin with.

Third party developers drive API and SDK improvement and expansion. Your products enable After Effects to do things we’d never considered. Your efforts make After Effects better; keep it up!

We work hard on the SDK, and welcome your comments and feedback. Almost every change we make to the API is suggested by developers like you. Talk to us.