New Scripting API for Selectable Track Matte Layers

[Catie Bass]

Good morning all, and happy Friday! Coming to you with an update on Selectable Track Matte Layers: with After Effects Beta version 23.0x37 we are introducing the following scripting changes to support the new Selectable Track Matte Layer behavior.

Previous scripting models, and After Effects as a whole, only required the setting of trackMatteType, as there was no ambiguity about which layer was the track matte — it was always the layer right above the matted layer in the layer stack (index-1).

Since Track Mattes can now be sourced from any layer, our scripting methods have been updated as well. However, legacy scripts that do not supply a Track Matte source will fall back to previous behavior of using the layer above the current layer as the Track Matte source.

New API

1. AVLayer.setTrackMatte() - Method to set the track matte on the AV Layer.
Parameters:
* trackMatteLayer : the AV layer to be used as the track matte layer for the fill layer. Passing null for layer will set the track matte layer to None.
* trackMatteType : the TrackMatteType enumerated value.
One of:

•	TrackMatteType.ALPHA, 
•	TrackMatteType.ALPHA_INVERTED,
•	TrackMatteType.LUMA,
•	TrackMatteType.LUMA_INVERTED,
•	TrackMatteType.NO_TRACK_MATTE.

Note that if the layer parameter is not null, then the type parameter should not be passed as:

TrackMatteType.NO_TRACK_MATTE

In this case the call will be a no-op.

Returns: Nothing

2. AVLayer.removeTrackMatte() - Method to remove any track matte set on the AV Layer.
Parameters: None

Returns: Nothing

3. AVLayer.trackMatteLayer - Attribute to get the track matte layer of the AV Layer.
Type: AV Layer. Read only.

Legacy API

• AVLayer.trackMatteType - This is the existing method to create a track matte. It will continue to work as before. However, since this is only one piece of information (type) we need to assume the other piece (track matte layer) to make a well-formed track matte.
  • There are two possibilities here -
    • If a track matte layer has not already been set, then we fall back to the previous track matte behavior and use the layer right above the fill layer as the track matte layer, using the track matte type specified.
      This also ensures that legacy scripts that assume the track matte will be the layer above the fill layer will continue to work as before.
    • If the fill layer already has a track matte layer set, this method will only update the track matte type.
  • For new scripts, both track matte layer and type should be set to match the current scripting model or layers that just happen to be above the matted layer may accidentally be included as track mattes.
  • Please note that writing to this attribute is not recommended for new scripts, as we should be setting both track matte layer and type together for a layer, instead of separately. Setting trackMatteType on its own can trigger old behavior, as described above. Please use the new APIs mentioned above.

Sample Code

// Declare the required layer variables

var curComp = app.project.activeItem;

var fillLayer = curComp.layer(3);

var trackMatteLayer = curComp.layer(5);



// Set layer at index 5 as track matte for layer at index 3

fillLayer.setTrackMatte(trackMatteLayer, TrackMatteType.LUMA_INVERTED);



// Invalid operation - will be a No-op

fillLayer.setTrackMatte(trackMatteLayer, TrackMatteType.NO_TRACK_MATTE); 



// Modify only type, while preserving matte layer 

fillLayer.setTrackMatte(fillLayer.trackMatteLayer, TrackMatteType.LUMA);



// Modify only track matte layer, while preserving the type

fillLayer.setTrackMatte(curComp.layer(6), fillLayer.trackMatteType);



// Remove the track matte

fillLayer.removeTrackMatte();

[jamesVoodooMotion]

Brillinat thanks for sharing this!

[babichfx]

Thank you!