Text layer

TextLayer ¶

Bases: AVLayer

The TextLayer object represents a text layer within a composition.

Example

from py_aep import parse

app = parse("project.aep")
comp = app.project.compositions[0]
text_layer = comp.text_layers[0]
print(text_layer.text)

Info

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

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

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: bool = 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 = 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_type",
    reverse_instance_field=_reverse_auto_orient,
)

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

blending_mode ¶

blending_mode = enum(BlendingMode, "_ldta", "blending_mode")

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 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, and text path options. 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 = bool(
    "_ldta", "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 is itself a PropertyGroup representing one effect. None when the layer has no effects.

effects_active ¶

effects_active = 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 = bool('_ldta', 'enabled')

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

environment_layer ¶

environment_layer: bool = 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.

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",
    reverse_instance_field=_reverse_frame_blending,
)

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 = 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 (Contents) 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", or "Layer". Read-only.

locked ¶

locked = 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 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 = bool('_ldta', 'motion_blur')

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

name ¶

name: str

Display name of the property. Read / Write.

null_layer ¶

null_layer = 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 layer for layer parenting. None if no parent.

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 = bool(
    "_ldta", "preserve_transparency"
)

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

properties ¶

properties: list[Property | PropertyGroup] = properties

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

The layer's sampling method. Read / Write.

selected ¶

selected: bool

When True, the layer is selected in the timeline. Read / Write.

shy ¶

shy = 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 = bool('_ldta', 'solo')

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

source ¶

source: Item | None

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

start_time ¶

start_time = ChunkField[float](
    "_ldta",
    "start_time",
    reverse_instance_field=_reverse_start_time,
)

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

stretch ¶

stretch = ChunkField[float](
    "_ldta",
    "stretch",
    reverse_instance_field=_reverse_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 = 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 = 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 = enum(
    TrackMatteType, "_ldta", "track_matte_type"
)

Specifies the way the track matte is applied. 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.

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.

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 may be soloed unless this layer is also soloed.
time must fall between in_point (inclusive) and out_point (exclusive).

Parameters:

time (float) –

The time in seconds.

property ¶

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

Look up a child property by index or name.

Mirrors ExtendScript PropertyGroup.property(indexOrName). Delegates to __getitem__.

Parameters:

key (int | str) –

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