Macromedia After Effects - 6.5 Instruction Manual

2

3

2

3

Help Using Help

Using Help Back 1

Using Help

About Help

Adobe Systems Incorporated provides complete documentation in an Adobe PDF-based
help system. This help system includes information on all tools, commands, and features
of an application. It is designed for easy on-screen navigation and can also be printed and
used as a desktop reference. Additionally, it supports third-party screen-reader applica­tions that run in a Windows environment.

Navigating in Help

Help opens in an Adobe Acrobat window with the Bookmarks pane open. (If the
Bookmarks pane is not open, click the Bookmarks tab at the left edge of the window.) At
the top and bottom of each page is a navigation bar containing links to this page (Using
Help), the table of contents (Contents), and the index (Index).

To move through pages sequentially, you can click the Next Page and the Previous
Page arrows; click the navigation arrows at the bottom of the page; or click Back to
return to the last page you viewed.

You can navigate Help topics by using bookmarks, the table of contents, the index, or the
Search (Acrobat 6) or Find (Acrobat 5) command.

To find a topic using bookmarks:

I

1

n the Bookmarks pane, click the plus sign (+) (Windows) or the right-facing arrow (Mac

OS) next to a bookmark topic to view its subtopics.

2

lick the bookmark to go to that topic.

C

To find a topic using the table of contents:

1

C

lick Contents in the navigation bar.

On the Contents page, click a topic to go to that topic.

To view a list of subtopics, click the plus sign (+) (Windows) or the right-facing arrow

(Mac OS) next to the topic name in the Bookmarks pane.

To find a topic using the index:

D

1

o one of the following:

Click Index in the navigation bar, and then click a letter at the top of the page.

•

Ι

•

n the Bookmarks pane, expand the Index bookmark to view the letter subtopics; then

click a letter.

Locate the entry you want to view, and click the page number to go to that topic.

To view other entries for the same topic, click Back to return to the same place in the

index, and then click another page number.

U

sing Help Back 1

2

2

Help Using Help

U

sing Help Back 2

To find a topic using the Search command (Acrobat 6):

1 Choose Edit > Search.

Type a word or phrase in the text box and click Search. Acrobat searches the document
and displays every occurrence of the word or phrase in the Results area of the Search PDF
pane.

To find a topic using the Find command (Acrobat 5):

1 Choose Edit > Find.

Type a word or phrase in the text box and click Find. Acrobat searches the document,
starting from the current page, and displays the first occurrence.

3

To find the next occurrence, choose Edit > Find Again.

Printing Help

Although Help is optimized for on-screen viewing, you can print selected pages or the
entire file.

To print Help:

Choose File > Print, or click the Print icon in the Acrobat toolbar.

U

sing Help Back 2

Help Overview

Using Help Back 3

Overview

The Adobe After Effects 6.5 Render Automation & Scripting Guide demonstrates how to take procedural control
of your After Effects projects via scripting. This feature set is available only in Adobe After Effects 6.5 Profes­sional 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 know nothing about scripting

After Effects 6.5 is a visual tool with a graphical user interface; you are used to interacting with it via interface
elements such as menus, palettes 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. 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).

Scripting is designed to help users of After Effects get past these types of obstacles, and it is available even to
users who have no inclination to learn the JavaScript language. If you are this type of user, you can still harness
the power of scripting via third party solutions such as Rush 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.adobe­forums.com.

After Effects objects

You may not think of After Effects as a collection of hierarchical objects, but when you make use of render
queue items, compositions, and projects, that is how they appear in scripting. Just as the expressions features
in After Effects give you access to virtually any property of any layer inside any composition of your project
(each of which we refer to as an object), scripting gives you access to the hierarchy of objects within After
Effects and allows you to make changes to these objects.

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.

Expressions and motion math

Because scripting can access individual layer properties, and because it utilizes JavaScript, one might assume
that expressions and scripting are one and the same. However, they are two entirely distinct entities. Expres­sions have no ability to access information from scripts (such as variables and functions), although a script
can be written to create or edit an expression.

The similarity between expressions and scripting is, however, apparent in that they are both drawn from the
same language, ECMA standard JavaScript. Thus, knowing how to utilize one is helpful in understanding the
other.

U

sing Help Back 3

Help Overview

U

sing Help Back 4

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 a bouncing ball by applying mathe­matical 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.

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.

Although this guide is intended to provide an understanding of the extensions that have been added to the
ECMAScript/JavaScript language for scripting of After Effects projects, 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 on the Mac and DOS shell scripts on Windows systems) and a background in
how to work with JavaScript.

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.

Note that 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 or
transform within an individual layer).

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.

By selecting this box, you enable the following:

Writing files

•

Creating folders

•

Setting the current folder

•

•

Creating a socket

•

Opening a socket

•

Listening to a socket

The JavaScript Debugger is disabled by default so that casual users do not encounter it. When editing or
writing scripts, the JavaScript Debugger can help you diagnose script problems more quickly.

To activate the JavaScript Debugger on the local machine when a script error is encountered, choose Prefer­ences > General, and select Enable JavaScript Debugger.

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

U

sing Help Back 4

Help Overview

U

sing Help Back 5

For detailed information on the JavaScript Debugger, see “JavaScript Debugging” on page 15.

Accessing and writing scripts

To create and edit scripts for After Effects, use 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 appli­cation folder. For details on writing and editing scripts, see “Writing Scripts” on page 6.

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

Uses of After Effects scripting

One primary use for scripting in After Effects 6.5 is render automation. Anyone charged with managing a
complex rendering pipeline will be interested in this. Render automation can be accomplished either by hand­coding scripts or via a third-party network rendering solution that supports automated management of
network rendering pipelines.

There are other uses for scripting; it can be a shortcut around tedious tasks that would otherwise involve
repetitious pointing and clicking.

See “Examples” on page 179 for examples of what scripts can do.

U

sing Help Back 5

Help Writing Scripts

Using Help Back 6

Writing Scripts

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.

The heart of a scriptable application is the object model. In After Effects, the object model is composed of
projects, 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. For more resources for
learning scripting, see “More resources to learn scripting” on page 8.

Editing scripts

After Effects 6.5 does not include a script editor. 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]).

The .jsx format

After Effects scripts must include the .jsx file extension in order to be properly recognized by the application.
This extension is a variation on the standard “.js” extension used with normal JavaScript files; any UTF-8
encoded text file with this extension will be recognized.

The Scripts menu and Scripts folder

After Effects scripts reside in the Scripts folder, within the same folder as your After Effects 6.5 application file.
Only scripts contained in this Scripts folder 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 > Run Script > Choose File, and choose
the script in the Open dialog box. Alternatively, you can send After Effects a script 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 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.

U

sing Help Back 6

Help Writing Scripts

U

sing Help Back 7

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 succeeding scripts during a given After Effects session. Once the application is quit, all such
globally defined variables and functions are cleared.

Please note that this persistence of global settings also means that if you are not careful about giving variables
in scripts unique names, you can inadvertently reassign global variables intended to persist throughout a
session.

Properties can also be embedded in existing objects such as the Application object (see “Application object”
on page 26) 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.

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
send a script directly to the open After Effects application, which then runs automatically.

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

Following are examples of DOS shell scripts 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 would copy and paste your After Effects script directly into the command line script
and then run it, as follows (your script text would appear in quotation marks following the afterfx.exe -s
command):

afterfx.exe –s “alert (“You just sent an alert to After Effects”)”

Alternatively, you could specify the location of the .jsx file to be executed, as follows:

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

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

Following are three examples of AppleScripts 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 AppleScript and then run it, as follows
(your script text would appear in quotation marks following the DoScript command):

tell application “Adobe After Effects 6.5”

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 6.5”

DoScript thefile

end tell

U

sing Help Back 7

Help Writing Scripts

U

sing Help Back 8

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 6.5"

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.

Additionally, After Effects includes a JavaScript debugger. For more information on activating and using the
debugger, see “JavaScript Debugging” on page 15.

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, please refer to Ecma-

262.pdf, available at www.ecma-international.org/publications/standards/ECMA-262.HTM.

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
Flanagan. Another very readable source is
these texts contain information that pertains only to extensions of JavaScript for Internet browsers; however,
they also contain thorough descriptions of scripting fundamentals.

JavaScript: A Beginner’s Guide (Osborne) by John Pollock. Both of

JavaScript, The Definitive Guide (O’Reilly) by David

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.

U

sing Help Back 8

Help Writing Scripts

U

sing Help Back 9

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

do - while

false

for

for - in

function

if/if - else

new

null

return

switch

this

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

Standard JavaScript construct. Similar to the
at the end of the loop.

Literal representing boolean false.

Standard JavaScript loop construct.

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

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 an expression and attempting to match the expression's
value to a

Standard JavaScript method of indicating the current object.

case

label.

while

loop, except loop condition evaluation occurs

true

undefined

var

while

with

Literal representing boolean true.

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
occurs at the beginning of the loop.

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

do - while

loop, except loop condition evaluation

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

U

sing Help Back 9

Allocate object.

.

[]

()

++

--

-

~

!

*

/

%

+

<<

>>

<

<=

>

>=

==

Help Writing Scripts

U

sing Help Back 10

Operators Description

!=

&

^

|

&&

||

?:

=

+=

-=

*=

delete

typeof

void

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.

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.

U

sing Help Back 10

Help Writing Scripts

U

sing Help Back 11

Operators Description

Assignment with divide operation.

Assignment with modulo operation.

/=

%=

<<=

>>=

>>>=

&=

^=

|=

,

Assignment with bitwise left shift operation.

Assignment with bitwise right shift operation.

Assignment with bitwise right shift unsigned operation.

Assignment with bitwise AND operation.

Assignment with bitwise XOR operation.

Assignment with bitwise OR operation.

Multiple evaluation.

Table 3 Operator Precedence

Operators (Listed from highest precedence —top row—to lowest) Associativity

[], (), .

new, delete, -(unary negation), ~, !, typeof, void,++, --

*, /, %

+, -(subtraction)

<<, >>, >>>

<, <=, >, >=

==, !=

left to right

right to left

left to right

left to right

left to right

left to right

left to right

&

^

|

&&

||

?:

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

,

left to right

left to right

left to right

left to right

left to right

right to left

right to left

left to right

Render automation with aerender

One primary use for scripting in After Effects 6.5 is render automation. Anyone charged with managing a
complex rendering pipeline will be interested in this. Render automation can be accomplished either by hand­coding scripts or via a third-party network rendering solution that supports automated management of
network rendering pipelines.

Note: There are other uses for scripting; it can be a shortcut around tedious tasks that would otherwise involve

repetitious pointing and clicking. See “Examples” on page 179 for examples of what scripts can do.

U

sing Help Back 11

Help Writing Scripts

Using Help Back 12

Usage

The command-line application aerender renders After Effects compositions. The render may be performed
either by an already running instance of After Effects or by a newly invoked instance. By default, aerender will
invoke a new instance of After Effects, even if one is already running. To change this, see the "-reuse" flag in
the following “Arguments” below.

Arguments

From the command line aerender takes a series of optional arguments that are added following the executable
command (i.e. aerender.exe). Some are single flags, like "-reuse". Some come in flag-argument pairs, like "­project project_path". And one comes in a triplet, -mem_usage image_cache_percent max_mem_percent.

With 0 arguments, or with any argument equaling "-help", aerender prints a usage message with the infor­mation contained in this section.

Argument Usage

-help

-reuse

-project project_path

-comp comp_name

print usage message

Use this flag if you want to try and reuse an already running instance
of After Effects to perform the render. By default, aerender launches
a new instance of After Effects, even if one is already running. But,
if After Effects is already running, and the

-reuse flag is provided,

aerender asks the already running instance of After Effects to
perform the render. Whenever aerender launches a new instance of
After Effects, it tells After Effects to quit when rendering is
completed; otherwise, it doesn’t quit After Effects. Also, the prefer­ences are written to file upon quitting when the

-reuse flag is

specified; otherwise it isn’t written.

where project_path is a file path or URI specifying a project file to
open. If none is provided, aerender will work with the currently
open project. If no project is open and no project is provided, an
error will result.

where comp_name specifies a comp to be rendered.

If the comp is in the render queue already, and in a queueable state,
then (only) the first queueable instance of that comp on the render­queue is rendered.

If the comp is in the project but not in the render queue, then it is
added to the render queue and rendered.

-comp argument is provided, aerender renders the entire

If no
render queue as is. In this case (no -comp), the only other
arguments used are

the -RStemplate, -OMtemplate, -output, -s, -e, and arguments

-project, -log, -v, -mem_usage, and -close;

are ignored.

Using Help Back 12

Help Writing Scripts

Using Help Back 13

Argument Usage

-RStemplate

render_settings_template

-OMtemplate

output_module_template

-output output_path

-log logfile_path

-s start_frame

-e end_frame

-i increment

where render_settings_template is the name of a template to apply
to the render queue item.

If the template does not exist, it is an error. Default is to use the
render template already defined for the item.

where output_module_template is the name of a template to apply
to the output module. If the template does not exist, it is an error.
Default is to use the template already defined for the output
module.

where output_path is a file path or URI specifying the destination
render file. Default is the path already in the project file.

where logfile_path is a file path or URI specifying the location of
the log file. Default is

stdout.

where start_frame is the first frame to render. Default is the start
frame in the file.

where end_frame is the last frame to render. Note, this is "inclusive;"
the final frame is rendered. Default is the end frame in the file.

where increment is the number of frames to advance before
rendering a new frame. A value of 1 (the default) results in a normal
rendering of all frames. Higher increments will repeat the same
(frame increment-1) times and then render a new one, starting the
cycle again. Higher values result in faster renders but choppier
motion. Default is 1.

-mem_usage

image_cache_percent

max_mem_percent

-v verbose_flag

-close close_flag

where image_cache_percent specifies the maximum percent of
memory used to cache already rendered images/footage, and

max_mem_percent specifies the total percent of memory that can

be used by After Effects.

where verbose_flag specifies the type of messages reported.
Possible values are

ERRORS_AND_PROGRESS (prints progress of rendering as

or
well). Default value is

ERRORS (prints only fatal and problem errors)

ERRORS_AND_PROGRESS.

where close_flag specifies whether or not toclose the project when
done rendering, and whether or not to save changes.

close_flag is DO_NOT_SAVE_CHANGES, the project is closed

If
without saving changes.

close_flag is SAVE_CHANGES, project is closed and changes are

If
saved. If

close_flag is DO_NOT_CLOSE the project is left open; but

the project is left open only if using an already-running instance of
After Effects, since new invocations of After Effects must always
close and quit when done. Default value is

DO_NOT_SAVE_CHANGES.

Using Help Back 13

Help Writing Scripts

Using Help Back 14

Argument Usage

-sound sound_flag

-version

where sound_flag specifies whether or not to play a sound when
rendering is complete. Possible values are

OFF.

is

ON or OFF. Default value

Displays the version number of aerender to the console. Does not
render.

Examples

To render just Comp 1 to a specified file, enter:

aerender -project c:\projects\proj1.aep -comp "Comp 1" -output c:\output\proj1\proj1.avi

To render everything in the render queue as is in the project file, enter:

aerender -project c:\projects\proj1.aep

To render frames 1-10 using multi-machine render, enter:

aerender -project c:\projects\proj1.aep -comp "Comp 1" -s 1 -e 10

-RStemplate "Multi-Machine Settings"

-OMtemplate "Multi-Machine Sequence"

-output c:\output\proj1\frames[####].psd

Using Help Back 14

Help JavaScript Debugging

K

Using Help Back 15

JavaScript Debugging

This section describes the JavaScript Debugger, which appears when the Enable JavaScript Debugger
preference is selected in General Preferences (it is deselected by default) and there is an error when executing
a script.

BACDEFGH

I

J

JavaScript Debugger window

A. Stack trace view B. Resume C. Pause D. Stop E. Step over F. Step into
G. Step out H. Breakpoints display I. Command line J. Debug output view
K. JavaScript source view

The current stack trace appears in the upper-left pane of the JavaScript Debugger window. This Stack Trace
view displays the calling hierarchy at the time of the breakpoint. Double-clicking a line in this view changes
the current scope, enabling you to inspect and modify scope-specific data.

All debugging output appears in the upper-right pane of the JavaScript Debugger window. Specifically, output
from the print method of the $ object appears in this Debug Output view.

The currently executing JavaScript source appears in the lower pane of the JavaScript Debugger window.
Double-clicking a line in this JavaScript Source view sets or clears an unconditional breakpoint on that line.
That is, if a breakpoint is in effect for that line, double-clicking it clears the breakpoint, and vice-versa. The
line number display on the left part displays a red dot for all lines with a breakpoint.

Using Help Back 15

Help JavaScript Debugging

Using Help Back 16

If Enable JavaScript Debugger is deselected in General Preferences, you see an error message but not the
JavaScript Debugger itself. This is the typical setup used in situations in which professional roles are divided
between those writing and administering scripts (technical directors, system administrators, and so on) and
those using them (the artist or animators). If you are writing and debugging your own scripts, you will want
to enable the JavaScript Debugger.

Controlling code execution in the JavaScript Debugger

This section describes the buttons that control the execution of code when the JavaScript Debugger window
is active. Most of these buttons also provide a keyboard shortcut.

Resume
Ctrl+R (Windows)
Command+R (Mac OS)

Resume execution of the script with the JavaScript Debugger window open. When the script terminates, the application closes the Jav­aScript Debugger window automatically. Closing the window manually also causes script execution to resume. This button is enabled
when script execution is paused or stopped.

Pause
Ctrl+P (Windows)
Command+P (Mac OS)

Halt the currently executing script temporarily and reactivate the JavaScript Debugger. This button is enabled when a script is running.
,,Ray, funnyy wrapping on this line . . . -cj>>

Stop
Ctrl+K (Windows)
Command+K (Mac OS)

Stop execution of the script and generate a runtime error. This button is enabled when a script is running.

Step Over
Ctrl+S (Windows)
Command+S (Mac OS)

Halt after executing a single JavaScript statement in the script; if the statement calls a JavaScript function, execute the function in its
entirety before stopping.

Step Into
Ctrl+T (Windows)
Command+T (Mac OS)

Halt after executing a single JavaScript statement in the script or after executing a single statement in any JavaScript function that the
script calls.

Using Help Back 16

Help JavaScript Debugging

Using Help Back 17

Step Out
Ctrl+U (Windows)
Command+U (Mac OS)

When the JavaScript Debugger is paused within the body of a JavaScript function, resume script execution until the function returns.
When the JavaScript Debugger is paused outside the body of a function, resume script execution until the script terminates.

Script Breakpoints Display

Display the Script Breakpoints window.

Using the JavaScript command line entry field

You can use the JavaScript Debugger’s command line entry field to enter and execute JavaScript code interac­tively within a specified stack scope. Commands entered in this field execute with a time-out of one second. If
a command takes longer than one second to execute, the script terminates and generates a time-out error.

Command line entry field

Enter in this field a JavaScript statement to execute within the stack scope of the line highlighted in the Stack
Trace view. When you’ve finished entering the JavaScript expression, you can execute it by clicking the
Command Line Entry button or pressing the Enter key. Click the button next to the field, or press Enter to
execute the JavaScript code in the command line entry field. The application executes the contents of the
command line entry field within the stack scope of the line highlighted in the Stack Trace view.

The command line entry field accepts any JavaScript code, making it very convenient to use for inspecting or
changing the contents of variables.

Note: To list the contents of an object as if it were JavaScript source code, enter the object.toSource() command.

Setting breakpoints

You can set breakpoints in the JavaScript Debugger itself, by calling methods of the $ object, or by defining
them in your JavaScript code.

Setting breakpoints in the JavaScript Debugger

When the JavaScript Debugger window is active, you can double-click a line in the JavaScript Source view to
set or clear a breakpoint at that line. Alternatively, you can click the Script Breakpoints Display button to
display the Script Breakpoints window and set or clear breakpoints in this window as described in “Script
Breakpoints window” on page 18.

Setting breakpoints in JavaScript code

Adding the debugger statement to a script sets an unconditional breakpoint. For example, the following code
causes the script to halt and display the JavaScript Debugger as soon as it enters the setupBox function.

function setupBox(box) {

// break unconditionally at the next line

debugger;

Using Help Back 17

Help JavaScript Debugging

Using Help Back 18

box.width = 48;

box.height = 48;

box.url = "none";

}

To execute a breakpoint in runtime code, call the $.bp() method, as shown in the following example:

function setupBox(box) {

box.width = (box.width == undefined) ? $.bp() : 48;

box.height = (box.height == undefined) ? $.bp() : 48;

box.url = (box.url == undefined) ? $.bp() : "none";

}

This example breaks into the JavaScript Debugger if any of the width, height, or url attributes of the custom
element are undefined. Of course, you wouldn’t put bp method calls into production code—it’s more appro­priate for shipping code to set default values for undefined properties, as the previous example does.

Script Breakpoints window

Display of the Script Breakpoints window is controlled by the Script Breakpoints button in the JavaScript
Debugger. This window displays all defined breakpoints. This window does not display temporary break­points or breakpoints defined by the debugger statement in JavaScript code.

The Script Breakpoints window provides the following controls:

• The Line field contains the line number of the breakpoint.

• The Condition field may contain a JavaScript expression to evaluate when the breakpoint is reached. If the

expression evaluates to false, the breakpoint is not executed.

• Breakpoints set in this window persist across multiple executions of a script. When the application quits or

a script is reloaded, it removes all breakpoints.

To set a breakpoint in the Script Breakpoints window:

1 Click New to create a new breakpoint, or click the breakpoint that you wish to edit.

2 Enter a line number in the Line Number field, or change the existing line number.

3 Optionally, enter a condition such as (i>5) in the Condition field. This can be any valid JavaScript

expression. If the result of evaluating the expression is true, the breakpoint activates.

The $ object

The $ object (Debugger Object) provides properties and methods you can use to debug your JavaScript code.
For example, you can call its methods to set or clear breakpoints programmatically, or to change the language
flavor of the script currently executing. It also provides properties that hold information about the version of
the host platform’s operating system.

Note: The $ object is not a standard JavaScript object.

Properties

Name Type Description

error

Error Retrieve the last runtime error. Reading this property returns an Error

object containing information about the last runtime error.

Using Help Back 18

Help JavaScript Debugging

Using Help Back 19

version

os

String Returns the version number of the JavaScript engine as a three-part num-

ber like e.g. "3.1.11". Read only.

String Outputs the current operating system version. Read only.

Debug output method

write (text, …);

writeln (text, …);

Write the given string to the Debug Output window. The writeln method appends a New Line character to its
arguments.

Parameters

text

Returns

String All parameters are concatenated to a single string.

None.

Clear breakpoint method

clearbp (scriptletName, line);

Clear a breakpoint. The breakpoint is defined by the name of the scriptlet or function and the line number. If
the scriptlet name is the empty string or is missing, the name of the currently executing scriptlet is used. If the
line number is zero or not supplied, the current line number is used. Thus, the call $.clearbp() without param­eters clears a breakpoint at the current position.

The special string "NEXTCALL" as the scriptlet name causes the engine to clear a breakpoint at the next
function call.

Parameters

scriptletName

line

Returns

String The name of the scriptlet where the breakpoint is to be cleared.

Number The line number where the breakpoint is to be cleared.

None.

Execute breakpoint method

bp([condition]);

Execute a breakpoint at the current position. Optionally, a condition may be supplied. The condition is a
JavaScript expression string that is evaluated before the breakpoint is executed. The breakpoint is executed
only if the expression returns true. If no condition is given, the use of the debugger statement is recommended
instead as it is a more widely supported JavaScript standard statement.

Using Help Back 19

Help JavaScript Debugging

Using Help Back 20

Parameters

condition

Returns

String An optional JavaScript expression string that is evaluated before the

breakpoint is executed. The expression needs to evaluate to the equivalent
of true in order to activate the breakpoint.

None.

Garbage collection method

gc ()

Initiate a garbage collection. Garbage collection is the process by which the JavaScript interpreter cleans up
memory it is no longer using. This is done automatically. Occasionally when you’re debugging a script, it may
be useful to call this process.

Returns

None.

Using Help Back 20

Help Reference

Using Help Back 21

Reference

This chapter lists and describes syntax (keywords, statements, operators,classes, objects, methods, attributes,
and global functions) particular to the After Effects scripting engine.

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, please refer to Ecma-262.pdf, available at www.ecma­international.org/publications/standards/ECMA-262.HTM

For an overview of the most common keywords and statements available from ECMA-262, see “Keywords and
statement syntax” on page 9.

Objects, methods, attributes, and globals

As you look through this reference section, which is organized alphabetically according to object groupings,
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.

application

settings

renderQueue item(s)

renderQueueItem(s)

outputModule(s)

project

compItem

layer(s)

properties

item(s) may be any of the following 3 types of item:

proxySource proxySourcemainSource

solidSource

color

Hierarchy diagram of the main After Effects scripting objects

OR

mainSource & proxySource

may be any of the following 3 types of item:

OR

placeholderSource

OR

OR

socketfile foldersystem

folderItemfootageItem

ITEM(S)

fileSource

file

Using Help Back 21

Help Reference

Using Help Back 22

The hierarchy of objects in scripting corresponds to the hierarchy in the user interface. The Application contains a Project window that
contains a Composition with a Layer. The source for the Layer can be a footage file, placeholder, or solid, and it is also listed in the Project
window. The Layer in turn contains settings known as Properties, and these can hold individual keyframes. The Render Queue contains
Render Queue Items as well as Render Settings and Output Modules. All of these rules are directly analogous to scripting.

Attributes and properties

Note that in ECMAScript and JavaScript, a named piece of data of a certain type is commonly referred to as a
property. However, After Effects already has a separate definition of a “property”: It is a specific editable value
within a layer. Therefore in this section the synonymous term “attribute” refers to these same pieces of data.

Global functions

This section describes globally available functions that are specific to After Effects. Any JavaScript object or
function can call the functions in this section.

Using Help Back 22

Help Reference

Using Help Back 23

Functions

Function Reference Description

alert()

prompt()

write()

writeLn()

clearOutput()

confirm()

fileGetDialog()

filePutDialog()

folderGetDialog()

alert() global function

alert(text)

see “alert() global function” on page 23 displays an alert dialog displaying a specified

see “prompt() global function” on
page 25

see “write() global function” on page 26 writes output to the Info palette, with no line

see “writeLn() global function” on
page 26

see “clearOutput() global function” on
page 23

see “confirm() global function” on
page 24

see “fileGetDialog() global function” on
page 24

see “filePutDialog() global function” on
page 24

see “folderGetDialog() global function”
on page 25

text string

opens a dialog box with a text field into which
the user can enter a text string

break added

writes output to the info palette, adding a line
break at the end

clears the Info palette

prompts the user with a modal dialog and yes/
no buttons which clear the dialog and return a
boolean

presents the platform’s standard Open dialog
box

presents the platform’s standard Save dialog
box

displays a dialog in which the user can select a
folder

Description

The Alert global function opens an alert dialog that can contain a text alert. The user then has the option of
clicking OK to close the window.

Parameters

text

Example

alert ( "CoSA Lives!");

text string that is displayed in the dialog, which can display up to 240 characters

clearOutput() global function

clearOutput()

Description

The clearOutput global function clears the output in the info palette.

Parameters

None.

Using Help Back 23

Help Reference

Using Help Back 24

confirm() global function

confirm(text)

Description

The Confirm global function prompts the user with a modal dialog and yes/no buttons that clear the dialog.
These return a boolean; true if yes, false if no.

Parameters

text

Returns

text string; Mac OS user interface can display 256 characters, Windows, 30 characters

Boolean.

Example

var shouldAdd = confirm("Add to Render Queue?");

if (shouldAdd == "true"){

proj.renderQueue.items.add(myCompItem);

}

fileGetDialog() global function

fileGetDialog(prompt,typeList)

Description

The fileGetDialog global function presents the Open dialog box that is standard for the platform on which
After Effects is running.

The typeList is a semicolon-separated list of four-character Mac OS file types followed by Windows file exten­sions. For example, a value of "EggP aep" for this argument specifies that the Open dialog box is to display
After Effects project items only; other file types will be grayed out.

Parameters

prompt

typeList

Returns

message that displays on the title bar of the dialog; truncated if too long

a platform-specific value indicating a list of file types to display

File object, or null if the user cancels the dialog.

filePutDialog() global function

filePutDialog(prompt,default,type)

Description

The filePutDialog global function presents the Save dialog box that is standard for the platform on which After
Effects is running.

Using Help Back 24

Help Reference

Using Help Back 25

Parameters

prompt

default

type

Returns

message that appears on the title bar of the dialog; truncated if too long

default file name to display in the file-saving dialog; this value must observe the file-naming
conventions of the platform on which After Effects is running

specified file type

File object, or null if the user cancels the dialog.

folderGetDialog() global function

folderGetDialog(prompt)

Description

The folderGetDialog global function displays a dialog in which the user can select a folder.

Parameters

prompt

Returns

Folder object, or null if the user cancels the dialog.

message that appears on the title bar of the dialog; truncated if too long

prompt() global function

prompt(prompt, default)

Description

The prompt global function opens a dialog box with a text field into which the user can enter a text string. The
text string is returned as a value, or is null if the dialog is cancelled.

Parameters

prompt

default

Returns

String, or null if dialog is cancelled. Read-only.

Example

// presuming a project loaded with at least one comp is open:

var myCompItem = app.project.item(1);

var newName = prompt( "What would you like to name the comp?");

// rename it

if (newName) { //if the user cancels, newName is null

myCompItem.name = newName; // newName now holds a string

}

text string that appears in the prompt dialog

text string that appears by default in the text field

Using Help Back 25

Help Reference

Using Help Back 26

write() global function

write(text)

Description

The write global function writes output to the Info palette, with no line break added.

Parameters

text

Example

write(“This text appears in Info palette.”);

See also

text string; truncated if too long for the info palette

“writeLn() global function” on page 26

writeLn() global function

writeLn(text)

Description

The write global function writes output to the info palette and adds a line break at the end.

Parameters

text

Example

writeLn(“This line of text appears in the console window with a line break at the end.”);

See also

“TextDocument.” on page 178

text string

Application object

app.

Description

The application (app) global object enables access to data and functionality within the After Effects appli­cation. Attributes of the Application object provide access to specific objects within After Effects. Methods of
the Application object can create documents, open existing documents, 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.

Using Help Back 26

Help Reference

Using Help Back 27

Attributes

Attribute Reference Description

project

language

version

serialNumber

registeredName

registeredCompany

buildName

buildNumber

isProfessionalVersion

isWatchFolder

isRenderEngine

see “Application project attribute” on
page 34 and “Project object” on
page 121

see “Application language attribute” on
page 32

see “Application version attribute” on
page 36

see “Application serialNumber
Attribute” on page 35

see“Application registeredName
attribute” on page 35

see “Application registeredCompany
attribute” on page 35

see “Application buildName attribute”
on page 29

see “Application buildNumber
attribute” on page 29

see “Application isProfessionalVersion
attribute” on page 31

see “Application isWatchFolder
attribute” on page 31

see “Application isRenderEngine
attribute” on page 31

instance of the current After Effects Project
and all of its associated methods & attributes

identifies the language in which the applica­tion is running

identifies the version number of the After
Effects application

identifies the serial number of the After Effects
installation

identifies the name to which the After Effects
installation is registered

identifies the company to which the After
Effects installation is registered

identifies the name of this build of the applica­tion

identifies the number of this build of the appli­cation

identifies if the After Effects version is the Pro­fessional Version

boolean that returns true when the local appli­cation is running in Watch Folder mode

identifies whether the local After Effects appli­cation is installed as a render engine

settings

onError

exitCode

exitAfterLaunchAndEval

see “Application settings attribute” on
page 36 and “Settings object” on
page 170

see “Application onError attribute” on
page 33

see “Application exitCode attribute” on
page 31

see “Application exitAfterLaunchAndE­val attribute” on page 30

calls settings within After Effects that can be
set via scripting

a callback that is called when an error occurs in
the application

Used only when executing script externally
(i.e., from a command line or AppleScript). Set
to zero, indicates no error occurred; set to a
positive number, indicates an error occurred
while running the script.

specifies whether the application remains
open after running a script from the command
line on Windows

Methods

Method Reference Description

newProject()

open()

see “Application newProject() method”
on page 32

see “Application open() method” on
page 33

opens a new project in After Effects

opens a project or an Open Project dialog

Using Help Back 27

Help Reference

Using Help Back 28

Method Reference Description

quit()

watchFolder()

pauseWatchFolder()

endWatchFolder()

purge()

beginUndoGroup()

endUndoGroup()

beginSuppressDialogs()

endSuppressDialogs()

setMemoryUsageLimits()

setSavePreferencesOnQuit()

see “Application quit() method” on
page 34

see “Application watchFolder() method”
on page 37

see “Application pauseWatchFolder()
method” on page 34

see “Application endWatchFolder()
method” on page 30

see “Application purge() method” on
page 34

see “Application beginUndoGroup()
method” on page 28

see “Application endUndoGroup()
method” on page 29

see “Application beginSuppressDia­logs() method” on page 28

see “Application endSuppressDialogs()
method” on page 29

see “Application setMemoryUsageLim­its() method” on page 36

see “Application setSavePreferencesOn­Quit() method” on page 36

quits the application

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

purges a targeted type of cached information
(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 one
script contains more than one undo group

begins suppression of dialogs in the user inter­face

ends suppression of dialogs in the user inter­face

sets memory usage limits as in the Cache pref­erences tab

sets whether Preferences are saved when the
application is quit

Application beginSuppressDialogs() method

app.beginSuppressDialogs()

Description

This method begins suppression of dialogs in the user interface.

Parameters

None.

Returns

None.

Application beginUndoGroup() method

app.beginUndoGroup(undoString)

Description

An undo group allows a script to logically group all of its actions as a single undoable action (for use with the
Edit Undo/Redo menu items). Should be used in conjunction with the application.endUndoGroup() method.

Please note that beginUndoGroup() and endUndoGroup() pairs can be nested. Groups within groups become
part of the larger group, and will undo correctly. In such cases, the names of inner groups are ignored.

Using Help Back 28

Help Reference

Using Help Back 29

Parameters

undoString

See also

(mandatory) the text that will appear for the Undo command in the Edit menu (i.e., “Undo undoString”)

“Application endUndoGroup() method” on page 29

Application buildName attribute

app.buildName

Description

The buildName attribute identfies the name of the build of After Effects being run. This attribute is used
primarily by Adobe for testing and troubleshooting purposes.

Typ e

String; read-only.

Application buildNumber attribute

app.buildNumber

Description

The buildNumber attribute identfies the number of the build of After Effects being run. This attribute is used
primarily by Adobe for testing and troubleshooting purposes.

Typ e

Integer; read-only.

Application endSuppressDialogs() method

app.endSuppressDialogs(alert)

Description

This method ends the suppression of dialogs in the user interface. It should be called only if beginSuppress­Dialogs() has previously been called.

If the input argument 'alert' is true, and any errors occurred between the calls to beginSuppressDialogs() and
endSuppressDialogs(), then a dialog will be presented to the user displaying that error message.

Parameters

alert

See also

boolean; specifies whether errors that have occurred following beginSuppressDialogs() should be dis­played

“Application beginSuppressDialogs() method” on page 28

Application endUndoGroup() method

app.endUndoGroup()

Using Help Back 29

Help Reference

Using Help Back 30

Description

This ends the 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.

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

Parameters

None.

Returns

None.

See also

“Application beginUndoGroup() method” on page 28

Application endWatchFolder() method

app.endWatchFolder()

Description

The endWatchFolder() method ends watch folder mode.

Parameters

None

See also

“Application version attribute” on page 36

“Application pauseWatchFolder() method” on page 34

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 and 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.

-r or -s command line flag will cause the application to run a script

Note that this attribute only has an effect when After Effects is run, and it has no effect on Mac OS.

Typ e

Boolean; read/write.

Using Help Back 30