Property

Property ¶

Bases: PropertyBase

The Property object contains value, keyframe, and expression information about a particular AE property of a layer. An AE property is a value, often animatable, of an effect, mask, or transform within an individual layer.

Example

from py_aep import parse

app = parse("project.aep")
comp = app.project.compositions[0]
prop = comp.layers[0].transform.property("ADBE Position")
print(prop.value)

Info

Property is a subclass of PropertyBase. All methods and attributes of PropertyBase are available when working with Property.

See: https://ae-scripting.docsforadobe.dev/property/property/

Attributes¶

active ¶

active: bool

Same as enabled.

auto_name ¶

auto_name: str

The automatic (display) name derived from match_name.

can_set_enabled ¶

can_set_enabled: bool

True if the enabled attribute value can be set.

This is True for all layers, effect property groups, shape vector groups, and text path options. Read-only.

can_vary_over_time ¶

can_vary_over_time: bool

When True, the named property can vary over time - that is, keyframe values or expressions can be written to this property.

Note

A small subset of effect dropdown / menu parameters may report can_vary_over_time as False in the binary even though After Effects allows keyframing them.

Read-only.

default_value ¶

default_value: Any = None

The default value of the property.

dimensions ¶

dimensions = ChunkField[int](
    "_tdb4", "dimensions", default=1
)

The number of dimensions in the property value (1, 2, 3, or 4). Read-only.

dimensions_separated ¶

dimensions_separated: bool

When True, the property's dimensions are represented as separate properties. For example, if the layer's position is represented as X Position and Y Position properties in the Timeline panel, the Position property has this attribute set to True. This attribute applies only when the property is a "separation leader" (a multidimensional property that can be separated). Read / Write.

elided ¶

elided: bool

When True, the property is not shown in the UI. An elided property is still present in the timeline but hidden from view. Read-only.

enabled ¶

enabled = bool('_tdsb', 'enabled', default=True)

Corresponds to the setting of the eyeball icon. Read / Write.

expression ¶

expression: str

The expression for the named property. Writeable only when can_set_expression for the named property is True. Read / Write.

expression_enabled ¶

expression_enabled: bool

When True, the named property uses its associated expression to generate a value. When False, the keyframe information or static value of the property is used. Read / Write.

expression_error ¶

expression_error: str = ''

Contains the error, if any, generated by evaluation of the string most recently set in expression. If no expression string has been specified, or if the last expression string evaluated without error, contains the empty string ("").

Warning

The parser cannot evaluate expressions, so this attribute is always an empty string. After Effects computes expression errors at runtime when it evaluates the expression engine; this information is not stored in the binary .aep file.

Read-only.

has_max ¶

has_max: bool

True if there is a maximum permitted value for the named property.

has_min ¶

has_min: bool

True if there is a minimum permitted value for the named property.

is_dropdown_effect ¶

is_dropdown_effect: bool

True if the property is the Menu property of a Dropdown Menu Control effect.

is_effect ¶

is_effect: bool

When True, this property is an effect PropertyGroup. Read-only.

is_mask ¶

is_mask: bool

When True, this property is a mask PropertyGroup. Read-only.

is_modified ¶

is_modified: bool

True if the property value differs from its default.

A property is considered modified when it has keyframes, has an expression (enabled or disabled), or when its current value differs from default_value.

is_name_set ¶

is_name_set: bool

True if the name has been explicitly set by the user. Read-only.

is_separation_follower ¶

is_separation_follower: bool

True if the property is a component of a separated multidimensional property (e.g. X Position, Y Position, Z Position).

is_separation_leader ¶

is_separation_leader: bool

True if the property is a multidimensional property that can be separated.

is_spatial ¶

is_spatial: bool

When True, the named property defines a spatial value.

Examples are position and effect point controls. Read-only.

is_time_varying ¶

is_time_varying: bool

True if the named property has keyframes or an enabled expression.

keyframes ¶

keyframes: list[Keyframe] = keyframes

The list of keyframes for this property. Read-only.

last_value ¶

last_value: Any = None

The last value of the property (before animation).

locked_ratio ¶

locked_ratio = bool(
    "_tdsb", "locked_ratio", read_only=True, default=False
)

When True, the property's X/Y ratio is locked. Read-only.

match_name ¶

match_name: str

A special name for the property used to build unique naming paths. The match name is not displayed, but you can refer to it in scripts. Every property has a unique match-name identifier. Read-only.

max_value ¶

max_value: Any

The maximum permitted value of the named property. Only valid if has_max is True. Read-only.

min_value ¶

min_value: Any

The minimum permitted value of the named property. Only valid if has_min is True. Read-only.

name ¶

name: str

Display name of the property. Read / Write.

nb_options ¶

nb_options: int | None = None

The number of options in a dropdown property.

parent_property ¶

parent_property: PropertyGroup | None

The parent PropertyGroup of this property, or None for top-level layer property groups. Read-only.

property_control_type ¶

property_control_type: PropertyControlType

The control type of the property (e.g., scalar, color, boolean). Read-only.

property_depth ¶

property_depth: int

The number of levels of parent groups between this property and the containing layer. The value is 0 for a layer. Read-only.

property_index ¶

property_index: int | None

The 0-based position of this property within its parent group.

Returns None for layers (property depth 0).

Warning

Unlike ExtendScript (1-based), this uses Python's 0-based convention so that group.properties[prop.property_index] works directly.

Read-only.

property_parameters ¶

property_parameters: list[str] | None = None

An array of all item strings in a dropdown menu property. This attribute applies to dropdown menu properties of effects and layers, including custom strings in the Menu property of the Dropdown Menu Control. Read-only.

property_type ¶

property_type: PropertyType

The type of this property. One of PropertyType.PROPERTY, PropertyType.NAMED_GROUP, or PropertyType.INDEXED_GROUP. Read-only.

property_value_type ¶

property_value_type: PropertyValueType

The type of value stored in the named property. Each type of data is stored and retrieved in a different kind of structure. For example, a 3D spatial property (such as a layer's position) is stored as an array of three floating-point values. Read-only.

selected ¶

selected: bool

When True, the property is selected. Read / Write.

separation_dimension ¶

separation_dimension: int | None

For a separated follower, the dimension it represents.

Returns 0, 1, or 2 for X, Y, or Z. Returns None for properties that are not separation followers.

separation_leader ¶

separation_leader: Property | None

For a separation follower, the leader property.

Returns the Property that acts as the separation leader (e.g. Position) for this follower (e.g. X Position). Returns None when this property is not a follower or the leader cannot be found.

units_text ¶

units_text: str

The text description of the units in which the value is expressed.

Common values include "pixels", "degrees", "percent", "seconds", and "dB". An empty string indicates the property has no specific unit. Read-only.

value ¶

value: Any

The value of the named property at the current time. If expression_enabled is True, returns the evaluated expression value. If there are keyframes, returns the keyframed value at the current time. Otherwise, returns the static value. Read / Write.

Functions¶

get_separation_follower ¶

get_separation_follower(dim: int) -> Property | None

Retrieve a specific follower property for a separated, multidimensional property.

For example, you can use this method on the Position property to access the separated X Position and Y Position properties.

Parameters:

dim (int) –

The dimension number (starting at 0).

nearest_key ¶

nearest_key(time: float) -> Keyframe

Returns the keyframe nearest to the specified time.

Parameters:

time (float) –

The time in seconds; a floating-point value. The beginning of the composition is 0.

nearest_key_index ¶

nearest_key_index(time: float) -> int

Returns the index of the keyframe nearest to the specified time.

Parameters:

time (float) –

The time in seconds; a floating-point value. The beginning of the composition is 0.

synthesized ¶

synthesized(
    spec: _PropSpec,
    property_depth: int,
    *,
    parent_property: PropertyGroup,
    value: Any = _USE_VALUE,
    default_value: Any = _USE_VALUE,
) -> Property

Create a synthesized Property from a _PropSpec.

Used to synthesize properties expected by ExtendScript but absent from the binary.

Parameters:

spec (_PropSpec) –

The property specification describing the property.
property_depth (int) –

The depth of the property in the tree.
parent_property (PropertyGroup) –

The container that owns the synthesized property.
value (Any, default: _USE_VALUE ) –

Override for the property value. When omitted, uses spec.value.
default_value (Any, default: _USE_VALUE ) –

Override for the default value. When omitted, uses the spec's default_value logic.

value_at_time ¶

value_at_time(
    time: float, pre_expression: bool = True
) -> (
    list[float]
    | float
    | MarkerValue
    | Shape
    | TextDocument
    | None
)

Get the value of the named property at the given time.

If the property has keyframes, the value is computed by interpolating between surrounding keyframes using the stored interpolation type and temporal ease.

If the property is not animated, returns the static value.

Parameters:

time (float) –

The composition time in seconds at which to evaluate the property.
pre_expression (bool, default: True ) –

When True the value is evaluated before any expression is applied (the only mode supported by the parser).

Raises:

NotImplementedError –

If pre_expression is False, because the parser cannot evaluate expressions.