Differences from ExtendScript¶

This page documents the intentional design differences between py_aep and the After Effects ExtendScript API. These are not bugs - they are choices made to provide a more Pythonic, convenient, or complete interface.

Naming Conventions¶

ExtendScript uses camelCase for attributes and methods. py_aep uses snake_case following Python conventions:

Indexing¶

ExtendScript collections are 1-based. Python lists and py_aep are 0-based:

var firstLayer = comp.layer(1);
var firstKey = prop.keyValue(1);

first_layer = comp.layers[0]
first_key = prop.keyframes[0].value

Layer.index and PropertyBase.property_index also use 0-based numbering, so that comp.layers[layer.index] and group.properties[prop.property_index] work directly without offset arithmetic.

Collections and Iterators¶

ExtendScript uses indexed accessor methods (item(index), layer(index)) on custom collection objects (ItemCollection, LayerCollection, OMCollection, RQItemCollection). py_aep uses standard Python lists:

for (var i = 1; i <= comp.numLayers; i++) {
    var layer = comp.layer(i);
}

for layer in comp.layers:
    ...

Keyframes¶

ExtendScript accesses keyframe data through Property.key*() methods that take a 1-based key index. py_aep exposes keyframes as a list of Keyframe objects on Property.keyframes:

var time = prop.keyTime(1);
var value = prop.keyValue(1);
var inType = prop.keyInInterpolationType(1);

kf = prop.keyframes[0]
kf.time        # seconds
kf.frame_time  # frames
kf.value
kf.in_interpolation_type

The Keyframe object bundles all keyframe attributes together, so you don't need separate method calls for each attribute.

Feather Points¶

ExtendScript exposes mask feather data as parallel arrays on Shape (featherSegLocs, featherRadii, etc.). py_aep exposes a list of FeatherPoint objects on Shape.feather_points:

var locs = shape.featherSegLocs;
var radii = shape.featherRadii;
var types = shape.featherTypes;

for fp in shape.feather_points:
    fp.seg_loc
    fp.radius
    fp.type

Each FeatherPoint bundles segment location, radius, interpolation, tension, and corner angle together.

Markers¶

In ExtendScript, CompItem.markerProperty and Layer.marker are Property objects accessed via keyValue(). In py_aep, CompItem.marker_property and Layer.marker expose the underlying Property (with keyframes holding marker times), while CompItem.markers and Layer.markers provide a convenient flat list[MarkerValue]:

var marker = comp.markerProperty.keyValue(1);
marker.comment;

marker = comp.markers[0]
marker.comment
marker.time        # seconds
marker.frame_time  # frames

Frame-Based Time Attributes¶

ExtendScript expresses all times in seconds (floating-point). py_aep adds integer frame-based equivalents for convenience:

Warning: AVItem.frame_duration is the total duration in frames (an integer), not the duration of a single frame in seconds (which is 1/frame_rate). This differs from ExtendScript's AVItem.frameDuration which is the duration of one frame in seconds.

Convenience Access Properties¶

Project¶

Project provides filtered views of items that ExtendScript requires manual filtering for:

project.compositions   # list[CompItem] - all compositions
project.folders        # list[FolderItem] - all folders
project.footages       # list[FootageItem] - all footages

CompItem¶

CompItem provides filtered layer lists:

comp.text_layers         # list[TextLayer]
comp.shape_layers        # list[ShapeLayer]
comp.camera_layers       # list[CameraLayer]
comp.light_layers        # list[LightLayer]
comp.null_layers         # list[Layer]
comp.solid_layers        # list[AVLayer]
comp.adjustment_layers   # list[AVLayer]
comp.three_d_layers      # list[AVLayer]
comp.guide_layers        # list[AVLayer]
comp.solo_layers         # list[Layer]
comp.composition_layers  # list[AVLayer] - layers sourced from comps
comp.footage_layers      # list[AVLayer] - layers sourced from footages
comp.file_layers         # list[AVLayer] - layers sourced from files
comp.placeholder_layers  # list[AVLayer]
comp.av_layers           # list[AVLayer] - all AV layers

Item type checks¶

item.is_composition   # True if item is a CompItem
item.is_footage       # True if item is a FootageItem
item.is_folder        # True if item is a FolderItem

Extra Attributes¶

py_aep exposes additional attributes parsed from the binary format that are not available in ExtendScript:

Property¶

FootageItem¶

CompItem¶

Layer¶

RenderQueueItem¶

OutputModule¶

Enums¶

py_aep provides 98 enum classes across 8 modules, covering values that ExtendScript exposes as plain integers or doesn't expose at all:

• Format options enums: VideoCodec, AudioCodec, OpenExrCompression, etc.
• Render settings enums: FieldRender, MotionBlurSetting, DiskCacheSetting, etc.
• Output module enums: OutputChannels, OutputColorDepth, ResizeQuality, etc.
• Font enums: CTFontTechnology, CTFontType, CTScript
• Text enums: ComposerEngine, BoxAutoFitPolicy, LineOrientation, etc.

Output Module Format Options¶

ExtendScript provides no access to format-specific render settings. py_aep parses these from the binary and exposes them as typed classes:

• CineonFormatOptions - black/white points, gamma, bit depth
• JpegFormatOptions - quality, format type, scans
• OpenExrFormatOptions - compression, luminance/chroma, bit depth
• PngFormatOptions - bit depth, compression, HDR10 metadata
• TargaFormatOptions - bits per pixel, RLE compression
• TiffFormatOptions - LZW compression, byte order
• XmlFormatOptions - video/audio codec, frame rate, MPEG settings