After Effects scripting referenceThe After Effects Object Model
11
Table3
Operator Precedence
Associativityleft to rightright to leftleft to rightleft to rightleft to rightleft to rightleft to rightleft to rightleft to rightleft to rightleft to rightleft to rightright to leftright to leftleft to right
Operators (highest precedence to lowest)
[], (), .
new, delete, – (unary negation), !, typeof, void, ++, ––*, /, %
+, – (subtraction)<<, >>, >>><, <=, >, >===, !=&^|&&||?:
=, /=, %=, <<=, >>=, >>>=, &=, ^=, |=, +=, –=, *=,
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 correspon-dence to the user interface.
APPLICATIONSYSTEMFILEFOLDERSOCKETSETTINGSPROJECTCOMP)TEMITEM??S????MAY??BE??ANY??OF??THE??FOLLOWING??????TYPES??OF??ITEM??/2FOOTAGE)TEM/2FOLDER)TEMRENDER1UEUEITEM??S??LAYER??S??ITEM??S??PROXY3OURCEPROPERTIESMAIN3OURCEPROXY3OURCERENDER1UEUE)TEM??S??MAIN3OURCE??????PROXY3OURCE??MAY??BE??ANY??OF??THE??FOLLOWING??????TYPES??OF??ITEM??SOLID3OURCE/2PLACEHOLDER3OURCE/2FILE3OURCEOUTPUT-ODULE??S??COLORFILEHierarchy diagram of the main After Effects scripting objects11
After Effects scripting referenceThe After Effects Object Model
12
Note that the File, Folder, and Socket objects are defined by ExtendScript, and are documented in the JavaS-cript 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.
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 repre-sented 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
“Global functions” on page14“Application object” on page17“AVItem object” on page30“AVLayer object” on page38“CameraLayer object” on page50“Collection object” on page51“CompItem object” on page52
Description
Globally available functions that allow you to display text for script debugging purposes, and help convert time values between seconds and frames.
A single global object, available by its name (app), that provides access to objects and application settings within the After Effects application. Represents audio/visual files imported into After Effects.
Represents those layers that contain AVItem objects (composition layers, footage layers, solid layers, text layers, and sound layers).Represents a camera layer within a composition.
Associates a set of objects or values as a logical group and provides access to them by index.
Represents a composition, and allows you to manipulate it and get information about it.
12
After Effects scripting referenceThe After Effects Object Model
13
Object
“FileSource object” on page61“FolderItem object” on page63“FootageItem object” on page65“FootageSource object” on page69“ImportOptions object” on page75“Item object” on page78
“ItemCollection object” on page82“KeyframeEase object” on page84“Layer object” on page86
“LayerCollection object” on page95“LightLayer object” on page100“MarkerValue object” on page102“MaskPropertyGroup object” on page106
“OMCollection object” on page109“OutputModule object” on page110
Description
Describes footage that comes from a file.Represents a folder in the Project panel.
Represents a footage item imported into a project, which appears in the Project panel. Describes the file source of some footage.
Encapsulates options for importing files into After Effects.Represents an item in a project that appears in the Project panel. Collects items in a project.
Encapsulates keyframe ease values in an After Effects property.A base class for layer classes.Collects layers in a project.
Represents a light layer within a composition.
Encapsulates marker values in an After Effects property.Encapsulates mask attributes in a layer.Collects output modules in a render queue.Represents an output module for a render queue.
“PlaceholderSource object” on page113Describes a placeholder for footage.“Project object” on page114“Property object” on page124“PropertyBase object” on page148“PropertyGroup object” on page155“RenderQueue object” on page160“RenderQueueItem object” on page163“RenderQueueItem object” on page163“RQItemCollection object” on page169“Shape object” on page172“ShapeLayer object” on page178“SolidSource object” on page179“System object” on page180“TextDocument object” on page182“TextLayer object” on page188“Viewer object” on page189
Represents an After Effects project.Represents an After Effects property.
A base class for After Effects property and property group classes.Represents an After Effects property group.Represents the After Effects render queue.Represents a renderable item in a render queue.Collects render-queue items in a render queue.Provides access to application settings and preferences.Encapsulates the outline shape information for a mask.Represents a shape layer within a composition.
Describes a solid color that is the source of some footage.Provides access to the operating system from the application.Encapsulates the text in a text layer.Represents a text layer within a composition.Represents a Composition, Layer, or Footage panel.
13
After Effects scripting referenceGlobal functions
14
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
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.When true, the specified object exists.
clearOutput()
currentFormatToTime()timeToCurrentFormat()write()writeLn()isValid()
Additional global functions for standard user I/O (alert, confirm, and prompt) and static functions for fileI/O, are defined by ExtendScript; for detailed reference information, see the JavaScript Tools Guide (available from the ExtendScript Toolkit’s Help menu).
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 page117).
ParametersformattedTimefps
The frame time value, a string specifying a number of frames in the project’s current time display format.The frames-per-second, a floating-point value.
14
After Effects scripting referenceGlobal functions
15
isDuration
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.
Returns
Floating-point value, the number of seconds.
isValid() global function
isValid(obj)Description
Determines if the specified After Effects object (e.g., composition, layer, mask, etc.) still exists. Some opera-tions, such as the PropertyBase moveTo() method, might invalidate existing variable assignments to related objects. This function allows you to test whether those assignments are still valid before attempting to access them.
ParametersobjReturns
The After Effects object to check for validity.
Boolean.
Example
var layer = app.project.activeItem.layer(1);// assume layer has three masksalert(isValid(layer));// displays “true”var mask1 = layer.mask(1);var mask2 = layer.mask(2);var mask3 = layer.mask(3);
mask3.moveTo(1);// move the third mask to the top of the mask stackalert(isValid(mask1));// displays “false”; mask2 and mask3 do as well
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 as 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 page117).
Parameterstimefps
The number of seconds, a floating-point value.The frames-per-second, a floating-point value.
15