Highlighted

After Effects CC 2017 (14.0) New Scripting Functionality

Adobe Employee ,
Nov 02, 2016

Copy link to clipboard

Copied

After Effects CC 2017 (14.0) includes new scripting access to tools, composition markers, the Queue In AME command, and GPU acceleration options.

The documentation and sample code below explains how to use this new functionality. We plan to post this to our blog, later in November as a part of series of in-depth articles about the new features in After Effects CC 2017, but we heard enough interest today that we thought you might appreciate seeing this sooner.

(Please pardon any formatting errors that may have occurred when pasting the sample code into this forum. I did my best to clean it up.)


Scripting Access to Tools


You can now get and set the active tool in the Tools panel using the new app.project.toolType attribute. This read/write attribute returns or accepts an enumerated ToolType value, of one of the following:

ValueTool Name
ToolType.Tool_Arrow

Selection Tool

ToolType.Tool_Rotate

Rotation Tool

ToolType.Tool_CameraMaya

Unified Camera Tool

ToolType.Tool_CameraOrbit

Orbit Camera Tool

ToolType.Tool_CameraTrackXY

Track XY Camera Tool

ToolType.Tool_CameraTrackZ

Track Z Camera Tool

ToolType.Tool_Paintbrush

Brush Tool

ToolType.Tool_CloneStamp

Clone Stamp Tool

ToolType.Tool_Eraser

Eraser Tool

ToolType.Tool_Hand

Hand Tool

ToolType.Tool_Magnify

Zoom Tool

GToolType.Tool_PanBehind

Pan Behind (Anchor Point) Tool

ToolType.Tool_Rect

Rectangle Tool

ToolType.Tool_RoundedRect

Rounded Rectangle Tool

ToolType.Tool_Oval

Ellipse Tool

ToolType.Tool_Polygon

Polygon Tool

ToolType.Tool_Star

Star Tool

ToolType.Tool_TextH

Horizontal Type Tool

ToolType.Tool_TextV

Vertical Type Tool

ToolType.Tool_Pen

Pen Tool

ToolType.Tool_Feather

Mask Feather Tool

ToolType.Tool_PenPlus

Add Vertex Tool

ToolType.Tool_PenMinus

Delete Vertex Tool

ToolType.Tool_PenConvert

Convert Vertex Tool

ToolType.Tool_Pin

Puppet Pin Tool

ToolType.Tool_PinStarch

Puppet Starch Tool

ToolType.Tool_PinDepth

Puppet Overlap Tool

ToolType.Tool_Quickselect

Roto Brush Tool

ToolType.Tool_Hairbrush

Refine Edge Tool

The following sample code checks the current tool, and if it is not the Unified Camera Tool, sets the current tool to that:

// Check the current tool, then set it to Unified Camera Tool (UCT).
{
    // Assume a composition is selected in the project.
    var comp = app.project.activeItem;
    if (comp instanceof CompItem) {
        // Add a camera to the current comp. (Requirement for UCT.)
        var cameraLayer = comp.layers.addCamera("Test Camera", [comp.width/2, comp.height/2]);
        comp.openInViewer();

        // If the currently selected tool is not one of the camera tools, set it to UCT.
        if (( app.project.toolType != ToolType.Tool_CameraMaya) &&
            ( app.project.toolType != ToolType.Tool_CameraOrbit ) &&
            ( app.project.toolType != ToolType.Tool_CameraTrackXY) &&
            ( app.project.toolType != ToolType.Tool_CameraTrackZ))
                app.project.toolType = ToolType.Tool_CameraMaya;
    }
}

The following sample code uses the new app.project.toolType attribute to create a 360° composition (environment layer and camera) from a selected footage item or composition selected in the Project panel. This script a good starting point for building VR compositions from equirectangular footage:

// Create a 360 VR comp from a footage item or comp selected in the Project panel.

var
item = app.project.activeItem;

if
(item != null && (item.typeName == "Footage" || item.typeName == "Composition")) {

    // Create a comp with the footage.
    var comp = app.project.items.addComp(item.name, item.width, item.height, item.pixelAspect, item.duration, item.frameRate);
    var layers = comp.layers;
    var footageLayer = layers.add(item);

    //Apply the CC Environment effect and create a camera.
    var effect = footageLayer.Effects.addProperty("CC Environment");
    var camera = layers.addCamera("360 Camera", [item.width/2, item.height/2]);
    comp.openInViewer(); app.project.toolType = ToolType.Tool_CameraMaya;
}
else {
    alert("Select a single footage item or composition in the Project panel.");
}


Scripting Access to Composition Markers


Composition markers can now be created and modified via the new comp.markerProperty attribute. Composition marker scripting has the same functionality as layer markers.

The following sample code creates a project and composition, then creates two composition markers with different properties:

// comp.markerProperty allows you add markers to a comp.
// It has the same functionality as layer.property("Marker")
{
    var currentProj = app.newProject();
    var comp = currentProj.items.addComp("mycomp", 1920, 1080, 1.0, 5, 29.97);
    var solidLayer = comp.layers.addSolid([1, 1, 1], "mylayer", 1920, 1080, 1.0);

    var
compMarker = new MarkerValue("This is a comp marker!");
    compMarker.duration = 1; compMarker.url = "http://www.adobe.com/aftereffects";

    var
compMarker2 = new MarkerValue("Another comp marker!");
    compMarker2.duration = 1;

    comp.markerProperty.setValueAtTime(1, compMarker)
    comp.markerProperty.setValueAtTime(3, compMarker2)
}


Scripting Access to Queue in AME


The Queue In AME command, introduced in After Effects CC 2015.3 (13.8), can now be triggered via scripting. This requires Adobe Media Encoder CC 2017 (11.0) or later.

The new method app.project.renderQueue.queueInAME(render_immediately_in_AME) calls the Queue In AME command. This method requires passing a boolean value, telling AME whether to only queue the render items (false) or if AME should also start processing its queue (true).

Note that when AME receives the queued items, it applies the most recently used encoding preset. If render_immediately_in_AME is set to true, you will not have an opportunity to change the encoding settings.

The new read-only boolean attribute app.project.renderQueue.canQueueInAME indicates whether or not there are queued render items in the After Effects render queue. Only queued items can be added to the AME queue.

The following sample code checks to see if there are queued items in the render queue, and if so queues them in AME but does not immediately start rendering:

// Scripting support for Queue in AME.
// Requires Adobe Media Encoder 11.0.
{
    if (app.project.renderQueue.canQueueInAME == true)
    {
        // Send queued items to AME, but do not start rendering.
        app.project.renderQueue.queueInAME(false);
    }
    else {
        alert("There are no queued item in the Render Queue.");
    }
}


Scripting Access to Available GPU Acceleration Options


You can now use scripting to request which GPU acceleration types are available on the current computer. The new read-only attribute app.availableGPUAccelTypes returns an array of gpuAccelType enums.

Use this in conjunction with app.project.gpuAccelType to set the value for Project Settings > Video Rendering and Effects > Use.

The following sample code checks the current computer's available GPU acceleration types, and sets it to Metal if available:

// app.availableGPUAccelTypes returns GPU acceleration types available on the current system.
// You can use this to check before setting the GPU acceleration type.
{
    var newType = GpuAccelType.METAL;

    // Before trying to set, check which GPU acceleration types are available on the current system.
    var canSet = false;
    var currentOptions = app.availableGPUAccelTypes;
    for (op in currentOptions) {
        if (currentOptions[op] == newType)
            canSet = true;
    }

    if
(canSet) {
       // Set the GPU acceleration type.
        app.project.gpuAccelType = newType
    }
    else {
        alert("Metal is not available on this OS.");
    }
}

Topics

Scripting

Views

21.7K

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more

After Effects CC 2017 (14.0) New Scripting Functionality

Adobe Employee ,
Nov 02, 2016

Copy link to clipboard

Copied

After Effects CC 2017 (14.0) includes new scripting access to tools, composition markers, the Queue In AME command, and GPU acceleration options.

The documentation and sample code below explains how to use this new functionality. We plan to post this to our blog, later in November as a part of series of in-depth articles about the new features in After Effects CC 2017, but we heard enough interest today that we thought you might appreciate seeing this sooner.

(Please pardon any formatting errors that may have occurred when pasting the sample code into this forum. I did my best to clean it up.)


Scripting Access to Tools


You can now get and set the active tool in the Tools panel using the new app.project.toolType attribute. This read/write attribute returns or accepts an enumerated ToolType value, of one of the following:

ValueTool Name
ToolType.Tool_Arrow

Selection Tool

ToolType.Tool_Rotate

Rotation Tool

ToolType.Tool_CameraMaya

Unified Camera Tool

ToolType.Tool_CameraOrbit

Orbit Camera Tool

ToolType.Tool_CameraTrackXY

Track XY Camera Tool

ToolType.Tool_CameraTrackZ

Track Z Camera Tool

ToolType.Tool_Paintbrush

Brush Tool

ToolType.Tool_CloneStamp

Clone Stamp Tool

ToolType.Tool_Eraser

Eraser Tool

ToolType.Tool_Hand

Hand Tool

ToolType.Tool_Magnify

Zoom Tool

GToolType.Tool_PanBehind

Pan Behind (Anchor Point) Tool

ToolType.Tool_Rect

Rectangle Tool

ToolType.Tool_RoundedRect

Rounded Rectangle Tool

ToolType.Tool_Oval

Ellipse Tool

ToolType.Tool_Polygon

Polygon Tool

ToolType.Tool_Star

Star Tool

ToolType.Tool_TextH

Horizontal Type Tool

ToolType.Tool_TextV

Vertical Type Tool

ToolType.Tool_Pen

Pen Tool

ToolType.Tool_Feather

Mask Feather Tool

ToolType.Tool_PenPlus

Add Vertex Tool

ToolType.Tool_PenMinus

Delete Vertex Tool

ToolType.Tool_PenConvert

Convert Vertex Tool

ToolType.Tool_Pin

Puppet Pin Tool

ToolType.Tool_PinStarch

Puppet Starch Tool

ToolType.Tool_PinDepth

Puppet Overlap Tool

ToolType.Tool_Quickselect

Roto Brush Tool

ToolType.Tool_Hairbrush

Refine Edge Tool

The following sample code checks the current tool, and if it is not the Unified Camera Tool, sets the current tool to that:

// Check the current tool, then set it to Unified Camera Tool (UCT).
{
    // Assume a composition is selected in the project.
    var comp = app.project.activeItem;
    if (comp instanceof CompItem) {
        // Add a camera to the current comp. (Requirement for UCT.)
        var cameraLayer = comp.layers.addCamera("Test Camera", [comp.width/2, comp.height/2]);
        comp.openInViewer();

        // If the currently selected tool is not one of the camera tools, set it to UCT.
        if (( app.project.toolType != ToolType.Tool_CameraMaya) &&
            ( app.project.toolType != ToolType.Tool_CameraOrbit ) &&
            ( app.project.toolType != ToolType.Tool_CameraTrackXY) &&
            ( app.project.toolType != ToolType.Tool_CameraTrackZ))
                app.project.toolType = ToolType.Tool_CameraMaya;
    }
}

The following sample code uses the new app.project.toolType attribute to create a 360° composition (environment layer and camera) from a selected footage item or composition selected in the Project panel. This script a good starting point for building VR compositions from equirectangular footage:

// Create a 360 VR comp from a footage item or comp selected in the Project panel.

var
item = app.project.activeItem;

if
(item != null && (item.typeName == "Footage" || item.typeName == "Composition")) {

    // Create a comp with the footage.
    var comp = app.project.items.addComp(item.name, item.width, item.height, item.pixelAspect, item.duration, item.frameRate);
    var layers = comp.layers;
    var footageLayer = layers.add(item);

    //Apply the CC Environment effect and create a camera.
    var effect = footageLayer.Effects.addProperty("CC Environment");
    var camera = layers.addCamera("360 Camera", [item.width/2, item.height/2]);
    comp.openInViewer(); app.project.toolType = ToolType.Tool_CameraMaya;
}
else {
    alert("Select a single footage item or composition in the Project panel.");
}


Scripting Access to Composition Markers


Composition markers can now be created and modified via the new comp.markerProperty attribute. Composition marker scripting has the same functionality as layer markers.

The following sample code creates a project and composition, then creates two composition markers with different properties:

// comp.markerProperty allows you add markers to a comp.
// It has the same functionality as layer.property("Marker")
{
    var currentProj = app.newProject();
    var comp = currentProj.items.addComp("mycomp", 1920, 1080, 1.0, 5, 29.97);
    var solidLayer = comp.layers.addSolid([1, 1, 1], "mylayer", 1920, 1080, 1.0);

    var
compMarker = new MarkerValue("This is a comp marker!");
    compMarker.duration = 1; compMarker.url = "http://www.adobe.com/aftereffects";

    var
compMarker2 = new MarkerValue("Another comp marker!");
    compMarker2.duration = 1;

    comp.markerProperty.setValueAtTime(1, compMarker)
    comp.markerProperty.setValueAtTime(3, compMarker2)
}


Scripting Access to Queue in AME


The Queue In AME command, introduced in After Effects CC 2015.3 (13.8), can now be triggered via scripting. This requires Adobe Media Encoder CC 2017 (11.0) or later.

The new method app.project.renderQueue.queueInAME(render_immediately_in_AME) calls the Queue In AME command. This method requires passing a boolean value, telling AME whether to only queue the render items (false) or if AME should also start processing its queue (true).

Note that when AME receives the queued items, it applies the most recently used encoding preset. If render_immediately_in_AME is set to true, you will not have an opportunity to change the encoding settings.

The new read-only boolean attribute app.project.renderQueue.canQueueInAME indicates whether or not there are queued render items in the After Effects render queue. Only queued items can be added to the AME queue.

The following sample code checks to see if there are queued items in the render queue, and if so queues them in AME but does not immediately start rendering:

// Scripting support for Queue in AME.
// Requires Adobe Media Encoder 11.0.
{
    if (app.project.renderQueue.canQueueInAME == true)
    {
        // Send queued items to AME, but do not start rendering.
        app.project.renderQueue.queueInAME(false);
    }
    else {
        alert("There are no queued item in the Render Queue.");
    }
}


Scripting Access to Available GPU Acceleration Options


You can now use scripting to request which GPU acceleration types are available on the current computer. The new read-only attribute app.availableGPUAccelTypes returns an array of gpuAccelType enums.

Use this in conjunction with app.project.gpuAccelType to set the value for Project Settings > Video Rendering and Effects > Use.

The following sample code checks the current computer's available GPU acceleration types, and sets it to Metal if available:

// app.availableGPUAccelTypes returns GPU acceleration types available on the current system.
// You can use this to check before setting the GPU acceleration type.
{
    var newType = GpuAccelType.METAL;

    // Before trying to set, check which GPU acceleration types are available on the current system.
    var canSet = false;
    var currentOptions = app.availableGPUAccelTypes;
    for (op in currentOptions) {
        if (currentOptions[op] == newType)
            canSet = true;
    }

    if
(canSet) {
       // Set the GPU acceleration type.
        app.project.gpuAccelType = newType
    }
    else {
        alert("Metal is not available on this OS.");
    }
}

Topics

Scripting

Views

21.7K

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Nov 02, 2016

Copy link to clipboard

Copied

comp markers = hallelujah

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Enthusiast ,
Nov 02, 2016

Copy link to clipboard

Copied

Tim, many thanks for posting that beforehand!

Also the question, I've wanted to ask for so long. Is that possible to create a sticky thread where all scripting changes will be gathered in one place?

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Engaged ,
Nov 03, 2016

Copy link to clipboard

Copied

They are collated on the Adobe Developer connection page...

After Effects Developer Center | Adobe Developer Connection

But! The is a hell of a lot of info from Region of interest that could be filtered out and

curated to a separate blog or something dedicated just to scripting updates / fixes / workarounds etc.

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Contributor ,
Nov 04, 2016

Copy link to clipboard

Copied

Hey Alan-- Rune Gangso (and myself a little bit) have brought the After Effects Scripting Guide up to date, and given it a nice online home, here: After Effects Scripting Guide

If you were looking for a single source to see all of the publicly announced changes to the scripting API since CS6, you can view the changelog here: Changelog — After Effects Scripting Guide

Hopefully this helps! The project is open source, anyone is welcome to contribute: motiondesign / After Effects Scripting Guide — Bitbucket

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Advocate ,
Nov 05, 2016

Copy link to clipboard

Copied

Thank you, very helpful.

And i thought aehancers were dead, they were only morphing!

Xavier.

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Engaged ,
Nov 05, 2016

Copy link to clipboard

Copied

Wow that's amazing Zack,  Adobe employees ? Perhaps a contribution towards Zach is in order !

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Advocate ,
Nov 09, 2016

Copy link to clipboard

Copied

You guys beat me too it. I've was working on a script version of an AE ExtendScript guide a few months ago, but have had to place it on the back burner. I was adding options to toggle a specific version of AE which would exclude items not relevant to that version. Also has a text box at the bottom that prints the syntax out for copying into your script. If you want to continue/pursue it further Zack, I can chat with you more offline. I had left off building the info arrays, but I'm sure there may be a faster way, if you guys already have those databases. Let me know.

Screen Shot 2016-11-09 at 12.36.48 PM.png

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Enthusiast ,
Nov 10, 2016

Copy link to clipboard

Copied

This is an awesome resource, and so well organized!  Thanks for taking initiative on this and for sharing with the community.

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Explorer ,
Nov 03, 2016

Copy link to clipboard

Copied

On GitHub exists a small group of devs which want to collect all knowledgement about extendscript.

Also a changelog should be integrated. It's not very far at the moment but maybe you find it usefull when its filled.

ExtendScript · GitHub

GitHub - ExtendScript/changelog: an overview of changes applied to ExtendScript

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Explorer ,
Nov 08, 2016

Copy link to clipboard

Copied

Yes! +1    It would be great if there could be a single manual that reflects the current state of the scripting API.  It is challenging to open the AE CS6 scripting guide, and then load up all the blog and forum posts from the intervening years to know what functions are actually available 🙂

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Advocate ,
Nov 09, 2016

Copy link to clipboard

Copied

Thanks for the update too Tim. Always helpful to know what has been added/changed.

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
New Here ,
Dec 11, 2017

Copy link to clipboard

Copied

If I starting rendering in AME from the script is it possible to be noticed when rendering would be done? Maybe some callback?

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
New Here ,
Dec 11, 2017

Copy link to clipboard

Copied

Or maybe is possible to run some script after render?

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...