Expression basics

When you want to create and link complex animations, but would like to avoid creating tens or hundreds of keyframes by hand, try using expressions. An expression is a little piece of software—much like a script—that evaluates to a single value for a single layer property at a specific point in time. Whereas scripts tell an application to do something, an expression says that a property is something.

With expressions, you can create relationships between layer properties and use the keyframes of one property to dynamically animate other layers. For example, you can use the pick whip to link path properties, so a mask can take its path from a brush stroke or a shape layer object.

The expression language is based on the standard JavaScript language, but you do not need to know JavaScript to use expressions. You can create expressions by using the pick whip or by copying simple examples and modifying them to suit your needs.

Animation presets can include expressions, or even consist entirely of an expression. Animation presets that use expressions instead of keyframes are sometimes called behaviors.

After you add an expression to a property, you can continue to add or edit keyframes for the property. An expression can take the value of a property as determined by its keyframes and use that as input to generate new, modified values. For example, the following expression on the Rotation property of a layer adds 90 degrees to the value of the Rotation property, in addition to the keyframed motion:

Some methods—such as wiggle—operate directly on the keyframed property values. (See Property attributes and methods (expression reference).)

The following expression on the Position property of a layer preserves the keyframed motion of the layer and causes it to wiggle a little:

When you are animating text, you can use the Expression selector to specify how much you want an animator property to affect each text character. You can add one or more Expression selectors to an animator group, and that animator group can contain one or more properties.

You can enter entire expressions yourself, by manually typing them or by using the Expression Language menu; or you can create an expression with the pick whip or paste it from an example or other property.

You can do all your work with expressions in the Timeline panel, though it is sometimes more convenient to drag the pick whip to a property in the Effect Controls panel. You enter and edit expressions in the expression field, a resizable text field in the time graph. The expression field appears alongside the property in layer bar mode; the expression field appears at the bottom of the Graph Editor in Graph Editor mode. You can write an expression in a text editor and then copy it into the expression field. When you add an expression to a layer property, a default expression appears in the expression field. The default expression essentially does nothing—it sets the property value to itself, which makes tweaking the expression yourself easy.

While you are editing an expression, previews of all kinds are suspended; a red bar appears at the bottom of panels that are waiting for you to exit text-editing mode.

The values for a property that contains an expression appear in red or pink type.

A good way to begin working with expressions is to create a simple expression with the pick whip and then adjust the behavior of the expression using simple math operations, such as those listed in the following table:

For example, you can double the result by typing *2 at the end of the expression; or you can halve the result by typing /2 at the end of the expression.

As you develop comfort editing expressions, you can combine these simple operations—and more. For example, you can add /360*100 to the end of an expression to change its range from 0-360 to 0-100. This change would be useful if you wanted to convert the values of a 360-degree dial to a slider that is measured in percentages.

The Expression Language menu in the Timeline panel contains language elements specific to After Effects that you can use in an expression. This menu is helpful for determining valid elements and their correct syntax; use it as a reference for available elements. When you choose any object, attribute, or method from the menu, After Effects automatically inserts it in the expression field at the insertion point. If text is selected in the expression field, the new expression text replaces the selected text. If the insertion point is not in the expression field, the new expression text replaces all text in the field.

The Expression Language menu lists arguments and default values. This convention makes it easy to remember which elements you can control when you write an expression. For example, in the language menu, the wiggle method in the Property category appears as wiggle (freq, amp, octaves=1, amp_mult=.5, t=time). Five arguments are listed in the parentheses following wiggle. The = in the last three arguments indicates that using those arguments is optional. If you specify no values for them, they default to 1, .5, and the current time, respectively.

Jeff Almasol provides a script that automatically processes expressions, making specified changes. For example, the script can be used to automatically remove or enable disabled expressions.

You can customize the code editor interface of the expression editor, including highlighting JavaScript syntax with custom colors, line numbers, code folding, and auto-complete. To customize these options, select Preferences > Scripting and Expressions.

• Customize syntax highlighting of JavaScript syntax and After Effects methods and properties:
  • You can assign custom colors to highlight each syntax, selection and alpha selection, and the background. Click the dropper icon to select a color from the color wheel.
  • You can customize how the expression editor looks with the different themes to select from. Click the Theme drop-down menu and select from the themes. You may also save custom themes.

• Edit preferences:

• Show Line numbers
• Tabs or Spaces
• Custom tab width
• Backspace un-indenting
• Indentation guides
• Braces:
  • Highlighting of matching braces
  • Automatic closing of braces
  • Auto Indent for Braces
• Adjustable font size
• Code folding:
  • Arrow
  • Plus & Minus
  • Circle Tree
  • Square Tree
• Word wrapping:
  • Word
  • Character
  • None
• Auto-complete:
  • JavaScript syntax
  • After Effects methods and properties
  • Composition, footage, layer, and effect names used in the current project
  • Custom variable names
• Optional inline error messages

• Code Preview box: All changes to the syntax colors and other editor preferences can be previewed live in this code preview box.

Tip: Use throw to debug expressions inline.

See the example below to understand how the editor works:

Composition names, layer names, footage names, and effect names are all pulled into the autoComplete and shown in the correct context with their respective comp(), layer(), footage(), and effect() methods. This allows you to keep your expression active while referencing items in the project. You do not need to scroll the Timeline or open other panels to refer to properties or items using the pickwhip.

• To add an expression to a property, select the property in the Timeline panel and choose Animation > Add Expression or press Alt+Shift+= (Windows) or Option+Shift+= (Mac OS); or Alt-click (Windows) or Option-click (Mac OS) the stopwatch button next to the property name in the Timeline panel or Effect Controls panel.
• To link a set of properties across layers and compositions, use property links.
  Select any one property or set of properties and choose Edit > Copy With Property Links or Edit > Copy With Relative Property Links, and then paste those properties on any layer in a composition. The pasted properties remain connected to the layer from which the properties were copied, such that any change made to the original property is reflected in all of the instances of the pasted property links.
  You can even copy an entire layer with property links and paste it to create duplicates that follow the changes made to the original.

  The command Copy With Relative Property Links, works like the command Copy With Property Links, except that the Copy With Relative Property Links command creates expressions that do not reference the source composition by name. This maintains a relative link between the layer with the expression and the composition containing that layer. This can be useful when, for example, you want to move expression-rigged layers from one composition to another but let the layers reference a control layer only in the same composition. The expressions created using the Copy With Relative Property Links command are identical to those created using the expression pick whip.

  The result of copying a layer’s Position property with the Copy With Relative Property Links command is as follows:

  thisComp.layer("control_layer").transform.position

  The result of copying a layer’s Position property with the Copy With Property Links command is as follows, which specifically references the layer’s source composition in the expression:

  comp("source_comp").layer("control_layer").transform.position

• To temporarily disable an expression, click the Enable Expression switch . When an expression is disabled, a slash appears through the switch .
• To remove an expression from a property, select the property in the Timeline panel and choose Animation > Remove Expression, or Alt-click (Windows) or Option-click (Mac OS) the stopwatch button next to the property name in the Timeline panel or Effect Controls panel.

If you are not familiar with JavaScript or the After Effects expression language, you can still take advantage of the power of expressions by using the pick whip. You simply drag the pick whip from one property to another to link the properties with an expression, and the expression text is entered in the expression field at the insertion point. If text is selected in the expression field, the new expression text replaces the selected text. If the insertion point is not in the expression field, the new expression text replaces all text in the field.

You can drag the pick whip to the name or value of a property. If you drag to the name of a property, the resulting expression displays all the values as one. For example, if you drag the pick whip to the name of the Position property, an expression like the following appears:

If you drag the pick whip to one of the component values of the Position property (such as the y value), an expression like the following appears, in which both the x and y coordinates of the property are linked to the y value of the Position property:

If the layer, mask, or effect that you drag the pick whip to does not have a unique name in its local context, After Effects renames it. For example, if you have two or more masks named “Mask” on the same layer, and you drag the pick whip to one of them, After Effects renames it “Mask 2."

The format of expressions created by the pick whip is determined by the Expression Pick Whip Writes Compact English preference (Edit > Preferences > General (Windows) or After Effects > Preferences > General (Mac OS)). By default, the pick whip creates compact English expressions, which use the names for properties as they appear in the Timeline panel for the properties within an expression. Because these names are coded into the application and never change, these expressions can work when After Effects is running in another language. Any property names that you can change are enclosed in double quotation marks and remain the same in any language. If you don’t plan on sharing your projects across languages, you can deselect this preference. This preference does not affect effect names or effect properties.

Here is an example in compact English:

Here is the same expression, not in compact English:

Follow along with this example to learn how to use the After Effects expression language reference to write expressions. The expression created in this example links the Position property of Solid 2 to the Position property of Solid 1, with the movement of Solid 2 offset by 2 seconds from the movement of Solid 1.

In Graph Editor mode, the single expression field appears as a resizable box at the bottom of the Graph Editor and shows only the expression for the selected property. To show multiple expression fields simultaneously, the Timeline panel must be in layer bar mode.

• To show only properties with expressions, select one or more layers, and then press EE.
• To show the expression field in the Graph Editor, choose Show Expression Editor from the Choose Graph Type And Options menu at the bottom of the Graph Editor. When you add an expression to a property, the expression editor is shown, regardless of this setting.

• To see how an expression changes the value or velocity graph, click the Show Post-Expression Graph button while showing the value or velocity graph in the Graph Editor.

  The dimly colored graph displays the value or velocity before the expression is applied, and the brightly colored graph displays the value or velocity after the expression is applied. Turning on the graph overlay for the Position property also changes the motion path display in the Composition panel so that you can see the expression-affected path.

The Source Text property of a text layer is interpreted by expressions as a JavaScript String. You can use the pick whip to retrieve the source text from another text layer; however, only the style of the first character of the destination layer is used.

For more information on the JavaScript String object, consult a JavaScript reference resource.

You can use "\r" in a string expression to start a new line of text. For example, to copy the original text from one layer onto the same layer and repeat it in all uppercase characters on a new line, use the following expression:

Adding a text layer to a composition and adding an expression to its Source Text property can be a great way to examine the property values of other layers. For example, the following expression on a Source Text property reports the name and value of the Opacity property for the next layer in the layer stacking order:

The following example reports the name of the footage item used as the source of the topmost image layer in the stacking order at the current time that has its Video switch set.

Aharon Rabinowitz provides a video tutorial and example expressions on Red Giant TV that show how to animate a video game score with the Source Text property and a Slider effect (an Expression Controls effect).

If you write a complex expression and intend for you or someone else to use it later, you should add comments that explain what the expression does and how its pieces work.

• Type // at the beginning of the comment. Any text between // and the end of the line is ignored. For example:  // This is a comment.

  For examples of this type of comment, see Expression example: Fade opacity of a 3D layer based on distance from camera.

• Type /* at the beginning of the comment and */ at the end of the comment. Any text between /* and */ is ignored. For example:  /*  This is a         multiline comment. */

  For examples of this type of comment, see Save and reuse expressions.

Once you have written an expression, you can save it for future use by copying and pasting it into a text-editing application or by saving it in an animation preset or template project. However, because expressions are written in relation to other layers in a project and may use specific layer names, you must sometimes modify an expression to transfer it between projects.

You can define your own functions within expressions using normal JavaScript function syntax. In this example, a function is defined that calculates the average of two values, and the last line uses this function:

If you want to save an expression for use in another project, you should add comments to the expression. (See Add comments to an expression.) You should also use variables so that you can change a value in one place rather than having to change it in several places.

For example, this expression has a multiline comment at the beginning that explains what the expression does and a short comment after a variable is declared and initialized that tells what the variable is for:

You can save an animation preset that includes an expression and reuse it in other projects, as long as the expression does not refer to properties that don’t exist in the other projects. When you save a preset in which a property has an expression but no keyframes, only the expression is saved. If the property has one or more keyframes, the saved preset contains the expression along with all keyframe values.

You can copy an expression from a layer property, with or without the keyframes for the property.

• To copy an expression and keyframes from one property to other properties, select the source layer property in the Timeline panel, copy the layer property, select the target layer properties, and paste.
• To copy an expression from one property to other properties without copying keyframes, select the source property, choose Edit > Copy Expression Only, select the target properties, and paste.

Paul Tuersley provides the pt_ExpressEdit script for managing and editing expressions.

Use an Expression Controls effect to add a control that you can use to manipulate the values of one or many properties by linking the property to the control using expressions. A single control can affect several properties at once.

The names for the Expression Control effects indicate what type of property control they provide: Angle Control, Checkbox Control, Color Control, Layer Control, Point Control, Slider Control. After Effects CS5.5 and later includes a 3D Point Control, as well.

You apply Expression Controls effects to a layer in the same ways that you apply other effects, such as dragging the effect onto the layer from the Effects & Presets panel.

You can apply Expression Controls effects to any layer; however, it is useful to apply them to a null layer, which you can simply use as a controlling layer. You then add expressions to properties on other layers to take input from that control. For example, you can add the Slider Control effect to a null layer (Null 1), and then apply this expression to the Position properties of multiple layers:

In this example, as you drag the slider, each layer with this expression moves. The layers with greater index numbers (layers toward the bottom in the Timeline panel) are shifted more than the layers with lower index numbers, at 10-pixel intervals. You can set keyframes for the slider on the null layer, and all the other layers animate accordingly.

It is often useful to rename each instance of an Expression Control effect to indicate its use. For example, renaming an instance of the Color Control effect to sky color makes it easier to tell what the effect is controlling. You can rename each instance of an Expression Control effect just as you rename any other effect: select it in the Timeline panel or Effect Controls panel and press Enter on the main keyboard (Windows) or Return (Mac OS).

Jerzy Drozda, Jr. (Maltaannon) provides a simple explanation and demonstration of the Angle Control effect and Expression Controls effects in general on the Motionworks website.

Todd Kopriva provides instructions for using the sampleImage method and the Point Control effect to monitor colors for a specified point during color correction on his After Effects Region of Interest blog.

In some situations, it’s useful to convert an expression to keyframes. For example, if you want to freeze the values in an expression, you can convert the expression to keyframes and then adjust the keyframes accordingly. If an expression takes a long time to evaluate, you can convert it to keyframes so that it renders more quickly. When you convert an expression to keyframes, After Effects evaluates the expression, creating a keyframe at every frame, and then disables the expression.

The After Effects expression language is based on JavaScript 1.2, with an extended set of built-in objects. After Effects uses only the core standard JavaScript 1.2 language, not the web browser–specific extensions. After Effects contains its own set of extension objects—such as Layer, Comp, Footage, and Camera—that you can use to get most of the values in an After Effects project.

Though the expression language is based on a scripting language, a subtle but important difference exists between a script and an expression: Whereas a script tells an application to do something, an expression says that a property is something.

For more information about JavaScript, see a JavaScript reference resource.

When creating expressions, keep in mind the following:

• The value of an expression is the value of the last statement evaluated.

• JavaScript is a case-sensitive language.

• Semicolons are required to separate statements or lines.

• Spaces between words are ignored, except within a string.

In JavaScript, a value stored in an object is called a property. However, After Effects uses the term property to refer to layer components as defined in the Timeline panel. For this reason, After Effects refers to JavaScript properties as either methods or attributes. In general practice, the difference between a method and an attribute is that a method usually does something to create its output (return) value, whereas an attribute simply refers to an existing value to determine its output (return) value. You can tell a method from an attribute most easily by looking for the parentheses following the method name, which surrounds any input arguments to the method.

An object is an item that can contain other objects, attributes, and methods. Compositions, layers, and footage items are examples of objects. Specifically, compositions, layers, and footage items are global objects, which means that they can be referred to in any context without reference to some higher-level object.

You use the expression language to access attributes and methods of layer properties. To access a value, use a chain of object references separated by the period (.) operator. To chain object references past the layer level (for example, to refer to effect properties, masks, or text animators), you can also use parentheses. For example, to link the Opacity property in Layer A to the Blurriness property of the Gaussian Blur effect in Layer B, enter the following expression in the expression field for the Opacity property for Layer A:

Reading this expression from left to right, you progress from the higher-level, containing object down to the specific property:

• The global object used refers to the current composition: thisComp.

• A specific layer object within that composition is referred to by its name: layer("Layer B").

• A specific effect object within that layer is referred to by its name: effect("Gaussian Blur").

• A specific effect property within that effect is referred to by its name: ("Blurriness").

For the nth component of a multidimensional property, like the y component of an effect control point, append [n] at the end, like this:

The default object for an expression is the property on which the expression is written, followed by the layer containing the expression; therefore, you do not need to specify the property. For example, a wiggle expression written on the Position property of a layer can be either of the following:

Include the layer and property when retrieving them from outside the layer and property on which the expression is written. For example, an expression written on the Opacity property of Layer B, linking it to the Rotation property of Layer A would look like this expression:

Jeff Almasol provides a script on his redefinery website with which you can determine how to refer to any property in expressions.

An Array is a type of object that stores an ordered set of numbers. An Array is represented as a list of numbers separated by commas and surrounded by brackets, as in this example:

You can assign an Array object to a variable, making it easy to refer to array values in other areas of the expression. For example:

The dimension of an Array object is the number of elements in the array. The dimension of myArray is 2. Different properties in After Effects have different dimensions depending on the number of value arguments they have. In the expression language, the values of properties are either single values (Number objects) or arrays (Array objects).

The following table provides examples of some properties and their dimensions:

You can access the individual elements of an Array object by using brackets and an index number to indicate which element you want. The elements in an Array object are indexed starting from 0. Using the previous example, myArray[0] is 10 and myArray[1] is 23.

The following two expressions are equivalent:

The Position property arrays are indexed as follows:

• position[0] is the x coordinate of position.

• position[1] is the y coordinate of position.

• position[2] is the z coordinate of position.

Colors are represented as four-dimensional arrays [red, green, blue, alpha]. In projects with a color depth of 8 bpc or 16 bpc, each value in a color array ranges from 0 (black) to 1 (white). For example, red can range from 0 (no color) to 1 (red). So, [0,0,0,0] is black and transparent, and [1,1,1,1] is white and opaque. In projects with a color depth of 32 bpc, values under 0 and over 1 are allowed.

If you use an index that is greater than the index of the highest-dimension component in an Array object, After Effects returns an error. For example, myArray[2] causes an error, but position[2] returns the z coordinate of Position.

Many of the properties and methods in the After Effects expression language take Array objects as arguments or return them as values. For example, thisLayer.position is an Array object that is either two-dimensional or three-dimensional depending on whether the layer is 2D or 3D.

If you want to write an expression that keeps the y value of an animation of Position but fixes the x value at 9, you would use the following:

The following is even more succinct:

This is an important point, so let’s look at one more example. If you want to combine the x position value from Layer A with the y position value from Layer B, you would use the following:

You can create an expression that refers to just one value within the array of a 2D or 3D property. By default, the first value is used, unless you specify otherwise. For example, if you drag the pick whip from the Rotation property of Layer A to Scale property of Layer B, the following expression appears:

By default, this expression uses the first value of the Scale property, which is width. If you prefer to use the height value instead, drag the pick whip directly to the second value instead of the property name, or change the expression as follows:

Conversely, if you drag the pick whip from the Scale property of Layer B to the Rotation property of Layer A, After Effects automatically creates a variable, assigns the one-dimensional Rotation property value to it, and then uses that variable for both dimensions of the Scale property:

In After Effects, many properties and methods take or return vectors. After Effects refers to an array as a vector if it represents either a point or direction in space. For example, After Effects describes position as returning a vector.

However, though a function like audioLevels does return a two-dimensional value (the left and right channel levels), it is not called a vector because it does not represent a point or direction. Some functions in After Effects accept vector arguments, but they are generally only useful when the values passed represent a direction. For example, cross(vec1, vec2) computes a third vector that is at right angles to the input vectors. The cross product is useful when vec1 and vec2 are two vectors representing directions in space, but not if they just represent two arbitrary collections of numbers.

Indexing for Layer, Effect, and Mask elements in After Effects starts from 1. For example, the first layer in the Timeline panel is layer(1).

Generally, it is best to use the name of a layer, effect, or a mask instead of a number to avoid confusion and errors if the layer, effect, or mask is moved, or if the arguments are changed during product updates and upgrades. When you use a name, always enclose it in straight quotes. For example, the first of these expressions is easier to understand than the second expression, and the first expression continues to work even if you change the order of effects:

Time within an expression is always in composition time (not layer time) and is measured in seconds. The default time for any expression is the current composition time at which the expression is being evaluated. The following expressions both use the default composition time and return the same values:

To use a relative time, add an incremental time value to the time argument. For example, to get the Position value 5 seconds before the current time, use the following expression:

Default time references to properties in nested compositions use the original default composition time, not remapped time. However, if you use the source function to retrieve a property, the remapped time is used.

For example, if the source of a layer in the containing composition is a nested composition, and in the containing composition you have remapped time, when you get the position values of a layer in the nested composition with the following expression, the position values use the default time of the composition:

However, if you access layer 1 using the source function, the position values use the remapped time:

Because expressions operate on time in units of seconds (not frames), you sometimes need to use time conversion methods to convert time values to perform operations on frames. (See Time conversion methods (expression reference).)

When an expression fails to evaluate, expression errors appear in a warning banner at the bottom of the Composition and Layer panels. After Effects does not disable the expression but continues to evaluate it. The warning banner is displayed as long as the expression fails to evaluate; that is, until the expression is either fixed or manually disabled.

Here’s an example of what the expression error warning banner looks like:

• The Left or Right arrow buttons display the previous or next expression error when multiple expressions fail to evaluate.
• The Reveal Expression (magnifying glass) button exposes the property with the failing expression in the Timeline panel. If the expression is in a different composition, that composition opens.
• The Expand/Collapse Warning (up/down arrows) button shows or hides the error text.

The expression error text is one line only, and is clipped to the width of the Composition panel.

To see the full expression error text:

Click  next to the expression. The complete error appears in a dialog box.

To hide the warning banner:

Choose After Effects (Mac OS) or Edit (Windows) > Preferences > General and disable Show Warning Banner When Project Contains Expressions Errors.

When this option is disabled, the warning banner remains hidden even when new expression errors occur.

Re-enable this option to view expression errors.

Many of the examples in this section are based on examples provided by Dan Ebberts. Dan Ebberts also has an excellent collection of example expressions and tutorials for learning how to work with expressions on his MotionScript website.

The AE Enhancers forum provides many examples and much information about expressions, as well as scripts and animation presets.