Shape layer

ShapeLayer ¶

Bases: AVLayer

The ShapeLayer object represents a shape layer within a composition.

Example

from py_aep import parse

app = parse("project.aep")
comp = app.project.compositions[0]
shape_layer = comp.shape_layers[0]
print(shape_layer.content)

Info

ShapeLayer is a subclass of [AVLayer][] object. All methods and attributes of [AVLayer][] are available when working with ShapeLayer.

See: https://ae-scripting.docsforadobe.dev/layer/shapelayer/

Attributes¶

active ¶

active: bool

When True, the layer is active at the current time.

Overrides [PropertyBase.active][] to evaluate [active_at_time][] at time.

adjustment_layer ¶

adjustment_layer = ChunkField[bool](
    "_ldta", "adjustment_layer"
)

When True, the layer is an adjustment layer. Read / Write.

audio_active ¶

audio_active: bool

True if the layer's audio is active at the current time.

For this to be True, [audio_enabled][] must be True, [has_audio][] must be True, no other layer with audio may be soloing unless this layer is also soloed, and the current time must be between [in_point][] and [out_point][]. Read-only.

audio_enabled ¶

audio_enabled = ChunkField[bool]('_ldta', 'audio_enabled')

When True, the layer's audio is enabled. This value corresponds to the audio toggle switch in the Timeline panel. Read / Write.

auto_name ¶

auto_name: str

Fall back to source name, then empty string.

auto_orient ¶

auto_orient = enum(AutoOrientType, '_ldta', 'auto_orient')

The type of automatic orientation to perform for the layer. Read / Write.

blending_mode ¶

blending_mode: BlendingMode

The blending mode of the layer. Read / Write.

can_set_collapse_transformation ¶

can_set_collapse_transformation: bool

True if it is possible to set the [collapse_transformation][AVLayer.collapse_transformation] value.

Returns True for pre-composition layers and solid layers. Read-only.

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, text path options, and the Layer Styles group and its individual styles. Read-only.

can_set_time_remap_enabled ¶

can_set_time_remap_enabled: bool

True if it is possible to enable time remapping on this layer.

Time remapping can be enabled when the layer's source has a non-zero duration (i.e. it is not a still image or text layer). Read-only.

collapse_transformation ¶

collapse_transformation = ChunkField[bool](
    "_ldta",
    "collapse_transformation",
    validate=_validate_collapse_transformation,
)

True if collapse transformation is on for this layer. Read / Write.

comment ¶

comment: str

A descriptive comment for the layer. Read / Write.

containing_comp ¶

containing_comp: CompItem

The composition that contains this layer. Read-only.

effects ¶

effects: PropertyGroup | None

Contains a layer's effects.

This is the Effects PropertyGroup (match name ADBE Effect Parade). Each child in [properties][PropertyGroup.properties] is itself a [PropertyGroup][] representing one effect. None when the layer has no effects.

effects_active ¶

effects_active = ChunkField[bool]("_ldta", "effects_active")

True if the layer's effects are active, as indicated by the icon next to it in the user interface. 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 = ChunkField[bool]('_ldta', 'enabled')

When True, the layer is enabled. Overrides PropertyBase.enabled to read from the ldta chunk. Read / Write.

environment_layer ¶

environment_layer = ChunkField[bool](
    "_ldta",
    "environment_layer",
    post_set="_on_environment_layer_set",
)

True if this is an environment layer in a Ray-traced 3D composition. Setting this to True automatically sets [three_d_layer][] to True. Read / Write.

essential_property_controllers ¶

essential_property_controllers: list[
    EssentialGraphicsController
]

The source composition's Essential Graphics controllers that this precomp layer's Essential Properties overrides reference.

Each entry corresponds to a UUID in essential_property_uuids (same order), resolved against the source comp's motion_graphics_controllers by shared UUID. Empty for a non-precomp layer, a source comp with no controllers, or a layer with no overrides. Read-only.

essential_property_uuids ¶

essential_property_uuids: list[str] = (
    essential_property_uuids
)

UUIDs of Essential Properties overrides on this layer.

Each UUID corresponds to an [EssentialGraphicsController][] in the source composition's Essential Graphics panel.

frame_blending ¶

frame_blending: bool

True if frame blending is enabled for this layer. Read-only.

frame_blending_type ¶

frame_blending_type = enum(
    FrameBlendingType, "_ldta", "frame_blending_type"
)

The type of frame blending for the layer. Read / Write.

frame_in_point ¶

frame_in_point: int

The "in" point of the layer, expressed in composition time (frames). Read / Write.

frame_out_point ¶

frame_out_point: int

The "out" point of the layer, expressed in composition time (frames). Read / Write.

frame_start_time ¶

frame_start_time: int

The start time of the layer, expressed in composition time (frames). Read / Write.

frame_time ¶

frame_time: int

The current time of the layer, expressed in composition time (frames). Read-only.

guide_layer ¶

guide_layer = ChunkField[bool]('_ldta', 'guide_layer')

True if the layer is a guide layer. Read / Write.

has_audio ¶

has_audio: bool

True if the layer has an audio component. Read-only.

has_track_matte ¶

has_track_matte: bool

True if this layer has track matte. When true, this layer's track_matte_type value controls how the matte is applied. Read-only.

has_video ¶

has_video: bool

True if the layer has a video component. An AVLayer has video when its [source][] has video, or when the layer has no external source (text and shape layers always render video). Read-only.

height ¶

height: int

The height of the layer in pixels.

Returns the source item's height if available, otherwise falls back to the containing composition's height (matches ExtendScript behavior for source-less layers like text and shape layers). Read-only.

id ¶

id = ChunkField[int]('_ldta', 'layer_id', read_only=True)

Unique and persistent identification number used internally to identify a Layer between sessions. Read-only.

in_point ¶

in_point: float

The "in" point of the layer, expressed in composition time (seconds). Clamped to start_time for non-still footage layers. Read / Write.

index ¶

index: int

The 0-based index position of the layer in its containing comp.

Warning

Unlike ExtendScript (1-based), this uses Python's 0-based convention so that comp.layers[layer.index] works directly.

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 any child property is modified.

For indexed groups (such as Effects or Masks parades), the group is considered modified when it has any children - adding items to an indexed group is itself a modification. Shape vector groups (value) follow the same rule.

is_name_from_source ¶

is_name_from_source: bool

True if the layer has no expressly set name, but contains a named source.

In this case, layer.name has the same value as layer.source.name. False if the layer has an expressly set name, or if the layer does not have a source. Read-only.

is_name_set ¶

is_name_set: bool

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

is_track_matte ¶

is_track_matte: bool

True if this layer is being used as a track matte. Read-only.

label ¶

label = enum(Label, '_ldta', 'label')

The label color. Colors are represented by their number (0 for None, or 1 to 16 for one of the preset colors in the Labels preferences). Read / Write.

layer_type ¶

layer_type: str

The type of layer. Matches ExtendScript layerType values: "AVLayer", "LightLayer", "CameraLayer", "ParametricMeshLayer", or "Layer". Read-only.

locked ¶

locked = ChunkField[bool]('_ldta', 'locked')

When True, the layer is locked. This corresponds to the lock toggle in the Layer panel. Read / Write.

marker ¶

marker: Property | None

The layer's marker property.

A Property with match_name="ADBE Marker" whose keyframes hold marker values. None when the layer has no markers.

markers ¶

markers: list[MarkerValue]

A flat list of [MarkerValue][] objects for this layer.

Shortcut for accessing marker data without navigating the property tree. Returns an empty list when the layer has no markers.

Example

for marker in layer.markers:
    print(marker.comment)

masks ¶

masks: PropertyGroup | None

Contains a layer's masks.

This is the Masks PropertyGroup (match name ADBE Mask Parade). Each child in [properties][PropertyGroup.properties] is itself a [PropertyGroup][] representing one mask. None when the layer has no masks.

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.

motion_blur ¶

motion_blur = ChunkField[bool]('_ldta', 'motion_blur_flag')

True if motion blur is enabled for the layer. Read / Write.

name ¶

name: None

null_layer ¶

null_layer = ChunkField[bool](
    "_ldta", "null_layer", read_only=True
)

When True, the layer was created as a null object. Read-only.

num_properties ¶

num_properties: int

The number of child properties in this group.

Equivalent to ExtendScript PropertyGroup.numProperties.

out_point ¶

out_point: float

The "out" point of the layer, expressed in composition time (seconds). Clamped to start_time + source.duration * stretch for non-still footage layers without time remapping. Read / Write.

parent ¶

parent: Layer | None

The parent of this layer; can be None.

Offset values are calculated to counterbalance any transforms above this layer in the hierarchy, so that when you set the parent there is no apparent jump in the layer's transform.

For example, if the new parent has a rotation of 30 degrees, the child layer is assigned a rotation of -30 degrees.

To set the parent without changing the child layer's transform values, use the set_parent_with_jump method.

Read / Write.

parent_property ¶

parent_property: PropertyGroup | None

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

preserve_transparency ¶

preserve_transparency = ChunkField[bool](
    "_ldta", "preserve_transparency"
)

True if preserve transparency is enabled for the layer. Read / Write.

properties ¶

properties: list[Property | PropertyGroup]

List of properties in this group. 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_type ¶

property_type: PropertyType

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

quality ¶

quality = enum(LayerQuality, '_ldta', 'quality')

The layer's draft quality setting. Read / Write.

sampling_quality ¶

sampling_quality = enum(
    LayerSamplingQuality,
    "_ldta",
    "sampling_quality",
    min_version=12,
)

The layer's sampling method. Read / Write.

selected ¶

selected: bool

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

Note

Property selection is stored in the .aep binary format but very complex. Parsed projects report False for now.

shy ¶

shy = ChunkField[bool]('_ldta', 'shy')

When True, the layer is "shy", meaning that it is hidden in the Layer panel if the composition's "Hide all shy layers" option is toggled on. Read / Write.

solo ¶

solo = ChunkField[bool]('_ldta', 'solo')

When True, the layer is soloed. Read / Write.

source ¶

source: AVItem | None

The source item for this layer. None for a text layer. Read-only.

start_time ¶

start_time = ChunkField[float]('_ldta', 'start_time')

The start time of the layer, expressed in composition time (seconds). Read / Write.

stretch ¶

stretch = ChunkField[float]('_ldta', 'stretch')

The layer's time stretch, expressed as a percentage. A value of 100 means no stretch. Values between 0 and 1 are set to 1, and values between -1 and 0 (not including 0) are set to -1. Read / Write.

text ¶

text: PropertyGroup | None

Contains a layer's text properties (if any).

three_d_layer ¶

three_d_layer = ChunkField[bool](
    "_ldta",
    "three_d_layer",
    post_set="_on_three_d_layer_set",
)

True if this layer is a 3D layer. Setting this to True automatically sets [environment_layer][] to False. Read / Write.

three_d_per_char ¶

three_d_per_char = ChunkField[bool](
    "_ldta", "three_d_per_char"
)

True if this layer has the Enable Per-character 3D switch set, allowing its characters to be animated off the plane of the text layer. Applies only to text layers. Read / Write.

time ¶

time: float

The current time of the layer, expressed in composition time (seconds). Read-only.

time_remap_enabled ¶

time_remap_enabled: bool

True if time remapping is enabled for this layer. Read / Write.

track_matte_layer ¶

track_matte_layer: AVLayer | None

The track matte layer for this layer. Returns None if this layer has no track matte layer. Read-only.

track_matte_type ¶

track_matte_type: TrackMatteType

Specifies the way the track matte is applied.

Setting TrackMatteType.NO_TRACK_MATTE removes the track matte for this layer and resets the matte layer reference.

Note

This functionality was updated in After Effects 23.0.

Warning

This is a legacy API. Consider using [set_track_matte][] and [remove_track_matte][] instead.

Read / Write.

transform ¶

transform: PropertyGroup

Contains a layer's transform properties.

This is the Transform PropertyGroup (match name ADBE Transform Group). Individual transform properties (Position, Scale, Rotation, etc.) are accessible via [properties][PropertyGroup.properties].

width ¶

width: int

The width of the layer in pixels.

Returns the source item's width if available, otherwise falls back to the containing composition's width (matches ExtendScript behavior for source-less layers like text and shape layers). Read-only.

Functions¶

active_at_time ¶

active_at_time(time: float) -> bool

Return whether the layer is active at the given time.

For this method to return True, three conditions must be met:

The layer must be enabled.
No other layer in the [containing_comp][] may be soloed unless this layer is also [solo][].
time must fall between [in_point][] (inclusive) and [out_point][] (exclusive).

Parameters:

time (float) –

The time in seconds.

add_property ¶

add_property(name: str) -> Property | PropertyGroup

Create and return a new property with the specified name, and add it to this group.

Indexed groups (and, as a named-group exception, the text animator Properties pool) support adding properties; see can_add_property. Accepted names cover every ExtendScript addable family: mask atoms (ADBE Mask Atom / Mask), the expression controls including the Dropdown Menu Control (e.g. ADBE Slider Control / Slider Control, ADBE Dropdown Control), shape elements on a contents group (e.g. ADBE Vector Shape - Rect, ADBE Vector Group), text selectors (e.g. ADBE Text Selector / Range Selector), text animators (ADBE Text Animator / Animator), and animator properties from the fixed pool (e.g. ADBE Text Position 3D / Position).

Note

Unlike ExtendScript, adding a property does not invalidate existing references to the group's other properties.

Parameters:

name (str) –

The display name or match name of the property to add.

Raises:

ValueError –

If a property with this name cannot be added to this group.

add_to_motion_graphics_template ¶

add_to_motion_graphics_template(comp: CompItem) -> bool

Add this layer to comp's Essential Graphics panel as a Media Replacement controller, named after the layer.

Returns True on success, or False when the layer cannot be added (see can_add_to_motion_graphics_template).

Parameters:

comp (CompItem) –

The composition to add the layer to.

add_to_motion_graphics_template_as ¶

add_to_motion_graphics_template_as(
    comp: CompItem, name: str
) -> bool

Add this layer to comp's Essential Graphics panel as a Media Replacement controller with an explicit name.

Returns True on success, or False when the layer cannot be added (see can_add_to_motion_graphics_template).

Parameters:

comp (CompItem) –

The composition to add the layer to.
name (str) –

The controller name to show in the Essential Graphics panel.

add_variable_font_axis ¶

add_variable_font_axis(
    axis_tag: str, font_file: str | None = None
) -> Property

Create and return a Property for a variable font axis, and add it to this group.

Mirrors ExtendScript PropertyGroup.addVariableFontAxis(). Can only be called on the ADBE Text Animator Properties group within a text animator. The axis binds to the first free of the 8 ADBE Text VF Axis slots; calling it again with an already active tag returns the existing property.

The axis bounds, default value, and display name are read from the variable font file with fontTools (After Effects reads them from the installed font; the project file does not store a font path). Pass font_file explicitly, or leave it None to locate the installed font from the text document's font family.

Note

This functionality was added in After Effects 26.0.

Parameters:

axis_tag (str) –

The 4-character tag identifying the variable font axis (e.g. wght, wdth, slnt, ital, opsz).
font_file (str | None, default: None ) –

Optional path to the variable font file. When None, the font is located in the OS font directories by the text document's font family.

Raises:

ValueError –

If this group is not a text animator Properties group, the font cannot be located or is not a variable font, axis_tag is not one of the font's axes, or all 8 axis slots are in use.

audio_active_at_time ¶

audio_active_at_time(time: float) -> bool

Return whether the layer's audio is active at the given time.

For this method to return True, four conditions must be met:

[has_audio][] must be True.
[audio_enabled][] must be True.
No other layer with audio in the [containing_comp][Layer.containing_comp] may be soloed unless this layer is also [soloed][Layer.solo].
time must fall between [in_point][] (inclusive) and [out_point][] (exclusive).

Parameters:

time (float) –

The time in seconds.

can_add_property ¶

can_add_property(name: str) -> bool

Check whether a property with the given name can be added.

Returns True if this group is an indexed group and name is a valid match name or display name for the group type. For the Effect Parade, the expression controls py_aep can create plus any effect already defined in the project (LIST:EfdG) are accepted.

Parameters:

name (str) –

A match name or display name to check.

can_add_to_motion_graphics_template ¶

can_add_to_motion_graphics_template(comp: CompItem) -> bool

Test whether this layer can be added to comp's Essential Graphics panel as a Media Replacement.

The layer must be a Media Replacement layer (has video, not an adjustment or null layer, and its source is a footage or comp item that is not a solid), must be in comp, and must not already be exposed.

Parameters:

comp (CompItem) –

The composition whose Essential Graphics panel to test.

copy_to_comp ¶

copy_to_comp(into_comp: CompItem) -> Layer

Copy this layer into another composition.

If the target is the same as this layer's [containing_comp][], the copy behaves like [duplicate][]: it is placed directly above the original and preserves parent and track matte references.

If the target is a different composition, the copy is placed at the top of the target layer stack and parent and track matte references are cleared.

Parameters:

into_comp (CompItem) –

The target CompItem.

Returns: The newly created Layer in the target composition.

duplicate ¶

duplicate() -> Layer

Create a duplicate of this layer in the same composition.

The duplicate is placed directly above (before) the original layer.

Returns:

Layer –

The newly created Layer.

move_after ¶

move_after(layer: Layer) -> None

Moves this layer to a position immediately after (below) the specified layer.

Parameters:

layer (Layer) –

The target layer in the same composition.

move_before ¶

move_before(layer: Layer) -> None

Moves this layer to a position immediately before (above) the specified layer.

Parameters:

layer (Layer) –

The target layer in the same composition.

move_to ¶

move_to(new_index: int) -> None

Move this property to a new 0-based index within its parent group.

Only valid for children of indexed groups.

Parameters:

new_index (int) –

The target 0-based position.

Raises:

ValueError –

If this property is not in an indexed group.
IndexError –

If new_index is out of range.

move_to_beginning ¶

move_to_beginning() -> None

Moves this layer to the topmost position of the composition.

move_to_end ¶

move_to_end() -> None

Moves this layer to the bottommost position of the composition.

property ¶

property(key: int | str) -> Property | PropertyGroup

Look up a child property by index or name.

Parameters:

key (int | str) –

An int index or a str display name / match name.

remove ¶

remove() -> None

Deletes this layer from the composition.

Layers that reference this layer as a parent become unparented (their transforms are recalculated to preserve world-space appearance). AVLayers that use this layer as a track matte lose their matte reference.

remove_all_keys ¶

remove_all_keys() -> None

Remove every keyframe from all properties in this group, recursively.

Calling this on a Layer clears the keyframes of every property on the layer, including its marker keyframes. Each animated property reverts to a static value; see Property.remove_all_keys.

remove_all_markers ¶

remove_all_markers() -> None

Remove all markers from this layer.

A no-op when the layer has no markers.

remove_track_matte ¶

remove_track_matte() -> None

Remove the track matte layer reference.

The [track_matte_type][] value is preserved. To also reset it, assign TrackMatteType.NO_TRACK_MATTE separately.

Note

Requires AE 23.0+ file format.

Raises:

AttributeError –

If the file predates AE 23.0.

replace_source ¶

replace_source(
    new_source: AVItem, fix_expressions: bool = False
) -> None

Replace the source item for this layer.

Warning

Contrary to ExtendScript, if this method is performed on a null layer, the layer's null_layer attribute changes to False, making the layer visible in comp viewer and renders.

Parameters:

new_source (AVItem) –

The new source [AVItem][].
fix_expressions (bool, default: False ) –

Update expressions that reference the old source name. Not yet implemented.

Raises:

NotImplementedError –

If fix_expressions is True.
ValueError –

If the layer has no source (e.g. shape or text layers), if new_source is not in the project, if new_source would create a composition cycle, or if the layer is a 3D model layer.

set_parent_with_jump ¶

set_parent_with_jump(new_parent: Layer | None) -> None

Sets the parent of this layer to the specified layer, without changing the transform values of the child layer.

There may be an apparent jump in the rotation, translation, or scale of the child layer, as this layer's transform values are combined with those of its ancestors.

If you do not want the child layer to jump, set the parent attribute directly. In this case, an offset is calculated and set in the child layer's transform fields, to prevent the jump from occurring.

Parameters:

new_parent (Layer | None) –

The new parent layer, or None to unparent.

Raises:

ValueError –

If new_parent is this layer itself, one of its descendants, or a layer in another composition.

set_track_matte ¶

set_track_matte(
    track_matte_layer: AVLayer | None,
    track_matte_type: TrackMatteType | int,
) -> None

Sets the track matte layer and type for this layer. Passing in None to track_matte_layer parameter removes the track matte. See [remove_track_matte] for another way of removing track matte.

Note

Requires AE 23.0+ file format.

Parameters:

track_matte_layer (AVLayer | None) –

The layer to use as a track matte, or None to remove the track matte.
track_matte_type (TrackMatteType | int) –

The [TrackMatteType][] to apply. Passing NO_TRACK_MATTE with a non-None layer is a no-op.

Raises:

AttributeError –

If the file predates AE 23.0.
ValueError –

If track_matte_layer belongs to a different composition.