AV Layer

Return whether the layer is active at the given time.

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

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

Parameters:

• time (float) –

  The time in seconds.

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

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 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 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.

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.

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.

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

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

1. has_audio must be True.
2. audio_enabled must be True.
3. No other layer with audio in the containing_comp may be soloed unless this layer is also soloed.
4. time must fall between in_point (inclusive) and out_point (exclusive).

Parameters:

• time (float) –

  The time in seconds.

Calculates a transformation from a set of points in this layer.

A pure function of the three points and the layer's source dimensions - the current transform is ignored (verified against AE 2026). Shear between the axes is absorbed into scale[2] = 100 * sin(angle), and mirrored point sets come out as 180-degree rotation combinations rather than negative scale.

Parameters:

• point_top_left (list[float]) –

  [x, y, z] comp-space position of the source's top-left corner.

• point_top_right (list[float]) –

  [x, y, z] position of the top-right corner.

• point_bottom_left (list[float]) –

  [x, y, z] position of the bottom-left corner.

Returns:

• dict[str, Any] –

  A dict of transform property values (anchor_point,

• dict[str, Any] –

  position, x_rotation, y_rotation, z_rotation,

• dict[str, Any] –

  scale), assignable to the matching transform properties.

Raises:

• ValueError –

  If the points are coincident or collinear.

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.

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.

Converts composition coordinates, such as sourcePointToComp, to layer coordinates.

The layer's transform chain (parenting included) is evaluated at the composition's current time - like After Effects, which uses the playhead position stored in the file; pass time to evaluate at another time (py_aep extension). For a 3D layer the comp point is cast as a ray from the ACTIVE camera (the front-most enabled camera layer active at that time, else AE's default comp camera) and intersected with the layer's plane - unlike sourcePointToComp(), this direction IS camera-dependent (verified against AE 2026). The camera is placed by its own parent chain. Transform values are read before expressions, as in source_point_to_comp.

Parameters:

• point (list[float]) –

  A position array of [x, y] composition coordinates.

• time (float | None, default: None ) –

  Composition time in seconds (py_aep extension; defaults to the comp's current time).

Returns:

• list[float] –

  A position array of [x, y] layer coordinates.

Raises:

• NotImplementedError –

  If a layer in the parent chain uses an auto-orientation the transform math does not model (see resolvers.transform.build_world_matrix).

• ValueError –

  If the camera ray does not reach the layer plane going forward - it is parallel to the plane, or the layer is at or behind the camera. After Effects returns a literal [0, 0] for these; py_aep raises instead, because that sentinel cannot be told apart from a real result. Also when the layer plane is degenerate (an X or Y scale of 0) or the result overflows a float.

Copy this layer into a composition, as After Effects' copyToComp() does.

The copy is placed at the top of the target layer stack. Its parent is cleared and its transform rewritten so it keeps its place (the parent's transform at time 0 is baked in, whatever the playhead), and the layers its effects reference are cleared - also when the target is this layer's own containing_comp (use duplicate to keep them). Into another composition the track matte and an environment light's source are cleared too, and keyframe and marker times are kept in seconds whatever the target's frame rate (measured on AE 2026).

Parameters:

• into_comp (CompItem) –

  The target CompItem.

Returns: The newly created Layer in the target composition.

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.

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

Parameters:

• layer (Layer) –

  The target layer in the same composition.

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

Parameters:

• layer (Layer) –

  The target layer in the same composition.

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.

Moves this layer to the topmost position of the composition.

Moves this layer to the bottommost position of the composition.

Look up a child property by index or name.

Parameters:

• key (int | str) –

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

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 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 from this layer.

A no-op when the layer has no markers.

Remove the track matte layer reference.

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

Raises:

• AttributeError –

  If the file predates AE 23.0.

Replace the source item for this layer.

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.

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.

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.

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.

Converts layer coordinates, such as boxTextPos, to composition coordinates.

The layer's transform chain (parenting included) is evaluated at the composition's current time - like After Effects, which uses the playhead position stored in the file; pass time to evaluate at another time (py_aep extension). 3D layers project through AE's DEFAULT comp camera: sourcePointToComp() is camera-independent (verified against AE 2026 across one-node, two-node and keyframed-zoom rigs). A 2D layer ignores the out-of-plane part of 3D ancestors, as After Effects does.

Transform values are read before expressions: a layer whose transform chain is driven by expressions converts with the values the expressions replace, where After Effects uses their results.

Parameters:

• point (list[float]) –

  A position array of [x, y] layer coordinates.

• time (float | None, default: None ) –

  Composition time in seconds (py_aep extension; defaults to the comp's current time).

Returns:

• list[float] –

  A position array of [x, y] composition coordinates.

Raises:

• NotImplementedError –

  If a layer in the parent chain uses an auto-orientation the transform math does not model (see resolvers.transform.build_world_matrix).

• ValueError –

  If the result overflows a float.

Retrieves the rectangle bounds of the layer at the specified time index, corrected for text or shape layer content.

For footage, solid, precomposition and adjustment layers this is (0, 0, width, height) of the layer source at every time (verified against AE 2026 - the layer transform never affects it). For a shape layer it is the box of its painted paths, grown by the strokes with extents (rules in resolvers.shape_bounds); for a text layer the tight box of its glyph outlines, from the fonts installed on this machine (rules in resolvers.text_ink). Values are read before expressions.

time is in the layer's own time, not composition time: After Effects neither offsets it by the layer's start time nor applies its stretch (measured on AE 2026 - a layer starting at 0.5 s and stretched to 200 % reports its layer-second-1 content at time=1).

Parameters:

• time (float) –

  The time index, in seconds of layer time.

• extents (bool) –

  True to include the extents. Only relevant for shape layers.

Returns:

• dict[str, float] –

  A dict with top, left, width and height keys.

Raises:

• NotImplementedError –

  For a shape layer using a path operation other than Trim Paths and Repeater, a text layer using a feature outside the measured envelope (text animators, text on a path, faux styles, a font that is not installed, ...), or a 3D model layer (whose box is the model's bounds).