Scripting changes in After Effects CS5

other useful scripting posts:

• scripting changes in After Effects CS6, plus new scripting guide
• After Effects CS5.5 scripting changes blog post
• After Effects CS4 scripting changes blog post
• After Effects CS3 Scripting Guide

Also, be sure to check out the “Scripts” section of After Effects CS5 Help on the Web, which provides links to useful scripting resources. You can also search the After Effects CS5 Help document and After Effects Community Help for specific scripts.

---

Changes to After Effects scripting

---

• Added AutoOrientType.CHARACTERS_TOWARD_CAMERA enumerated value for per-character 3D text layers, to make each character automatically orient toward the camera.
• Added CompItem motionBlurAdaptiveSampleLimit attribute and CompItem motionBlurSamplesPerFrame attribute, which specify how motion blur is sampled.
• Added Item label attribute and Layer label attribute. Acceptable values are 0 (None), 1..16 (one of the preset colors). You can set an item’s label to one of the 16 colors specified in the Labels preferences category, but you can’t programmatically set a specific color.
• Added TextDocument tracking attribute, for specifying text tracking (spacing between letters).
• Changed CompItem layer(name) method to work with unbounded layer names.
• Changed FootageItem replace method to preserve non-main interpretation options (e.g., color management, Cineon settings, and RED settings).
• Changed LayerCollection add, addLight, and addCamera methods to honor the Create Layers at Composition Start Time preference setting.
• No longer updating system.osName attribute for Windows 7. It’ll appear blank. Please migrate to using $.os instead.
• Removed previously deprecated fileGetDialog, filePutDialog, and folderGetDialog functions. Use File.openDialog, File.saveDialog, and Folder.selectDialog instead. The latter work in older versions of After Effects, too.
• (Mac only) Added Esc shortcut for interrupting a script (in addition to Cmd+period).
• Changed Item pixelAspect attribute to return more accurate values for pixel aspect ratio:
  
  

  PAR as it appears in the After Effects UI	CS4	CS5
  0.91	0.9091	0.90909090909091
  1	1	1
  1.5	1.5	1.5
  1.09	1.094	1.09401709401709
  1.21	1.2121	1.21212121212121
  1.33	1.33	1.33333333333333
  1.46	1.4587	1.45868945868946
  2	2	2

Here’s a toy script that exercises most of the changes described above:

var myProject = app.project;

var myComposition = myProject.items.addComp("After_Effects_CS5_scripting_changes", 1920, 1080, 1.0, 5, 24);

// Use the $.os method to query the operating system.

var myTextLayer = myComposition.layers.addText("After Effects CS5 on "+"r"+$.os);

var myTextDocument = myTextLayer.property("ADBE Text Properties").property("ADBE Text Document");

var textDocument1 = myTextDocument.value;

var myCamera = myComposition.layers.addCamera("camera_layer",[960,540]);

// new attribues for setting layer and footage item label colors

myComposition.label = 16;
myTextLayer.label = 13;
myCamera.label = 0;

// new attributes for setting advanced motion blur parameters

myComposition.motionBlurAdaptiveSampleLimit = 256;
myComposition.motionBlurSamplesPerFrame = 64;

// new option for making each character orient toward the camera,
// which depends on the layer having the per-character 3D switch on

myTextLayer.threeDPerChar = true;
myTextLayer.autoOrient = AutoOrientType.CHARACTERS_TOWARD_CAMERA;

// new text tracking (spacing) attribute

textDocument1.tracking = 50;

textDocument1.fontSize = 120;
textDocument1.strokeWidth = 2;
textDocument1.justification = ParagraphJustification.CENTER_JUSTIFY;

myTextDocument.setValue(textDocument1);


---

Changes to ScriptUI

---

The biggest change in After Effects CS5 is the use of a different skin for the user interface (ScriptUI). The look is more consistent with that used in the rest of the After Effects interface and between Mac OS and Windows.

However, if you don’t use a resource string to define your user interface (i.e., you add controls with hard-coded coordinates) the slight differences in control sizes might cause clipping of text labels for checkbox and radiobutton controls. The problem can be more apparent if controls are tightly spaced, such as when using 15px for a control’s height.

One workaround is to increase the bounds (width or height) of these controls (e.g., 20px for the height). Another is to use a resource string for defining the layout. The latter is more flexible if control sizes change in the future and can adapt to text or layout changes more easily, but requires After Effects CS3 or later. The conversion process can take some time. If your script requires compatibility with After Effects 7.0 or earlier, just increase control bounds as needed.

Other changes to ScriptUI include the following:

• Added support for the “flashplayer” object, which allows a SWF file to appear in a panel.
• Changed Window object’s size, visible, bounds, and location attributes to be read-only when running in a dockable ScriptUI panel.
• Removed Window opacity attribute when running in a dockable ScriptUI panel.
• Changed the order that items appear in the selection attribute for a multiselect listbox from top-to-bottom to selected order.

---

Other scripting issues you should be aware of

---

• Scripts run from and targeting ExtendScript Toolkit CS5 do not use the same user interface skin for ScriptUI as used within After Effects CS5.
• Some keyboard shortcuts for menu commands or general panel operations (such as maximizing or restoring a panel’s size) might not work when a ScriptUI panel or control within it has focus.
• (Mac OS X 10.6) In some configurations, a script that uses osascript to launch AppleScript might not run correctly or might hang. The easiest workaround at this time is to change the command
  osascript ...
  to this:
  arch -i386 osascript ...
  See this article for more details.
• (Mac OS) The title argument for the prompt function does not appear.