Scripting: After Effects Projects and Compositions

Introduction

In this article I'll be going through some of the basics of navigating After Effects projects and compositions using a script. I'll be referencing some of the most useful parts of the scripting guide, and showing off some practical examples of how it works.

Let's get started.

Application

app

app references the application After Effects itself. To reference anything inside After Effects, you'll need to start by telling your script to look at the application.

While you can reference the settings, files and the computer system After Effects is installed on (i'll be going into these options in another article), it is more than likely the main object you will need to reference after the application is an After Effects project.

app.newProject()

newProject() creates a new, empty project. You'll be prompted by After Effects if you'd like to save your current work before this happens.

app.open(file)

open() meanwhile allows you to open an existing project. Leaving the brackets blank, it will bring up the open project dialogue box as if navigating to File > Open Project... in the After Effects menu. Alternatively, you can reference a file inside the brackets to open a specific project.

project = new File ("...FilePath/AE Project.aep");
app.open(project);

You will need to create a new File() to locate the file from within your script. I prefer to store this in a variable to keep things tidy. Again, you'll be prompted to save your current project before the file opens.

Project

app.project

project references the current project open in After Effects. From here, we can access all the items from within our project, create new ones, and access the render queue.

app.project.save([file])

save() saves the project. Without adding the option of a file, or if the project has not been previously saved, this method will bring up the save dialogue for the user to save their project. Remember - you need to create a new File in your project before you can reference it in this method.

app.project.importFile(importOptions)

importFile() works a little like this:

new ImportOptions().file = new File("...FilePath/My File.jpg");
app.project.importFile(file)

I'll be going into importing files in more detail in another article. But as a quick overview, you use this method to import files into your project. Not only do you need to create a new File, but you also have to create new ImportOptions to specify what you are importing, and how. This allows us to do things like import image sequences, import files as, and force alphabetical order.

app.project.importFileWithDialog()

importFileWithDialog() meanwhile opens up the import footage dialogue box, for the end user to select their file.

app.project.renderQueue

renderQueue grants us access to the render queue, and allows us to set render settings and even render compositions. I will be going more into this in another article.

app.project.activeItem

activeItem refers to the current item being viewed, usually a composition, footage layer, placeholder, or solid. It only references one item at a time, and returns a null if multiple items are active, or if none are active. It can be handy to reference the active composition, for scripts which add layers or affect what the user is currently working on in some way. Note that this isn't the same as an item being selected.

app.project.selection

selection refers to all the items currently selected inside the project panel. This is what you need when referencing the items selected, rather than the item that is active.

app.project.item(index)

item() refers specifically to a single item inside of your project - be it a composition, solid, or what have you. Like so:

app.project.item(1)
app.project.item("Comp 01")

The index represents either the index number of the item inside the project window, or, can also refer to the name of the layer.

app.project.items

items meanwhile refers to the collection of items inside your project. It is used to create new compositions and folders.

Folders And Compositions

This brings us nicely onto folders and compositions.

app.project.items.addFolder(name);
app.project.items.addComp(name, width, height, pixelAspect, duration, frameRate);

addFolder() creates a new folder for your project. Make sure the name argument is a string (in " " or ' ').

addComp() however has many more arguments to consider. This is because there is a lot of information that is needed to create a new composition:

You can create new comps inside of folders by referencing the folder instead, like this:

folder01 = app.project.items.addFolder("Comps");
Comp01 = folder01.items.addComp("Comp 01", 1920, 1080, 1, 5, 25);

And can move items into the folder after the fact, by setting the item's parentFolder attribute:

folder01 = app.project.items.addFolder("Comps");
Comp01 = app.project.items.addComp("Comp 01", 1920, 1080, 1, 5, 25);

Comp01.parentFolder = folder01;

Once you've created a composition, you can set it as your active item by using openInViewer()

comp1.openInViewer();

Example

Using a little of what I've covered, here is a short script which allows you to open a new project, create 2 folders and 2 compositions, and add one comp to the other as a precomp.

app.newProject();

folder1 = app.project.items.addFolder("_Final");
folder2 = app.project.items.addFolder("Precomps");
comp1 = folder1.items.addComp("Comp 01", 1920, 1080, 1, 10, 25);
comp2 = folder2.items.addComp("Comp 02", 1920, 1080, 1, 10, 25);

comp1.openInViewer();
app.project.activeItem.layers.add(comp2);

Quick Tips

You'll find, after running this script, if you were to press undo in After Effects, it will only undo each action one at a time. Most of the time this isn't ideal, as scripts often undergo many actions, making this very time consuming and annoying for the end user.

app.beginUndoGroup(undoString)
app.endUndoGroup(undoString)

That is where beginUndoGroup() and endUndoGroup() come in. They allow you to group the script's actions together, so that they can be undone in one motion. The undoString is what you will see next to the undo option in After Effects. While you don't necessarily need to add endUndoGroup() if you only have one instance of beginUndoGroup() in your script (as it will close automatically), it is good practice to add it to the end of your script, to keep your script tidy.

Conclusion

I hope this has helped to shed some light on how to reference After Effects projects and compositions while making your After Effects scripts. In the next article, I will go over creating pop up windows for users to interact with your scripts.

Have any questions? Something wrong here or not working? Let me know in the comments.