Skip to content

After Effects Expression Reference

by

https://docsforadobe.dev

Hosted at https://ae-expressions.docsforadobe.dev/
Repository https://github.com/docsforadobe/after-effects-expression-reference/
Copyright All content is copyright Adobe Systems Incorporated.

Introduction

Use the After Effects expression elements along with standard JavaScript elements to write your expressions. You can use the Expression Language menu at any time to insert methods and attributes into an expression, and you can use the pick whip at any time to insert properties.

  • For resources on how to get started with expressions, see Resources.
  • For some broad examples, see Examples.
  • For info on changes to the expression engine over the years, see Changelog.

Navigating the docs

Within each page, you'll see categories for each logical group of pages, and then specific pages within each category.

When you open a page, you'll be presented with:

  • A brief introduction to that topic ("This is what the page is about")
  • Headers for Attributes and Methods
    • Attributes are accessible bits of information:
      • thisComp.name gets the name of the comp!
      • text.sourceText.fontSize gets the font size of the text
    • Methods are functions that you run, to either get some other info or generate a result:
      • thisComp.layer("Banana") retrieves a layer called Banana, or
      • text.sourceText.setFontSize(123) will set the font size to 123

  • A list of each expression method or attribute alphabetically sorted under its header, which includes:

    • The name of the item
    • At least one way of how to access it from an expression (ie if you want to use the "TextStyle.font" item, you access it via text.sourceText.style.font)
    • A brief description on what the item does & how it works

    • The type of info an attribute provides, or the type of info a method returns(1)

      1. Some return-value descriptions include a number in square brackets—this number specifies the dimension of the returned property or Array.

        If a specific dimension is not included, the dimension of the returned Array depends on the dimension of the input.

    • (Methods only) A list of all arguments/parameters needed to call the method, including optional arguments/parameters(1)

      1. If an argument description contains an equal sign (=) and a value (such as t=time or width=.2), then the argument uses the included default value if you don't specify a different value.

        Some argument descriptions include a number in square brackets—this number indicates the dimension of the expected property or Array.

    • And, sometimes, an example showing how to use that item

Tip

The docs also include notes (where applicable) indicating any other warnings, bugs, issues, or tips that may apply to a given item. We've also tried to provide info on when an item was added into After Effects, so that you can ensure it'll work for your project.

A Note on Sources

Please note that the majority of this document is community-supported and community-generated by volunteers just trying to help out!

While we're lucky enough to have some Adobe staff keeping these docs up-to-date with each version of After Effects, their time and energy is also being donated in a volunteer capacity.

If you have any questions, comments, or concerns about anything in these docs – or if you'd like to contribute (no code experience necessary!), propose suggestions, or anything else – please reach out to the admins at hi@docsforadobe.dev.

Introduction ↵

Changelog

What's new and changed for expressions?

After Effects 25.0 (October 2024)

Added many new text style properties and methods for both characters and paragraphs, as well as the ability to control per-character styling through expressions.

After Effects 17.7 (Feb 2021)

  • Fixed: An issue where expression edits made in the Graph Editor were not applied consistently.

After Effects 17.6 (Jan 2021)

  • Fixed: An issue that could cause an expression to be replaced instead of appending when using expression or property pick-whip.

After Effects 17.1.2 (Jul 2020)

  • Fixed: An issue where Markers could not be referenced by name in the JavaScript Expressions Engine.

After Effects 17.1 (May 19 2020)

  • Fixed: An issue with Expression editor to auto-complete 'timeToFrames' function.

After Effects 17.0.5 (Mar 2020)

  • Fixed: An issue where the Link Focus to Layer command produced an expression that did not work with the JavaScript expression engine.

After Effects 17.0.2 (Jan 2020)

  • Fixed: An issue where wrong line numbers would be displayed related to errors in JavaScript expressions.

After Effects 17.0 (Jan 24 2020)

  • Implemented Dropdown Menu Expression Control
  • Expression Editor improvements:
    • You can now use the new scrolling functionality to prevent the scroll from adjusting incorrectly when the box is resized by typing the return character.
    • Prevent numbers from matching in an autocomplete list if the variable begins with a number. Smarter autocomplete prevents from overriding closing brackets and quotes.
    • You can now scale font size for Hi-DPI displays.
    • Graph editor now commits changes in preferences for all the open graph editors.
    • If you enable syntax highlight, the folding icon buttons in the UI now respect the default and background color, or the line numbers color and background color.
  • Expression performance improvements:
    • After Effects now attempts to detect an expression that does not change throughout a comp and calculates the expression only once. Load your favorite expression-filled comp and experience the improved performance.
    • Any expression using posterizeTime() now calculates only once for the entire comp, not on every frame.
  • Added: Extended expressions access to Text properties.

After Effects 16.1.3 (Sep 2019)

  • Fixed: Indentation of curly braces on new lines could be incorrect in the Expressions editor.

After Effects 16.1.2 (June 2019)

  • Fixed: After Effects crashes when you close a project that has an expression containing an error.
  • Fixed: Expression error messages could be truncated in the error ribbon if there were multiple lines of error text to show.
  • Fixed: The property, this_Layer had stopped working when using the Legacy ExtendScript expression engine.
  • Fixed: Crash when switching the project level expression engine from JavaScript to Legacy ExtendScript.
  • Fixed: Crash with expressions that contain calls to Date.toLocaleString().
  • Fixed: Crash when editing expressions in the Graph Editor expression field when AutoComplete is disabled.

After Effects 16.1 (CC 19) (Apr 2 2019)

  • Implemented new expression editor
  • Fixed: The JavaScript expressions engine does not generate the same random number results as the Legacy ExtendScript engine.
  • Fixed: When an expression references the name of a layer in a string or in a Source Text property, the name of the layer is not returned. Instead, it returns [Object].
  • Fixed: The sampleImage() expression method returns the wrong value if the post-expression value of the property is read by a ScriptUI panel.
  • Fixed: Applying the createPath() expression via the Expression Language menu autofills the (is_Closed) parameter as deprecated snake case instead of camel caseisClosed.
  • Fixed: Renaming an effect that is referenced by an expression causes the expression to incorrectly update references to that effect properties when those properties have the same name as the effect.
  • Fixed: The Link Focus Distance to Layer, Link Focus Distance to Point of Interest, Create Stereo 3D Rig, and Create Orbit Null commands create expressions that are incompatible with the JavaScript expression engine.
  • Fixed: Specific complex, multi-composition expressions cause fast flickering of the expression error warning banner and icons. Note that to fix this, there is a small slowdown in expression evaluation speed for these expressions.

After Effects 16.0 (CC 19) (Oct 15 2018)

After Effects 15.1.2 (Jul 16 2018)

  • Fixed: If your project contains multiple master properties by the same name, the expressions that refer to the master properties evaluate incorrectly.
  • Fixed: The Property Link pick whip incorrectly writes a self-referential expression for the other selected properties.

After Effects 15.1 (Apr 3 2018)

After Effects 15.0 (CC) (Oct 18 2017)

After Effects 13.6 (CC 2015) (Nov 30 2015)

  • Improved performance of expressions on time-remapped layers. This also reduces rendering time for audio on time-remapped layers with expressions.
  • Fixed: Changing the source text of a text layer no longer causes expressions to fail when the name of the text layer was referenced.
  • Fixed: After Effects no longer crashes when the graph editor is displayed while processing an time remapping expression.

After Effects 13.5 (CC 2015) (Jun 15 2015)

  • More efficient expression evaluation
  • Added: Expression warning banner

After Effects 13.2 (CC 2014.2) (Dec 16 2014)

After Effects 12.1 (CC) (Sep 8 2013)

After Effects 10.5 (CS5.5) (Apr 11 2011)

After Effects 5.5 (Jan 7 2002)

  • Added: Looping via expressions
  • Added: Expression controllers

After Effects 5.0 (Apr 2001)

  • Expressions first added

Resources

Note

Have suggestions for new resources to add here? Please reach out! Happy to add your site, book, training channel, etc.

Dan Ebberts provides example expressions and tutorials for learning how to work with expressions on his MotionScript website. For example, Dan provides an excellent page about collision detection.

The AE Enhancers forum provides many examples and much useful information about expressions, as well as scripts and animation presets. In this post on the AE Enhancers forum, Paul Tuersley provides a tutorial and example project that show how to use expressions to animate several layers in a swarm.

Rick Gerard provides an example on Rick's site that demonstrates rolling a square object along a floor so that the sides stay in contact with the floor plane.

Chris Zwar provides an example project on chriszwar.com for automatically arranging still images or videos into a grid (like a video wall). You can easily adjust position and spacing with sliders that are connected to a system of expressions. There are three compositions in the project—one for stills, one for videos, and one to create an auto-storyboard in which a video is sampled at user-defined intervals and aligned into a grid.

JJ Gifford's website provides several example projects that demonstrate how to use expressions.

Examples

Note

Many of the examples in this section are based on expressions provided by Dan Ebberts.

Get this project's AEP name (AE 15.1+ only)

While there is no method to directly access your AEP's name, you CAN get the full path to the AEP.

With some string manipulation, you can derive the aep name from this:

var aepName = thisProject.fullPath.split($.os.indexOf("Windows") > -1 ? "\\" : "/").pop();

If you wanted to write "Unsaved" in that case, you can use the following expression:

var aepName = thisProject.fullPath.split($.os.indexOf("Windows") > -1 ? "\\" : "/").pop();
aepName = aepName === "" ? "Unsaved" : aepName;

Make a layer revolve in a circle

You can create an expression without using properties from other layers. For example, you can make a layer revolve in a perfect circle.

  1. Select a layer, press P to reveal its Position property in the Timeline panel, and Alt-click (Windows) or Option-click (Mac OS) the stopwatch to the left of the property name.
  2. Enter the following in the expression field: 
    [(thisComp.width/2), (thisComp.height/2)] + [Math.sin(time)*50, -Math.cos(time)*50]

Rotate the hands of a clock

You can use the pick whip to link rotation values between layers to animate the hands on a clock—as the hour hand moves from hour to hour, the minute hand rotates the full circumference of the clock face. This type of animation would take a long time to create if you had to set each keyframe for both hand layers, but with the pick whip, you can do it in a matter of minutes.

  1. Import or create two long, narrow solid-color layers: an hour hand and a minute hand.
  2. Set the anchor points at the ends of the layers.
  3. Move the layers so that the anchor points are at the center of the composition.
  4. Set Rotation keyframes for the hour hand.
  5. Select the Rotation property for the minute hand and choose Animation > Add Expression.
  6. Drag the pick whip to the Rotation property for the hour hand. The following expression appears: 
    thisComp.layer("hour hand").rotation
  7. To make the minute hand rotate 12 times as fast as the hour hand, add * 12 at the end of the expression as follows: 
    thisComp.layer("hour hand").rotation * 12

Position one layer between two others

This example expression positions and maintains one layer at a balanced distance between two other layers.

  1. Start with three layers.
  2. Animate the positions of the first two layers in the Timeline panel.
  3. Select the third layer, press P to reveal the Position property, and Alt-click (Windows) or Option-click (Mac OS) the stopwatch button to the left of the property name.
  4. Enter the following in the expression field: 
    (thisComp.layer(1).position + thisComp.layer(2).position)/2

Create a trail of images

This example expression instructs a layer to be at the same position as the next higher layer in the Timeline panel, but delayed by a specified amount of time (in this case, 0.5 seconds). You can set similar expressions for the other geometric properties.

  1. Start with two solid-color layers that are scaled to approximately 30% of the composition size. (See Solid-color layers and solid-color footage items.)
  2. Animate the position of the first layer.
  3. Select the second layer, press P to reveal the Position property, and Alt-click (Windows) or Option-click (Mac OS) the stopwatch button to the left of the property name.
  4. Enter the following in the expression field: 
    thisComp.layer(thisLayer, -1).position.valueAtTime(time - .5)
  5. Duplicate the last layer five times by selecting it and pressing Ctrl+D (Windows) or Command+D (Mac OS) five times.

All layers follow the same path, and each is delayed 0.5 seconds from the previous.

Note

Dan Ebberts provides more examples and techniques for creating trails of images on his MotionScript.

Create a bulge between two layers

This example expression synchronizes the Bulge Center argument of the Bulge effect in one layer with the position of another layer. For example, you can create an effect that looks like a magnifying glass moving over a layer, with the contents under the magnifying glass bulging as the lens (that is, the overlying layer) moves. This expression uses the fromWorld method, which makes the expression work correctly regardless of whether you move the magnifying glass layer or the underlying layer. You can rotate or scale the underlying layer, and the expression stays intact.

You can also use other effects, such as Ripple, with this expression.

  1. Start with two layers. Make one layer a magnifying glass or similar object with a hole in the middle and name it Magnifier. (See Creating layers.)
  2. Animate the position of the magnifying glass layer. (See Motion paths.)
  3. Apply the Bulge effect to the other layer. (See Apply an effect or animation preset.)
  4. Select the Bulge Center property of the Bulge effect in the Timeline panel and choose Animation > Add Expression, or Alt-click (Windows) or Option-click (Mac OS) the stopwatch button for the property.
  5. Select the default expression text and type the following: 
    fromWorld(thisComp.layer("Magnifier").position)

Fade opacity of a 3D layer based on distance from camera

Apply the following expression to the Opacity property of a 3D layer:

startFade = 500; // Start fade 500 pixels from camera.
endFade = 1500;  // End fade 1500 pixels from camera.

try { // Check whether there's a camera
C = thisComp.activeCamera.toWorld([0,0,0]);
} catch (err) { // No camera, so assume 50mm
w = thisComp.width * thisComp.pixelAspect;
z = (w/2)/Math.tan(degreesToRadians(19.799));
C = [0,0,-z];
}

P = toWorld(anchorPoint);
d = length(C,P);

linear(d,startFade,endFade,100,0)

The fade starts at a distance of 500 pixels from the camera and is complete at 1500 pixels from the camera. The linear interpolation method is used to map distance values to opacity values.

Make a 3D layer invisible if facing away from camera

Apply the following expression to the Opacity property of a 3D layer:

if (toCompVec([0, 0, 1])[2] > 0 ) value else 0

Note

Dan Ebberts explains this expression on his site.

Flip layer horizontally if facing away from camera

Apply the following expression to the Scale property of a 3D layer:

if (toCompVec([0, 0, 1])[2] > 0 ) value else [-value[0], value[1], value[2]]

Animate scale at each layer marker

Apply the following expression to a Scale property to make a layer wobble at each marker:

n = 0;
t = 0;

if (marker.numKeys > 0){
    n = marker.nearestKey(time).index;
    if (marker.key(n).time > time) n--;
}

if (n > 0) t = time - marker.key(n).time;

amp = 15;
freq = 5;
decay = 3.0;

angle = freq * 2 * Math.PI * t;
scaleFact = (100 + amp * Math.sin(angle) / Math.exp(decay * t)) / 100;
[value[0] * scaleFact, value[1] / scaleFact];

Start or stop wiggle at specific time

You can use any expression in place of the wiggle expression used here, to begin and end the influence of any expression at a specific time.

Apply the following expression to a property to wiggle it beginning at time 2 seconds:

timeToStart = 2;
if (time > timeToStart) {
wiggle(3,25);
} else {
    value;
}

Apply the following expression to a property to stop wiggling it at time 4 seconds:

timeToStop = 4;

if (time > timeToStop) {
        value;
} else {
        wiggle(3,25);
}

Apply the following expression to a property to start wiggling it at time 2 seconds and stop wiggling it at time 4 seconds:

timeToStart = 2;
timeToStop = 4;

if ((time > timeToStart) && (time < timeToStop)) {
    wiggle(3,25);
} else {
    value;
}

Match camera focal plane to another layer

Apply the following expression to the Focus Distance property of a camera layer to have its focus distance match the distance to the anchor point of a layer named "target":

target = thisComp.layer("target");
V1 = target.toWorld(target.anchorPoint) - toWorld([0,0,0]);
V2 = toWorldVec([0,0,1]);
dot(V1,V2);

Note

Dan Ebberts explains this expression example in detail on his website.

Ended: Introduction

General ↵

General

The methods and attributes in this category apply to–and can be used by–nearly every expression in After Effects.

These global, top-level elements have been grouped into several categories for the sake of organization.

Those categories are:

  • Global is for broad, commonly-used elements such as the current comp or property; the current comp time, and so on.
  • Time Conversion holds various methods for converting time to and from various other methods.
  • Vector Math provides a suite of methods for working with vectors and arrays.
  • Random Numbers is for generating randomness within your expression.
  • Interpolation is for converting values from one set to another, or using one set of values to drive another set of values.
  • Color Conversion is for changing between colour modes (such as converting RGB values to HSL, or Hex values to RGB)
  • Other Math is for all other assorted math– namely, converting between degrees and radians for rotation values.

Global

These attributes and methods are global, top-level elements accessible from any expression across your project. They're among the most commonly-used expression elements.

Attributes

colorDepth

colorDepth

Description

Type the project color depth value.

For example, colorDepth returns 16 when the project color depth is 16 bits per channel.

Type

Number

thisComp

thisComp

Description

Represents the composition containing the expression.

Type

Comp

thisLayer

thisLayer

Description

Represents the layer containing the expression.

Because thisLayer is the default object, its use is optional.

For example, you can start an expression with thisLayer.width or width and get the same result.

Type

Layer, Light, or Camera object

thisProject

thisProject

Description

Represents the project which contains the expression.

Type

Project

thisProperty

thisProperty

Description

Represents the property containing the expression.

For example, if you write an expression on the Rotation property, you can start an expression with thisProperty to refer to the Rotation property.

Type

Property

time

time

Description

Represents the composition time, in seconds, at which the expression is being evaluated.

Type

Number

value

value

Description

Represents the value at the current time for the property containing the expression.

Type

A value of the same property type as the property being refrenced.

Methods

comp()

comp(name)

Description

Retrieves another composition by name.

Parameters

Parameter Type Description
name String The name of the composition to get

Returns

Comp

footage()

footage(name)

Description

Retrieves a footage item by name.

Parameters

Parameter Type Description
name String The name of the footage item to get

Returns

Footage

posterizeTime()

posterizeTime(updatesPerSecond)

Description

This expression allows you to set the frame rate for a property to be lower than the frame rate of the composition.

Parameters

Parameter Type Description
updatesPerSecond Number The number of times per second the expression should evaluate

Returns

Number

Example

To change a property to a random value 1 time per second:

posterizeTime(1);

random()

To change a 2d property (such as Position or Scale) to a random value 3 times per second:

posterizeTime(3);

const newValue = random(0, 100);
[newValue, newValue];

To change a property to a random value within a specified range, every 12 frames:

const holdFrames = 12;
const minValue = 50;
const maxValue = 100;

posterizeTime(1 / framesToTime(holdFrames));

const newValue = random(minValue, maxValue);
newValue;

Time Conversion

These methods are all about converting between various time formats.

Tip

If you want more control over the look of timecode in your footage, use the timeToCurrentFormat() method or other timeTo methods to generate the timecode instead of using the Timecode or Numbers effect.

Example

You can easily format and animate the timecode text by creating a text layer, applying whatever text styling you'd like, and adding this expression to the Source Text property:

timeToCurrentFormat();

Methods

framesToTime()

framesToTime(frames[, fps=1.0 / thisComp.frameDuration])

Description

Returns the time corresponding to the frames argument. It doesn't have to be an integer.

The inverse of timeToFrames().

Parameters

Parameter Type Description
frames Number The amount of frames to convert.
fps Number Optional. The number of frames per second to use to convert. Defaults to 1.0 / thisComp.frameDuration (the frame rate of the current composition).

Returns

Number

timeToCurrentFormat()

timeToCurrentFormat([t=time + thisComp.displayStartTime][, fps=1.0 / thisComp.frameDuration][, isDuration=false][, ntscDropFrame=thisComp.ntscDropFrame])

Description

Converts the value of t to a String representing time in the current Project Settings display format.

Parameters

Parameter Type Description
t Number Optional. The time (in seconds) to convert. Defaults to time + thisComp.displayStartTime.
fps Number Optional. Defaults to 1.0 / thisComp.frameDuration (the frame rate of the current composition).
isDuration Boolean Optional. Whether t represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to false.
ntscDropFrame Boolean Optional. If false, the result is NTSC non-drop-frame timecode. If true, the result is NTSC drop-frame timecode. Defaults to thisComp.ntscDropFrame.

Note

The ntscDropFrame argument was added in After Effects CS5.5.

Returns

String

timeToFeetAndFrames()

timeToFeetAndFrames([t=time + thisComp.displayStartTime][, fps=1.0 / thisComp.frameDuration][, framesPerFoot=16][, isDuration=false])

Description

Converts the value of t to a String representing feet of film and frames.

Parameters

Parameter Type Description
t Number Optional. The time (in seconds) to convert. Defaults to time + thisComp.displayStartTime.
framesPerFoot Number Optional. Specifies the number of frames in one foot of film. Defaults to 16 (the most common rate for 35mm footage).
isDuration Boolean Optional. Whether t represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to false.

Returns

String

timeToFrames()

timeToFrames([t=time + thisComp.displayStartTime][, fps=1.0 / thisComp.frameDuration][, isDuration=false])

Description

Converts the value of t (some amount of time, in seconds) to an integer number of frames.

Parameters

Parameter Type Description
t Number Optional. The time (in seconds) to convert. Defaults to time + thisComp.displayStartTime.
fps Number Optional. The number of frames per second to use to convert. Defaults to 1.0 / thisComp.frameDuration (the frame rate of the current composition).
isDuration Boolean Optional. Whether t represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to false.

Returns

Number

timeToNTSCTimecode()

timeToNTSCTimecode([t=time + thisComp.displayStartTime][, ntscDropFrame=false][, isDuration=false])

Description

Converts t to a String representing NTSC timecode.

Parameters

Parameter Type Description
t Number Optional. The time (in seconds) to convert. Defaults to time + thisComp.displayStartTime.
ntscDropFrame Boolean Optional. If false, the result is NTSC non-drop-frame timecode. If true, the result is NTSC drop-frame timecode. Defaults to false.
isDuration Boolean Optional. Whether t represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to false.

Returns

String

timeToTimecode()

timeToTimecode([t=time + thisComp.displayStartTime][, timecodeBase=30][, isDuration=false])

Description

Converts the value of t to a String representing timecode.

Parameters

Parameter Type Description
t Number Optional. The time (in seconds) to convert. Defaults to time + thisComp.displayStartTime.
timecodeBase Number Optional. Specifies the number of frames in one second. Defaults to 30.
isDuration Boolean Optional. Whether t represents a difference between two times, vs an absolute time. Absolute times are rounded down toward negative infinity; durations are rounded away from zero (up for positive values). Defaults to false.

Returns

String

Vector Math

Vector Math functions are global methods that perform operations on arrays, treating them as mathematical vectors.

Unless otherwise specified, Vector Math methods are lenient about dimensions and return a value that is the dimension of the largest input Array object, filling in missing elements with zeros.

Unlike built-in JavaScript methods, such as Math.sin, these methods are not used with the Math prefix.

Example

This expression returns [11, 22, 3]:

add([10, 20], [1, 2, 3])

Methods

add()

add(vec1, vec2)

Description

Adds two vectors.

Parameters

Parameter Type Description
vec1 Array First vector to add.
vec2 Array Second vector to add.

Returns

Array

clamp()

clamp(value, limit1, limit2)

Description

The value of each component of value is constrained to fall between the values of the corresponding values of limit1 and limit2.

Parameters

Parameter Type Description
value Number or Array Value to clamp.
limit1 Number or Array Minimum amount to clamp value to.
limit2 Number or Array Maximum amount to clamp value to.

Returns

Number or Array

Example

Ensure that a wiggled amount never exceeds the 0-100 range:

const wiggled = wiggle(0.5, 500);
clamp(wiggled, 0, 500);

cross()

cross(vec1, vec2)

Description

Returns the vector cross product of vec1 and vec2.

Refer to a math reference or JavaScript guide for more information.

Parameters

Parameter Type Description
vec1 Array (2- or 3-dimensional) First vector to calculate cross product of.
vec2 Array (2- or 3-dimensional) Second vector to calculate cross product of.

Returns

Array (2- or 3-dimensional)

div()

div(vec, amount)

Description

Divides every element of the vector by the amount.

Parameters

Parameter Type Description
vec Array The vector to divide
amount Number The amount to divide by

Returns

Array

dot()

dot(vec1, vec2)

Description

Returns the dot (inner) product of the vector arguments.

Parameters

Parameter Type Description
vec1 Array First vector to calculate dot product of.
vec2 Array Second vector to calculate dot product of.

Returns

Number

length()

length(vec[, point2])

Description

Returns the length of vector vec.

If a second argument is provided, instead treats the first argument as a point and returns the distance between the two points.

Tip

Using length() with two arguments is the same as length(sub(vec, point2)).

Parameters

Parameter Type Description
vec Array The vector to normalize, or the first point to measure from.
point2 Array Optional. The second point to measure to.

Returns

Number

Example

For example, add this expression to the Focus Distance property of a camera to lock the focal plane to the camera's point of interest so that the point of interest is in focus:

length(position, pointOfInterest)

lookAt()

lookAt(fromPoint, atPoint)

Description

Orients a layer to look at a given point, from a given point.

The return value can be used as an expression for the Orientation property, making the z-axis of the layer point at atPoint.

This method is especially useful for cameras and lights.

Tip

If you use this expression on a camera, turn off auto-orientation.

Parameters

Parameter Type Description
fromPoint Array (3-dimensional) The location (in world space) of the layer to orient.
atPoint Array (3-dimensional) The point (in world space) you want to point the layer at.

Returns

Array (3-dimensional)

Example

This expression on the Orientation property of a spot light makes the light point at the anchor point of layer number 1 in the same composition:

lookAt(position, thisComp.layer(1).position)

mul()

mul(vec, amount)

Description

Multiplies every element of the vector by the amount.

Parameters

Parameter Type Description
vec Array The vector to multiply
amount Number The amount to multiply by

Returns

Array

normalize()

normalize(vec)

Description

Normalizes the vector so that its length is 1.0.

Using the normalize method is a short way of performing the operation div(vec, length(vec)).

Parameters

Parameter Type Description
vec Array The vector to normalize

Returns

Array

sub()

sub(vec1, vec2)

Description

Subtracts two vectors.

Parameters

Parameter Type Description
vec1 Array The first vector
vec2 Array The second vector

Returns

Array

Random Numbers

These items deal with randomness in expressions.

Note

The wiggle() method—which is used to randomly vary a property value—is in the Property attributes and methods category.

Methods

gaussRandom()

gaussRandom([maxValOrArray=1])

Description

When maxValOrArray is a Number, this method returns a random number. Approximately 90% of the results are in the 0 to maxValOrArray range, and the remaining 10% are outside this range.

When maxValOrArray is an Array, this method returns an Array of random values, with the same dimension as maxValOrArray. 90% of the values are in the range from 0 to maxValOrArray, and the remaining 10% are outside this range.

The results have a Gaussian (bell-shaped) distribution.

Parameters

Parameter Type Description
maxValOrArray Number or Array Optional. The max value (or array) to generate a random number to, from 0. Defaults to 1.

Returns

Number or Array

gaussRandom(minValOrArray, maxValOrArray)

gaussRandom(minValOrArray, maxValOrArray)

Description

If minValOrArray and maxValOrArray are Numbers, this method returns a random number. Approximately 90% of the results are in the range from minValOrArray to maxValOrArray, and the remaining 10% are outside this range.

If the arguments are Arrays, this method returns an Array of random numbers with the same dimension as the argument with the greater dimension. For each component, approximately 90% of the results are in the range from the corresponding component of minValOrArray to the corresponding component of maxValOrArray, and the remaining 10% are outside this range.

The results have a Gaussian (bell-shaped) distribution.

Parameters

Parameter Type Description
minValOrArray Number or Array The min value (or array) to generate a random number from.
maxValOrArray Number or Array The max value (or array) to generate a random number to.

Returns

Number or Array

noise(valOrArray)

noise(valOrArray)

Description

Returns a number in the range from -1 to 1.

The noise is not actually random; it is based on Perlin noise, which means that the return values for two input values that are near one another tend to be near one another.

This type of noise is useful when you want a sequence of seemingly random numbers that don't vary wildly from one to the other—as is usually the case when animating any apparently random natural motion.

Parameters

Parameter Type Description
valOrArray Number or an Array (2- or 3-dimensional) The input value (or array) to use to generate the random number.

Returns

Number

Example

rotation + 360*noise(time)

random()

random([maxValOrArray=1])

Description

If maxValOrArray is a Number, this method returns a number in the range from 0 to maxValOrArray.

If maxValOrArray is an Array, this method returns an Array with the same dimension as maxValOrArray, with each component ranging from 0 to the corresponding component of maxValOrArray.

Note

In After Effects CC and CS6, the behavior of random() is changed to be more random when layer IDs are close together. The wiggle() expression is not affected.

Parameters

Parameter Type Description
maxValOrArray Number or Array Optional. The max value (or array) to generate a random number to, from 0. Defaults to 1.

Returns

Number or Array

random(minValOrArray, maxValOrArray)

random(minValOrArray, maxValOrArray)

Description

If minValOrArray and maxValOrArray are Numbers, this method returns a number in the range from minValOrArray to maxValOrArray.

If the arguments are Arrays, this method returns an Array with the same dimension as the argument with the greater dimension, with each component in the range from the corresponding component of minValOrArray to the corresponding component of maxValOrArray.

For example, the expression random([100, 200], [300, 400]) returns an Array whose first value is in the range 100–300 and whose second value is in the range 200–400. If the dimensions of the two input Arrays don't match, higher-dimension values of the shorter Array are filled out with zeros.

Parameters

Parameter Type Description
minValOrArray Number or Array The min value (or array) to generate a random number from.
maxValOrArray Number or Array The max value (or array) to generate a random number to.

Returns

Number or Array

seedRandom()

seedRandom(offset[, timeless=false])

Description

The random() and gaussRandom() methods use a seed value that controls the sequence of numbers.

By default, the seed is computed as a function of a unique layer identifier, the property within the layer, the current time, and an offset value of 0.

Call seedRandom() to set the offset to something other than 0 to create a different random sequence.

The multiplication by 100 in this example converts the value in the range 0–1 returned by the random method into a Number in the range 0–100; this range is more typically useful for the Opacity property, which has values from 0% to 100%.

Parameters

Parameter Type Description
offset Number The value with which to offset the seed. This is also used to control the initial value of the wiggle() function.
timeless Boolean Optional. Use true for the timeless argument to not use the current time as input to the random seed. This allows you to generate a random number that doesn't vary depending on the time of evaluation. Defaults to false.

Returns

None

Example

This expression on the Opacity property sets the Opacity value to a random value that does not vary with time:

seedRandom(123456, true);
random()*100

Interpolation

For all the Interpolation methods, the argument t is often time or value, though it can have other values, instead. If t is time, the interpolation between values happens over a duration. If t is value, then the expression maps one range of values to a new range of values.

All the Interpolation methods can also be used to convert from one range of values to another.

Chris and Trish Meyer provide additional information and examples for these methods in an article on the ProVideo Coalition website.

Ian Haigh provides a script on After Effects Scripts website that you can use to easily apply advanced interpolation method expressions—such as bounces—to properties.

Methods

linear(t, tMin, tMax, value1, value2)

linear(t, tMin, tMax, value1, value2)

Description

Returns value1 when t <= tMin. Returns value2 when t >= tMax. Returns a linear interpolation between value1 and value2 when tMin < t < tMax.

Parameters

Parameter Type Description
t Number Interpolation Driver
tMin Number Minimum driver value
tMax Number Maximum driver value
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

Example

This expression on the Opacity property causes Opacity values to ramp linearly from 20% to 80% over the time from 0 seconds to 6 seconds:

linear(time, 0, 6, 20, 80)

This expression on the Opacity property converts the Opacity values from the range 0%-100% to the range 20%-80%:

linear(value, 0, 100, 20, 80)

linear(t, value1, value2)

linear(t, value1, value2)

Description

Returns a value that linearly interpolates from value1 to value2 as t ranges from 0 to 1. Returns value1 when t <= 0. Returns value2 when t >= 1.

Parameters

Parameter Type Description
t Number Interpolation Driver
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

ease(t, tMin, tMax, value1, value2)

ease(t, tMin, tMax, value1, value2)

Description

Similar to linear with the same arguments, except that the interpolation eases in and out so that the velocity is 0 at the start and end points. This method results in a smooth animation.

Parameters

Parameter Type Description
t Number Interpolation Driver
tMin Number Minimum driver value
tMax Number Maximum driver value
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

ease(t, value1, value2)

ease(t, value1, value2)

Description

Similar to linear with the same arguments, except that the interpolation eases in and out so that the velocity is 0 at the start and end points. This method results in a smooth animation.

Parameters

Parameter Type Description
t Number Interpolation Driver
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

easeIn(t, tMin, tMax, value1, value2)

easeIn(t, tMin, tMax, value1, value2)

Description

Similar to ease, except that the tangent is 0 only on the tMin side and interpolation is linear on the tMax side.

Parameters

Parameter Type Description
t Number Interpolation Driver
tMin Number Minimum driver value
tMax Number Maximum driver value
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

easeIn(t, value1, value2)

easeIn(t, value1, value2)

Description

Similar to ease, except that the tangent is 0 only on the value1 side and interpolation is linear on the value2 side.

Parameters

Parameter Type Description
t Number Interpolation Driver
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

easeOut(t, tMin, tMax, value1, value2)

easeOut(t, tMin, tMax, value1, value2)

Description

Similar to ease, except that the tangent is 0 only on the tMax side and interpolation is linear on the tMin side.

Parameters

Parameter Type Description
t Number Interpolation Driver
tMin Number Minimum driver value
tMax Number Maximum driver value
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

easeOut(t, value1, value2)

easeOut(t, value1, value2)

Description

Similar to ease, except that the tangent is 0 only on the value2 side and interpolation is linear on the value1 side.

Parameters

Parameter Type Description
t Number Interpolation Driver
value1 Number or Array Value to interpolate from
value2 Number or Array Value to interpolate to

Returns

Number or Array

Color Conversion

These methods are all around converting colours from one format to another. Think converting a hex code to RGB, so you can use your client's brand colours in an expression in the project, or converting a value to HSL so you can adjust the lightness or saturation procedurally.

Methods

rgbToHsl()

rgbToHsl(rgbaArray)

Description

Converts a color in RGBA space to HSLA space.

The input is an Array of normalized red, green, blue, and alpha channel values, all in the range of 0.0 to 1.0.

The resulting value is an Array of hue, saturation, lightness, and alpha channel values, also in the range of 0.0 to 1.0.

Parameters

Parameter Type Description
rgbaArray Array of numbers (4-dimensional) RGBA values, in the range [0.0..1.0]

Returns

HSLA Array (4-dimensional)

Example:

rgbToHsl.effect("Change Color")("Color To Change")

hslToRgb()

hslToRgb(hslaArray)

Description

Converts a color in HSLA space to RGBA space.

This conversion is the opposite of the conversion performed by the rgbToHsl() method.

Parameters

Parameter Type Description
hslaArray Array of numbers (4-dimensional) HSLA values, in the range [0.0..1.0]

Returns

RGBA Array (4-dimensional)

hexToRgb()

hexToRgb(hexString)

Note

This functionality was added in After Effects 16.0.

Description

Converts a color in hex triplet space to RGB space, or in hex quartet space to RGBA space.

For hex triplets, the alpha channel defaults to 1.0.

Parameters

Parameter

Type

Description

hexString

Optional leading characters 0x, 0X, or # will be ignored. Characters beyond 8 digits will be ignored.

String

Hex triplet (6 digits, no alpha channel) or quartet (8 digits, includes alpha channel) containing only numerals or characters A–F.

Returns

Array (4-dimensional)

Examples

Any of the following will return [1.0, 0.0, 1.0, 1.0]:

  • hexToRgb("FF00FF")
  • hexToRgb("#FF00FF")
  • hexToRgb("0xFF00FF")
  • hexToRgb("0XFF00FFFF")
    • Note: This inputs an 8-digit hex quartet; the last two digits set alpha channel to 1.0.

Other Math

This category holds other math functions not otherwise covered.

Methods

degreesToRadians()

degreesToRadians(degrees)

Description

Converts degrees to radians.

Parameters

Parameter Type Description
degrees Number The value (in degrees) to convert to radians

Returns

Number

radiansToDegrees()

radiansToDegrees(radians)

Description

Converts radians to degrees.

Parameters

Parameter Type Description
radians Number The value (in radians) to convert to degrees

Returns

Number

Ended: General

Objects ↵

Project

thisProject

This category holds info related to your current project as a whole -- that is, the current AEP. Thus, changing the corresponding project settings will also update the values that these expressions return.

Attributes

Project.bitsPerChannel

thisProject.bitsPerChannel

Description

The color depth of the project in bits per channel (bpc), as set in Project Settings > Color Management

They are one of 8, 16, or 32. Equivalent to the scripting project attribute app.project.bitsPerChannel.

Type

Number

Example

thisProject.bitsPerChannel

Project.fullPath

thisProject.fullPath

Description

The platform-specific absolute file path, including the project file name. If the project has not been saved, it returns an empty string.

Type

String

Example

thisProject.fullPath

Project.linearBlending

thisProject.linearBlending

Description

The state of the Blend Colors Using 1.0 Gamma option in Project Settings > Color Management.

Equivalent to the scripting project attribute app.project.linearBlending.

Type

Boolean

Example

thisProject.linearBlending

Comp

thisComp

comp("CompName")

layer("layerName").source

These attributes and methods can be called on Comp objects.

These are typically accessed in a few ways, most commonly:

  • thisComp to get the Comp object of the active comp the expression is written in,
  • comp("CompName") to get a specific comp by name,
  • layer("layerName").source, if referring to a precomp layer, to get the targeted precomp layer's source comp

Info

On this page, we're going to use thisComp as a sample on how to call these items, however note that any method that returns a Comp will work.

Attributes

Comp.activeCamera

thisComp.activeCamera

Description

Returns the Camera object for the camera through which the composition is rendered at the current frame.

This camera is not necessarily the camera through which you are looking in the Composition panel.

Type

Camera

Comp.bgColor

thisComp.bgColor

Description

Returns the background color of the composition.

Type

Array (4-dimensional)

Comp.displayStartTime

thisComp.displayStartTime

Description

Returns the composition start time, in seconds.

Type

Number

Comp.duration

thisComp.duration

Description

Returns the composition duration, in seconds.

Type

Number

Comp.frameDuration

thisComp.frameDuration

Description

Returns the duration of a frame, in seconds.

Type

Number

Comp.height

thisComp.height

Description

Returns the composition height, in pixels.

Type

Number

Comp.marker

thisComp.marker

Description

Returns a given composition's Marker property.

Note

You can no longer access a composition marker by marker number.

If you have a project created in a previous version of After Effects that uses composition marker numbers in expressions, you must change those calls to use marker.key(name) instead. Because the default name of a composition marker is a number, converting the reference to use the name is often just a matter of surrounding the number with quotation marks.

Type

Marker Property

Comp.name

thisComp.name

Description

Returns the name of the composition.

Type

String

Comp.ntscDropFrame

thisComp.ntscDropFrame

Note

This functionality was added in After Effects CS5.5

Description

Returns true if the timecode is in drop-frame format.

Type

Boolean

Comp.numLayers

thisComp.numLayers

Description

Returns the number of layers in the composition.

Type

Number

Comp.pixelAspect

thisComp.pixelAspect

Description

Returns the pixel aspect ratio of the composition.

Type

Number

Comp.shutterAngle

thisComp.shutterAngle

Description

Returns the shutter-angle value of the composition, in degrees.

Type

Number

Comp.shutterPhase

thisComp.shutterPhase

Description

Returns the shutter phase of the composition, in degrees.

Type

Number

Comp.width

thisComp.width

Description

Returns the composition width, in pixels.

Type

Number

Example

Apply the following expression to the Position property of a layer to center the layer in the composition frame:

[thisComp.width / 2, thisComp.height / 2];

Methods

Comp.layer()

thisComp.layer(index)

thisComp.layer(name)

thisComp.layer(otherLayer, relIndex)

Description

Return the Layer object with the specified index or name.

The index value refers to the layer order in the Timeline panel.

The name value refers to the user-specified layer name, or the layer source name if there is no layer name.

If duplicate names exist, After Effects uses the first (topmost) one in the Timeline panel.

If using the otherLayer, relIndex call, this retrieves the layer that is relIndex layers above or below otherLayer.

Parameters

Parameter

Type

Description

index

name

Number

String

Layer name or index to get.

otherLayer

Layer

The "other" layer to start getting layers relative to

relIndex

Number

The number of layers to move above or below the otherLayer

Returns

Layer, Light, or Camera object

Example

Get the 3rd layer in the current comp:

thisComp.layer(3)

Get the layer named "Solid 1" from the current comp:

thisComp.layer("Solid 1")

Check whether the next layer down in the Timeline panel is active:

const nextLayer = thisComp.layer(thisLayer, 1);
nextLayer.active;

Comp.layerByComment()

thisComp.layerByComment(comment)

Description

Retrieves a layer by matching the comment parameter to the value in the layer's Comment column.

The matches are simple text matches. They will match partial words, and are case sensitive. Matching does not appear to use regular expressions or wildcards. If duplicate comments exist, After Effects uses the first (topmost) one in the Timeline panel.

Parameters

Parameter Type Description
comment String The comment to find a layer from

Returns

Layer, Light, or Camera object

Example

// note this will match a layer with a comment "Controller" or "Motion Control"
thisComp.layerByComment("Control");

Footage

footage("myFile")

To use a footage item from the Project panel as an object in an expression, use the global footage method, as in footage("myFile").

You can also access a footage object using the source attribute on a layer whose source is a footage item (i.e. thisLayer.source)

Info

On this page, we're going to use footage("myFile") as a sample on how to call these items, however note that any method that returns a Footage object will work.

Attributes

Footage.duration

footage("myFile").duration

Description

Returns the duration of the footage item, in seconds.

Type

Number

Footage.frameDuration

footage("myFile").frameDuration

Description

Returns the duration of a frame in the footage item, in seconds.

Type

Number

Footage.height

footage("myFile").height

Description

Returns the height of the footage item, in pixels.

Type

Number

Footage.name

footage("myFile").name

Description

Returns the name of the footage item as shown in the Project panel.

Type

String

Footage.ntscDropFrame

footage("myFile").ntscDropFrame

Note

This functionality was added in After Effects CS5.5

Description

Returns true if the timecode is in drop-frame format.

Type

Boolean

Footage.pixelAspect

footage("myFile").pixelAspect

Description

Returns the pixel aspect ratio of the footage item.

Type

Number

Footage.sourceData

footage("myFile").sourceData

Description

Returns the data of a JSON file as an array of sourceData objects.

The structure of the JSON file will determine the size and complexity of the array.

Individual data streams can be referenced as hierarchal attributes of the data.

Type

An array of sourceData objects; read-only.

Example

Given a data stream named "Color", the following will return the value of "Color" from the first data object:

footage("sample.json").sourceData[0].Color

Typical use is to assign a JSON file's sourceData to a variable, and then reference the desired data stream. For example:

const myData = footage("sample.json").sourceData;
myData[0].Color;

Footage.sourceText

footage("myFile").sourceText

Description

Returns the contents of a JSON file as a string.

The eval() method can be used to convert the string to an array of sourceData objects, identical to the results of the Footage.sourceData attribute, from which the individual data streams can be referenced as hierarchal attributes of the data.

Type

String, the contents of the JSON file; read-only.

Example

const myData = eval(footage("sample.json").sourceText);
myData.sampleValue;

Footage.width

footage("myFile").width

Description

Returns the width of the footage item, in pixels.

Type

Number

Methods

Footage.dataKeyCount()

footage("myFile").dataKeyCount(dataPath)

Description

Returns the number of samples in a specificed dynamic data stream in a MGJSON file.

Accepts a single array value to define the path in the hierarchy to the desired dynamic data stream.

Parameters

Parameter Type Description
dataPath Array Required. The path in the hierarchy to a static or dynamic data stream.

Returns

The number of samples in the dynamic data stream.

Example

To return the count of samples for the first child:

footage("sample.mgjson").dataKeyCount([0])

To return the count of samples for the second group:

footage("sample.mgjson").dataKeyCount([1][0])

Footage.dataKeyTimes()

footage("myFile").dataKeyTimes(dataPath[, t0=startTime][, t1=endTime])

Description

Returns the time in seconds for the samples of a specificed dynamic data stream in a MGJSON file.

Optionally specify the time span from which to return samples. By default the time for all samples between startTime and endTime in the dynamicdata stream are returned, as defined by the data stream's samplesTemporalExtent property in the MGJSON file.

Accepts a single array value to define the path in the hierarchy to the desired dynamic data stream.

Parameters

Parameter Type Description
dataPath Array Required. The path in the hierarchy to a static or dynamic data stream.
t0 Number Optional. The start time, in seconds, of the span from which to return samples. Defaults to startTime.
t1 Number Optional. The end time, in seconds, of the span from which to return samples. Defaults to endTime.

Returns

Array of numbers representing the sample times.

Example

Return the times of samples between 1 second and 3 seconds for the first child:

footage("sample.mgjson").dataKeyTimes([0], 1, 3)

Footage.dataKeyValues()

footage("myFile").dataKeyValues(dataPath[, t0=startTime][, t1=endTime])

Description

Returns the values for the samples of a specificed dynamic data stream in a MGJSON file.

Optionally specify the time span from which to return samples. By default the time for all samples between startTime and endTime in the dynamicdata stream are returned, as defined by the data stream's samplesTemporalExtent property in the MGJSON file.

Accepts a single array value to define the path in the hierarchy to the desired dynamic data stream.

Parameters

Parameter Type Description
dataPath Array Required. The path in the hierarchy to a static or dynamic data stream.
t0 Number Optional. The start time, in seconds, of the span from which to return samples. Defaults to startTime.
t1 Number Optional. The end time, in seconds, of the span from which to return samples. Defaults to endTime.

Returns

Array of numbers representing the sample values.

Example

Return the values of samples between 1 second and 3 seconds for the first child:

footage("sample.mgjson").dataKeyValues([0], 1, 3)

Footage.dataValue()

footage("myFile").dataValue(dataPath)

Description

Returns the value of specificed static or dynamic data stream in a MGJSON file.

Accepts a single array value to define the path in the hierarchy to the desired data stream.

Parameters

Parameter Type Description
dataPath Array Required. The path in the hierarchy to a static or dynamic data stream.

Returns

The value of the data stream.

Example

To return data of the first child:

footage("sample.mgjson").dataValue([0])

To return data of the first child in the second group:

footage("sample.mgjson").dataValue([1][0])

Camera

thisLayer.cameraOption

This category is for items specific to Camera Layers.

Info

Camera is a subclass of the Layer object. All methods and attributes of Layer are available when working with Camera, except:

  • source
  • effect
  • mask
  • width
  • height
  • anchorPoint
  • scale
  • opacity
  • audioLevels
  • timeRemap
  • all the 3d material properties

Attributes

Camera.active

thisLayer.cameraOption.active

Description

Returns true if:

  1. The camera is the active camera for the composition at the current time: the video switch for the camera layer is on,
  2. the current time is in the range from the in point of the camera layer to the out point of the camera layer, and
  3. The camera is the first (topmost) such camera layer listed in the timeline panel

Returns false otherwise.

Type

Boolean

Camera.aperture

thisLayer.cameraOption.aperture

Description

Returns the aperture value of a camera, in pixels.

Type

Number

Camera.blurLevel

thisLayer.cameraOption.blurLevel

Description

Returns the blur level value of a camera as a percentage.

Type

Number

Camera.depthOfField

thisLayer.cameraOption.depthOfField

Description

Returns 1 if the Depth Of Field property of a camera is on, or returns 0 if the Depth Of Field property is off.

Type

Boolean Number

Camera.focusDistance

thisLayer.cameraOption.focusDistance

Description

Returns the focus distance value of a camera, in pixels.

Type

Number

Camera.highlightGain

thisLayer.cameraOption.highlightGain

Description

Returns the camera highlight gain, from 1 to 100.

Type

Number

Camera.highlightSaturation

thisLayer.cameraOption.highlightSaturation

Description

Returns the camera highlight saturation, from 1 to 100.

Type

Number

Camera.highlightThreshold

thisLayer.cameraOption.highlightThreshold

Description

Returns the camera highlight threshhold.

  • In an 8-bit comp, this value ranges from 0 to 100
  • In a 16-bit comp, this value ranges from 0 to 32768
  • In a 32-bit comp, this value ranges from 0 to 1.0

Type

Number

Camera.irisAspectRatio

thisLayer.cameraOption.irisAspectRatio

Description

Returns the camera iris aspect ratio, from 1 to 100.

Type

Number

Camera.irisDiffractionFringe

thisLayer.cameraOption.irisDiffractionFringe

Description

Returns the camera iris diffraction fringe, from 1 to 100.

Type

Number

Camera.irisRotation

thisLayer.cameraOption.irisRotation

Description

Returns the iris rotation value, in degrees.

Type

Number

Camera.irisRoundness

thisLayer.cameraOption.irisRoundness

Description

Returns the camera iris roundness value as a percentage.

Type

Number

Camera.irisShape

thisLayer.cameraOption.irisShape

Description

Returns the iris shape value from 1-10, corresponding to the selected dropdown value.

Note

Value 2 is reserved for the divider.

Type

Number

Camera.pointOfInterest

thisLayer.cameraOption.pointOfInterest

Description

Returns the point of interest values of a camera in world space.

Type

Array (3 dimensional)

Camera.zoom

thisLayer.cameraOption.zoom

Description

Returns the zoom values of a camera in pixels.

Type

Number

Example

Here's an expression for the Scale property of a layer that maintains the relative size of the layer in frame while changing the z position (depth) of a layer or the Zoom value of a camera:

cam = thisComp.activeCamera;
distance = length(sub(position, cam.position));
scale * distance / cam.zoom;

Light

thisLayer.lightOption

This category is for items specific to Light Layers.

Info

Light is a subclass of the Layer object. All methods and attributes of Layer are available when working with Light, except:

  • source
  • effect
  • mask
  • width
  • height
  • anchorPoint
  • scale
  • opacity
  • audioLevels
  • timeRemap
  • all the material properties

Note

David Van Brink provides an instructional article and sample project on his omino pixel blog that shows how to use expressions with lights.

Attributes

Light.castsShadows

thisLayer.lightOption.castsShadows

Description

Returns whether the light casts shadows.

Type

Boolean

Light.color

thisLayer.lightOption.color

Description

Returns the color value of a light.

Type

Array (4-dimensional)

Light.coneAngle

thisLayer.lightOption.coneAngle

Description

Returns the cone angle of a light, in degrees.

Type

Number

Light.coneFeather

thisLayer.lightOption.coneFeather

Description

Returns the cone feather value of a light as a percentage.

Type

Number

Light.falloff

thisLayer.lightOption.falloff

Description

Returns the cone falloff dropdown option.

Type

Number

Light.falloffDistance

thisLayer.lightOption.falloffDistance

Description

Returns the falloff distance of a light.

Type

Number

Light.intensity

thisLayer.lightOption.intensity

Description

Returns the intensity values of a light as a percentage.

Type

Number

Light.pointOfInterest

thisLayer.lightOption.pointOfInterest

Description

Returns the point of interest values for a light in world space.

Type

Array (3-dimensional)

Light.radius

thisLayer.lightOption.radius

Description

Returns the radius values of a light.

Type

Number

Light.shadowDarkness

thisLayer.lightOption.shadowDarkness

Description

Returns the shadow darkness value of a light as a percentage.

Type

Number

Light.shadowDiffusion

thisLayer.lightOption.shadowDiffusion

Description

Returns the shadow diffusion value of a light, in pixels.

Type

Number

PropertyGroup

thisLayer("ADBE Effect Parade")

All properties in the Timeline are organized into groups, which share some attributes of properties like name and propertyIndex.

Property Groups can have a fixed number of properties (e.g. an individual effect whose properties don't change) or a variable number of properties (e.g. the "Effects" group itself which can have any number of effect within it).

Top-level groups in a Layer

  • Motion Trackers
  • Text
  • Contents
  • Masks
  • Effects
  • Transform
  • Layer Styles
  • Geometry Options
  • Material Options
  • Audio
  • Data
  • Essential Properties

Nested groups

  • Individual effects
  • Individual masks
  • Shape groups
  • Text Animators

Info

On this page, we're going to use thisLayer("ADBE Effect Parade") (the "Effects" group) as a sample on how to call these items, however note that any method that returns a PropertyGroup will work.

Attributes

PropertyGroup.name

thisLayer("ADBE Effect Parade").name

Description

Returns the name of the property group.

Type

String

PropertyGroup.numProperties

thisLayer("ADBE Effect Parade").numProperties

Description

Returns the number of properties or groups directly within a group.

Note

This does not include properties nested inside child groups.

Type

Number

Example

To find the number of effects applied to a layer:

thisLayer("ADBE Effect Parade").numProperties

PropertyGroup.propertyIndex

thisLayer("ADBE Effect Parade").propertyIndex

Description

Returns the index of a property group relative to other properties or groups in its property group.

Type

Number

Methods

PropertyGroup.propertyGroup()

propertyGroup([countUp=1])

Description

Returns a higher-level property group relative to the property group on which the method is called.

See propertyGroup() for additional details.

Parameters

Parameter Type Description
countUp Number Optional. The number of property groups "up" the hierarchy to climb. Defaults to 1.

Returns

PropertyGroup object

Effect

thisLayer.effect("Bulge")

This category contains information relating to Effects.

Info

On this page, we're going to use thisLayer.effect("Bulge") as a sample on how to call these items, however note that any method that returns an Effect will work.

Attributes

Effect.active

thisLayer.effect("Bulge").active

Description

Returns true if the effect is turned on (the effect switch is selected).

Type

Boolean

Methods

Effect.param()

thisLayer.effect("Bulge").param(name)

thisLayer.effect("Bulge").param(index)

Description

Returns a property within an effect. Effect control points are always in layer space.

This method can be called using either the property's name or its index.

Parameters

Parameter

Type

Description

name

index

String

Number

Property name or index to access property by.

Returns

Property object

Example

To return the "Bulge Height" property from the "Bulge" effect by name:

thisLayer.effect("Bulge").param("Bulge Height");

To return the "Bulge Height" property from the "Bulge" effect by index:

thisLayer.effect("Bulge").param(4);

Mask

thisLayer.mask("Mask 1")

This category contains information relating to mask objects. To manipulate the actual mask path, see Mask Path.

Note

You can link Mask Path properties to other path properties (paths in a shape layer and brush strokes), but the properties are not accessible for direct numerical manipulation through expressions.

Info

On this page, we're going to use thisLayer.mask("Mask 1") as a sample on how to call these items, however note that any method that returns a Mask will work.

Attributes

Mask.invert

thisLayer.mask("Mask 1").invert

Description

Returns true if the mask is inverted or false if it is not.

Type

Boolean

Mask.maskExpansion

thisLayer.mask("Mask 1").maskExpansion

Description

Returns the expansion value of a mask, in pixels.

Type

Number

Mask.maskFeather

thisLayer.mask("Mask 1").maskFeather

Description

Returns the feather value of a mask, in pixels.

Type

Number

Mask.maskOpacity

thisLayer.mask("Mask 1").maskOpacity

Description

Returns the opacity value of a mask as a percentage.

Type

Number

Mask.maskPath

thisLayer.mask("Mask 1").maskPath

Description

Returns the actual mask Path.

Type

Path object

Property

This category holds generic entries relating to generic properties.

In expressions, a Property is typically anything that exists in the timeline (even if it can't be keyframed, or hold an expression).

Examples of Properties

All of the following AE items are actually "Properties" for the use of expressions, along with some ways to access those properties by code:

  • Position (thisLayer.transform.position, layer.position)
  • Scale (thisLayer.transform.scale, layer.scale)
  • A slider effect's actual slider (effect("Slider Control")("Slider"), effect("Slider Control")(1))
  • A text layer's Text property (thisLayer.text)
    • Note that in this case, Text also has its own special items, found in the above link.

Info

On this page, we're going to use thisLayer.position as a sample on how to call these items, however note that any method that returns a Property will work.

Attributes

name

thisLayer.position.name

Description

Returns the name of the property or property group.

Type

String

numKeys

thisLayer.position.numKeys

Description

Returns the number of keyframes on a property, or the number of markers on a marker property.

Note

If you use the Separate Dimensions command to separate the dimensions of the Position property into individual components, the number of keyframes changes, so the value returned by this method changes.

Type

Number

propertyIndex

thisLayer.position.propertyIndex

Description

Returns the index of a property relative to other properties in its property group, including property groups within masks, effects, text animators, selectors, shapes, trackers, and track points.

Type

Number

speed

thisLayer.position.speed

Description

Returns a 1-dimensional, positive speed value equal to the speed at which the property is changing at the default time.

Note

This can be used only for spatial properties.

Type

Number

value

thisLayer.position.value

Description

Returns the value of a property at the current time.

Type

Number, Array, or String

velocity

thisLayer.position.velocity

Description

Returns the temporal velocity value at the current time. For spatial properties, such as Position, it returns the tangent vector value. The result is the same dimension as the property.

Type

Number or Array

Methods

key()

thisLayer.position.key(index)

Description

Returns the Key or MarkerKey object by index number.

Parameters

Parameter Type Description
index Number The key (or MarkerKey) index number

Returns

Key or MarkerKey

Example

To retrieve the first keyframe on a property:

thisLayer.scale.key(1);

To retrieve the last keyframe on a property:

thisLayer.rotation.key(thisLayer.rotation.numKeys);

key()

thisLayer.position.key(markerName)

Description

Returns the MarkerKey object with this name.

Note

This can be used only on marker properties.

Parameters

Parameter Type Description
markerName String The name of the marker to return the matching key of.

Returns

MarkerKey

loopIn()

thisLayer.position.loopIn([type="cycle"][, numKeyframes=0])

Description

Loops a segment of time that is measured from the first keyframe on the layer forward toward the Out point of the layer. The loop plays from the In point of the layer.

You can use keyframe-looping methods to repeat a series of keyframes. You can use these methods on most properties. Exceptions include: - properties that can't be expressed by simple numeric values in the Timeline panel, such as: - the Source Text property, - path shape properties, and - the Histogram property for the Levels effect.

Keyframes or duration values that are too large are clipped to the maximum allowable value. Values that are too small result in a constant loop.

Parameters

Parameter Type Description
type Predefined string as defined in Loop Types Optional. The loop type to use. Defaults to "cycle"
numKeyframes Number Optional. The segment to loop, from keyframe #1 to keyframe #numKeyframes + 1. If unspecified (or 0), all keyframes loop. Defaults to 0.

Returns

A looped value of the same property type as this current property.

Example

To loop the segment bounded by the first and fourth keyframes:

loopIn("cycle", 3);

To loop forward and backward indefinitely from your current keyframes:

loopIn("continue") + loopOut("continue") - value;

Note that we need to subtract value, because both loopIn() and loopOut() include the current value; by adding them, we have two copies of the current value, and need to remove one (the - value) to get back to the proper keyframe value.

loopInDuration()

thisLayer.position.loopInDuration([type="cycle"][, duration=0])

Description

Loops a segment of time that is measured from the first keyframe on the layer forward toward the Out point of the layer.

Parameters

Parameter Type Description
type Predefined string as defined in Loop Types Optional. The loop type to use. Defaults to "cycle"
duration Number Optional. The number of composition seconds in a segment to loop, measured from the first keyframe. If unspecified (or 0), the segment to loop begins at the layer Out point. Defaults to 0.

Returns

A looped value of the same property type as this current property.

Example

To loop the first second of the entire animation:

loopInDuration("cycle", 1);

loopOut()

thisLayer.position.loopOut([type="cycle"][, numKeyframes=0])

Description

Loops a segment of time that is measured from the last keyframe on the layer back toward the In point of the layer. The loop plays until the Out point of the layer.

Info

David Van Brink provides an instructional article and sample project on his omino pixel blog that show how to use the Echo effect, the Particle Playground effect, and the loopOut() method to animate a swarm of stylized swimming bacteria.

Parameters

Parameter Type Description
type Predefined string as defined in Loop Types Optional. The loop type to use. Defaults to "cycle"
numKeyframes Number Optional. The segment to loop, measured backward from the last keyframe. If unspecified (or 0), all keyframes loop. Defaults to 0.

Returns

A looped value of the same property type as this current property.

Example

To loop the segment bounded by the last keyframe and second-to-last keyframe:

loopOut("cycle", 1);

loopOutDuration()

thisLayer.position.loopOutDuration([type="cycle"][, duration=0])

Description

Loops a segment of time that is measured from the last keyframe on the layer back toward the In point of the layer. The loop plays until the Out point of the layer.

Parameters

Parameter Type Description
type Predefined string as defined in Loop Types Optional. The loop type to use. Defaults to "cycle"
duration Number Optional. The number of composition seconds in a segment to loop, measured backward from the last keyframe. If unspecified (or 0), the segment to loop begins at the layer In point. Defaults to 0.

Returns

A looped value of the same property type as this current property.

Example

To loop the last second of the entire animation:

loopOutDuration("cycle", 1);

nearestKey()

thisLayer.position.nearestKey(t)

Description

Returns the Key or MarkerKey object nearest to a designated time t.

Parameters

Parameter Type Description
t Number The time to find the nearest key from

Returns

Key or MarkerKey

Example

Get the nearest keyframe to the 2-second time in the comp:

const twoSecondKey = thisLayer.scale.nearestKey(2);

// and then, to get the value of that key:
twoSecondKey.value;

propertyGroup()

thisLayer.position.propertyGroup([countUp=1])

Description

Returns a group of properties relative to the property on which the expression is written.

For example, if you add the propertyGroup(1) expression to the Rotation property of a brush stroke, the expression targets the Transform property group, which contains the Rotation property. If you add propertyGroup(2) instead, the expression targets the Brush property group.

This method lets you establish name-independent relationships in the property hierarchy. It is especially useful when duplicating properties that contain expressions.The numProperties method for propertyGroup returns the number of properties in the property group.

Parameters

Parameter Type Description
countUp Number Optional. The number of property groups "up" the hierarchy to climb. Defaults to 1.

Returns

PropertyGroup object

Example

Return the number of properties in the group that contains the property on which this expression is written:

thisProperty.propertyGroup(1).numProperties;

smooth()

thisLayer.position.smooth([width=.2][, samples=5][, t=time])

Description

Smooths the property values over time, converting large, brief deviations in the value to smaller, more evenly distributed deviations. This smoothing is accomplished by applying a box filter to the value of the property at the specified time.

Parameters

Parameter

Type

Description

width

Number

Optional. The range of time (in seconds) over which the filter is averaged. Defaults to 0.2.

samples

Number

Optional. The number of discrete samples evenly spaced over time. Use a larger value for greater smoothness (but decreased performance). Defaults to 5.

Generally, you'll want samples to be an odd number so that the value at the current time is included in the average.

t

Number

Optional. The specified time (in comp seconds) to apply the smoothing filter to. Defaults to time (the current comp time, in seconds).

Returns

Number or Array

Example

To smooth a position property's animation:

position.smooth(0.1, 5)

speedAtTime()

thisLayer.position.speedAtTime(t)

Description

Returns the spatial speed value at the specified time.

Parameters

Parameter Type Description
t Number The specified time at which to get the spatial speed value.

Returns

Number

temporalWiggle()

thisLayer.position.temporalWiggle(freq, amp[, octaves=1][, amp_mult=0.5][, t=time])

Description

Samples the property at a wiggled time.

For this function to be meaningful, the property it samples must be animated, because the function alters only the time of sampling, not the value.

Parameters

Parameter Type Description
freq Number The frequency, in wiggles per second.
amp Number The amplitude, in units of the property to which it is applied.
octaves Number Optional. The number of octaves of noise to add together. Defaults to 1.
amp_mult Number Optional. The amount that amp is multiplied by for each octave. Defaults to 0.5.
t Number Optional. The base start time. Defaults to time (the current comp time, in seconds).

Returns

Number or Array

Example

To add a temporal wiggle to scale:

scale.temporalWiggle(5, 0.2)

valueAtTime()

thisLayer.position.valueAtTime(t)

Description

Returns the value of a property at the specified time, in seconds.

Note

Dan Ebberts provides more examples and techniques for using the valueAtTime and velocityAtTime methods on MotionScript.

Parameters

Parameter Type Description
t Number The time, in seconds, to get the value from

Returns

Number or Array

Example

For example, to have a property value for each frame chosen randomly from a set of four values, set your four values as keyframes at 0, 1, 2, and 3 seconds, and then apply the following expression to the property:

valueAtTime(random(4))

velocityAtTime()

thisLayer.position.velocityAtTime(t)

Description

Returns the temporal velocity value at the specified time.

Parameters

Parameter Type Description
t Number The time, in seconds, to get the temporal velocity from

Returns

Number or Array

wiggle()

thisLayer.position.wiggle(freq, amp[, octaves=1][, amp_mult=0.5][, t=time])

Description

Randomly shakes (wiggles) the value of the property.

Note

Dan Ebberts provides an example expression and a detailed explanation on his website that shows how to use the time parameter of the wiggle method to create a looping animation.

Parameters

Parameter

Type

Description

freq

Number

Frequency, in wiggles per second.

amp

Number

Amplitude, in units of the property to which it is applied.

octaves

Number

Optional. Number of octaves of noise to add together. This value controls how much detail is in the wiggle.

Make this value higher than the default to include higher frequencies or lower to include amplitude harmonics in the wiggle. Defaults to 1.

amp_mult

Number

Optional. Amount that amp is multiplied by for each octave. This value controls how fast the harmonics drop off.

Make this value closer to 1 to have the harmonics added at the same amplitude as the base frequency, or closer to 0 to add in less detail. Defaults to 0.5.

t

Number

Optional. Base start time. This value defaults to the current time. Use this parameter if you want the output to be a wiggle of the property value sampled at a different time. Defaults to time (the current comp time, in seconds).

Returns

Number or Array

Example

This produces about 5 wiggles per second with an average size of about 20 pixels. In addition to the main wiggle, two more levels of detailed wiggles occur with a frequency of 10 and 20 wiggles per second, and sizes of 10 and 5 pixels, respectively:

position.wiggle(5, 20, 3, 0.5);

This example, on a two-dimensional property such as Scale, wiggles both dimensions by the same amount:

const v = wiggle(5, 10);

[v[0], v[0]];

This example, on a two-dimensional property, wiggles only along the y-axis:

const freq = 3;
const amp = 50;
const w = wiggle(freq,amp);

[value[0], w[1]];

Loop Types

The following loop types are predefined strings used in the "type" parameter for:

Type

Behaviour

"cycle"

Default. Repeats the specified segment.

"pingpong"

Repeats the specified segment, alternating between forward and backward.

"offset"

Repeats the specified segment, but offsets each cycle by the difference in the value of the property at the start and end of the segment, multiplied by the number of times the segment has looped.

"continue"

Does not repeat the specified segment, but continues to animate a property based on the velocity at the first or last keyframe.

For example, if the last keyframe of a Scale property of a layer is 100%, the layer continues to scale from 100% to the Out point, instead of looping directly back to the Out point. This type does not accept a keyframes or duration argument.

Marker Property

thisComp.marker

comp("CompName").marker

layer("precompName").source.marker

thisLayer.marker

The Marker Property is a special version of the Property object specifically for composition & layer markers.

It contains a special version of some of the same attributes and methods as the standard Property object, however most elements are not applicable here.

Info

On this page, we're going to use thisComp.marker as a sample on how to call these items, however note that any method that returns a Marker Property will work.

Attributes

Marker.numKeys

thisComp.marker.numKeys

Description

Returns the total number of markers in this composition or layer.

Type

Number

Methods

Marker.key(index)

thisComp.marker.key(index)

thisComp.marker.key(name)

Description

Returns the MarkerKey object of the marker with the specified index or name.

The index refers to the order of the marker in composition time, not to the numbered name of the marker.

The name value is the name of the marker, as typed in the comment field in the marker dialog box. For example, marker.key("1").

If more than one marker has the same name, this method returns the marker that occurs first in time (in composition or layer time, depending on whether this is a composition or layer marker).

Parameters

Parameter

Type

Description

index

Number

The marker index to get

name

index

String

Number

Marker name or index to access marker by.

Type

MarkerKey

Example

Return the time of the first composition marker:

thisComp.marker.key(1).time;

Return the time of the layer marker with the name "0":

thisLayer.marker.key("0").time;

On a layer, ramp the value of the property from 0 to 100 between two markers identified by name:

const m1 = thisLayr.marker.key("Start").time;
const m2 = thisLayr.marker.key("End").time;
linear(time, m1, m2, 0, 100);

Marker.nearestKey()

thisComp.marker.nearestKey(t)

Description

Returns the marker that is nearest in comp or layer time to the provided time t.

Parameters

Parameter Type Description
t Number The time to find the nearest marker from

Returns

MarkerKey

Example

Return the time of the composition marker nearest to the time of 1 second:

thisComp.marker.nearestKey(1).time;

This expression returns the time of the layer marker nearest to the current comp time:

thisLayer.marker.nearestKey(time).time;

Path Property

thisLayer.mask("Mask 1").maskPath

thisLayer.content("Shape 1").content("Path 1").path;

Note

This functionality was added in After Effects 15.0 (CC)

This category contains information relating to mask & shape paths.

Info

On this page, we're going to use thisLayer.mask("Mask 1").maskPath as a sample on how to call these items, however note that any method that returns a Path will work.

Attributes

name

thisLayer.mask("Mask 1").maskPath.name

Description

Returns the name of the property.

Type

String

Methods

PathProperty.createPath()

thisLayer.mask("Mask 1").maskPath.createPath(points=[[0,0], [100,0], [100,100], [0,100]], inTangents=[], outTangents=[], is_closed=true)

Description

Creates a path object from a set of points and tangents.

The points(), inTangents(), outTangents(), and isClosed() methods of a path can be passed into the points, inTangents, outTangents, and is_closed parameters to duplicate a path.

The points and tangents of the same path can be passed into createPath() with modifications to generate a different result.

Parameters

Parameter

Type

Description

points

Array of number pair arrays

Optional. An array of number pair arrays representing the [x, y] coordinates of the points. The array must contain at least 1 item, and can be of any greater length. Defaults to [[0,0], [100,0], [100,100], [0,100]].

inTangents

Array of number pair arrays

Optional. An array of number pair arrays representing their [x, y] offset coordinates. The length of this array must be exactly the same as the points parameter. Defaults to [].

Coordinate values are offset relative to the parent point's coordinates. i.e. The value [0, 0] creates no curvature at the incoming tangent.

outTangents is_closed

Array of number pair arrays Boolean

Optional. See inTangents. Defaults to []. Optional. Defaults to true.

Returns

Path

Example

For example, the following expression will remove curves from Mask 1 by not passing the inTangents or outTangents parameters:

const myMask = mask("Mask 1").path;
myMask.createPath(myMask.points());

The following example passes the points and tangents of Mask 1 and converts it to an open path by setting is_closed to false:

const myMask = mask("Mask 1").path;
myMask.createPath(myMask.points(), myMask.inTangents(), myMask.outTangents(), false);

PathProperty.inTangents()

thisLayer.mask("Mask 1").maskPath.inTangents([t=time])

Description

Get the [x, y] coordinates of the incoming tangent handle for all points on a path.

Tangent coordinate values are offset relative to the parent point's coordinates (i.e. the value [0, 0] creates no curvature at the incoming tangent).

This method can be passed into the createPath() method for the inTangents parameter when duplicating a path.

Parameters

Parameter Type Description
t Number Optional. The specified time (in comp seconds) to sample the tangents. Defaults to time (the current comp time, in seconds).

Returns

Array of number pair arrays, rounded to the fourth decimal place

PathProperty.isClosed()

thisLayer.mask("Mask 1").maskPath.isClosed()

Description

Determines if the path is open or closed. Returns true if the path is closed, false if the path is open.

This method can be passed into the createPath() method for the is_closed parameter when duplicating a path.

Returns

Boolean

PathProperty.normalOnPath()

thisLayer.mask("Mask 1").maskPath.normalOnPath(percentage=0.5, t=time)

Description

Get the calculated [x, y] coordinates of the normal for an arbitrary point along a path.

Coordinate values of normals are offset relative to the parent point's coordinates (i.e. the value [0, 0] is the same as the parent point).

The normal's parent point is expressed as a percentage of the arc-length of the path. Read the description of the pointOnPath() method for details about arc-length percentage.

The linear distance between the parent point's coordinates and normalOnPath() coordinates will always be 1.

Parameters

Parameter Type Description
percentage Number Optional. The percentage along the path at which to sample the normal. Defaults to 0.5 (50%).
t Number Optional. The specified time (in comp seconds) to sample the path. Defaults to time (the current comp time, in seconds).

Returns

A number pair array

Example

Sample a normal and make it longer:

myPath.normalOnPath() * 100

PathProperty.outTangents()

thisLayer.mask("Mask 1").maskPath.outTangents([t=time])

Description

Get the [x, y] coordinates of the outgoing tangent handle for all points on a path.

Tangent coordinate values are offset relative to the parent point's coordinates (i.e. the value [0, 0] creates no curvature at the outgoing tangent).

This method can be passed into the createPath() method for the outTangents parameter when duplicating a path.

Parameters

Parameter Type Description
t Number Optional. The specified time (in comp seconds) to sample the tangents. Defaults to time (the current comp time, in seconds).

Returns

Array of number pair arrays, rounded to the fourth decimal place

PathProperty.pointOnPath()

thisLayer.mask("Mask 1").maskPath.pointOnPath([percentage=0.5][, t=time])

Description

Get the [x, y] coordinates of an arbitrary point along a path.

The point is expressed as a percentage of the arc-length of the path. 0.0 (0%) is the first point and 1.0 (100%) is the last point. When the path is closed, 0% and 100% will return the same coordinates.

Info

Percentage of arc-length is used to ensure uniform speed along the path.

Other than 0% and 100%, percentages do not necessarily correlate with the Bezier points on the path. (i.e., For a path with three points, the second point will not necessarily be at 50%.)

This also means that for an open path and closed path with identical points, the percentage along the open path will not return the same coordinates as the closed path due to the additional length of the closed path.

Parameter Type Description
percentage Number Optional. The percentage along the path at which to sample the point. Defaults to 0.5 (50%).
t Number Optional. The specified time (in comp seconds) to sample the path. Defaults to time (the current comp time, in seconds).

Returns

A number pair array

PathProperty.points()

thisLayer.mask("Mask 1").maskPath.points([t=time])

Description

Get the x,y coordinates of all points on a path.

The returned values are relative, depending on the context: - Coordinates for layer mask path points are relative to the layer's origin in its upper-left hand corner. - Coordinates for Bezier shape path points are are relative to the anchor point of the path's shape group - (ex., "Transform: Shape 1 > Anchor Point"). - Coordinates for brush stroke path points are relative to the start of the stroke; the first point is [0,0]. - This method can be passed into the createPath() method for the points parameter when duplicating a path.

Parameters

Parameter Type Description
t Number Optional. The specified time (in comp seconds) to sample the path. Defaults to time (the current comp time, in seconds).

Returns

Array of number pair arrays, rounded to the fourth decimal place

Example

Read the coordinates of the first vertex of Mask 1 on Dark Gray Solid 1 and converts them to composition coordinates.

Apply this to a 2D point control of an effect, such as Write-on or CC Particle Systems II, to make the effect trace or track the first point of an animated mask.

Duplicate the effect and change the path points index value ([0]) to trace or track the other points of the mask.

const myLayer = thisComp.layer("Dark Gray Solid 1");
myLayer.toComp(myLayer.mask("Mask 1").maskPath.points()[0]);

PathProperty.tangentOnPath()

thisLayer.mask("Mask 1").maskPath.tangentOnPath([percentage=0.5][, t=time])

Description

Get the calculated [x, y] coordinates of the outgoing tangent handle for an arbitrary point along a path.

Tangent coordinate values are offset relative to the parent point's coordinates (i.e. the value [0, 0] creates no curvature at the outgoing tangent). Values will differ from those returned by outTangents() if a user-defined point also exists at that arc-length pecentage.

The incoming tangent handle is the inverse of this value (multiply the [x, y] coordinates by -1).

The tangent's parent point is expressed as a percentage of the arc-length of the path. Read the description of the pointOnPath() method for details about arc-length percentage.

The linear distance between the parent point's coordinates and tangentOnPath() coordinates will always be 1.

Parameters

Parameter Type Description
percentage Number Optional. The percentage along the path at which to sample the tangent. Defaults to 0.5 (50%).
t Number Optional. The specified time (in comp seconds) to sample the path. Defaults to time (the current comp time, in seconds).

Returns

A number pair array

Example

Sample a tangent and make it longer:

myPath.tangentOnPath() * 100

Example

Writes the list of point and tangent coordinates from Path 1 of Shape 1 on layer Shape Layer 1, at time=0, into a string.

Apply this to the source text property of a text layer for a readout of the coordinates and incoming and outgoing tangents of the shape.

let pointsList = "";
const sampleTime = 0;
const myShape = thisComp.layer("Shape Layer 1").content("Shape 1").content("Path 1").path;

for (i = 0; i < myShape.points(sampleTime).length; i++) {
    pointsList += "c: " + myShape.points(sampleTime)[i].toString() + " i: " + myShape.inTangents(sampleTime)[i].toString() + " o: " + myShape.outTangents(sampleTime)[i].toString() + "\n";
}

pointsList;

Key

thisProperty.key(1)

When you access a Key object, you can get time, index, and value properties from it.

Tip

In expressions, "Key" refers to Keyframes.

Info

On this page, we're going to use thisProperty.key(1) as a sample on how to call these items, however note that any method that returns a Key will work.

Attributes

Key.index

thisProperty.key(1).index

Description

Returns the index of the keyframe.

Type

Number

Key.time

thisProperty.key(1).time

Description

Returns the time of the keyframe.

Type

Number

Key.value

thisProperty.key(1).value

Description

Returns the value of the keyframe.

Type

A value of the same property type as the property being refrenced.

Example

The following expression, when written on an Opacity property with keyframes, ignores the keyframe values and uses only the placement of the keyframes in time to determine where a flash should occur:

const d = Math.abs(time - nearestKey(time).time);
easeOut(d, 0, .1, 100, 0)

The following expression gives you the value of the third Position keyframe:

position.key(3).value;

MarkerKey

thisComp.marker.key(1)

You can access values for composition markers and layer markers using the same methods. Access layer markers through the thisLayer.marker object; access composition markers through the Marker Property object.

For the purpose of expressions, markers are a special type of Key object, so you can use methods such as nearestKey(time) to access markers, and markers also have time and index attributes. The index attribute is not the number (name) of the marker; it is the keyframe index number, representing the order of the marker in the time ruler.

Expressions have access to all the values for a marker that you can set in the Composition Marker or Layer Marker dialog box.

Because the XMP metadata in a footage item can be converted into layer markers for a layer based on that item, expressions can interact with XMP metadata. For information, see XMP metadata in After Effects.

Dan Ebberts provides a tutorial on the After Effects Developer Center that includes an example of using XMP metadata with expressions.

Info

On this page, we're going to use thisComp.marker.key(1) as a sample on how to call these items, however note that any method that returns a MarkerKey will work.

Attributes

MarkerKey.chapter

thisComp.marker.key(1).chapter

Description

Contents of Chapter field in marker dialog box.

Type

String

MarkerKey.comment

thisComp.marker.key(1).comment

Description

Contents of Comment field in marker dialog box.

Type

String

MarkerKey.cuePointName

thisComp.marker.key(1).cuePointName

Description

Contents of cue point Name field in marker dialog box.

Type

String

MarkerKey.duration

thisComp.marker.key(1).duration

Description

Duration, in seconds, of marker.

Type

Number

MarkerKey.eventCuePoint

thisComp.marker.key(1).eventCuePoint

Description

Setting for cue point type in marker dialog box.

true for Event; false for Navigation.

Type

Boolean

MarkerKey.frameTarget

thisComp.marker.key(1).frameTarget

Description

Contents of Frame Target field in marker dialog box.

Type

String

MarkerKey.parameters

thisComp.marker.key(1).parameters

Description

Contents of Parameter Name and Parameter Value fields in marker dialog box.

Type

Associative array of String values

Example

If you have a parameter named "background color", then you can use the following expression to access its value at the nearest marker:

thisComp.marker.nearestKey(time).parameters["background color"];

MarkerKey.protectedRegion

thisComp.marker.key(1).protectedRegion

Note

This functionality was added in After Effects 16.0

Description

State of the Protected Region option in the Composition Marker dialog box.

When true, the composition marker behaves as a protected region.

Will also return true for protected region markers on nested composition layers, but is otherwise not applicable to layer markers.

Type

Boolean

MarkerKey.url

thisComp.marker.key(1).url

Description

Contents of URL field in marker dialog box.

Type

String

Example

This expression on the Source Text property of a text layer displays the time, duration, index, comment (name), chapter, URL, frame target, and cue point name for the layer marker nearest the current time, and whether the marker is for an event cue point:

const m = thisLayer.marker.nearestKey(time);
const s = [
    "time:" + timeToCurrentFormat(m.time),
    "duration: " + m.duration,
    "key index: " + m.index,
    "comment:" + m.comment,
    "chapter:" + m.chapter,
    "URL:" + m.url,
    "frame target: " + m.frameTarget,
    "cue point name: " + m.cuePointName,
    "Event cue point? " + m.eventCuePoint,
    ""
];

for (let param in m.parameters){
    s.push("parameter: " + param + " value: " + m.parameters[param]);
}

s.join("\n");

Ended: Objects

Layer ↵

Layer

As Layers are the foundation of most things in After Effects, this category is large and has been split into smaller pages for various focuses.

These pages reflect the organization of the Expression fly-out menu within After Effects.

Info

Layer is the base class for Camera and Light, so Layer attributes and methods are available when working with those layer types (except when noted).

Layer is also a subclass of PropertyGroup, so all methods of PropertyGroup, in addition to those listed in the below pages, are available when working with Layer.

Those categories are:

  • Layer Sub-objects is for items that give you other objects based on the current layer; things like the source (for precomps or footage), effects, masks, sourceRect, etc.
  • Layer General holds general info about the layer; width and height, whether the layer has audio or video, the layer's start and end points, etc. With few exceptions, typically don't change over the duration of the comp.
  • Layer Properties is generally for more dynamic properties; the layer's transform data (position, scale, rotation, etc), its audio or time remap, info about markers, and so on.
  • Layer Space Transforms contains info on how to convert values from one "space" to another, such as from layer space to world space.
  • Layer 3D is all about the 3d properties of layers. 3d rotation values, material properties, and more live here.

Layer Sub-objects

thisLayer

This category describes items that give you other objects based on the current layer; things like the source (for precomps or footage), effects, masks, sourceRect, etc.

Info

On this page, we're going to use thisLayer as a sample on how to call these items, however note that any method that returns a Layer will work.

Note

For After Effects CC and CS6, the Expression language menu, the "Layer Sub-objects", "Layer General", "Layer Properties", "Layer 3D", and "Layer Space Transforms" have been arranged into a "Layer" submenu.

Attributes

Layer.source

thisLayer.source

Description

Returns the source Comp or Footage object for the layer.

Default time is adjusted to the time in the source.

Example:

source.layer(1).position

Type

Comp or Footage

Methods

Layer.effect()

thisLayer.effect(name)

thisLayer.effect(index)

Description

The name value will have After Effects find the effect by its name in the Effect Controls panel. The name can be the default name or a user-defined name. If multiple effects have the same name, the effect closest to the top of the Effect Controls panel is used.

The index value will have After Effects finds the effect by its index in the Effect Controls panel, starting at 1 and counting from the top.

Parameters

Parameter

Type

Description

name

index

String

Number

Effect name or index to get.

Returns

Effect

Example

Get the "Blurriness" effect by name:

thisLayer.effect("Fast Blur")

Get the first effect on the layer:

thisLayer.effect(1)

Layer.mask()

thisLayer.mask(name)

thisLayer.mask(index)

Description

The name value can be the default name or a user-defined name. If multiple masks have the same name, the first (topmost) mask is used.

The index value will have After Effects finds the mask by its index in the Timeline panel, starting at 1 and counting from the top.

Parameters

Parameter

Type

Description

name

index

String

Number

Effect name or index to get.

Returns

Effect

Example

Get the mask "Mask 1" by name:

thisLayer.mask("Mask 1")

Get the first mask on the layer:

thisLayer.mask(1)

Layer.sourceRectAtTime()

thisLayer.sourceRectAtTime(t = time, includeExtents = false)

Note

This functionality was added in After Effects 13.2 Paragraph text extents was added in After Effects 15.1.

Description

Returns the bounding box of the layer (or the layer's source).

Parameters

Parameter

Type

Description

t

Number

Optional. The specified time (in comp seconds) to apply the smoothing filter to. Defaults to time (the current comp time, in seconds).

includeExtents

Boolean

Optional. Only applies to shape layers and paragraph text layers. Defaults to false.

  • For shape layers: Increases the size of the layer bounds as necessary.
  • For paragraph text layers: Returns the bounds of the paragraph box

Returns

An object with four attributes: {top, left, width, height}

Example

myTextLayer.sourceRectAtTime().width

Layer.sourceTime()

thisLayer.sourceTime([t=time])

Note

This functionality was added in After Effects CS5.5

Description

Returns the layer source corresponding to time t.

Parameters

Parameter Type Description
t Number Optional. The specified time (in comp seconds) to apply the smoothing filter to. Defaults to time (the current comp time, in seconds).

Returns

Number

Layer General

thisLayer

Info

On this page, we're going to use thisLayer as a sample on how to call these items, however note that any method that returns a Layer will work.

Attributes

Layer.active

thisLayer.active

Description

Returns true if the Video switch is on for the layer and the current time is in the range from the In point of the layer to the Out point of the layer; false otherwise.

Type

Boolean

Layer.audioActive

thisLayer.audioActive

Description

Returns true if the Audio switch is on for the layer and the current time is in the range from the In point of the layer to the Out point of the layer; false otherwise.

Type

Boolean

Layer.enabled

thisLayer.enabled

Description

Whether the layer is enabled.

Type

Boolean. true if the Video switch is on for the layer; false otherwise.

Layer.hasAudio

thisLayer.hasAudio

Description

Whether the layer has audio.

Type

Boolean. true if the layer has audio or false if it doesn't.

Layer.hasParent

thisLayer.hasParent

Description

Use the hasParent attribute to determine if a layer has a parent layer. You can use this attribute even if the layer has no parent layer at present.

Type

Boolean. true if the layer has a parent, false if it doesn't.

Example

The following expression indicates that the layer to which you apply it wiggles based on the position of the parent. If the layer has no parent, then it wiggles based on its own position.

If the layer is given a parent later, then the behavior of the layer changes accordingly:

idx = index;
if (hasParent) {
        idx = parent.index;
}
thisComp.layer(idx).position.wiggle(5,20)

Layer.hasVideo

thisLayer.hasVideo

Description

Whether the layer has video.

Type

Boolean. true if the layer has audio or false if it doesn't.

Layer.height

thisLayer.height

Description

Returns the height of the layer, in pixels.

If the layer has a source, this is the same as either the source comp height or the source footage height (as applicable).

Type

Number

Layer.index

thisLayer.index

Description

Returns the index number of the layer in the composition.

Type

Number

Layer.inPoint

thisLayer.inPoint

Description

Returns the In point of the layer, in seconds.

Note

In general, the value of outPoint is greater than the value of inPoint. However, if a layer is reversed in time, the value of inPoint is greater than the value of outPoint. Similarly, the value of startTime can be greater than the value of inPoint.

Type

Number

Layer.outPoint

thisLayer.outPoint

Description

Returns the Out point of the layer, in seconds.

Type

Number

Layer.parent

thisLayer.parent

Description

Returns the parent Layer object of the layer, if it has one.

You can check whether a layer has a parent with the Layer.hasParent attribute.

Type

Layer, Light, or Camera object

Example

position[0] + parent.width

Layer.startTime

thisLayer.startTime

Description

Returns the start time of the layer, in seconds.

Type

Number

Layer.width

thisLayer.width

Description

Returns the width of the layer, in pixels.

If the layer has a source, this is the same as either the source comp width or the source footage width (as applicable).

Type

Number

Methods

Layer.sampleImage()

thisLayer.sampleImage(point[, radius=[0.5, 0.5]][, postEffect=true][, t=time])

Description

Samples the color and alpha channel values of a layer and returns the average alpha-weighted value of the pixels within the specified distance of the point as an array: [red, green, blue, alpha].

Note

Using sampleImage() in an expression no longer disables multiprocessing.

Parameters

Parameter Type Description
point 2-dimensional Number array Required. The point at which to sample, im layer space. The point [0, 0] is the center of the upper-left pixel in the layer.
radius 2-dimensional Number array Optional. Specifies the horizontal and vertical distance from the sample center to the edges of the sampled rectangle. The default value samples one pixel. Defaults to [0.5, 0.5].
postEffect Boolean Optional. If true, to sample the values after layer masks and effects directly applied to the layer have been rendered. If false, sample values before layer masks and effects. Defaults to true.
t Number Optional. Defaults to time.

Type

Array (4-dimensional)

Examples

This samples a rectangle 4 pixels wide and 3 pixels high, centered around a point 100 pixels down and to the right of the upper-left corner of the layer:

thisComp.layer(1).sampleImage([100, 100], [2, 1.5])

Layer Properties

thisLayer

When you add masks, effects, paint, or text to a layer, After Effects adds new properties to the Timeline panel. There are too many of these properties to list here, so use the pick whip to learn the syntax for referring to them in your expressions.

Info

On this page, we're going to use thisLayer as a sample on how to call these items, however note that any method that returns a Layer will work.

Attributes

Layer.anchorPoint

thisLayer.anchorPoint

Description

Returns the anchor point value of the layer in the coordinate system of the layer (layer space).

Type

Array of Numbers (2- or 3-dimensional)

Layer.audioLevels

thisLayer.audioLevels

Description

Returns the value of the Audio Levels property of the layer, in decibels. This value is a 2D value; the first value represents the left audio channel, and the second value represents the right. The value is not the amplitude of the audio track of the source material. Instead, it is the value of the Audio Levels property, which may be affected by keyframes.

Type

Array of Numbers (2-dimensional)

Layer.marker

thisLayer.marker

Description

Returns a given layer's Marker property.

Type

Marker Property

Layer.name

thisLayer.name

Description

Returns the name of the layer.

Type

String

Layer.opacity

thisLayer.opacity

Description

Returns the opacity value for the layer, expressed as a percentage.

Type

Number

Layer.position

thisLayer.position

Description

Returns the position value of the layer, in world space if the layer has no parent. If the layer has a parent, it returns the position value of the layer in the coordinate system of the parent layer (in the layer space of the parent layer).

Type

Array of Numbers (2- or 3-dimensional)

Layer.rotation

thisLayer.rotation

Description

Returns the rotation value of the layer in degrees. For a 3D layer, it returns the z rotation value in degrees.

Type

Number

Layer.scale

thisLayer.scale

Description

Returns the scale value of the layer, expressed as a percentage.

Type

Array of Numbers (2- or 3-dimensional)

Layer.timeRemap

thisLayer.timeRemap

Description

Returns the value of the Time Remap property, in seconds, if Time Remap is enabled.

Type

Number

Layer Space Transforms

thisLayer

Use layer space transform methods to transform values from one space to another, such as from layer space to world space.

Composition (comp) and world space are the same for 2D layers. For 3D layers, however, composition space is relative to the active camera, and world space is independent of the camera.

Info

On this page, we're going to use thisLayer as a sample on how to call these items, however note that any method that returns a Layer will work.

"From" & "To" Methods

The from methods transform values from the named space (composition or world) to the layer space.

The to methods transform values from the layer space to the named space (composition or world). Each transform method takes an optional argument to determine the time at which the transform is computed; however, you can almost always use the current (default) time.

"Vec" Methods

Use Vec transform methods when transforming a direction vector, such as the difference between two position values.

Use the plain (non-Vec) transform methods when transforming a point, such as position.

Methods

toComp()

thisLayer.toComp(point[, t=time])

Description

Transforms a point from layer space to composition space.

Parameters

Parameter Type Description
point Array (2- or 3-dimensional) The point to convert
t Number Optional. The time at which to sample the point at. Defaults to time.

Type

Array (2- or 3-dimensional)

fromComp()

thisLayer.fromComp(point[, t=time])

Description

Transforms a point from composition space to layer space. The resulting point in a 3D layer may have a nonzero value even though it is in layer space.

Parameters

Parameter Type Description
point Array (2- or 3-dimensional) The point to convert
t Number Optional. The time at which to sample the point at. Defaults to time.

Type

Array (2- or 3-dimensional)

Example

fromComp(thisComp.layer(2).position)

toWorld()

thisLayer.toWorld(point[, t=time])

Description

Transforms a point from layer space to view-independent world space.

Tip

Dan Ebberts provides an expression on his MotionScript website that uses the toWorld method to auto-orient a layer along only one axis. This is useful, for example, for having characters turn from side to side to follow the camera while remaining upright.

Tip

Rich Young provides a set of expressions on his AE Portal website that use the toWorld method link a camera and light to a layer with the CC Sphere effect.

Parameters

Parameter Type Description
point Array (2- or 3-dimensional) The point to convert
t Number Optional. The time at which to sample the point at. Defaults to time.

Type

Array (2- or 3-dimensional)

Example

toWorld.effect("Bulge")("Bulge Center")

fromWorld()

thisLayer.fromWorld(point[, t=time])

Description

Transforms a point from world space to layer space.

Parameters

Parameter Type Description
point Array (2- or 3-dimensional) The point to convert
t Number Optional. The time at which to sample the point at. Defaults to time.

Type

Array (2- or 3-dimensional)

Example

fromWorld(thisComp.layer(2).position)

toCompVec()

thisLayer.toCompVec(vec[, t=time])

Description

Transforms a vector from layer space to composition space.

Parameters

Parameter Type Description
vec Array (2- or 3-dimensional)
t Number

Type

Array (2- or 3-dimensional)

Example

toCompVec([1, 0])

fromCompVec()

thisLayer.fromCompVec(vec[, t=time])

Description

Transforms a vector from composition space to layer space.

Parameters

Parameter Type Description
vec Array (2- or 3-dimensional)
t Number

Type

Array (2- or 3-dimensional)

Example:

For a 2D layer:

const dir = sub(position, thisComp.layer(2).position);
fromCompVec(dir)

toWorldVec()

thisLayer.toWorldVec(vec[, t=time])

Description

Transforms a vector from layer space to world space.

Parameters

Parameter Type Description
vec Array (2- or 3-dimensional)
t Number

Type

Array (2- or 3-dimensional)

Example

Transform two different "Bulge Center" properties from the layer space of the layer the effect is applied to, to the world space of the comp the layers live in:

const p1 = effect("Eye Bulge 1")("Bulge Center");
const p2 = effect("Eye Bulge 2")("Bulge Center");

toWorld(sub(p1, p2))

fromWorldVec()

thisLayer.fromWorldVec(vec[, t=time])

Description

Transforms a vector from world space to layer space.

Parameters

Parameter Type Description
vec Array (2- or 3-dimensional)
t Number

Type

Array (2- or 3-dimensional)

Example

Convert layer #2's position from world space to this layer's space:

fromWorld(thisComp.layer(2).position)

fromCompToSurface()

thisLayer.fromCompToSurface(point[, t=time])

Description

Projects a point located in composition space to a point on the surface of the layer (zero z-value) at the location where it appears when viewed from the active camera. This method is useful for setting effect control points.

Note

Use with 3D layers only.

Parameters

Parameter Type Description
point Array (2- or 3-dimensional) The point to convert
t Number Optional. The time at which to sample the point at. Defaults to time.

Type

Array (2-dimensional)

Layer 3D

thisLayer

These attributes are related to the 3d properties of layers.

Info

On this page, we're going to use thisLayer as a sample on how to call these items, however note that any method that returns a Layer will work.

Attributes

Layer.acceptsLights

thisLayer.acceptsLights

Description

Returns a value of 1 if the layer accepts lights.

Type

Boolean Number

Layer.acceptsShadows

thisLayer.acceptsShadows

Description

Returns a value of 1 if the layer accepts shadows and 2 if the property is set to Only.

Type

Number

Layer.ambient

thisLayer.ambient

Description

Returns the ambient component value as a percentage.

Type

Number

Layer.castsShadows

thisLayer.castsShadows

Description

Returns a value of 1.0 if the layer casts shadows and 2 if the property is set to Only.

Type

Number

Layer.diffuse

thisLayer.diffuse

Description

Returns the diffuse component value as a percentage.

Type

Number

Layer.lightTransmission

thisLayer.lightTransmission

Description

Returns the value of the Light Transmission property for a 3D layer.

Type

Number

Layer.metal

thisLayer.metal

Description

Returns the metal component value as a percentage.

Type

Number

Layer.orientation

thisLayer.orientation

Description

Returns the 3D orientation value, in degrees, for a 3D layer.

Type

Array (3-dimensional)

Layer.rotationX

thisLayer.rotationX

Description

Returns the x rotation value, in degrees, for a 3D layer.

Type

Number

Layer.rotationY

thisLayer.rotationY

Description

Returns the y rotation value, in degrees, for a 3D layer.

Type

Number

Layer.rotationZ

thisLayer.rotationZ

Description

Returns the z rotation value, in degrees, for a 3D layer.

Type

Number

Layer.shininess

thisLayer.shininess

Description

Returns the shininess component value as a percentage.

Type

Number

Layer.specular

thisLayer.specular

Description

Returns the specular component value as a percentage.

Type

Number

Ended: Layer

Text ↵

Text

text

This category holds generic text-related entries for text layers.

Attributes

Text.sourceText

text.sourceText

Description

Returns the text content of a text layer.

Note

As of After Effects 17.0, this property returns the Source Text object to access text style properties. If no style properties are specified, this returns the text content as expected.

Type

String of text content, or Source Text (AE 17.0+)

Text.Font...

Description

Note

This isn't actually an expression method! Instead, it's a button from the expression fly-out menu.

Launches a dialog window for the user to specify a font name and weight.

Upon selection, the internal font name is injected into the expression editor as a string.

Type

String

Source Text

text.sourceText

These functions are accessible on the Text.sourceText object in AE 17.0 and later.

Attributes

SourceText.isHorizontalText

text.sourceText.isHorizontalText

Note

This functionality was added in After Effects 25.0.

Description

Returns true if the Text layer is horizontal and false if it is vertical.

Type

Boolean

SourceText.isParagraphText

text.sourceText.isParagraphText

Note

This functionality was added in After Effects 25.0.

Description

Returns true if a Text layer is Paragraph text. If the Text layer is a Point text, it returns false.

Type

Boolean

SourceText.isPointText

text.sourceText.isPointText

Note

This functionality was added in After Effects 25.0.

Description

Returns true if a Text layer is Point text. If the Text layer is Paragraph text, it returns false.

Type

Boolean

SourceText.isVerticalText

text.sourceText.isVerticalText

Note

This functionality was added in After Effects 25.0.

Description

Returns true if the Text layer is vertical and false if it is horizontal.

Type

Boolean

SourceText.style

text.sourceText.style

Description

Returns the Text Style object for a given sourceText property.

Type

Text Style object

Methods

SourceText.createStyle()

text.sourceText.createStyle()

Description

Used to initialize an empty Text Style object in which you'd manually bake in specific values.

Returns

Empty Text Style object.

Example

To create a new style with font size 300 and the font Impact:

text.sourceText
    .createStyle()
    .setFontSize(300)
    .setFont("Impact");

SourceText.getStyleAt()

text.sourceText.getStyleAt(charIndex[, time])

Description

This function returns the Text Style object of a particular character at a specific time.

In case the style is keyframed and changes over time, use the second time parameter to specify the target time to get the style at.

Note

Using SourceText.style is the same as using text.sourceText.getStyleAt(0,0)

Parameters

Parameter Type Description
index Number The index of the letter or character whose style is needed
time Number Optional. The time within the composition to get the style from. Defaults to time.

Returns

Text Style object

Example

To get the style of the first character at the beginning of the timeline:

text.sourceText.getStyleAt(0,0);

Text Style

text.sourceText.style

Most of these functions are accessible from the SourceText.style object in AE 17.0 and later. Where noted, additional methods were added in AE 25.0. The ability to control percharacter styling was also added in 25.0. Use the second and third arguments (when available) to control per-character styling.

Note

When using per-character styling, line breaks and spaces are also considered characters and must be accounted for (or skipped, if desired) when calcuating character indexes.

For more info on working with text styles, see:

Chaining

All the methods for Text Style will return a Text Style object, so you can call them in a chain, e.g.:

text.sourceText.style.setFont("Times New Roman").setFontSize(42).setText("New Text");

Tip

You can also format this chain with line breaks to make it easier to read: 

text.sourceText.style
    .setFont("Times New Roman")
    .setFontSize(42)
    .setText("New Text");

Attributes

TextStyle.applyFill

text.sourceText.style.applyFill

Description

Returns whether Fill Color is enabled.

Type

Boolean

TextStyle.applyStroke

text.sourceText.style.applyStroke

Description

Returns whether Stroke is enabled.

Type

Boolean

TextStyle.baselineDirection

text.sourceText.style.baselineDirection

Note

This functionality was added in After Effects 25.0.

Description

Returns the Baseline Direction for a Text layer.

Type

Predefined string. One of:

  • "default"
  • "rotated"
  • "tate-chuu-yoko"

TextStyle.baselineOption

text.sourceText.style.baselineOption

Note

This functionality was added in After Effects 25.0.

Description

Returns the Baseline Option Type for a Text layer.

Type

Predefined string. One of:

  • "default"
  • "subscript"
  • "superscript"

TextStyle.baselineShift

text.sourceText.style.baselineShift

Description

Returns the value of Baseline Shift for a Text layer.

Type

Number

TextStyle.digitSet

text.sourceText.style.digitSet

Note

This functionality was added in After Effects 25.0.

Description

Returns the Digit Set for a Text layer.

Type

Predefined string. One of:

  • "default"
  • "hindidigits"

TextStyle.direction

text.sourceText.style.direction

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of Direction of the first paragraph of a Text layer.

Type

Predefined string. One of:

  • "left-to-right"
  • "right-to-left"

TextStyle.fillColor

text.sourceText.style.fillColor

Description

Returns the text Fill Color as RGB values on a scale from 0 - 1.0.

Type

Array of Numbers.

TextStyle.firstLineIndent

text.sourceText.style.firstLineIndent

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of First Line Indent of the first line of the first paragraph of a Text layer.

Type

Number

TextStyle.font

text.sourceText.style.font

Description

Returns the font name for a Text layer.

Type

String

TextStyle.fontSize

text.sourceText.style.fontSize

Description

Returns the value of Font Size for a Text layer.

Type

Number

TextStyle.horizontalScaling

text.sourceText.style.horizontalScaling

Note

This functionality was added in After Effects 25.0.

Description

Returns the Horizontal Scaling for a Text layer.

Type

Number

TextStyle.isAllCaps

text.sourceText.style.isAllCaps

Description

Returns whether All Caps is enabled.

Type

Boolean

TextStyle.isAutoLeading

text.sourceText.style.isAutoLeading

Description

Returns whether Auto Leading is enabled.

Type

Boolean

TextStyle.isEveryLineComposer

text.sourceText.style.isEveryLineComposer

Note

This functionality was added in After Effects 25.0.

Description

Returns true if the Text layer if Every-Line Composer is set for the first paragraph of a Text layer and false if Single-Line Composer is set for the first paragraph of a Text layer

Type

Boolean

TextStyle.isFauxBold

text.sourceText.style.isFauxBold

Description

Returns whether Faux Bold is enabled.

Type

Boolean

TextStyle.isFauxItalic

text.sourceText.style.isFauxItalic

Description

Returns whether Faux Italics are enabled.

Type

Boolean

TextStyle.isHangingRoman

text.sourceText.style.isHangingRoman

Note

This functionality was added in After Effects 25.0.

Description

Whether Hanging Roman Punctuation is set for the entire Text layer.

Type

Boolean

TextStyle.isLigature

text.sourceText.style.isLigature

Note

This functionality was added in After Effects 25.0.

Description

Returns whether ligatures are enabled.

Type

Boolean

TextStyle.isSmallCaps

text.sourceText.style.isSmallCaps

Description

Returns whether Small Caps is enabled.

Type

Boolean

TextStyle.justification

text.sourceText.style.justification

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of Justification of the first paragraph of a Text layer.

Warning

The left and right values for alignment/justification will be reversed if the Text layer's TextStyle.direction is set to use right-to-left. You can control this using the Property or Paragraph panel, or via TextStyle.setDirection().

Type

Predefined string. One of:

  • "alignCenter"
  • "alignLeft"
  • "alignRight"
  • "justifyFull"
  • "justifyLastCenter"
  • "justifyLastLeft"
  • "justifyLastRight"

TextStyle.kerning

text.sourceText.style.kerning

Note

This functionality was added in After Effects 25.0.

Description

Returns the Kerning Value for a Text Layer.

For this value to be returned as anything other than zero, the KerningType must not be set.

Type

Number. Read-only.

TextStyle.kerningType

text.sourceText.style.kerningType

Note

This functionality was added in After Effects 25.0.

Description

Returns the Kerning Type for a Text layer.

Type

Read-only. Predefined string. One of:

  • "manual"
  • "metrics"
  • "optical"

TextStyle.leading

text.sourceText.style.leading

Description

Returns the value of Leading for a Text layer.

Type

Number

TextStyle.leadingType

text.sourceText.style.leadingType

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of Leading Type for the first paragraph of a Text layer.

Type

Predefined string. One of:

  • "bottom-to-bottom"
  • "top-to-top"

TextStyle.leftMargin

text.sourceText.style.leftMargin

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of Left Margin of the first paragraph of a Text layer.

Type

Number

TextStyle.lineJoin

text.sourceText.style.lineJoin

Note

This functionality was added in After Effects 25.0.

Description

Returns the Line Join Type for a Text layer.

Type

Predefined string. One of:

  • "bevel"
  • "miter"
  • "round"

TextStyle.rightMargin

text.sourceText.style.rightMargin

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of Right Margin of the first paragraph of a Text layer.

Type

Number

TextStyle.spaceAfter

text.sourceText.style.spaceAfter

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of the Space After the first paragraph of a Text layer.

Type

Number

TextStyle.spaceBefore

text.sourceText.style.spaceBefore

Note

This functionality was added in After Effects 25.0.

Description

Returns the value of the Space Before the first paragraph of a Text layer.

Type

Number

TextStyle.strokeColor

text.sourceText.style.strokeColor

Description

Returns the Stroke Color as RGB values on a scale from 0 - 1.0.

Type

Array of numbers

TextStyle.strokeWidth

text.sourceText.style.strokeWidth

Description

Returns the Stroke Width value for a Text layer.

Type

Number

TextStyle.tracking

text.sourceText.style.tracking

Description

Returns the value of Tracking for a Text layer.

Type

Number

TextStyle.tsume

text.sourceText.style.tsume

Note

This functionality was added in After Effects 25.0.

Description

Returns the Tsume value for a Text layer.

Type

Number (between 0 and 1).

TextStyle.verticalScaling

text.sourceText.style.verticalScaling

Note

This functionality was added in After Effects 25.0.

Description

Returns the Vertical Scaling for a Text layer.

Type

Number

Methods

TextStyle.replaceText()

text.sourceText.style.replaceText(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

This is used when you want to define (or inherit) a Text Style, while setting the content for a substring of the text.

Parameters

Parameter Type Description
value String Required. The text to set.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

Example

To create a custom style and then set a substring of the text within the expression:

// assume the value of the source text is "Old Text"
const referenceText = thisComp.layer("Source Layer Name").text.sourceText;
const style = referenceText.getStyleAt(0,0);

// This will change the text from "Old Text" to "NewText" as the first 4 characters are replaced.
style.replaceText("New", 0, 4);

TextStyle.setAllCaps()

text.sourceText.style.setAllCaps(value[, startIndex, numOfCharacters])

Description

Used to set the All Caps status.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable All Caps.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setApplyFill()

text.sourceText.style.setApplyFill(value[, startIndex, numOfCharacters])

Description

Used to set whether Fill Color is enabled.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable Fill.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setApplyStroke()

text.sourceText.style.setApplyStroke(value[, startIndex, numOfCharacters])

Description

Used to set whether Stroke is enabled.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable Stroke.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setAutoLeading()

text.sourceText.style.setAutoLeading(value[, startIndex, numOfCharacters])

Description

Used to set the Auto Leading status.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable Auto Leading.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setBaselineDirection()

text.sourceText.style.setBaselineDirection(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Baseline Direction.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Predefined string as defined in BaselineDirection The value to set for Baseline Direction.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setBaselineShift()

text.sourceText.style.setBaselineShift(value[, startIndex, numOfCharacters])

Description

Used to set the Baseline Shift to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Number Required. The Baseline Shift value to set.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setBaselineOption()

text.sourceText.style.setBaselineOption(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the baseline option.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Predefined string as defined in BaselineOption Required. The value to set for Baseline Option.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setDigitSet()

text.sourceText.style.setDigitSet(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Digit Set.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Predefined string as defined in DigitSet Required. The value to use for Digit Set.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setDirection()

text.sourceText.style.setDirection(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the Direction for the entire Text layer, either left-to-right or right-to-left.

Parameters

Parameter Type Description
value Predefined string as defined in Direction The desired value for Direction.

Returns

A TextStyle object.

TextStyle.setEveryLineComposer()

text.sourceText.style.setEveryLineComposer(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to enable or disable the Every-Line Composer for the entire Text layer.

Parameters

Parameter Type Description
value Boolean Whether to enable or disable Every-Line Composer.

Returns

A TextStyle object.

TextStyle.setFauxBold()

text.sourceText.style.setFauxBold(value[, startIndex, numOfCharacters])

Description

Used to set the Faux Bold status.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable Faux Bold.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setFauxItalic()

text.sourceText.style.setFauxItalic(value[, startIndex, numOfCharacters])

Description

Used to set the Faux Italics status.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable Faux Italics.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setFillColor()

text.sourceText.style.setFillColor(value[, startIndex, numOfCharacters])

Description

Used to set the text Fill Color.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Keep in mind that TextStyle.applyFill must be true in order for the fill color to show up. You can set it to true by enabling Fill in the Properties or Character panel, or by using TextStyle.setApplyFill().

Parameters

Parameter Type Description
value Array of numbers Required. [R, G, B] with each value between 0.0 and 1.0.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setFirstLineIndent()

text.sourceText.style.setFirstLineIndent(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the First Line Indent of a Text layer to a specified value.

Parameters

Parameter Type Description
value Number The desired value for First Line Indent.

Returns

A TextStyle object.

TextStyle.setFont()

text.sourceText.style.setFont(value[, startIndex, numOfCharacters])

Description

Used to set the font to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value String Required. The font to set.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setFontSize()

text.sourceText.style.setFontSize(value[, startIndex, numOfCharacters])

Description

Used to set the Font Size to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Number Required. The Font Size to set.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setHangingRoman()

text.sourceText.style.setHangingRoman(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to enable or disable Hanging Roman Punctuation for the entire Text layer.

Parameters

Parameter Type Description
value Boolean Whether to enable or disable Roman Hanging Punctuation.

Returns

A TextStyle object.

TextStyle.setHorizontalScaling()

text.sourceText.style.setHorizontalScaling(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Horizontal Scaling to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Number Required. The value to set the Horizontal Scaling.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setJustification()

text.sourceText.style.setJustification(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the Justification for the entire Text layer.

Warning

The left and right values for alignment/justification will be reversed if the Text layer's TextStyle.direction is set to use right-to-left. You can control this using the Property or Paragraph panel, or via TextStyle.setDirection().

Parameters

Parameter Type Description
value Predefined string as defined in Justification The desired value for the Justification.

Returns

A TextStyle object.

TextStyle.setKerning()

text.sourceText.style.setKerning(value, characterIndex)

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Kerning Value at the specifed character index.

This will only affect the Text layer when KerningType is not set for the character index.

Parameters

Parameter Type Description
value Number Required. The value to set the Kerning Value.
characterIndex Number Required. The character index for the substring to be applied.

Returns

None

TextStyle.setKerningType()

text.sourceText.style.setKerningType(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Kerning Type.

The value will be applied to the entire Text layer unless a start index and number of characters are specified.

Note

manual is not a valid value for this method. To set manual kerning, use TextStyle.setKerning().

Also, note that automatic kerning will take a precendence over manual kerning.

Parameters

Parameter Type Description
value metrics or optical, as defined in KerningType. Required. The value to set for Kerning Type.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be changed. Defaults to the number of characters until end of the string.

Returns

None

TextStyle.setLeading()

text.sourceText.style.setLeading(value[, startIndex, numOfCharacters])

Description

Used to set the Leading to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Keep in mind that TextStyle.isAutoLeading must be false in order for setLeading() to have any visible affect. You can set Leading to a value other than Auto in the Properties or Character panel, or via TextStyle.setAutoLeading().

Parameters

Parameter Type Description
value Number Required. The Leading value to set.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setLeadingType()

text.sourceText.style.setLeadingType(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the Leading Type for the entire Text layer.

Parameters

Parameter Type Description
value Predefined string as defined in LeadingType The desired value for Leading Type.

Returns

A TextStyle object.

TextStyle.setLeftMargin()

text.sourceText.style.setLeftMargin(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the Left Margin of a Text layer to a specified value.

Parameters

Parameter Type Description
value Number The desired value for Left Margin.

Returns

A TextStyle object.

TextStyle.setLigature()

text.sourceText.style.setLigature(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to enable or disable ligatures.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable ligatures.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setLineJoin()

text.sourceText.style.setLineJoin(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Line Join Type to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Predefined string as defined in LineJoin Required. The value to set for Line Join Type.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setRightMargin()

text.sourceText.style.setRightMargin(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the Right Margin of a Text layer to a specified value.

Parameters

Parameter Type Description
value Number The desired value for Right Margin.

Returns

A TextStyle object.

TextStyle.setSmallCaps()

text.sourceText.style.setSmallCaps(value[, startIndex, numOfCharacters])

Description

Used to set the Small Caps status.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Boolean Required. Whether to enable or disable Small Caps.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setSpaceAfter()

text.sourceText.style.setSpaceAfter(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the Space After attribute of a Text layer to a specified value.

Parameters

Parameter Type Description
value Number The desired value for the Space After attribute.

Returns

A TextStyle object.

TextStyle.setSpaceBefore()

text.sourceText.style.setSpaceBefore(value)

Note

This functionality was added in After Effects 25.0.

Warning

This method must be called after TextStyle.setText() if both are being used.

Description

Used to set the Space Before attribute of a Text layer to a specified value.

Parameters

Parameter Type Description
value Number The desired value for the Space Before attribute.

Returns

A TextStyle object.

TextStyle.setStrokeColor()

text.sourceText.style.setStrokeColor(value[, startIndex, numOfCharacters])

Description

Used to set the Stroke Color.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Keep in mind that TextStyle.applyStroke must be true and TextStyle.strokeWidth must be greater than zero in order for any stroke color to be shown. You can set these by enabling Stroke or increasing Stroke Width in the Properties or Character panel, or by using TextStyle.setApplyStroke() and TextStyle.setStrokeWidth(), respectively.

Parameters

Parameter Type Description
value Array of numbers Required. [R, G, B] with each value between 0.0 and 1.0.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setStrokeWidth()

text.sourceText.style.setStrokeWidth(value[, startIndex, numOfCharacters])

Description

Used to set the Stroke Width to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Keep in mind that TextStyle.applyStroke must be true in order to see any change in stroke width. You can set this either by enabling Stroke in the Properties or Character panel, or via TextStyle.setApplyStroke().

Parameters

Parameter Type Description
value Number Required. The value to set the Stroke Width.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setText()

text.sourceText.style.setText(value)

Description

This is used when you want to define (or inherit) a Text Style while setting the text content separately.

Parameters

Parameter Type Description
value String The text to set.

Returns

A TextStyle object.

Examples

To inherit the style and content from another layer:

const referenceText = thisComp.layer("Source Layer Name").text.sourceText;

const style = referenceText.getStyleAt(0, 0);
style.setText(referenceText);

To create a custom style and then set the text within the expression:

text.sourceText
    .createStyle()
    .setFontSize(300)
    .setFont("Impact")
    .setText("Hello world!");

TextStyle.setTracking()

text.sourceText.style.setTracking(value[, startIndex, numOfCharacters])

Description

Used to set the Tracking to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Number Required. The Tracking value to set.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

TextStyle.setTsume()

text.sourceText.style.setTsume(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Tsume to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Number Required. The value to set the Tsume, between 0 and 100.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

None

TextStyle.setVerticalScaling()

text.sourceText.style.setVerticalScaling(value[, startIndex, numOfCharacters])

Note

This functionality was added in After Effects 25.0.

Description

Used to set the Vertical Scaling to a specified value.

The value will be set for the entire Text layer unless startIndex and numOfCharacters are specified.

Parameters

Parameter Type Description
value Number Required. The value to set the Vertical Scaling.
startIndex Number Optional. The start index for the substring to be replaced. Defaults to 0.
numOfCharacters Number Optional. The length of the substring to be replaced. Defaults to the number of characters until end of the string.

Returns

A TextStyle object.

Ended: Text