redefinery

Compositions

This section describes how to work with compositions in a project. The following topics are covered:


Creating a composition

The process of creting a new composition in a project involves using the addComp() method of an ItemCollection object. You can add a composition to the root folder (top-level) or a specific folder of the Project panel.

The following code shows how to create a composition at both the top level and within a specific folder.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var newComp;

// Create a new comp (320x240, 0.91 pixel aspect ratio, 10.0 seconds, 29.97 fps) 
// at the top level of the Project panel
newComp = app.project.items.addComp("Top-Level Comp", 320, 240, 0.91, 10.0, 29.97);
// ... or, equivalently, ...
newComp = app.project.rootFolder.items.addComp("Top-Level Comp", 320, 240, 0.9, 10.0, 29.97);

// Create a new comp (640x480, 1.0 pixel aspect ratio, 5.0 seconds, 25.0 fps) 
// within a subfolder named "Comps"
//
// given:
// subfolder = FolderItem object representing the "Comps" subfolder
//
newComp = subfolder.items.addComp("Lower-Level Comp", 640, 480, 1.0, 5.0, 25.0);

Retrieving all compositions in a project

If you need to retrieve all compositions in a project, iterate over the project’s items and check for the ones that are compositions. You can check if either the item is an instanceof CompItem or if the composition Item’s typeName is "Composition".

The following code shows how to iterate over the project’s items (ItemCollection object of Item objects) and store compositions in an array for retrieval or use elsewhere in your code.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var items = app.project.items;
var comps = new Array();                         // Store comps in an array; starts as empty

for (var i = 1; i <= items.length; i++)
    if (items[i] instanceof CompItem)
        comps[comps.length] = items[i];
// ... or, equivalently, ...
for (var i = 1; i <= items.length; i++)
    if (items[i].typeName === "Composition")
        comps[comps.length] = items[i];
// The comps array now contains the list of compositions
// The number of compositions is comps.length 

Retrieving the selected compositions in a project

If your script needs to operate on the selected compositions in a project, you need to check if the selected attribute for the composition (CompItem) is true.

The following code shows how to iterate over the items of a project, and store only the CompItem objects whose selected attribute is true in an array for retrieval or use elsewhere in your code. This code is very similar to the code for retrieving the compositions in a project, with the extra check for the selected attribute value. The instanceof CompItem check is used in this code, but you can use the equivalent typeName comparison instead.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var items = app.project.items;
var selectedComps = new Array();                  // Store comps in an array; starts as empty

for (var i = 1; i <= items.length; i++)
    if ((items[i] instanceof CompItem) && items[i].selected)
        selectedComps[selectedComps.length] = items[i];
// The selectedComps array now contains the list of selected compositions
// The number of selected compositions is selectedComps.length in top-to-bottom order

Retrieving the active composition

Sometimes you need to operate on a single composition or the contents of the currently selected composition. Although you can retrieve the selected compositions and proceed with the operation if only one is selected, the easier way is to retrieve the project’s active (selected) item and check if it is a composition.

The following code shows how to retrieve the project’s activeItem value, and checks if it is a CompItem object.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var activeItem = app.project.activeItem;

if ((activeItem !== null) && (activeItem instanceof CompItem))
    // The activeItem is the active composition

Selecting or deselecting a composition

Selecting or deselecting a composition is as simple as changing the Boolean value of the selected attribute for the composition’s CompItem.

Note: Changing the selection of a composition does not affect the selection state of other compositions. If you want to select only one composition, first deselect all existing selected project items, then select the composition as described in this section.

The following code shows how to select and deselect a composition.

// given:
// comp = CompItem associated with the composition to select or deselect
//
comp.selected = true;                            // Select the composition

comp.selected = false;                           // Deselect the composition

Removing a composition from a project

Removing a composition from a project is as simple as calling the remove() method for the composition (CompItem).

Note: If you want to remove all compositions in a project, index the composition’s ItemCollection in reverse. Otherwise, incrementing through the ItemCollection will cause your script to access indices that no longer exist as compositions are deleted.

The following code shows how to remove a single composition, as well as all compositions in a project.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
// comp = CompItem object associated with the composition to remove
//
comp.remove();                                   // Removes a specific composition

                                                 // Remove all compositions in a project
var items = app.project.items;

for (var i = items.length; i >= 1; i--)
    if (items[i] instanceof CompItem)
        items[i].remove();