Macromedia After Effects - CS3 User Manual

SCRIPTING GUIDE

Adobe

Creative Suite 3 After Effects® Scripting Guide

NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Adobe Systems Incorporated. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license.

This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights.

Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization.

Adobe, the Adobe logo, After Effects, Photoshop, and Bridge are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Apple, Mac, Macintosh, and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries. Microsoft, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. JavaScript and all Java-related marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group.

All other trademarks are the property of their respective owners.

If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement.

The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.

Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

Overview

The After Effects Scripting Guide demonstrates how to take procedural control of your After Effects projects via scripting. This feature set is available in Adobe® After Effects® CS3 Professional Edition.

With the use of system-level scripting, you can streamline your render pipeline and avoid a lot of repetitive pointing and clicking. If you have used expressions or other JavaScript-like techniques for animating, or worked with system scripting in AppleScript or Visual Basic, you will recognize the power of application scripting in After Effects. With some practice, and with sufficient experience using the JavaScript language, you can take control of your graphics pipeline.

If you are new to scripting

After Effects is a visual tool with a graphical user interface; you are used to interacting with it via interface elements such as menus, panels, and icons. For the most part, this is the most accessible way to work. Scripting is designed for situations in which this methodology involves tedious repetition or painstaking searching and sorting that could be automated. Scripting can be a shortcut around tedious tasks that would otherwise involve repetitious pointing and clicking. It is also useful for leveraging the power of networked rendering in situations where Watch Folder is less powerful (and less convenient to set up). See “Examples” on page 173 for examples of what scripts can do.

If you are new to scripting, see Adobe Introduction to Scripting, which introduces basic scripting concepts and describes different scripting languages that are available, including JavaScript. JavaScript and other scripting languages are object-oriented, and this book also describes the basic concepts of object-oriented programming and document object models.

Even if you have no inclination to learn the JavaScript language, you can still harness the power of scripting via third-party solutions such as Rush Network Render Queue, a graphical user interface to set up distributed renders from any computer on the network without having to set up on individual machines.

You can also leverage the contributions of scripting users who share scripts with other users. Larger studios may have such users in-house, while other users can visit forums such as those found at

www.adobeforums.com.

About this guide

This guide is for users who manage a graphics pipeline (which may include other scriptable applications as well) and who want to write scripts to add custom capabilities to After Effects.

This functionality is also offered via third-party network rendering management solutions. These products feature software designed to help manage this process, so it is possible to take advantage of this functionality without having to perform manual editing of scripts.

Overview Editing scripts

The heart of a scriptable application is the object model. When you use Adobe After Effects, you create projects, compositions, and render-queue items along with all of the elements that they contain: footage, images, solids, layers, masks, effects, and properties. Each of these items, in scripting terms, is an object. This guide describes the JavaScript objects that have been defined for After Effects projects.

Much of what scripting can accomplish replicates what can be done via the After Effects user interface, so a thorough knowledge of the application itself is also essential to understanding how to use this functionality.

The After Effects object model is composed of a project, items, compositions, layers, and render-queue items. Each object has its own special attributes, and every object in an After Effects project has its own identity (although not all are accessible to scripting). You should be familiar with the After Effects object model in order to create scripts.

After Effects scripting is based on ECMAScript (or more specifically, the 3rd Edition of the ECMA-262 Standard). Further documentation on this standard can be found at www.ecma-international.org. To take full advantage of what is possible with scripting you will also need an understanding of writing scripts at the system level (for integration with AppleScript or the Terminal command line in Mac OS and command-line scripts on Windows systems) and a background in how to work with JavaScript.

NOTE: JavaScript objects normally referred to as “properties” are consistently called “attributes” in this guide, to avoid confusion with After Effects’ own definition of a property (an animatable value of an effect, mask, or transform within an individual layer).

Expressions

Although both After Effects expressions and the After Effects scripting interface use JavaScript and can access individual layer properties, they are entirely distinct entities. Expressions cannot access information from scripts (such as variables and functions), although a script can be written to create or edit an expression.

Because both expressions and scripting use JavaScript, familiarity with either one is helpful in understanding the other.

Motion math

Motion math is no longer included in After Effects; its functionality has been superseded by scripting and expressions. All mathematical and logical operators common to ECMAScript are available in scripting.

For example, with expressions it is possible to simulate the physics of a bouncing ball by applying mathematical rules to a “ball” layer. But using scripting, you can create a whole user interface that allows a bouncing ball and shadow layer to be animated using criteria entered by the user.

Editing scripts

After Effects includes a JavaScript editor. To start it, choose File > Scripts > Open Script Editor. This script editor and debugger, called the ExtendScript Toolkit, provides a convenient interface for creating and testing your own scripts.

You can use any text editor to create, edit, and save scripts, but it is recommended that you choose an application that does not automatically add header information when saving files and that saves with Unicode (UTF-8) encoding.

• Windows applications that are useful for editing scripts include EM Editor or the built-in Notepad (be sure

to set Encoding within save options to UTF-8).

• Mac OS applications that are useful for editing scripts include BBEdit or the built-in OS X TextEdit (be sure

to set the Save type in Preferences to Unicode [UTF-8]).

Overview Activating full scripting features

The ExtendScript JSX format

After Effects supports ExtendScript, Adobe’s extended implementation of JavaScript. ExtendScript is used by all Adobe applications that provide a scripting interface. In addition to implementing the JavaScript language according to the ECMA 262 and E4X ECMA 357 specifications, ExtendScript provides certain additional features and utilities:

ExtendScript Toolkit: For help in developing, debugging, and testing scripts, ExtendScript provides an inter-

active development and testing environment, the ExtendScript Toolkit. It also defines a global debugging object, the dollar ($) object, and a reporting utility for ExtendScript elements, the ExtendScript Reflection interface.

File and Folder Objects: Because path name syntax is very different in different operating systems, Adobe

ExtendScript defines system.

ScriptUI User Interface Module: The ExtendScript ScriptUI module provides the ability to create and interact

with user interface elements. ScriptUI provides an object model for windows and UI control elements that you can use to create a user interface for your scripts.

Tools and Utilities: In addition, ExtendScript provides tools and features such as a localization utility for

providing user-interface string values in different languages and global functions for displaying short messages in dialog boxes (

File and Folder objects to provide platform-independent access to the underlying file

alert, confirm, and prompt).

Interapplication Communication: ExtendScript provides a common scripting environment for all Adobe

applications, and allows interapplication communication through scripts.

External Communication: ExtendScript provides a Socket object that allows you to communicate with remote

systems from your After Effects scripts.

These features and more are described in detail in the JavaScript Tools Guide, which is available with After Effects, and from partners.adobe.com

ExtendScript script files are distinguished by the used with standard JavaScript files. After Effects scripts must include the properly recognized by the application. Any UTF-8 encoded text file with the

.jsx file extension, a variation on the standard .js extension

.jsx file extension in order to be

.jsx extension is recognized as

an ExtendScript file.

You can use the ExtendScript Toolkit to export a binary version of an ExtendScript file, which has the extension

.jsxbin. Such a binary file may not be usable with all of the scripting integration features in After

Effects.

Activating full scripting features

For security reasons, the scripting features that operate outside the After Effects application (such as adding and deleting files and folders on volumes, or accessing the network) are disabled by default.

To enable these features, choose Preferences > General, and select “Allow Scripts To Write Files And Access Network.” This allows you to:

• Write to files

• Create folders and set the current folder

• Create a socket connection (for details of this JavaScript utility, see the JavaScript Tools Guide)

Overview Accessing and writing scripts

Adobe supplies a full-featured JavaScript debugger, called the ExtendScript Toolkit. The Toolkit is disabled by default so that casual users do not encounter it. When editing or writing scripts, the Toolkit can help you diagnose script problems more quickly. To activate the Toolkit on the local computer when a script error is encountered, choose Preferences > General, and select Enable JavaScript Debugger. For detailed information on the ExtendScript Toolkit, see the JavaScript Tools Guide.

Note that the Toolkit operates only when executing a script, not with expressions, even though expressions also make use of JavaScript.

Accessing and writing scripts

To create and edit scripts for After Effects, you can use the ExtendScript Toolkit, or an external text-editing application that creates files with Unicode UTF-8 text encoding. Beware of applications such as Microsoft Word that by default add header information to files; these create line 0 errors in scripts, causing them to fail.

A script can reside anywhere, although to appear in the Scripts menu it must be saved in the Scripts folder within the After Effects application folder.

There is no built-in method for recording a series of actions in After Effects into a script, as you can with Adobe Photoshop® actions. Scripts are created outside After Effects and then executed within it, or externally via a command-line, the ExtendScript Toolkit, or third-party render management software.

The Scripts menu and Scripts folder

After Effects scripts reside in the Scripts folder, within the same folder as your After Effects application file. Only scripts contained in this Scripts folder when the application starts are automatically listed in the Scripts menu, although a script file can reside anywhere.

To run a script that does not appear in the Scripts menu, choose File > Scripts > Run Script File, and choose the script in the Open dialog box. Alternatively, you can send After Effects a script from the ExtendScript Toolkit, from a command line (on Windows) or from AppleScript (on Mac OS).

To appear in the Open dialog box, your script must include the proper

.jsx file extension.

Shutdown and Startup folders

Within the Scripts folder are two folders called Startup and Shutdown. After Effects runs scripts in these folders automatically, in alphabetical order, on starting and quitting, respectively.

In the Startup folder you can place scripts that you wish to execute at startup of the application. They are executed after the application is initialized and all plug-ins are loaded.

Scripting shares a global environment, so any script executed at startup can define variables and functions that are available to all scripts. In all cases, variables and functions, once defined by running a script that contains them, persist in subsequent scripts during a given After Effects session. Once the application is quit, all such globally defined variables and functions are cleared. Be sure to give variables in scripts unique names, so that a script does not inadvertently reassign global variables intended to persist throughout a session.

Attributes can also be added to existing objects such as the Application object (see “Application object” on page 19) to extend the application for other scripts.

The Shutdown folder scripts are executed as the application quits. This occurs after the project is closed but before any other application shutdown occurs.

Overview Sending a script to After Effects from the system

The Window menu and ScriptUI Panels folder

Within the Scripts folder, you can create another folder named ScriptUI Panels. Use this folder for scripts whose user interface appears in a native panel (as opposed to a floating palette, dialog box, or window). The advantage of a panel is that it can be docked with other panels, such as Project, Composition, and Time Controls, and appear more integrated into the application. Like native panels, ScriptUI Panels scripts are accessed from the Window menu.

Instead of creating a Window object an adding controls to it, a ScriptUI Panels scr ipt u ses the "thi s" o bjec t th at represents the panel. For example, the following code adds a button to a panel:

var myPanel = this;

myPanel.add("button", [10, 10, 100, 30], "Tool #1");

myPanel.show();

If your script creates its user interface in a function, you cannot use "this" as it will refer to the function itself, not the panel. In this case, you should pass the "this" object as an argument to your function. For example:

function createUI(thisObj) {

var myPanel = thisObj;

myPanel.add("button", [10, 10, 100, 30], "Tool #1");

return myPanel;

}

var myToolsPanel = createUI(this);

myToolsPanel.show();

You cannot use the File > Scripts > Run Script File menu command to run a script that refers to "this". To make your script work with either a Window object (accessible from the File > Scripts menu) or a native panel (accessible from the Window menu), check whether "this" is a Panel object. For example:

function createUI(thisObj) {

var myPanel = (thisObj instanceof Panel) ? thisObj : new Window("palette", "My Tools",

[100, 100, 300, 300]);

myPanel.add("button", [10, 10, 100, 30], "Tool #1");

return myPanel;

}

var myToolsPanel = createUI(this);

myToolsPanel.show();

Sending a script to After Effects from the system

If you are familiar with how to run a script from the command line in Windows or via AppleScript, you can se nd a s cri pt d irec tly to th e op en Af ter Effects application, so that the application automatically runs the script.

How to include After Effects scripting in a command line (Windows)

Following are examples of Windows command-line entries that will send an After Effects script to the application without using the After Effects user interface to execute the script.

In the first example, you copy and paste your After Effects script directly on the command line and then run it. The script text appears in quotation marks following the

afterfx.exe -s command:

afterfx.exe -s "alert("You just sent an alert to After Effects")"

Overview Testing and troubleshooting

Alternatively, you can specify the location of the JSX file to be executed. For example:

afterfx.exe -r c:\myDocuments\Scripts\yourAEScriptHere.jsx

afterfx.exe -r "c:\myDocuments\Scripts\Script Name with Spaces.jsx"

How to include After Effects scripting in an AppleScript (Mac OS)

Following are three examples of AppleScript scripts that will send an existing JSX file containing an After Effects script to the application without using the After Effects user interface to execute the script.

In the first example, you copy your After Effects script directly into the Script Editor and then run it. The script text appears within quotation marks following the DoScript command, so internal quotes in the script must be escaped using the backslash escape character, as follows:

tell application "Adobe After Effects CS3"

DoScript "alert(\"You just sent an alert to After Effects\")"

end tell

Alternatively, you could display a dialog box asking for the location of the JSX file to be executed, as follows:

set theFile to choose file

tell application "Adobe After Effects CS3"

DoScript theFile

end tell

Finally, this script is perhaps most useful when you are working directly on editing a JSX script and want to send it to After Effects for testing or to run. To use it effectively you must enter the application that contains the open JSX file (in this example it is TextEdit); if you do not know the proper name of the application, type in your best guess to replace “TextEdit” and AppleScript prompts you to locate it.

Simply highlight the script text that you want to run, and then activate this AppleScript:

This script sends the current selection to After Effects as a script.

tell application "TextEdit"

set the_script to selection as text

end tell

tell application "Adobe After Effects CS3"

activate

DoScript the_script

end tell

For more information on using AppleScript, check out Matt Neuberg’s AppleScript: the Definitive Guide (O’Reilly & Associates) or Sal Soghoian’s AppleScript 1-2-3 (Peachpit Press).

Testing and troubleshooting

Any After Effects script that contains an error preventing it from being completed generates an error message from the application. This error message includes information about the nature of the error and the line of the script on which it occurred.

Overview More resources to learn scripting

Additionally, After Effects includes a JavaScript debugger. For more information on activating and using the debugger, see the ExtendScript Toolkit documentation in the JavaScript Tools Guide.

More resources to learn scripting

Many resources exist for learning more about scripting that uses the ECMA standard.

The After Effects scripting engine supports the 3rd Edition of the ECMA-262 Standard, including its notational and lexical conventions, types, objects, expressions, and statements.

For a complete listing of the keywords and operators included with ECMAScript, refer to ECMA-262.pdf, available at

Books that deal with JavaScript 1.2 are also useful for understanding how scripting works in After Effects. One book that is something of a standard for JavaScript users is JavaScript: The Definitive Guide (O’Reilly) by David Flanagan. Another very readable source is JavaScript: A Beginner’s Guide (Osborne) by John Pollock. Both of these texts contain information that pertains only to extensions of JavaScript for Internet browsers; however, they also contain thorough descriptions of scripting fundamentals.

There are also books for using AppleScript and creating Windows command line scripts, each of which can be used to send scripts to After Effects.

www.ecma-international.org/publications/standards/Ecma-262.htm .

JavaScript variables

Scripting shares a global environment, so any script executed at startup can define variables and functions that are available to all scripts. In all cases, variables and functions, once defined by running a script that contains them, persist in subsequent scripts during a given After Effects session. Once the application is quit, all such globally defined variables and functions are cleared. Scripters should be careful about giving variables in scripts unique names, so that a script does not inadvertently reassign global variables intended to persist throughout a session.

JavaScript keywords and statement syntax

Although it is not possible to provide an exhaustive resource describing usage of JavaScript, the following tables provide an overview of keywords, statements, operators, precedence, and associativity.

The following table lists and describes all keywords and statements recognized by the After Effects scripting engine.

Table 1 Keywords and Statement Syntax

Keyword/Statement Description

break

continue

case

default

Standard JavaScript; exit the currently executing loop.

Standard JavaScript; cease execution of the current loop iteration.

Label used in a switch statement.

Label used in a switch statement when a case label is not found.

do...while

false

for

for...in

Standard JavaScript construct. Similar to the while loop, except loop condition evaluation occurs at the end of the loop.

Literal representing the boolean false value.

Standard JavaScript loop construct.

Standard JavaScript construct. Provides a way to easily loop through the properties of an object.

Overview More resources to learn scripting

Keyword/Statement Description

function

if/if...else

new

null

return

switch

this

true

undefined

var

while

with

Used to define a function.

Standard JavaScript conditional constructs.

Standard JavaScript constructor statement.

Assigned to a variable, array element, or object property to indicate that it does not contain a legal value.

Standard JavaScript way of returning a value from a function or exiting a function.

Standard JavaScript way of evaluating a JavaScript expression and attempting to match the expression’s value to a case label.

Standard JavaScript method of indicating the current object.

Literal representing the boolean true value.

Indicates that the variable, array element, or object property has not yet been assigned a value.

Standard JavaScript syntax used to declare a local variable.

Standard JavaScript construct. Similar to the do...while loop, except loop condition evaluation occurs at the beginning of the loop.

Standard JavaScript construct used to specify an object to use in subsequent statements.

JavaScript operators

The following tables list and describe all operators recognized by the After Effects scripting engine and show the precedence and associativity for all operators.

Table 2 Description of Operators

Operators Description

new

delete

typeof

void

[]

()

––

–

Allocate object.

Deallocate object.

Returns data type.

Returns undefined value.

Structure member.

Array element.

Function call.

Pre- or post-increment.

Pre- or post-decrement.

Unary negation or subtraction.

Bitwise NOT.

Logical NOT.

Multiply.

Divide.

Modulo division.

Overview More resources to learn scripting

Operators Description

>>>

Add.

Bitwise left shift.

Bitwise right shift.

Unsigned bitwise right shift.

Less than.

Less than or equal.

Greater than.

Greater than or equal.

Equal.

Not equal.

Bitwise AND.

Bitwise XOR.

Bitwise OR.

Logical AND.

Logical OR.

Conditional (ternary).

Assignment.

–=

<<=

>>=

>>>=

Assignment with add operation.

Assignment with subtract operation.

Assignment with multiply operation.

Assignment with divide operation.

Assignment with modulo division operation.

Assignment with bitwise left shift operation.

Assignment with bitwise right shift operation.

Assignment with unsigned bitwise right shift operation.

Assignment with bitwise AND operation.

Assignment with bitwise XOR operation.

Assignment with bitwise OR operation.

Multiple evaluation.

Table 3 Operator Precedence

Operators (highest precedence to lowest) Associativity

[], (), .

left to right

new, delete, – (unary negation), !, typeof, void, ++, ––

right to left

Overview More resources to learn scripting

Operators (highest precedence to lowest) Associativity

*, /, %

+, – (subtraction)

<<, >>, >>>

<, <=, >, >=

==, !=

=, /=, %=, <<=, >>=, >>>=, &=, ^=, |=, +=, –=, *=

left to right

right to left

left to right

JavaScript Reference

APPLICATION

PROJECT

SETTINGS

RENDER1UEUE ITEMS

ITEMSMAYBEANYOFTHEFOLLOWINGTYPESOFITEM

ITEMS

RENDER1UEUE)TEMS

OUTPUT-ODULES

SOCKETFILE FOLDERSYSTEM

FOLDER)TEMFOOTAGE)TEM

PROXY3OURCE PROXY3OURCEMAIN3OURCE

SOLID3OURCE

COLOR

FILE3OURCE

FILE

PLACEHOLDER3OURCE

LAYERS

PROPERTIES

COMP)TEM

MAIN3OURCEPROXY3OURCE

MAYBEANYOFTHEFOLLOWINGTYPESOFITEM

This chapter lists and describes JavaScript classes, objects, methods, attributes, and global functions defined by After Effects.

The After Effects scripting engine supports ExtendScript, Adobe’s extended version of JavaScript, which implements the 3rd Edition of the ECMA-262 Standard, including its notational and lexical conventions, types, objects, expressions and statements. For a complete listing of the keywords and operators included with ECMAScript, refer to

Ecma-262.htm. For an overview of the most common keywords and statements available from ECMA-262,

see “JavaScript keywords and statement syntax” on page 9.

The After Effects Object Model

As you look through this reference section, which is organized alphabetically by object, you can refer to the following diagrams for an overview of where the various objects fall within the hierarchy, and their correspondence to the user interface.

ECMA-262.pdf, available at www.ecma-international.org/publications/stan dards/

Hierarchy diagram of the main After Effects scripting objects

Note that the File, Folder, and Socket objects are defined by ExtendScript, and are documented in the JavaScript Tools Guide. ExtendScript also defines the ScriptUI module, a set of window and user-interface control

objects, which are available to After Effects scripts. These are also documented in the JavaScript Tools Guide.

The hierarchy of objects in scripting corresponds to the hierarchy in the user interface.

JavaScript Reference The After Effects Object Model

The application contains a Project panel, which displays a project. The project contains compositions, which contain layers. The source for a layer can be a footage file, placeholder, or solid, also listed in the Project panel. Each layer contains settings known as properties, and these can contain markers and keyframes. The render queue contains render-queue items as well as render settings and output modules. All of these entities are represented by objects in scripting.

NOTE: To avoid ambiguity, this manual uses the term “attribute” to refer to JavaScript object properties, and the term “property” or “AE property” to refer to After-Effects layer properties.

Object summary

The following table lists all objects alphabetically, with links to the documentation page for each.

Object Description

“Global functions” on page 16 Globally available functions that allow you to display text for script debugging purposes,

“Application object” on page 19 A single global object, available by its name (app), that provides access to objects and

“AVItem object” on page 32 Represents audio/visual files imported into After Effects.

“AVLayer object” on page 39 Represents those layers that contain AVItem objects (Comp layers, footage layers, solid

“CameraLayer object” on page 50 Represents a camera layer within a composition.

“Collection object” on page 51 Associates a set of objects or values as a logical group and provides access to them by

and help convert time values between seconds and frames.

application settings within the After Effects application.

layers, text layers, and sound layers).

index.

“CompItem object” on page 52 Represents a composition, and allows you to manipulate it and get information about it.

JavaScript Reference The After Effects Object Model

Object Description

“FileSource object” on page 60 Describes footage that comes from a file.

“FolderItem object” on page 62 Represents a folder in the Project panel.

“FootageItem object” on page 64 Represents a footage item imported into a project, which appears in the Project panel.

“FootageSource object” on page 67 Describes the file source of some footage.

“ImportOptions object” on page 73 Encapsulates options for importing files into After Effects.

“Item object” on page 76 Represents an item in a project that appears in the Project panel.

“ItemCollection object” on page 79 Collects items in a project.

“KeyframeEase object” on page 81 Encapsulates keyframe ease values in an After Effects property.

“Layer object” on page 83 A base class for layer classes.

“LayerCollection object” on page 92 Collects layers in a project.

“LightLayer object” on page 97 Represents a light layer within a composition.

“MarkerValue object” on page 98 Encapsulates marker values in an AE property.

“MaskPropertyGroup object” on page 102

“OMCollection object” on page 104 Collects output modules in a render queue.

“OutputModule object” on page 105 Represents an output module for a render queue.

“PlaceholderSource object” on page 108 Describes a placeholder for footage.

“Project object” on page 109 Represents an After Effects project.

“Property object” on page 118 Represents an After Effects property.

“PropertyBase object” on page 140 A base class for After Effects property and property group classes.

“PropertyGroup object” on page 147 Represents an After Effects property group.

“RenderQueue object” on page 152 Represents the After Effects render queue.

“RenderQueueItem object” on page 155 Represents a renderable item in a render queue.

“RenderQueueItem object” on page 155 Collects render-queue items in a render queue.

“RQItemCollection object” on page 161 Provides access to application settings and preferences.

“Shape object” on page 164 Encapsulates the outline shape information for a mask.

“ShapeLayer object” on page 167 Represents a shape layer within a composition.

“SolidSource object” on page 168 Describes a solid color that is the source of some footage.

“System object” on page 169 Provides access to the operating system from the application.

“TextDocument object” on page 171 Encapsulates the text in a text layer.

Encapsulates mask attributes in a layer.

“TextLayer object” on page 172 Represents a text layer within a composition.

JavaScript Reference Global functions

Global functions

These globally available functions that are specific to After Effects. Any JavaScript object or function can call these functions, which allow you to display text in a small (3-line) area of the Info panel, and to convert numeric time values to and from string values.

Global function Description

clearOutput()

currentFormatToTime()

timeToCurrentFormat()

write()

writeLn()

Additional global functions for standard user I/O (

Clears text from the Info panel.

Converts string time value to a numeric time value.

Converts a numeric time value to a string time value.

Writes text to the Info panel, with no line break added.

Writes text to the Info panel, adding a line break at the end.

alert, confirm, and prompt) and static functions for file

I/O, are defined by ExtendScript; for detailed reference information, see the Adobe Bridge® JavaScript

Reference.

NOTE: The After Effects global functions for standard dialogs and file I/O are still supported in this release, but are deprecated and will not be supported in future releases. For details, see the After Effects 6.5 documentation.

clearOutput() global function

clearOutput()

Description

Clears the output in the Info panel.

Parameters

None.

Returns

Nothing.

currentFormatToTime() global function

currentFormatToTime(formattedTime, fps, isDuration)

Description

Converts a formatted string for a frame time value to a number of seconds, given a specified frame rate. For example, if the formatted frame time value is 0:00:12 (the exact string format is determined by a project setting), and the frame rate is 24 fps, the time would be 0.5 seconds (12/24). If the frame rate is 30 fps, the time would be 0.4 seconds (12/30).

If the time is a duration, the frames are counted from 0. Otherwise, the frames are counted from the project’s starting frame (see “Project displayStartFrame attribute” on page 111).

Parameters

formattedTime

The frame time value, a string specifying a number of frames in the project’s current time display format.

JavaScript Reference Global functions

fps

isDuration

Returns

The frames-per-second, a floating-point value.

Optional. When true, the time is a duration (measured from frame 0). When false (the default), the time is measured from the project’s starting frame.

Floating-point value, the number of seconds.

timeToCurrentFormat() global function

timeToCurrentFormat(time, fps, isDuration)

Description

Converts a numeric time value (a number of seconds) to a frame time value; that is, a formatted string that shows which frame corresponds to that time, at the specified rate. For example, if the time is 0.5 seconds, and the frame rate is 24 fps, the frame would be 0:00:12 (when the project is set to Display Timecode). If the frame rate is 30 fps, the frame would be 0:00:15. The format of the timecode string is determined by a project setting.

If the time is a duration, the frames are counted from 0. Otherwise, the frames are counted from the project’s starting frame (see “Project displayStartFrame attribute” on page 111).

Parameters

time

fps

The number of seconds, a floating-point value.

The frames-per-second, a floating-point value.

isDuration

Returns

Optional. When true, the time is a duration (measured from frame 0). When false (the default), the time is measured from the project’s starting frame.

String in the project’s current time display format.

write() global function

write(text)

Description

Writes output to the Info panel, with no line break added.

Parameters

text

Returns

Nothing.

Example

write("This text appears in Info panel ");

write("with more on same line.");

The string to display. Truncated if too long for the Info panel.

JavaScript Reference Global functions

writeLn() global function

writeLn(text)

Description

Writes output to the Info panel and adds a line break at the end.

Parameters

text

Returns

The string to display.

Nothing.

Example

writeln("This text appears on first line");

writeln("This text appears on second line");

JavaScript Reference Application object

Application object

app

Description

Provides access to objects and application settings within the After Effects application. The single global object is always available by its name,

Attributes of the Application object provide access to specific objects within After Effects. Methods of the Application object can create a project, open an existing project, control Watch Folder mode, purge memory, and quit the After Effects application. When the After Effects application quits, it closes the open project, prompting the user to save or discard changes as necessary, and creates a project file as necessary.

Attributes

Attribute Reference Description

app.

project

language

version

buildName

buildNumber

isWatchFolder

isRenderEngine

settings

onError

exitCode

“Application project attribute” on page 28 and “Project object” on page 109

“Application language attribute” on page 24

“Application version attribute” on page 30

“Application buildName attribute” on page 21

“Application buildNumber attribute” on page 22

“Application isWatchFolder attribute” on page 24

“Application isRenderEngine attribute” on page 24

“Application settings attribute” on page 30 and “RQItemCollection object” on page 161

“Application onError attribute” on page 26

“Application exitCode attribute” on page 24

The current After Effects project.

The language in which the application is running.

The version number of the After Effects application.

The name of this build of the application.

The number of this build of the application.

When true, the local application is running in Watch Folder mode.

When true, the local After Effects application is running as a render engine.

Application settings that can be set via scripting.

A callback function that is called when an error occurs in the application.

A numeric status code used when executing a script externally (that is, from a command line or AppleScript). 0 if no error occurred. A positive number indicates an error that occurred while running the script.

exitAfterLaunchAndEval

saveProjectOnCrash

memoryInUse

“Application exitAfterLaunchAndEval attribute” on page 23

“Application saveProjectOnCrash attribute” on page 28

“Application memoryInUse attribute” on page 25

When true, the application remains open after running a script from the command line on Windows.

When true, the project is saved if the application closes unexpectedly.

Memory in use by this application.

JavaScript Reference Application object

Methods

Method Reference Description

newProject()

open()

quit()

watchFolder()

pauseWatchFolder()

endWatchFolder()

purge()

beginUndoGroup()

endUndoGroup()

beginSuppressDialogs()

endSuppressDialogs()

setMemoryUsageLimits()

“Application newProject() method” on page 25

“Application open() method” on page 26 Opens a project or an Open Project dialog box.

“Application quit() method” on page 28 Quits the application.

“Application watchFolder() method” on page 30

“Application pauseWatchFolder() method” on page 27

“Application endWatchFolder() method” on page 23

“Application purge() method” on page 28 Purges a targeted type of cached information

“Application beginUndoGroup() method” on page 21

“Application endUndoGroup() method” on page 22

“Application beginSuppressDialogs() method” on page 21

“Application endSuppressDialogs() method” on page 22

“Application setMemoryUsageLimits() method” on page 29

Creates a new project in After Effects.

Starts Watch Folder mode; does not return until Watch Folder mode is turned off.

Pauses a current watch-folder process.

Ends a current watch-folder process.

(replicates Purge options in the Edit menu).

Groups the actions that follow it into a single undoable step.

Ends an undo group; needed only when a script contains more than one undo group.

Begins suppression of dialogs in the user interface.

Ends suppression of dialogs in the user interface.

Sets memory usage limits as in the Memory & Cache preferences area.

setSavePreferencesOnQuit()

activate()

scheduleTask()

cancelTask()

parseSwatchFile()

“Application setSavePreferencesOnQuit() method” on page 29

“Application activate() method” on page 20 Brings the After Effects main window to the

“Application scheduleTask() method” on page 29

“Application cancelTask() method” on page 22

“Application parseSwatchFile() method” on page 27

Sets whether preferences are saved when the application is quit.

front of the screen.

Schedules a JavaScript script for delayed execution.

Cancels a scheduled task.

Loads a color swatch from an Adobe Swatch Exchange (ASE) file.

Application activate() method

app.activate()

Description

Opens the application main window if it is minimized or iconified, and brings it to the front of the desktop.

Parameters

None.

JavaScript Reference Application object

Returns

Nothing.

Application beginSuppressDialogs() method

app.beginSuppressDialogs()

Description

Begins suppression of script error dialog boxes in the user interface. Use endSuppressDialogs() to resume the display of error dialogs. See “Application endSuppressDialogs() method” on page 22.

Parameters

None.

Returns

Nothing.

Application beginUndoGroup() method

app.beginUndoGroup(undoString)

Description

Marks the beginning of an undo group, which allows a script to logically group all of its actions as a single undoable action (for use with the Edit > Undo/Redo menu items). Use the

endUndoGroup() method to mark

the end of the group. (See “Application endUndoGroup() method” on page 22.)

beginUndoGroup() and endUndoGroup() pairs can be nested. Groups within groups become part of the

larger group, and will undo correctly. In this case, the names of inner groups are ignored.

Parameters

undoString

Returns

The text that will appear for the Undo command in the Edit menu (that is, “Undo <undoString>”)

Nothing.

Application buildName attribute

app.buildName

Description

The name of the build of After Effects being run, used internally by Adobe for testing and troubleshooting.

Type

String; read-only.

JavaScript Reference Application object

Application buildNumber attribute

app.buildNumber

Description

The number of the build of After Effects being run, used internally by Adobe for testing and troubleshooting.

Type

Integer; read-only.

Application cancelTask() method

app.cancelTask(taskID)

Description

Removes the specified task from the queue of tasks scheduled for delayed execution.

Parameters

taskID

Returns

An integer that identifies the task, as returned by app.scheduleTask().

Nothing.

Application endSuppressDialogs() method

app.endSuppressDialogs(alert)

Description

Ends the suppression of script error dialog boxes in the user interface. Error dialogs are displayed by default; call this method only if

beginSuppressDialogs() has previously been called. See “Application beginSuppress-

Dialogs() method” on page 21.

Parameters

alert

Returns

Boolean; when true, errors that have occurred following the call to beginSuppressDialogs() are displayed in a dialog box.

Nothing.

Application endUndoGroup() method

app.endUndoGroup()

Description

Marks the end of an undo group begun with the app.beginUndoGroup() method. You can use this method to place an end to an undo group in the middle of a script, should you wish to use more than one undo group for a single script.

If you are using only a single undo group for a given script, you do not need to use this method; in its absence at the end of a script, the system will close the undo group automatically.

JavaScript Reference Application object

Calling this method without having set a beginUndoGroup() method yields an error.

Parameters

None.

Returns

Nothing.

Application endWatchFolder() method

app.endWatchFolder()

Description

Ends Watch Folder mode.

Parameters

None

Returns

Nothing.

Application exitAfterLaunchAndEval attribute

app.exitAfterLaunchAndEval

Description

This attribute is used only when executing a script from a command line on Windows. When the application is launched from the command line, the (from a file or from a string, respectively).

If this attribute is set to true, After Effects will exit after the script is run; if it is false, the application will remain open.

This attribute only has an effect when After Effects is run from the Windows command line. It has no effect in Mac OS.

Type

Boolean; read/write.

–r or –s command line flag causes the application to run a script

JavaScript Reference Application object

Application exitCode attribute

app.exitCode

Description

A numeric status code used when executing a script externally (that is, from a command line or AppleScript).

• In Windows, the value is returned on the command line when After Effects was launched on the commands

line (using the

• in Mac OS, the value is returned as the AppleScript DoScript result for each script.

In both Mac OS and Windows, the value is set to 0 ( ation. In the event of an error while the script is running, the script can set this to a positive integer that indicates what error occurred.

Type

Integer; read/write.

Example

app.exitCode = 2; //on quit, if value is 2, an error has occurred

afterfx or afterfx –m command), and a script was specified with the –r or –s option.

EXIT_SUCCESS) at the beginning of each script evalu-

Application isRenderEngine attribute

app.isRenderEngine

Description

True if After Effects is running as a render engine.

Type

Boolean; read-only.

Application isWatchFolder attribute

app.isWatchFolder

Description

True if the Watch Folder dialog box is currently displayed and the application is currently watching a folder for rendering.

Type

Boolean; read-only.

Application language attribute

app.language

Description

The language After Effects is running.

Type

A Language enumerated value; read-only. One of:

JavaScript Reference Application object

Language.ENGLISH

Language.FRENCH

Language.GERMAN

Language.ITALIAN

Language.JAPANESE

Language.SPANISH

Example

var lang = app.language;

if (lang == Language.ENGLISH)

alert("After Effects is running in English.");

else if (lang == Language.FRENCH)

alert("After Effects is running in French.");

else

alert("After Effects is not running in English or French.");

Application memoryInUse attribute

app.memoryInUse

Description

The number of bytes of memory currently used by this application.

Type

Number; read-only.

Application newProject() method

app.newProject()

Description

Creates a new project in After Effects, replicating the File > New > New Project menu command.

If the current project has been edited, the user is prompted to save it. If the user cancels out of the Save dialog box, the new project is not created and the method returns null. Use

tions.DO_NOT_SAVE_CHANGES)

to close the current project before opening a new one. See “Project

close() method” on page 111.

Parameters

None.

Returns

A new Project object, or null if no new project is created.

app.project.close(CloseOp-

Example

app.project.close(CloseOptions.DO_NOT_SAVE_CHANGES);

app.newProject();

JavaScript Reference Application object

Application onError attribute

app.onError

Description

The name of a callback function that is called when an error occurs. By creating a function and assigning it to this attribute, you can respond to errors systematically; for example, you can close and restart the application, noting the error in a log file if it occurred during rendering. See “RenderQueue render() method” on page 153.

The callback function is passed the error string and a severity string. It should not return any value.

Type

A function name string, or null if no function is assigned; read/write.

Example

function err(errString) {

alert(errString);

}

app.onError = err;

Application open() method

app.open()

app.open(file)

Description

Opens a project.

Parameters

file

Returns

A new Project object for the specified project, or null if the user cancels the Open dialog box.

Example

var my_file = new File("../my_folder/my_test.aep");

if (my_file.exists){

new_project = app.open(my_file);

if (new_project){

alert(new_project.file.name);

}

Optional. An ExtendScript File object for the project file to open. If not supplied, the method prompts the user to select a project file.

JavaScript Reference Application object

Application parseSwatchFile() method

app.parseSwatchFile(file)

Description

Loads color swatch data from an Adobe Swatch Exchange (ASE) file.

Parameters

file

Returns

The file specification, an ExtendScript File object.

The swatch data, in this format:

data.majorVersion

data.minorVersion

data.values

SwatchValue.type

SwatchValue.r

SwatchValue.g

SwatchValue.b

SwatchValue.c

SwatchValue.m

SwatchValue.y

SwatchValue.k

SwatchValue.L

SwatchValue.a

SwatchValue.b

SwatchValue.value

The ASE version number.

An array of SwatchValue.

One of "RGB", "CMYK", "LAB", "Gray"

When type = "RGB", the color values in the range [0.0..1.0].

0, 0, 0 is Black.

When type = "CMYK", the color values in the range [0.0..1.0].

0, 0, 0, 0 is White.

When type = "LAB", the color values.

L is in the range [0.0..1.0]. a and b are in the range [-128.0..+128.0]

0, 0, 0 is Black.

When type = "Gray", the value range is [0.0..1.0].

0.0 is Black.

Application pauseWatchFolder() method

app.pauseWatchFolder(pause)

Description

Pauses or resumes the search of the target watch folder for items to render.

Parameters

pause

Returns

Nothing.

True to pause, false to resume.

JavaScript Reference Application object

Application project attribute

app.project

Description

The project that is currently loaded. See “Project object” on page 109.

Type

Project object; read-only.

Application purge() method

app.purge(target)

Description

Purges unused data of the specified types from memory. Replicates the Purge options in the Edit menu.

Parameters

target

The type of elements to purge from memory; a PurgeTarget enumerated value, one of:

• PurgeTarget.ALL_CACHES: Purges all data that After Effects has cached to physical memory.

• PurgeTarget.UNDO_CACHES: Purges all data saved in the undo cache.

• PurgeTarget.SNAPSHOT_CACHES: Purges all data cached as comp/layer snapshots.

• PurgeTarget.IMAGE_CACHES: Purges all saved image data.

Returns

Nothing.

Application quit() method

app.quit()

Description

Quits the After Effects application.

Parameters

None.

Returns

Nothing.

Application saveProjectOnCrash attribute

app.saveProjectOnCrash

JavaScript Reference Application object

Description

When true (the default), After Effects attempts to display a dialog box that allows you to save the current project if an error causes the application to quit unexpectedly. Set to false to suppress this dialog box and quit without saving.

Type

Boolean; read/write.

Application scheduleTask() method

app.scheduleTask(stringToExecute, delay, repeat)

Description

Schedules the specified JavaScript for delayed execution.

Parameters

stringToExecute

delay

repeat

Returns

A string containing JavaScript to be executed.

A number of milliseconds to wait before executing the JavaScript. A floating-point value.

When true, execute the script repeatedly, with the specified delay between each execution. When false the script is executed only once.

Integer, a unique identifier for this task, which can be used to cancel it with app.cancelTask().

Application setMemoryUsageLimits() method

app.setMemoryUsageLimits(imageCachePercentage, maximumMemoryPercentage)

Description

Sets memory usage limits as in the Memory & Cache preferences area. For both values, if installed RAM is less than a given amount (n gigabytes), the value is a percentage of the installed RAM, and is otherwise a percentage of n. The value of n is: 2 Gb for Win32, 4 Gb for Win64, 3.5 Gb for Mac OS.

Parameters

imageCachePercentage

maximumMemoryPercentage

Returns

Nothing.

Floating-point value, the percentage of memory assigned to image cache.

Floating-point value, the maximum usable percentage of memory.

Application setSavePreferencesOnQuit() method

app.setSavePreferencesOnQuit(doSave)

Description

Set or clears the flag that determines whether preferences are saved when the application is closed.

JavaScript Reference Application object

Parameters

doSave

Returns

When true, preferences saved on quit, when false they are not.

Nothing.

Application settings attribute

app.settings

Description

The currently loaded settings. See “Settings object” on page 162.

Type

Settings object; read-only.

Application version attribute

app.version

Description

An alphanumeric string indicating which version of After Effects is running.

Type

String; read-only.

Example

var ver = app.version;

alert("This machine is running version " + ver + " of After Effects.");

Application watchFolder() method

app.watchFolder(folder_object_to_watch)

Description

Starts a Watch Folder (network rendering) process pointed at a specified folder.

Parameters

folder_object_to_watch

Returns

Nothing.

Example

var theFolder = new Folder(“c:/tool”);

app.watchFolder(theFolder);

The ExtendScript Folder object for the folder to watch.

+ 163 hidden pages