Skip to content

Mask Property Group

MaskPropertyGroup

Bases: PropertyGroup

An individual mask applied to a layer.

The MaskPropertyGroup object encapsulates mask attributes in a layer.

Info

MaskPropertyGroup is a subclass of PropertyGroup object. All methods and attributes of PropertyBase object and [PropertyGroup][], in addition to those listed below, are available when working with MaskPropertyGroup.

Example 
from py_aep import parse

app = parse("project.aep")
comp = app.project.compositions[0]
layer = comp.layers[0]
mask = layer.masks[0]
print(mask.inverted)

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

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

color 

color = ChunkField[List[float]](
    "_mkif", "color", validate=validate_rgb_color
)

The color used to draw the mask outline as it appears in the user interface (Composition panel, Layer panel, and Timeline panel). The three array values specify the red, green, and blue components of the color. 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](
    "_tdsb",
    "enabled",
    default=True,
    validate=_validate_enabled,
)

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

inverted 

inverted = ChunkField[bool]('_mkif', 'inverted')

When True, the mask is inverted. Read / Write.

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_set 

is_name_set: bool

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

locked 

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

When True, the mask is locked and cannot be edited in the user interface. Read / Write.

mask_feather_falloff 

mask_feather_falloff = enum(
    MaskFeatherFalloff, "_mkif", "mask_feather_falloff"
)

The feather falloff mode for the mask. Applies to all feather values for the mask. Read / Write.

mask_mode 

mask_mode = enum(MaskMode, '_mkif', 'mode')

The blending mode for the mask. Controls how the mask interacts with other masks and with the layer below. Read / Write.

mask_motion_blur 

mask_motion_blur = enum(
    MaskMotionBlur, "_mkif", "mask_motion_blur"
)

How motion blur is applied to this mask. Read / Write.

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.

name 

name: str

Display name of the property. Read / Write.

num_properties 

num_properties: int

The number of child properties in this group.

Equivalent to ExtendScript PropertyGroup.numProperties.

parent_property 

parent_property: PropertyGroup | None

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

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.

roto_bezier 

roto_bezier: bool

When True, the mask uses RotoBezier, enabling curved mask segments without direction handles. Read / Write.

The flag lives in the Mask Shape's tdsb. A freshly added mask has no Mask Shape subtree (AE treats it as the implicit default full-frame rectangle), so enabling RotoBezier materializes that default path - mirroring what After Effects writes.

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.

Functions

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

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.

duplicate 

duplicate() -> PropertyBase

Duplicate this property within its parent group.

The duplicate is inserted immediately after the original. Only valid for children of indexed groups (see [PropertyType][]).

Returns:

Raises:

  • ValueError –

    If this property is not in an indexed group.

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.

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

Remove this property from its parent group.

Only valid for children of indexed groups (effects, masks, shape contents, text animators).

Raises:

  • ValueError –

    If this property is not in an indexed group.

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.