AE CS3 Scripting Compatibility

This page describes changes in the After Effects CS3 scripting interface that will affect compatibility of existing scripts, and will require updates to your scripts for them to be compatible with CS3. More topics will be added as I encounter issues running existing scripts in CS3. User interface changes will be covered in a separate document.

The following topics are covered:

Detecting if running in After Effects CS3
Detecting a shape layer
Detecting a per-character 3D text layer
Accessing per-character 3D text animators via match name
Accessing Pixel Motion frame blending
Accessing Flash Video cue point fields for a layer marker
(Windows only) Detecting if using Windows on a Windows XP 64 system
Obsolete attributes

Detecting if running in After Effects CS3

If you intend to use any of the new features and capabilities of After Effects CS3 in your scripts, detect if your script is running in CS3 by checking that the application’s version number is 8.0, as follows:

// Detecting After Effects CS3
if (parseFloat(app.version) >= 8.0)
{
    // using After Effects CS3 or later
}
else
{
    // using After Effects 7.0 or earlier
}

Detecting a shape layer

In After Effects CS3, shape layers are represented as ShapeLayer objects. Because these layers are new in CS3, and there is no identifiable property either unique to any or all shape layers (well, the Content property group is unique today, but who knows if it will be in the future), it is best to do a version check for CS3 and then for a ShapeLayer object, as follows:

// Detecting a shape layer in AE CS3 (app.version is 8.0):
if ((parseFloat(app.version) >= 8.0) && (layer instanceof ShapeLayer))
{
    // layer is a shape layer
}
else                                  // If earlier than CS3 (8.0)
{
    // layer is not a shape layer
}

Detecting a per-character 3D text layer

In After Effects CS3, text layers can had per-character 3D transforms applied to them (i.e., 2D, 3D, or 3D per-character). A new attribute called threeDPerChar (similar to the existing threeDLayer attribute) is true when the Enable Per-character 3D option is enabled for a text layer. Although this attribute makes most sense for a text layer, it exists on non-text layers but returns false. To detect a per-character 3D text layer, do the following:

// Detecting a per-character 3D text layer in AE CS3:
if ((parseFloat(app.version) >= 8.0) && layer.threeDPerChar)
{
    // layer is a per-character 3D text layer
}
else
{
    // layer is not a per-character 3D text layer
}

Accessing per-character 3D text animators via match name

A few of the text animators extended to support per-character 3D (Anchor Point, Position, and Scale) now have different match names than those in previous versions — even when the text layer isn't per-character 3D. As a result, if your existing scripts reference these animators by match name, you will need to change their names, as follows:

// Old match names:
ADBE Text Anchor Point
ADBE Text Position
ADBE Text Scale

// New match names:
ADBE Text Anchor Point 3D
ADBE Text Position 3D
ADBE Text Scale 3D

The existing Rotation animator (representing Z Rotation) has the same match name as before.

If you were referencing these animators by name, no update is necessary other than knowing that there is an additional z-axis value.

Accessing Pixel Motion frame blending

In After Effects 7.0, Pixel Motion was available as a frame blending option for a layer. However, a script couldn't detect if Pixel Motion was used — only that frame blending was on (Frame Mix or Pixel Motion) or off. In After Effects CS3, a new AVLayer object attribute called frameBlendingType was added to both set and get the Pixel Motion frame blending type. Use it as follows:

// Detect the frame blending used for an AVLayer
switch (layer.frameBlendingType)
{
    case FrameBlendingType.NO_FRAME_BLEND:
        // no frame blending (Off)
        // layer.frameBlending == false
        break;
    case FrameBlendingType.FRAME_MIX:
        // Frame Mix frame blending
        // layer.frameBlending == true
        break;
    case FrameBlendingType.PIXEL_MOTION:
        // Pixel Motion frame blending
        // layer.frameBlending == true
        break;
    default:
        // some unknown frame blending
        break;
}

Accessing Flash Video cue point fields for a layer marker

After Effects CS3 extends layer markers to include Flash Video cue point data. As a result, the existing MarkerValue object includes additional attributes and methods for accessing these new fields. If your scripts are simply setting or getting the old marker fields, you do not need to make any changes. It is only when you want to use the new Flash Video cue point fields that you need to worry about the new attibutes and methods.

// Flash Video cue point data
var markerStream = layer.property("Marker");
var myMarkerData = new MarkerValue("Flash Video cue point test");  // create MarkerValue object

myMarkerData.cuePointName = "trigger";        // cue point name
myMarkerData.eventCuePoint = true:            // event (not navigation) cue point
var cueData = new Object;                     // new object with custom names and values
cueData.fadeTime = 2;
cueData.fadeMode = "slow";
myMarkerData.setParameters(cueData);

markerStream.setValueAtTime(1, myMarkerData); // create new marker

(Windows only) Detecting if using Windows on a Windows XP 64 system

If you are using the system.osName attribute, similar to the following, to detect if your script is running on a Windows operating system:


var onWindows = (system.osName.indexOf("Windows") != -1);

it will not work on Windows XP 64 systems using After Effects CS3. As a workaround, check the $.os attribute, as such, instead:


var onWindows = ($.os.indexOf("Windows") != -1);

Obsolete attributes

In After Effects CS3, the following attributes for the Application object are no longer available. I don’t know how many scripts use this information, but it’s good to know nonetheless.

// Obsolete attributes
// var regCo = application.registeredCompany;
// var regName = application.registeredName;
// var regSN = application.serialNumber;