About expressions

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.

Note:

Two sources of example expressions are the Expression Sampler template project (File > Browse Template Projects) and the animation presets in the Behaviors category (Animation > Browse Presets).

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:

  value + 90

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:

  wiggle(10, 10)

Note:

Using the wiggle expression is often much faster and easier than using the Wiggler.

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.

Working with expressions

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

Expression interface in the Timeline panel in layer bar mode
Expression interface in the Timeline panel in layer bar mode

A. Enable Expression switch B. Show Post-Expression Graph button C. Pick whip D. Expression Language menu E. Expression field 

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:

Symbol

Function

+

add

-

subtract

/

divide

*

multiply

*-1

perform opposite of original, such as counterclockwise instead of clockwise

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.

Note:

You must replace the argument names written by the Expression Language menu with actual values.

Paul Tuersley provides a script on the AE Enhancers forum that automatically adds wiggle, smooth, and loop expressions to selected properties. Using this script is a good way for a beginner to experiment with expressions.

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. For more information, see Jeff Almasol’s redefinery website.

Add, disable, link, or remove an expression

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

Edit an expression with the pick whip

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.

Drag the pick whip to a property
Drag the pick whip to a property to create a link to the value of the property.

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:

  thisComp.layer("Layer 1").transform.position

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:

  temp = thisComp.layer("Layer 1").transform.position[1]; 
  [temp, temp]

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:

  thisComp.layer("Layer 1").transform.position

Here is the same expression, not in compact English:

  thisComp.layer("Layer 1")("Transform")("Position")

Note:

Because the default is to use compact English, this document uses compact English in most examples and illustrations.

  1. Drag the pick whip to another property in the Timeline panel or Effect Controls panel.
  2. Optionally, modify the default expression in the expression field.

Note:

If you use the pick whip to create an expression to refer to a layer, and that layer has the same name as another layer in the same composition, then the targeted layer’s name changes. The new layer name is the old layer name with a numeral at the end. This change is necessary to ensure that the expression unambiguously refers to a single layer in the composition.

Edit an expression manually

  1. Click in the expression field to enter text-editing mode.

    Note:

    When you enter text-editing mode, the entire expression is selected. To add to the expression, click within the expression to place the insertion point; otherwise, you will replace the entire expression.

  2. Type and edit text in the expression field, optionally using the Expression Language menu.

    Note:

    To see more of a multiline expression, drag the bottom or top of the expression field to resize it.

  3. To exit text-editing mode and activate the expression, do one of the following:
    • Press Enter on the numeric keypad.

    • Click outside the expression field.

Example: Use the expression language reference to write an expression

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.

  1. Create two solid layers: Solid 1 and Solid 2.

  2. Animate the Position property values for Solid 1 using keyframes. (See About animation, keyframes, and expressions.)

  3. Select the Position property for Solid 2 and choose Animation > Add Expression or Alt-click (Windows) or Option-click the stopwatch button for the property. The following expression appears by default:

      transform.position
  4. Type the following directly over transform.position:

      thisComp
  5. The element thisComp is a global attribute whose value is a Comp object representing the current composition. To determine what can follow thisComp in your expression, look up the return value for thisComp under Global objects, attributes, and methods (expression reference).

    Note that thisComp returns a Comp object. Next, look at Comp attributes and methods (expression reference) to see which attributes and methods you can use with a Comp object. One option is layer(index). The index, or number, inside the parentheses specifies the layer that you want to use. For this example, we assume that Solid 1 is the first layer in your composition. To retrieve values from the first layer in the active composition, type .layer(1) at the end of the expression, to get the following:

      thisComp.layer(1)
  6. Again, look at the expression elements reference to see that layer(index) returns a Layer object. Look at Layer General attributes and methods (expression reference), and find the element you want to use. For example, if you want to get the values of the Position property for the layer, type .position at the end of the expression to get the following:

      thisComp.layer(1).position
  7. From Layer General attributes and methods (expression reference), you can see that the position attribute returns a property. Look up Property attributes and methods (expression reference) and notice that you can add a time factor to the expression. To add a specific time, such as current time plus 2 seconds, type .valueAtTime(time+2)at the end of the expression to get the following:

      thisComp.layer(1).position.valueAtTime(time+2)
  8. From Property attributes and methods (expression reference), notice that the valueAtTime method returns a Number or Array. When an expression returns a Number, Array, or Boolean (true or false), you cannot add further attributes or methods to the expression (if you want, however, you can add arithmetic operators, such as +, -, *, and /).

Show expressions and the expression graph

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.

Note:

To toggle between layer bar mode and Graph Editor mode, press Shift+F3.

  • 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 a new expression to a property, the expression editor is shown, regardless of this setting.

Note:

To resize the expression field, drag its bottom edge up or down.

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

Note:

You can use the search field in the Timeline panel to search expressions as well as other components of a property. If the search string appears in an expression, the property and its containing property groups and layer are shown in the filtered set of search results.

Write expressions for source text

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:

  text.sourceText + "\r" + text.sourceText.toUpperCase()

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:

  thisComp.layer(index + 1).name + "\rOpacity = " + thisComp.layer(index + 1).opacity.value

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.

  source_footage_name = ""; 
  for (i = 1; i <= thisComp.numLayers; i++){ 
      if (i == index) continue; 
      my_layer = thisComp.layer(i); 
      if (! (my_layer.hasVideo && my_layer.active)) continue; 
      if (time >= my_layer.inPoint && time < my_layer.outPoint){ 
          try{ 
              source_footage_name = my_layer.source.name; 
          }catch(err1){ 
              source_footage_name = my_layer.name 
          } 
          break; 
      } 
  } 
  source_footage_name

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

 

Add comments to an expression

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.

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:

  function average(a, b) 
  { 
    return (a + b) / 2; 
  } 
  average(position, thisComp.layer(1).position);

Note:

You must define each function fully within each expression in which it is used. There is no global library of functions that you can add to.

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:

  /*  This expression on a Source Text property reports the name 
      of a layer and the value of its Opacity property. */  
    
  var myLayerIndex = 1; // layer to inspect, initialized to 1, for top layer  
    
  thisComp.layer(myLayerIndex).name + ": \rOpacity = " +   thisComp.layer(myLayerIndex).opacity.value

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.

Note:

Copying an expression without keyframes is useful when you want to simultaneously copy multiple expressions and paste them onto one or more new layers, or when you want to copy one expression and paste it onto more than one layer.

Note:

As with pasting keyframes and other items, you can often paste the item into the target layer and rely on After Effects to determine which property should be the target of the paste operation. For example, this works for copying Position properties from one layer to another, but you must select the target property yourself if you are pasting an expression from a Position property into a Scale property.

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

Expression Controls effects

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.

Note:

If you apply an animation preset from the Animation Presets > Shapes > Backgrounds category, you can see a custom Animated Shape Control effect in the Effect Controls panel. This custom effect is a specialized expression control effect that was created specifically for these animation presets. You can copy and paste this effect to other layers, or you can save it as an animation preset itself so that you can apply it elsewhere.

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:

  position+[0,10*(index-1)*thisComp.layer("Null 1").effect("Slider Control")("Slider")]

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 of 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).

Note:

To modify the range of a control, right-click (Windows) or Control-click (Mac OS) the underlined property value for the control and choose Edit Value from the context menu.

Additional resources about Expression Controls effects

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.

Convert an expression to keyframes

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; or, 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.

  • In the Timeline panel, select the property on which the expression is written and choose Animation > Keyframe Assistant > Convert Expression To Keyframes.

The expression language

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

Accessing attributes and methods

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:

  thisComp.layer("Layer B").effect("Gaussian Blur")("Blurriness")

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:

  thisComp.layer("Layer B").effect("Advanced Lightning")("Origin")[1]

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:

  wiggle(5, 10) 
  position.wiggle(5, 10)

You do need to 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:

  thisComp.layer("Layer A").rotation

Note:

To see more examples of how this works, use the pick whip to link one layer property to another, and look at the expressions it creates.

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

Arrays and multidimensional properties

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:

  [10, 23]

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:

  myArray = [10, 23]

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:

Dimension

Property

1

Rotation °

Opacity %

2

Scale [x=width, y=height]

Position [x, y]

Anchor Point [x, y]

Audio Levels [left, right]

3

Scale [width, height, depth]

3D Position [x, y, z]

3D Anchor Point [x, y, z]

Orientation [x, y, z]

4

Color [red, green, blue, alpha]

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:

  [myArray[0], 5] 
  [10, 5]

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 completely 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:

  y = position[1]; 
  [9,y]

The following is even more succinct:

  [9, position[1]]

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:

  x = thisComp.layer("Layer A").position[0];  
  y = thisComp.layer("Layer B").position[1];  
  [x,y]

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:

  thisComp.layer("Layer B").scale[0]

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:

  thisComp.layer("Layer B").scale[1]

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:

  temp = thisComp.layer(1).transform.rotation; 
  [temp, temp]

Vectors

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.

Indices and labels

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 will continue to work even if you change the order of effects:

  effect("Colorama").param("Get Phase From")  
  effect(1).param(2)

Expression time

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:

  thisComp.layer(1).position 
  thisComp.layer(1).position.valueAtTime(time)

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:

  thisComp.layer(1).position.valueAtTime(time-5)

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:

  comp("nested composition").layer(1).position

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

  thisComp.layer("nested composition").source.layer(1).position

Note:

If you use a specific time in an expression, After Effects ignores 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).)

Expression errors

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:

An example expression error
An example expression error

A. Left or Right arrow buttons B. The Reveal Expression C. The Expand/Collapse Warning 
  • 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 will expose the property with the failing expression in the Timeline panel. If the expression is in a different composition, that composition will open.
  • 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 CC (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.

Online resources

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.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy