Expressions

Properties can have expressions associated with them, when this is the case the value of such properties can be modified by using the expression.

The expression language is based on JavaScript / ECMAScript.

For the most part it uses what is described in the After Effects expressions.

More resources on AE expressions:

Global objects

`$bm_rt`

Name	`$bm_rt`
Type	Depends on the property
Description	Output value for the expression
Notes	Must be declared and be assigned a value in every expression

The special variable $bm_rt is used to determine the value of the expression.

This variable must be declared by the expression and must have a value compatible with the property;

var $bm_rt;
$bm_rt = 60;

Rotation Expression
var $bm_rt = 60;
Position Expression
var $bm_rt = [256, 256];

`time`

Name	`time`
Type	`number`
Description	The current time within the composition in seconds
Notes	Read only

Rotation Expression
var $bm_rt = time * 360;

`value`

Name	`value`
Type	Depends on the property
Description	The value the property would have without expressions
Notes	Read only

Position Expression
var $bm_rt = []; $bm_rt[0] = value[0] + Math.cos(2 * Math.PI * time) * 100; $bm_rt[1] = value[1];

`thisProperty`

Name	`thisProperty`
Type	Property
Description	Property the expression is operating on
Notes	Read only

`thisComp`

Name	`thisComp`
Type	Composition
Description	Composition the property is in
Notes	Read only

`thisLayer`

Name	`thisLayer`
Type	Layer
Description	Layer the property is in
Notes	Read only

Animation Structure functions

comp()

Synopsis

comp (
    name: string
): Composition

Parameters

Name	Type	Default	Description
`name`	`string`		Composition name

Return

Type	Composition
Description	Composition object matching the given name

Misc Functions

posterizeTime()

Synopsis

posterizeTime (
    fps: number
)

The rest of the expression will only be updated this many times per second

Parameters

Name	Type	Default	Description
`fps`	`number`		Frames per second

timeToFrames()

Synopsis

timeToFrames (
    time: number = time + thisComp.displayStartTime
    fps: number = 1.0 / thisComp.frameDuration
): number

Converts a time in seconds to a number of frames

Parameters

Name	Type	Default	Description
`time`	`number`	`time + thisComp.displayStartTime`	Time in seconds
`fps`	`number`	`1.0 / thisComp.frameDuration`	Frames per second

Return

Type	`number`
Description	Number of frames

framesToTime()

Synopsis

framesToTime (
    frames: number
    fps: number = 1.0 / thisComp.frameDuration
): number

Converts a number of frames to a time in seconds

Parameters

Name	Type	Default	Description
`frames`	`number`		Number of frames
`fps`	`number`	`1.0 / thisComp.frameDuration`	Frames per second

Return

Type	`number`
Description	Time in seconds

rgbToHsl()

Synopsis

rgbToHsl (
    rgb: array[3]|array[4]
): array[3]|array[4]

Parameters

Name	Type	Default	Description
`rgb`	`array[3]`\|`array[4]`		RGB(A) color, with components in 0, 1

Return

Type	`array[3]`\|`array[4]`
Description	HSL(A) color, with components in 0, 1

hslToRgb()

Synopsis

hslToRgb (
    hsl: array[3]|array[4]
): array[3]|array[4]

Parameters

Name	Type	Default	Description
`hsl`	`array[3]`\|`array[4]`		HSL(A) color, with components in 0, 1

Return

Type	`array[3]`\|`array[4]`
Description	RGB(A) color, with components in 0, 1

createPath()

Synopsis

createPath (
    points: array
    in_tangents: array = []
    out_tangents: array = []
    is_closed: boolean = true
): Path

Creates bezier path data

Parameters

Name	Type	Default	Description
`points`	`array`		Array of points (each point is a list with 2 numbers)
`in_tangents`	`array`	`[]`	Array of in tangents correponding to the point with the same index
`out_tangents`	`array`	`[]`	Array of out tangents correponding to the point with the same index
`is_closed`	`boolean`	`true`	Whether the path is closed

Return

Type	Path

Math functions

add()

Synopsis

add (
    a: any
    b: any
): any

Parameters

Name	Type	Default	Description
`a`	any
`b`	any

Return

Type	any

If a and b are numbers, it will return their sum.

If they string, their concatenation.

If they are vectors, their element-wise sum.

If one is a vector and the other a number, it will return the sum of the number by the first element of the vector.

This function is also available as $bm_sum and sum.

sub()

Synopsis

sub (
    a: any
    b: any
): any

Parameters

Name	Type	Default	Description
`a`	any
`b`	any

Return

Type	any

If a and b are numbers, or can be converted to numbers, it will return their difference.

If they are vectors, their element-wise difference.

This function is also avilable as $bm_sub.

mul()

Synopsis

mul (
    a: any
    b: any
): any

Parameters

Name	Type	Default	Description
`a`	any
`b`	any

Return

Type	any

If a and b are numbers, or can be converted to numbers, it will return their product.

If one of them is a vector and the other a number, it will return a vector with each element multiplied by the number.

This function is also avilable as $bm_mul.

div()

Synopsis

div (
    a: any
    b: any
): any

Parameters

Name	Type	Default	Description
`a`	any
`b`	any

Return

Type	any

If a and b are numbers, or can be converted to numbers, it will return their division.

If one of them is a vector and the other a number, it will return a vector with each element divided by the number.

This function is also avilable as $bm_div.

mod()

Synopsis

mod (
    a: any
    b: any
): any

Parameters

Name	Type	Default	Description
`a`	any
`b`	any

Return

Type	any

clamp()

Synopsis

clamp (
    value: number
    minimum: number
    maximum: number
): number

Clamps a value inside a range

Parameters

Name	Type	Description
`value`	`number`	The value to clamp
`minimum`	`number`	Minimum value
`maximum`	`number`	Maximum value

Return

Type	`number`

normalize()

Synopsis

normalize (
    vector: array
): number

Divides a vector by its length

Parameters

Name	Type	Default	Description
`vector`	`array`

Return

Type	`number`
Description	same as `div(vector, length(vector))`

length()

Synopsis

length (
    vector: array
): number

Parameters

Name	Type	Default	Description
`vector`	`array`

Return

Type	`number`
Description	length of `vector`

Synopsis

length (
    a: array
    b: array
): number

Parameters

Name	Type	Default	Description
`a`	`array`
`b`	`array`

Return

Type	`number`
Description	Distance between `a` and `b`.

looAt()

Synopsis

lookAt (
    from_point: array[3]
    to_point: array[3]
): number

Parameters

Name	Type	Default	Description
`from_point`	`array[3]`
`to_point`	`array[3]`

Return

Type	`number`
Description	length of `vector`

seedRandom()

Synopsis

seedRandom (
    seed: number
)

Sets the seed for random functions

Parameters

Name	Type	Default	Description
`seed`	`number`

random()

Synopsis

random (): number

Return

Type	`number`
Description	Random number between 0 and 1

Synopsis

random (
    max: number|array
): number|array

Parameters

Name	Type	Default	Description
`max`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Random number between 0 and `max`, element wise if the argument is an array

Synopsis

random (
    min: number|array
    max: number|array
): number|array

Parameters

Name	Type	Default	Description
`min`	`number`\|`array`
`max`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Random number between `min` and `max`, element wise if the arguments are arrays

linear()

Synopsis

linear (
    t: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between 0 and 1
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Linear interpolation between `value1` and `value2`

Synopsis

linear (
    t: number
    t_min: number
    t_max: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between `t_min` and `t_max`
`t_min`	`number`	Lower bound for the `t` range
`t_max`	`number`	Lower bound for the `t` range
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Linear interpolation between `value1` and `value2`, `t` is first normalized inside `t_min` and `t_max`

ease()

Works the same as linear() but with a smooth cubic interpolation.

Synopsis

ease (
    t: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between 0 and 1
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Interpolation between `value1` and `value2`

Synopsis

ease (
    t: number
    t_min: number
    t_max: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between `t_min` and `t_max`
`t_min`	`number`	Lower bound for the `t` range
`t_max`	`number`	Lower bound for the `t` range
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Interpolation between `value1` and `value2`, `t` is first normalized inside `t_min` and `t_max`

easeIn()

Interpolation, starts the same as ease() and ends the same as linear()

Synopsis

easeIn (
    t: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between 0 and 1
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Interpolation between `value1` and `value2`

Synopsis

easeIn (
    t: number
    t_min: number
    t_max: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between `t_min` and `t_max`
`t_min`	`number`	Lower bound for the `t` range
`t_max`	`number`	Lower bound for the `t` range
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Interpolation between `value1` and `value2`, `t` is first normalized inside `t_min` and `t_max`

easeOut()

Interpolation, starts the same as linear() and ends the same as ease()

Synopsis

easeOut (
    t: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between 0 and 1
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Interpolation between `value1` and `value2`

Synopsis

easeOut (
    t: number
    t_min: number
    t_max: number
    value1: number|array
    value2: number|array
): number|array

Parameters

Name	Type	Description
`t`	`number`	Interpolation factor between `t_min` and `t_max`
`t_min`	`number`	Lower bound for the `t` range
`t_max`	`number`	Lower bound for the `t` range
`value1`	`number`\|`array`
`value2`	`number`\|`array`

Return

Type	`number`\|`array`
Description	Interpolation between `value1` and `value2`, `t` is first normalized inside `t_min` and `t_max`

degreesToRadians()

Synopsis

degreesToRadians (
    degrees: number
): number

Parameters

Name	Type	Default	Description
`degrees`	`number`		Angle in degrees

Return

Type	`number`
Description	Angle in radians

radiansToDegrees()

Synopsis

radiansToDegrees (
    radians: number
): number

Parameters

Name	Type	Default	Description
`radians`	`number`		Angle in radians

Return

Type	`number`
Description	Angle in degrees

Property

Property.value

Name	`value`
Type	Depends on the property
Description	The current value the property
Notes	Read only

Property.numKeys

Name	`numKeys`
Type	`number`
Description	Number of keyframes
Notes	Read only

Property.propertyIndex

Name	`propertyIndex`
Type	`number`
Description	Value of `ix` in the JSON for this property
Notes	Read only

Property.valueAtTime()

Synopsis

valueAtTime (
    t: number
): any

Parameters

Name	Type	Default	Description
`t`	`number`		Time in seconds

Return

Type	Depends on the property
Description	The value of the property at the given time (without expressions)

Property.getVelocityAtTime()

Synopsis

getVelocityAtTime (
    t: number
): any

Parameters

Name	Type	Default	Description
`t`	`number`		Time in seconds

Return

Type	Depends on the property
Description	The rate of change for the property, with the same dimensions as the value

Property.getSpeedAtTime()

Synopsis

getSpeedAtTime (
    t: number
): number

Parameters

Name	Type	Default	Description
`t`	`number`		Time in seconds

Return

Type	`number`
Description	The rate of change for the property as a scalar

Property.smooth()

Synopsis

smooth (
    width: number
    samples: number
): any

Parameters

Name	Type	Default	Description
`width`	`number`
`samples`	`number`

Return

Type	Depends on the property

Property.loopIn()

Synopsis

loopIn (
    type: string
    duration: number
    wrap: boolean
): any

Parameters

Name	Type	Default	Description
`type`	`string`
`duration`	`number`
`wrap`	`boolean`

Return

Type	Depends on the property

Property.loopOut()

Synopsis

loopOut (
    type: string
    duration: number
    wrap: boolean
): any

Parameters

Name	Type	Default	Description
`type`	`string`
`duration`	`number`
`wrap`	`boolean`

Return

Type	Depends on the property

Composition

Composition object

Position Expression
var $bm_rt = [256, 256] var rotation = comp("Animation").layer("Layer").transform.rotation / 180 * Math.PI; $bm_rt[0] += Math.cos(rotation) * 200; $bm_rt[1] += Math.sin(rotation) * 200;

As a function

As a function a composition object can give you access to the layers by name or index

Position Expression
var $bm_rt = [256, 256] var rotation = thisComp("Layer").transform.rotation / 180 * Math.PI; $bm_rt[0] += Math.cos(rotation) * 200; $bm_rt[1] += Math.sin(rotation) * 200;

Composition.numLayers

Name	`numLayers`
Type	`number`
Description	Number of layers in the composition

Composition.width

Name	`width`
Type	`number`
Description	Width of the composition, same as `w` in the JSON

Composition.height

Name	`height`
Type	`number`
Description	Height of the composition, same as `h` in the JSON

Composition.displayStartTime

Name	`displayStartTime`
Type	`number`
Description	Start time of the composition, in seconds. Similar to `ip` in the JSON but converted into seconds

Composition.frameDuration

Name	`frameDuration`
Type	`number`
Description	Duration of a frame in second, reciprocal of frames per second

Composition.pixelAspect

Name	`pixelAspect`
Type	`number`
Description	Pixel aspect ratio, generally `1`

Composition.layer()

Synopsis

layer (
    layer: number|string
): Layer

Returns the given layer

Parameters

Name	Type	Default	Description
`layer`	`number`\|`string`		Layer name or index

Return

Type	Layer

Layer

Layer object.

Note that it also has all the attributes from Transform.

Layer.index

Name	`index`
Type	`number`
Description	Layer index, same as `ind` in the JSON

Layer.inPoint

Name	`inPoint`
Type	`number`
Description	Same as `ip` in the JSON but in seconds

Layer.outPoint

Name	`outPoint`
Type	`number`
Description	Same as `op` in the JSON but in seconds

Layer.startTime

Name	`startTime`
Type	`number`
Description	Same as `st` in the JSON but in seconds

Layer.transform

Transform attributes can also be accessed from the layer object directly

Name	`transofrm`
Type	Transform
Description

Layer.source

Name	`source`
Type	`string`
Description	For layers referencing an asset, the `id` of that asses. (Same as `refId` in the JSON)

Layer.width

Name	`width`
Type	`number`
Description	Same as `Layer.sourceRectAtTime().width`

Layer.height

Name	`height`
Type	`number`
Description	Same as `Layer.sourceRectAtTime().height`

Layer.hasParent

Name	`hasParent`
Type	`boolean`
Description	Whether the layer has a parent

Layer.parent

Name	`parent`
Type	Layer
Description	Parent layer

Layer.sourceRectAtTime

Synopsis

sourceRectAtTime (): object

Return

Type	`object`
Description	Object with these attributes

Layer.effect

Synopsis

effect (
    effect: number|string
): Effect

Returns the given effect

Parameters

Name	Type	Default	Description
`effect`	`number`\|`string`		Name or index

Return

Type	Effect

Layer.contents

Synopsis

contents (
    shape: number|string
): Shape

For shape layers, returns the given shape

Parameters

Name	Type	Default	Description
`shape`	`number`\|`string`		Name or index

Return

Type	Shape

Layer space transforms

These methods convert between coordinates systems within a layer.

Some of these functions have a Vec suffix, which means they should be used for difference between points (the version without this suffix is for points).

Layer.toComp

Synopsis

toComp (
    point: Array
    time: number = time
): Array

Maps a point from Layer coordinates to composition coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Point
`time`	`number`	`time`	Time

Return

Type	Array

Layer.fromComp

Synopsis

toComp (
    point: Array
    time: number = time
): Array

Maps a point from composition coordinates to Layer coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Point
`time`	`number`	`time`	Time

Return

Type	Array

Layer.toCompVec

Synopsis

toComp (
    point: Array
    time: number = time
): Array

Maps a vector from Layer coordinates to composition coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Vector
`time`	`number`	`time`	Time

Return

Type	Array

Layer.fromCompVec

Synopsis

toComp (
    point: Array
    time: number = time
): Array

Maps a vector from composition coordinates to Layer coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Vector
`time`	`number`	`time`	Time

Return

Type	Array

Layer.toWorld

Synopsis

toWorld (
    point: Array
    time: number = time
): Array

Maps a point from Layer coordinates to world coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Point
`time`	`number`	`time`	Time

Return

Type	Array

Layer.fromWorld

Synopsis

toWorld (
    point: Array
    time: number = time
): Array

Maps a point from world coordinates to Layer coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Point
`time`	`number`	`time`	Time

Return

Type	Array

Layer.toWorldVec

Synopsis

toWorld (
    point: Array
    time: number = time
): Array

Maps a vector from Layer coordinates to world coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Vector
`time`	`number`	`time`	Time

Return

Type	Array

Layer.fromWorldVec

Synopsis

toWorld (
    point: Array
    time: number = time
): Array

Maps a vector from world coordinates to Layer coordinates

Parameters

Name	Type	Default	Description
`point`	Array		Vector
`time`	`number`	`time`	Time

Return

Type	Array

Transform

Name	`anchorPoint`
Type	`array[2]`
Description	Value of `a`

Name	`position`
Type	`array[2]`
Description	Value of `p`

Name	`scale`
Type	`number`
Description	Value of `s`

Name	`rotation`
Type	`number`
Description	Value of `r`

Name	`opacity`
Type	`number`
Description	Value of `o`

Name	`skew`
Type	`number`
Description	Value of `sk`

Name	`skewAxis`
Type	`number`
Description	Value of `sa`

Effect

Name	`active`
Type	`boolean`
Description	Whether the effect is active

Effect()

Synopsis

 (
    property: number|string
): number|Array

Returns the value for the given property of the effect

Parameters

Name	Type	Default	Description
`property`	`number`\|`string`		Name or index of the property

Return

Type	`number`\|Array