DEV Community: Kat

Scripting: Creating Windows For Your After Effects Scripts

Kat — Wed, 22 Jan 2025 11:38:18 +0000

Contents
1. Introduction	6. Buttons
2. Windows	7. Options
3. Groups	8. Example
4. Panels	9. Conclusion
5. Text

Introduction

Creating a window for a script is ideal when you need the end user to input information, and display instructions. In this article I'll go through the basics of creating a window for your AE script using some basic javascript and Adobe Extendscript Toolkit CC.

Windows

To make your window, it's very simple:

//New Window
var mainWindow = new Window("palette", "Title", undefined);

new Window() is the argument to create the window. Then, inside you need to specify the type, title and bounds. A palette window is suitable for After Effects scripts, and leaving the bounds as undefined is also recommended, as the size and position can be affected later.

To call your window:

mainWindow.show();

Since there is nothing currently in the window, this will simply call a small window to show it is working.

Groups

The next thing to do is to create an object to house information for your window.

The "group" allows you to organize objects inside of it. Before mainWindow.show() add this line to your script:

group01 = mainWindow.add("group", undefined, "Group 01");

We add the group to our mainWindow, outlining the type, bounds, and text properties. Since we are adding a group, the first argument is "group". Again, you can leave the bounds undefined. Lastly, include what you want the group to be named. This is not displayed by default in the window.

The default orientation of panels is by row. If you want to change this to sort of column, you can do so by adding this to your script:

group01.orientation = "column";

Panels

However, if you do want the name of the group to be visible, you could consider using a "panel" object instead. This type of object is helpful for sectioning off parts of the window:

group02 = mainWindow.add("panel", undefined, "Group 02");

It has the same properties as the "group" object, but displays slightly differently.

The default orientation of panels is by column. If you want to change this to sort of row, you can do so by adding this to your script:

group02.orientation = "row";

Text

There are likely 2 types of text you would want to include in your script: static text, and editable text.

Static Text
Static text can be used for instructions to the end user. Add "statictext"to your object like so:

var staticText = group01.add("statictext", undefined, "Here is some static text.");

Again we use the add control object, with the same type, bounds, and text arguments.

Editable Text
Editable text provides a text box field for the end user to type into. This is useful if our script requires information from the end user, like customizable text layers. Add "edittext" to your object like so:

var editText = group02.add("edittext", undefined, "Here is some editable text.");

This is simply a different type of object. The text we provide in the text argument will initially be inside the text box, ready for the end user to delete and write their own text inside.

As you can see, with the size of the boxes undefined, the text in the editable box is slightly cut off. We can fix this by defining the size after the fact:

var editText = group02.add("edittext", undefined, "Here is some editable text.");
editText.size = [200, 25];

This allows us to make the textbox size adaptable later, if we so choose.

Buttons

It is also likely you will need buttons for your script, at the very least to give the end user an option to "run" the script.

Adding a button is a similar process:

var button01 = group02.add("button", undefined, "Run");

This creates our button.

However, for our button to do anything, we will need to tell our script what to do when our button is pressed. I like to create a function to house all the tasks I want the button to complete.

button01.onClick = function(){
    app.beginUndoGroup("Tutorial");
    completeTasks();
    };

function completeTasks(){
    mainWindow.close();
    app.endUndoGroup("Tutorial");
    }

Here, we use button01.onClick to run our first function, where we ask it to run app.beginUndoGroup("Tutorial") so that undoing the script is a single action from inside After Effects. Next, we tell it to run our function completeTasks. Underneath, I define the function completeTasks. Here, include all the actions you want your button to complete (for now, mine only closes the script window), and finish the function by adding app.endUndoGroup("Tutorial") to close the undo group.

I'll be going into more detail about this in a future article.

Options

Other options for control objects available are located on the Javascript Tools Guide CC

Objects such as checkboxes, dropdown menus, radio buttons, and sliders are covered here, to name a few, and follow similar procedures to adding text or buttons.

Example

Let's connect what we've learned about windows to the previous article, and make an example script which creates and opens a new composition.

//Create window and groups
var mainWindow = new Window("palette", "Title", undefined);
group01 = mainWindow.add("panel", undefined, "Description");
group02 = mainWindow.add("group", undefined, "Button");
group02.orientation = "column";

//Create objects
var staticText = group01.add("statictext", undefined, "Enter the width and height of the new composition.");
var compWidth = group02.add("edittext", undefined, "Comp Width");
compWidth.size = [100, 25];
var compHeight = group02.add("edittext", undefined, "Comp Height");
compHeight.size = [100, 25];
var button01 = group02.add("button", undefined, "Run");


//Functions
button01.onClick = function(){
    app.beginUndoGroup("NewComp");
    completeTasks();
    };

function completeTasks(){
    var compWidthSize = parseInt(compWidth.text);
    var compHeightSize = parseInt(compHeight.text);
    var comp01 = app.project.items.addComp("New Comp", compWidthSize, compHeightSize, 1, 10, 25);
    comp01.openInViewer()
    mainWindow.close();
    app.endUndoGroup("NewComp");
    };

//Return
mainWindow.show();

Let's go through this script.

I start off by creating my window and my groups. Group01 is my "panel", adding the heading "description" to the static text. Meanwhile the rest of my objects go inside Group02, a "group" object. Since I want the orientation of Group02 to be a column, I set that here.

Then, I create my objects. I start with my statictext inside of Group01. Next, I create 2 edittext objects inside of Group02, for the user to specify the size of the new composition they want to create, and I specify the size of both those text fields. Lastly, I create a button so that the script can be run by the end user.

Once I have created all my variables, I create my functions. I first set my onClick function for my button as explained, by opening the undo group and running the custom function completeTasks.

I then define completeTasks. First, I need to use parseInt() on the text of both compWidth and compHeight edit text objects. This converts them from text to integers, so that the rest of the script can understand the inputs. Once this is done, I create a new composition, setting the width and height to the values inputted by the user. The composition is then opened and becomes the active comp, before the script window closes, and the undo loop is closed.

Running this script allows you to make a new composition set to the width and height values specified in the text fields.

This script can be improved by adding an alarm, should anything be added to the text fields that isn't an integer (or perhaps setting a maximum value), to warn the user that the script has failed. This is something I will go over in more detail in another article. For now, if there is an illegal character in the text field, the script will simply not work until both the width and height text fields have numbers typed into them.

Conclusion

This concludes the beginners guide to creating windows for After Effects scripts using Adobe Extendscript Toolkit CC. Next article I will cover creating different types of layers for your compositions.

After Effects: The Modulo Operator (%)

Kat — Mon, 20 Jan 2025 10:46:23 +0000

Contents
Introduction
Looping Expressions
Example: Digital Clock
Example: Analog Clock
Conclusion

Introduction

The Modulo operator (written %), aka the remainder operator, is a useful part of expression making that isn't immediately easy to understand. So what does it do, and what is it used for?

% is used to work out the remainder of an equation. Here is an example:

10 % 3

In this example, the expression will return 1. This is because when you divide 10 by 3, you get 3 remainder 1.

This is very useful for creating loops when used on the time variable.

Looping Expressions

Most designers starting out with After Effects expressions will know the loopOut() expression. This allows us to loop keyframes in our property, using "cycle" (looping back from start to finish), "pingpong" (looping from start - finish - then backwards to the start again), "offset" (repeating the keyframes but offsetting the values each time to build the animation), or "continue" (uses the velocity from the last keyframe to continue the motion). This is very comprehensive, and covers everything you could need while keyframing animation.

But, if you want to loop an expression, loopOut isn't a viable solution. There could be a few reasons for not wanting to use keyframes, but the main reason is if a value needs to be dynamic, and constantly updated. It is much easier to update an expression attached to a slider, than a set of keyframes.

If the motion is continuous, then Linear or Ease would work just fine. But for complex animations that require a loop, we can use the modulo operator against time to achieve that loop.

To understand how it works, copy and paste this expression into a text layer's Source Text property:

Math.floor(time % 5)

You will see the layer counts from 0-4 each second, looping back to 0 on every 5 second interval. This is because, as time moves, the remainder of our expression will change each second:

Remainders over time
1 % 5 = 1
2 % 5 = 2
3 % 5 = 3
4 % 5 = 4
5 % 5 = 0

The Math.floor addition rounds the argument to return only whole numbers.

From here, it is easy to see how this can be employed when needing to animate numbers between certain parameters.

Example: Digital Clock

Let’s use % to make a digital clock.

The seconds need to count between 0 - 60, meanwhile the minutes need to count up at each interval of 60. Let's paste this into our text layer's Source Text property again:

sec = Math.floor(time % 60);
minute = Math.floor(time / 60);

if (sec < 10) sec = "0" + sec;

minute + ":" + sec

Breaking the expression down, our sec variable will count from 0 - 60, while the minute variable will increase on every multiple of 60 (again, we use Math.floor to round out the numbers). The if statement that follows adds a 0 to the front of the sec variable if it is less than 10, ensuring that our seconds variable always has 2 digits (which could also be repeated for the minutes if desired). Then, it is just a case of stringing it all together with a time separator.

If you need the counter to work independently of time, you can achieve the same effect by swapping time out with a slider, and animating its value.

You can also make the time separator blink, using the modulo operator and the After Effects text expression selector.

Go to your text layer, and add an opacity animation option to your text layer (if you're not sure how to do this, you can check out this article all about it). Then add an expression selector, and remove the range selector.

Set the opacity within the animator to 0, and then add this expression to the amount property:

//Digital Clock Divider Blink
//Add to the expression selector

minute = Math.floor(time / 60);

minute < 10 && textIndex == 2 ? Math.floor(time*2 % 1.5) * 100 : minute >= 10 && textIndex == 3 ? Math.floor(time*2 % 1.5) * 100 : 0;

I have written a conditional statement, based on the number of digits within the minutes variable not being fixed. First, I copy the minute variable from my source text property. Then, I used it to calculate my time separator's textIndex value. When there is 1 digit in the minute display, it will equal 2. When the minute display is over 10, then it will be 3. The conditional statement can also be written as an if statement, like this, to explain further what it is doing:

if (minute < 10 && textIndex == 2) Math.floor(time*2 % 1.5) * 100
    else if (minute >= 10 && textIndex == 3) Math.floor(time*2 % 1.5) * 100
        else 0

If the minutes are under 10 and the textIndexequals 2, then Math.floor(time*2 % 1.5) * 100 affects the 2nd character in the text layer. This will make the letter flash (to a ratio of 2:1 on:off) thanks to the modulo operator. The Math.floor argument rounds the numbers, while the whole thing is multiplied by 100 at the end to toggle between the numbers 0 and 100, the range of our expression selector.

However, if the minutes are equal to or above 10 and the textIndex equals 3, the effect will then be applied to the 3rd character in the text layer instead. This accounts for the extra digit in the minutes display. If your minutes display will need to go past 99, another argument will need to be added to affect the time separator when it is in the 4th position.

However, if your minutes display is set to a constant number of digits, the statement becomes much simpler:

dividerIndex = 3;
textIndex == dividerIndex ? Math.floor(time*2 % 1.5) * 100 : 0

And with that, you have a digital clock!

After displaying how the modulo operator helps create loops, we can now think about how to apply this to other properties.

Example: Analog Clock

Let's now make an analog clock. When the hands tick, it usually isn't one continuous motion, but instead something which stops and starts abruptly. This is the kind of loop the modulo operator can help with.

Let's go through the following expression we can paste into the rotation property of a clock hand layer:

//Second Hand Rotation
frames = thisComp.frameDuration;

loopTime = 1;
dur = frames * 6;
strength = 6;

counter = Math.floor(time/loopTime);
t = time % loopTime;

ease(t, 0, dur, strength * counter, strength * (counter + 1))

First, we set some variables. frames is how long a frame in our composition lasts, making it able to work across multiple framerates.

Set loopTime to how much time you want to loop. I want the loop to last a second, so I set it to 1. dur is the duration of the animation within the loop, so I set mine to frames * 6, making it last for 6 frames. strength is the change in value of the animation, and since I'm animating a clock hand, I set mine to 6, so the clock hand will make a full rotation in 60 ticks.

Next, I make a counter variable, which will help offset my values. I create this with Math.floor(time/loopTime), rounding the number with Math.floor and setting the speed of the counter to match the loops. Lastly, t is the variable we can use to time our expression driven animation. This is time % loopTime, so the time loops whenever it reaches the number stored inside loopTime.

After that, we can make our animation. I'm using an ease expression in this example. By setting the first argument to t, we remap our rotation value to our loop time variable. The next 2 arguments are 0 and dur, the start and end points of the animation. The last 2 arguments are strength * counter and strength * (counter + 1), the value of our rotation property. By multiplying the strength by the counter, we can offset the values each loop, ending on strength * (counter + 1), ready for the next loop.

The advantage of powering the motion via expressions rather than keyframes in this instance would be if you need to build a clock template for constantly changing times. The static values of the expression can be connected to sliders, making it much easier to update constantly.

You could use a more advanced expression or build your own function to make more bespoke animation:

//Second Hand Rotation
frames = thisComp.frameDuration;

loopTime = 1;
dur = frames * 6;
change = 6;

counter = Math.floor(time/loopTime);
t = time % loopTime;

function easeInOutBack (t, b, c, d, s) {
    if (s == undefined) s = 1.70158;
    if ((t/=d/2) < 1) return c/2*(t*t*(((s*=(1.525))+1)*t - s)) + b;
    return c/2*((t-=2)*t*(((s*=(1.525))+1)*t + s) + 2) + b;
}

easeInOutBack(clamp(t, 0, dur), change * counter, change, dur)

Lastly, you could create a variable to set the start value and use an if statement to skip the first iteration of the animation for the minute (and possibly hour) hands:

//Minute Hand Rotation
frames = thisComp.frameDuration;

loopTime = 60;
dur = frames * 6;
strength = 6;
startValue = 180;

counter = Math.floor(time/loopTime);
t = time % loopTime;

function easeInOutBack (t, b, c, d, s) {
    if (s == undefined) s = 1.70158;
    if ((t/=d/2) < 1) return c/2*(t*t*(((s*=(1.525))+1)*t - s)) + b;
    return c/2*((t-=2)*t*(((s*=(1.525))+1)*t + s) + 2) + b;
}

if (time < loopTime) startValue
    else easeInOutBack(clamp(t, 0, dur), (strength * counter) + startValue, strength, dur)

From here, it is just a case of connecting a slider to our startValue variable. From there, you have an analog clock that can be updated by simply changing the value in the slider.

Conclusion

The modulo operator is very useful for creating loops to aid dynamic expressions, where other means do not fit the project's needs.

Try testing it out in some of your own projects!

Have any comments? Something not adding up? Let me know down below.

Scripting: After Effects Projects and Compositions

Kat — Wed, 04 Dec 2024 14:17:00 +0000

Contents
Introduction
Application
Project
Folders And Compositions
Example
Quick Tips
Conclusion

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:

Argument	Description
`name`	The name of the composition. Needs to be a string (in " " or ' ')
`width`	The width of your composition
`height`	The height of your composition
`pixelAspect`	The pixel aspect ratio. You are almost certainly looking to set this to Square Pixels, which you can do by setting the ratio to `1`. Any other pixel aspect ratio can be set by entering the correct ratio (for example, Anamorphic 2:1 can be set by entering `2`, and D1/DV PAL Widescreen can be set by entering `1.46`).
`duration`	The duration of the composition in seconds
`frameRate`	The frame rate of the 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.

Scripting: Beginner's Guide To Creating After Effects Scripts

Kat — Thu, 28 Nov 2024 11:25:57 +0000

Contents
Introduction
Why Scripts?
Extendscript Toolkit
Conclusion

Introduction

After spending years with After Effects expressions, it seems natural to branch out into writing custom scripts. However, I found it's not that easy. It can be quite daunting for beginners - with information in the scripting guide available, but with very few practical examples to learn from. I found myself constantly asking "Okay, but how do I apply these functions without throwing an error?"

In this series, I aim to create some basic guides to help you create your own scripts for After Effects. I'll be referencing all the useful information in the scripting guide, but aim to contextualize it a little.

Why Scripts?

So, why make scripts? There are many reasons to create a script for After Effects.

My main reason for wanting to make scripts is to have a tangible, separate file, meaning there's no need to open up or import an existing After Effects project. Instead of copy-pasting information, adjusting sliders, or using the Essential Graphics panel, a script will allow you to create your own panel to store information, or create buttons which can trigger custom code.

In short, they are useful for making templates to hand over to clients, but also for creating shortcuts for yourself and your own workflow. Many of the most popular scripts out there improve efficiency in this way.

Extendscript Toolkit

To create your script, you will need software. Any program which lets you generate a .jsx file will work, but I personally like to use Extendscript Toolkit because it can connect directly into Adobe software while testing.

If you have Adobe Creative Cloud, you will already have access to Extendscript Toolkit, however you may be unaware of this. This is because Extendscript Toolkit is old software, and hidden away from view.

In order to find and download Extendscript Toolkit, open up Creative Cloud, and navigate to your preferences menu. Click on the "Apps" tab, and scroll all the way to the bottom until you find the toggle labelled Show Older Apps.

Once this toggle is on, Extendscript Toolkit will be available to download on your app page.

Opening up Extendscript Toolkit, you'll see this:

This is where we will write our scripts. At the top, navigate to the dropdown menu Extendscript Toolkit CC. You'll see the option to select any Adobe software currently installed on your machine.

This will allow you to connect Extendscript Toolkit directly to whichever Adobe program you are writing scripts for. I have selected my most up to date version of After Effects. Now, whenever I press the play button on the top toolbar, it will run the script directly in After Effects without me having to save out the file - which is great for testing things out.

With After Effects open, try adding the following code to Extendscript Toolkit and running it:

var mainWindow = new Window("palette", "My First Window", undefined);
var mainGroup = mainWindow.add("group", undefined);
var mainText = mainGroup.add("statictext", undefined, "Hello World!");


mainWindow.show();
mainWindow.center();

If you have selected the correct version of After Effects, you should see your first window pop up!

We'll go into detail about creating windows and the options available in another article.

Now that you have Extendscript Toolkit installed, you're ready to start making scripts!

Conclusion

Scripts are powerful tools which let us create After Effects templates and improve our own workflows by adding custom, unique tools.

In upcoming articles I will go over:

Navigating After Effects and selecting projects and compositions
Creating windows and panels
Adding new layers and compositions
Creating, editing, and animating text layers
Creating, editing, and animating shape layers
And more!

Let me know in the comments if there is a specific topic you would like to see me cover.

After Effects: The Essential Graphics Panel

Kat — Tue, 12 Nov 2024 14:49:07 +0000

Introduction
Setting Up Your Precomps
Adding To The Essential Graphics Panel
Adding A Dropdown Menu
Advanced Text Options
Changing Fill Options
Limitations
Other Ideas
Conclusion

Introduction

Creating efficient After Effects templates is incredibly important, especially when passing the projects to clients who may not be as software savvy. In the past, this meant shy-guying layers away out of sight, locking everything down, and hoping they wouldn't be too confused by the concept of opening a precomp.

However, with the addition of the Essential Graphics panel, we can now put all of our template options in one place. And, if we combine this with some helpful expressions - we can create all sorts of options for our users.

Let me show you how I achieve this.

Setting Up Your Precomps

First thing first, design and animate your layout. You will want to get this nailed down first before you version your project (if necessary).

If your project will contain multiple options, for instance a different number of people, I suggest starting with the maximum number and working backwards. I have made this quick example:

Now that I'm happy with my layout, I need to make the rest of my versions, so I end up with this:

It is also important that your project is tidy before you start making your template, otherwise you may have problems down the line. I have separated each of my layouts with a precomp:

And all of my people are inside of their own precomps (with their images inside a further precomp for swapping out images later):

Now that my project is tidy and I'm happy with the animation and layout, I can begin importing information into my Essential Graphics Panel.

Adding To Your Essential Graphics Panel

If it is not already open, open the panel by selecting window > Essential Graphics. You will see the panel open. Select your main comp as your primary composition, and name your template something appropriate.

In the spirit of keeping our template tidy, let's start with making 4 folders to store information for the 4 different speakers. At the bottom of the Essential Graphics panel, selecting Add Formatting > Add Group. Name your group, and repeat for all your speakers.

Now we are ready to add our layers. Navigate to the precomp which contains the layers you wish to edit as part of your template. For me, that is Person_01.

For text layers, open up the layer options until you see Text > Source Text. Click and drag the Source Text option into your Person 01 folder in the Essential Graphics panel to add it to your template. At this point, you can rename your text field label if you wish.

For images, such as our display image, click and drag the image into your folder. Since my image is multiple layers, I create 1 more precomp and drag that into my template.

Repeat these steps for all your other precomps.

Once you are done, you can close all other timeline panels except your main composition. To test your template, edit the text in all your layers. You should see them update in your main comp, without having to go into all your individual precomps.

Great! Our text layers all work. But what about our images? To test your images, double click on them in your Essential Graphics panel. This will open up the exact precomp which contains the image. Drag in a new image from your project, then close the precomp. You'll see it updated in your main comp.

I prefer this method as it opens the correct precomp for the user, as opposed to them having to look for it. This is why I make sure my images are precomped nicely. If your images and precomps are correctly sized, the end users should only have to drag and drop assets (although you may also want to make a Photoshop or Canva template to help them scale their images too).

We have our basic template! Now we have to add a way to toggle between the layouts.

Adding A Dropdown Menu

Add a null layer to your composition, and name it "DROPDOWN". In the effects and presets panel, search for the "Dropdown Menu Control". Add it to your new null layer. You'll see it in your effect controls panel like so:

Press the edit button. You'll see another box pop up with 3 items by default in the menu. Add as many items as you need, and rename them to match your template. In my case, I will rename them after the number of people in my layouts.

When you're happy, press ok to close the box. Now we need to connect the menu to the opacity of our precomps. We can do this with some simple expressions.

Effectively, we want to create an expression so After Effects understands "When the 1 person option is selected in the dropdown menu, only display the 1 person precomp." And so on with all our other options.

This is easily achieved with an if statement inside each precomp's opacity property.

Starting with our 1 person precomp:

if (thisComp.layer("DROPDOWN").effect("Dropdown Menu Control")("Menu") == 1) 100
    else 0

If our dropdown menu has its first option selected, the 1 person precomp will be set to 100% opacity. If any other option is selected however, the 1 person precomp will be set to 0% opacity.

We can add this expression to all our other precomps, making sure to change it slightly to target the correct menu option for each layer.

2 people precomp:

if (thisComp.layer("DROPDOWN").effect("Dropdown Menu Control")("Menu") == 2) 100
    else 0

3 people precomp:

if (thisComp.layer("DROPDOWN").effect("Dropdown Menu Control")("Menu") == 3) 100
    else 0

4 people precomp:

if (thisComp.layer("DROPDOWN").effect("Dropdown Menu Control")("Menu") == 4) 100
    else 0

With this, our dropdown menu is ready to test. Drag it to the top of the Essential Graphics panel, outside each of the folders. One by one, select each option, to make sure it is working.

Advanced Text Options

Now that our basic template is in place, we need to consider what other options need to be available for the end user. For instance, if the goal is to prevent the user from going into precomps for text, we should add an option for them to change things like text size. What if our name is too long at the current font size?

I've opted to change the text size across all of my precomps with one slider, so the text size stays consistent across the layout. However, if you want to have separate controls for each speaker, you can do so by repeating the following actions for each precomp separately, instead of inside the main comp.

First, I make a null object in my main comp and name it "FONT SIZE OPTIONS." Here, I add 4 sliders: Name Font Size, Title Font Size, Padding and Position Adjust. I then lock my effects panel, so I can still access these sliders while I'm inside the other layer precomps.

Next, I head inside my first precomp. Here, I'll add expressions to allow the end user to change the text size of both the name and job layers, as well as the padding between these layers, and the overall position in relation to the display image.

To begin, I turn my attention to the Name layer. To fix the anchor point of this layer, you can use this simple expression:

var copy = thisLayer;

var cWidth = copy.sourceRectAtTime().width;
var cHeight = copy.sourceRectAtTime().height;
var cTop = copy.sourceRectAtTime().top;
var cLeft = copy.sourceRectAtTime().left;

var x = cLeft + cWidth / 2;
var y = cTop;

[x, y]

The expression sourceRectAtTime() works out the size of a layer at any given time. This means that as the text changes, After Effects is able to recalculate the size of the layer. Using this, we are able to work out the layer's width, height, top and left parameters.

Since I would like my anchor point to sit top-centre, my y coordinate = the layer's sourceRectAtTime().top value. My x coordinate = the sum of the left and width, divided by 2 to find the middle.

You may have to move your layer back into position after changing the anchor point's location, but once you're done, the anchor point will always sit in the top-centre of the layer, no matter the layer's size.

Speaking of size, we're now ready to add an expression to affect the layer's font size. In the layer's Source Text property, we can use this expression to do so:

textSize = comp("MAIN COMP").layer("FONT SIZE OPTIONS").effect("Name Font Size")("Slider")
text.sourceText.style.setFontSize(textSize)

First, we reference the slider from our main comp labelled "Name Font Size", so that this layer knows what to look for. Then, we use the sourceText.style expression to set the font size to match the number on this slider.

Now that the name layer is complete, we can do the same again for the Title text layer. Copy and paste the same expression inside the anchor point property, and the Source Text property, changing the slider effect in the latter to "Title Font Size" so it has its own unique control.

textSize = comp("MAIN COMP").layer("FONT SIZE OPTIONS").effect("Title Font Size")("Slider")
text.sourceText.style.setFontSize(textSize)

One final trick we need to set up is the position of both of these layers. Ideally, I would like to control the padding between these layers, and the position overall in case this needs a bit of tweaking. We can do this with some simple expressions in the position properties.

First, we can use this inside the Name layer:

y = value[1] + comp("MAIN COMP").layer("FONT SIZE OPTIONS").effect("Position Adjust")("Slider");

[value[0], y]

To reference the "Position Adjust" slider in our main comp. This simply adds the value of that slider to this layer's position, allowing us to move it up or down.

For the title layer, to ensure the padding changes along with the name font size, we need to be a little more clever. First, parent the title layer to the Name layer. Then, we write this inside the position property:

nameLayer = thisComp.layer("Name Copy 01");

nWidth = nameLayer.sourceRectAtTime().width;
nHeight = nameLayer.sourceRectAtTime().height;
nTop = nameLayer.sourceRectAtTime().top;
nLeft = nameLayer.sourceRectAtTime().left;

padding = nHeight / 1.7;
paddingSlider = comp("MAIN COMP").layer("FONT SIZE OPTIONS").effect("Padding")("Slider")
paddingNew = padding * paddingSlider;

x = value[0];
y = nTop + nHeight + paddingNew;

[x, y]

First, we create variables to store the data from our name layer's sourceRectAtTime() values in our Title layer's position property. This will allow us to change position based on the size of the Name layer. Next, we work out our padding. The space between my text = the height of the name layer divided by 1.7. Yours may differ, so feel free to change the number 1.7 for something that is more suitable to your template.

I then reference my main comp slider "Padding", and multiply the value by my padding variable. This will allow me to change the padding value by a percentage, rather than addition, keeping the spacing consistent across text sizes.

Lastly, I establish my x and y values. Since I don't want there to be any adjustment in the x value, I simply keep it value[0]. The y coordinate however should equal the sum of the name layer's top and height values, plus the variable paddingNew, the percentage change to our default padding.

Phew! That was a lot of calculations. But after all that, we can return to our main comp and see whether or not it works. Drag each slider into the Essential Graphics panel, and then change the values one by one in order to test them.

It works! Now that we're happy with these, we can go ahead and copy and paste the expressions in the rest of the people precomps. Remember to update the expressions with the correct precomp layer names.

Once you have copied the expressions to all of the precomps, you'll be able to resize them all so they are uniform with adaptive leading between your text layers. Useful when you're handing the template over to someone who may not have a designer's eye!

You can just as easily have the title font size be adaptive based on the name layer size too, as well as the leading. In fact, with hindsight, this is probably what I would want to do to prevent overwhelming the end user with options. Providing the user with just a "Name Font Size" option (and perhaps an "overall position adjustment") would be enough to change everything proportionately!

For an adaptive Title Font size, simply use this expression inside of the Title Source Text property instead:

nameTextSize = comp("MAIN COMP").layer("FONT SIZE OPTIONS").effect("Name Font Size")("Slider");
textSize = (nameTextSize/15)*9;
textSizeSlider = comp("MAIN COMP").layer("FONT SIZE OPTIONS").effect("Title Font Size")("Slider")
textValue = textSize * textSizeSlider;


text.sourceText.style.setFontSize(textValue)

The ratio between my Name text and Title text in this template is 15:9, which is why I divide the Name Font Size slider by 15, and then multiply it by 9. If your ratio is different, simply change these values to suit your project.

Changing Fill Options

Depending on your template, you may find you need a variety of other options for your template. One of the main ones I encounter is colour options. There are 2 ways which I tackle this in templates.

The first is simple, and allows the user to pick whatever colour they desire. Let's say we would like to change the colour of the circles in my template. Simply navigate to this layer in your project, and add a Fill effect. Then, drag that fill effect into the essential graphics panel.

Then from the main comp, you can change the colour of the circle to any other colour.

This method however may not be suitable for all users. What if the end user doesn't know the colour codes to use for their brand? When colours need to be matched completely, it's best to give the user less options. I achieve this by combining a Color Control effect with another dropdown menu.

Create another null and add a Color Control effect to it. Name it "Font Colour". We will use this to change the colours of all the fonts in our template.

In turn, go into each precomp and add a fill effect to each text layer. Then, inside the fill effect, write an expression referencing the Color Control effect in the main comp:

comp("MAIN COMP").layer("COLOUR CONTROL").effect("FONT COLOUR")("Color")

Do this to every text layer in every precomp. Once you are done, return to the main precomp and create a new dropdown effect. Name it "Colour Dropdown". Edit the dropdown to have as many options as you need colours. In my case, I am creating a purple, pink and black option.

Drag your dropdown menu into your Essential Graphics panel. After this, we can add our expression to our Color Control effect.

After Effects references colour with 4 arguments: Red, Green, Blue and Alpha. So we will need to create variables for each colour we plan to make.

//Purple
r1 = 102 / 255;
g1 = 36 / 255;
b1 = 131 / 255;

//pink
r2 = 240 / 255;
g2 = 82 / 255;
b2 = 118 / 255;

//black
r3 = 0;
g3 = 0;
b3 = 0;

Inside the Color Control effect, I create my RGB variables for each colour. I divide each entry by 255, since this is how After Effects processes colours for expressions.

Once this is done, I need to add a variable for my dropdown menu, and create a final if statement to connect all the variables to the dropdown menu:

dropdown = thisComp.layer("DROPDOWN").effect("Colour Dropdown")("Menu");

//Purple
r1 = 102 / 255;
g1 = 36 / 255;
b1 = 131 / 255;

//pink
r2 = 240 / 255;
g2 = 82 / 255;
b2 = 118 / 255;

//black
r3 = 0;
g3 = 0;
b3 = 0;


if (dropdown == 1) [r1, g1, b1, 1]
    else if (dropdown == 2) [r2, g2, b2, 1]
    else [r3, g3, b3, 1]

If the menu has the first option selected, it will display the first colour (in this case, purple). If it has the second selected, it will display the second colour. If any other option is selected, it will display the third colour.

This method is a little more technical, but overall means that the user can never select a colour they are not supposed as part of the template.

Limitations

Of course, it's important to know the limitations of every template. After all, we should remember a template can never be all inclusive - some things we just have to do manually. But understanding why that’s the case goes a long way, and can help you explain to clients and coworkers quality work takes time, and cannot simply be automated.

In terms of the limitations I encountered in my project - sometimes you need to be mindful of using the text animator in conjunction with the fixed anchor point expression. Because of the way sourceRecAtTime works, you may find your layer moves around while the text animator is in motion. I have gotten around this by duplicating my text layer and doing the following:

Paste the anchor point expression in layer 1. Then, parent layer 2 to layer 1 (without the anchor point expression). Your text animator motion goes on layer 2. Connect the source text property of layer 1 to layer 2, so layer 1's text automatically updates when layer 2's source text is changed. Finally, turn off layer 1 so it is not visible. Layer 1 will constantly be centred and updated with the same text as layer 2 - but layer 2 will have the added bonus of the Text Animator and be moved thanks to the parenting.

One other limitation to consider when making your template is its longevity. No one wants to make a template that is old news before a project is finished (or within a month for those ongoing projects). So it's important to consider the template's functionality. Will you, in the future, need more options than you have right now? If you know this to be the case, you should consider what will be the easiest course of action to update your templates later. Build your projects so that they work for you - not the other way around!

Other Ideas

You can go further with your projects than I did in this article. Here are some ideas:

You can connect data in your project with .csv files for your clients to use and update, should they understand spreadsheets better than After Effects. I've gone through the process in my Kinetic Text project here, for more information on how to achieve this.

Your template may need to change duration length depending on your options. This is something we can accomplish with on and off animations, if statements, and a slider. You can find examples of how I tackle on and off animations in my linear and ease article, and work it out from there.

Conclusion

In conclusion, by deploying the Essential Graphics panel we can create much more responsive, easier to use After Effects templates than ever before.

Did this article help? Do you have any questions? Let me know in the comments.

After Effects: While Loops

Kat — Thu, 10 Oct 2024 12:22:05 +0000

Introduction
while Loops Vs if Statements
while Loops Vs for Loops
When To Use while Loops
Conclusion

Introduction

Full disclosure: I hate while loops. It has taken me a long time to get my head around them, but I think I finally understand their purpose.

Starting out, everytime I tried to write my own while loop, I would crash After Effects immediately. Now that I have a bit more knowledge on what went wrong, I want to write up what a while loop is, when to use it, and how you can incorporate it in your After Effects expressions without crashing your project (remember to save regularly, folks).

`while` Loops Vs `if` Statements

A while loop, like the name suggests, is a loop which executes as long as the expression is true.

"Executes as long as the expression is true" - that sounds a little bit like an if statement, doesn't it?

if (time < 2) "Text On"

If you add this expression to the Source Text property of a text layer, you will find that the text reads "Text On" for the first 2 seconds of your timeline, and displays no text after that time. An if statement checks whether or not an expression is true, and if it is, it executes the command once, and only once.

However, if you changed it to this expression, you would find that After Effects crashes almost immediately:

while (time < 2) "Text On"

This is because the while loop is a loop, so it executes the command repeatedly if the statement is true. As long as your cursor is in the first 2 seconds of your timeline, the while loop will loop infinitely. Not exactly ideal, and certainly not what we were trying to achieve! It is important to make sure that your while loop will, eventually, become false, to avoid these infinity loops.

For more on if statements, see my previous article here.

`while` Loops Vs `for` Loops

Okay, so it's important to note not to use while loops like if statements. But there are other types of loops we can use to make expressions. How does a while loop differ from a for loop, for instance?

A for loop works with 3 arguments, and is ideal when you know how many times you need to loop your commands.

Take this example, generating random numbers:

//variables
let counter = 0;
let num = 0;
let numArray = [];

//For loop
for (let i = 0; time >= i/2; i++) {
    seedRandom(counter, timeless = true);
    num = Math.floor(random(1, 6));
    numArray.push(num);
    counter++
}

//return
numArray[counter - 1]

After setting up my variables, the loop starts with let i = 0, setting the first argument which executes once. Then, time >= i/2 establishes how often the loop should execute. Setting the loop this way will mean the loop executes twice every second, because time needs to be more than or equal to half of i. Finally, the third argument i++ will run everytime after the loop is executed. In this case, the value of i increases by 1.

Running this expression again in the Source Text property of a text layer will display a random number between 1 and 5 twice every second.

For more information on for loops, see my previous article here.

A while loop is best used when you do not know how many times your loop will need to execute. Because of this, I've found that they don't work well with expressions which involve time like for loops do so well, as that traps you in those pesky infinite loops.

So when should we use while loops?

When To Use `while` Loops

Keeping all of this in mind, a while loop should be used in these conditions:

We need to execute the expression more than once
We do not know how many times we need to execute our loop
We are able to break the loop, to avoid it executing to infinity

I recently found a use for this within After Effects, while working on my random number generator project.

Let's look at the following code:

//variables
let counter = 0;
let num = 0;
let numArray = [];

//For loop
for (let i = 0; time >= i/2; i++) {
    seedRandom(counter, timeless = true);
    num = Math.floor(random(1, 6));

//While loop inside of For loop
        while (num == numArray[counter - 1]) {
        num = Math.floor(random(1, 6));
        }

    numArray.push(num);
    counter++
}

//return
numArray[counter - 1]

In this instance, the while loop is checking to see if the current value of num equals the previous value, stored in the numArray array. If it does, it generates a new random number between 1 and 5. The loop will execute as long as num and the previous number stored in the array are the same. However, once the numbers do not match, the while loop ends, and the expression is free to continue to the next line of code.

Because I may have to generate a new random number more than once, an if statement doesn't work here.

And because I don't know how many times I will need to refresh the random number, the number of loops is also a mystery: so a for loop is no good here either.

Therefore a while loop is my best option. It will execute as many times as I need it to, until the argument inside it is false, which will certainly happen as long as the random() function generates a number which does not match the previous one.

Conclusion

In conclusion, while loops are likely to be an uncommon tool in your After Effects expression belt. However they are useful to learn, for instances where the usual suspects may not be suitable.

Did you find this helpful? Do you have an example of using a while loop in your project? Did I get something wrong? Please leave me a comment and let me know.

Project: Random Number Generator But Excluding The Previous Entry

Kat — Mon, 07 Oct 2024 16:59:49 +0000

Contents
Introduction
`random`
Creating An Array
`while` Loop
Applying It To Things Other Than Numbers
Conclusion

Introduction

Sometimes you just need a random number. But not that random. I find that, when having numbers flash randomly on the screen for a video effect, that it works best when there are no repeats in the sequence. This can happen from time to time, especially if your range isn't that large, when using the random() function. While it is perfectly understandable for what the function does, it still makes our animation look a little staggered.

So I set myself the challenge of writing an expression that excludes the previous number from the random generation, and thought about how this could be applied to projects in the future.

Here's what I did.

`random()`

Let's start at the beginning. If you need a random number in After Effects, using the random(minVal, maxVal) function is a great place to start. By inputting a minimum and maximum value into the function, After Effects will generate a random number from within those bounds every frame.

random(1, 11)

That's a lot of decimal places! Since I just want integers, I use Math.floor to round the numbers down. Because the range of the random function is 1 to 11, this method will produce a random number between 1 and 10, since the top of the range is not included.

Math.floor(random(1, 11))

Much better. However I want to control how often the number changes, not on every frame. To do that, we need to use the seedRandom(seed, timeless?) function. This function requires 2 arguments, the seed, and whether or not timeless mode is set to true or false. By default, timeless is set to false, meaning that the random function will generate a new number each frame. However, if we set this to true, the random function will only generate a number once.

seedRandom(0, timeless = true);
Math.floor(random(1, 11))

Now that the number only generates once, I can manipulate the seed number using a simple for loop to control how often the number generates. If you're unfamiliar with for loops I've written up an article about them in depth here.

Here is my basic loop:

let counter = 0;
let num = 0;

for (i = 0; time >= i; i++) {
    seedRandom(counter, timeless = true);
    num = Math.floor(random(1, 11));
    counter++
}

num

First, I set up the variables counter to track the changes in time, and num, to store my random number. The loop is set to add 1 to i whenever time >= i, meaning the loop updates every second the timeline is active. Everytime the loop refreshes, seedRandom is updated by the change in counter's value, producing a new random number when num is called at the end of the expression.

By adjusting i in the for loop, we can control how often the number changes per second. For instance, if we were to change the argument to time >= i/2, the number will change twice every second instead of once.

Now that we have an expression which allows us to generate a new random number at an interval of our choosing, it needs to be amended to ensure we never have any duplicate entries one after another.

Creating An Array

In order for After Effects to be able to compare numbers, the numbers need to be saved somewhere for After Effects to review. So I decided to save my random numbers to an array as they are generated over time.

let counter = 0;
let num = 0;
let allNum = [];

for (i = 0; time >= i/2; i++) {
    seedRandom(counter, timeless = true);
    num = Math.floor(random(1, 11));
    allNum.push(num);
    counter++
}

allNum

I create the variable allNum outside of my for loop, and then push() the number currently inside of our num variable to the array. This saves each number as it is generated across the timeline.

By calling allNum at the end, we are able to see all the numbers in our array by the end of our timeline:

As you can see, this is less than ideal with a set of double 7s and triple 1s in our sequence. If we called num and played our timeline, the doubles could make it look as if our timeline had frozen or stopped animating. Therefore, we need to ensure that our expression takes into account the previous entry of this array, and excludes it from being added again in such quick succession.

`while` Loop

I found the answer to this was to add a while loop within the existing for loop.

A while loop allows you to specify a command while certain criteria is true. In this case, we want it to be active while the current value of num matches the previous value, listed in our allNum array.

while (num == allNum[counter - 1]) num = Math.floor(random(1, 11));

While the current value of num matches the previous entry inside of allNum, the while loop will generate a new random number using a new iteration of Math.floor(random(1, 11)). This loop remains active as long as the numbers stay the same. Therefore, until a different number is generated, the while loop will prevent the same number from being added to the allNum array.

The while loop is inserted into our for loop like so:

let counter = 0;
let num = 0;
let allNum = [];

for (i = 0; time >= i/2; i++) {
    seedRandom(counter, timeless = true);
    num = Math.floor(random(1, 11));
    while (num == allNum[counter - 1]) num = Math.floor(random(1, 11));
    allNum.push(num);
    counter++
}

allNum

It is added after num has attempted to generate a new number with the update to seedRandom, but before it is pushed to the array so it can be re-generated if necessary.

With this amend, our array now looks like this:

As you can see, we no longer have double 7s or triple 1s in our sequence.

Therefore, if we call num at the end of our expression instead of allNum, we will have a random number between 1 and 10, excluding the previous entry generated, twice every second. Hooray!

Applying It To Things Other Than Numbers

While random numbers are all well and good, there are other uses for this expression too. For instance, what if we wanted to randomise words on the screen instead, without duplicate repeats?

All we need to do is add another array.


var ranText = ["Banana", "Apple", "Pear", "Peach", "Pulm", "Orange", "Mango", "Lychee", "Pinapple", "Dragonfruit"];

Here is an array housing the text we want randomised. There are 10 entries, matching the range of the number generator we made previously.

By calling an entry of our new array using our num variable, we can call the entry whose index matches that number:


//Text
var ranText = ["Banana", "Apple", "Pear", "Peach", "Pulm", "Orange", "Mango", "Lychee", "Pinapple", "Dragonfruit"];

//variables
let counter = 0;
let num = 0;
let allNum = [];

//For loop
for (i = 0; time >= i/2; i++) {
    seedRandom(counter, timeless = true);
    num = Math.floor(random(1, 11));
    while (num == allNum[counter - 1]) num = Math.floor(random(1, 11));
    allNum.push(num);
    counter++
}

//return
ranText[num - 1]

Useful! Just remember to make sure that your num variable at the end includes -1, to account for the array index starting at 0.

Instead of using an array, it is possible to connect your expression to data inside of a .csv file. I go into how this is possible in my kinetic text breakdown here, should you want to make a template that is constantly updatable.

However you can use it in other ways too. Images can be randomly displayed as well, by connecting this expression to a slider controlling the frames of a precomp.

Conclusion

In conclusion, it is possible to add a little bit more control over random numbers in order to make them look a little more aesthetically pleasing to the eye.

What did you think of this method? Is there an easier way? Did this help you with your project in any way? Please leave a comment and let me know.

Project: Spreadsheet To Video, Kinetic Text

Kat — Tue, 13 Aug 2024 09:38:33 +0000

Introduction
Initial Testing With Arrays
Setting Up My Spreadsheet
Using Data From The .CSV File
Adding Line Breaks
Aligning The Text
Text Size
Using The Essential Graphics Panel
Animation: Opacity
Animation: Position
Animation: Scale
Animation: Other Ideas
Limitations
Conclusion

Introduction

Recently I set myself the target of writing expressions for After Effects which allow me to animate text, song lyrics, or captions, using a spreadsheet to dictate the copy and timings. Here is how I achieved this.

Initial Testing With Arrays

Before creating my .csv file, I wanted to work with some arrays to ensure I was able to get my expression working the way I wanted. In the "Source Text" parameter of a text layer, I create my arrays:

var textCopy = ["Apple", "Banana", "Strawberry", "Orange", "Peach"];
var textDuration = [.5, 1, .5, 1, 1];

textCopy is the text I want to see on screen. Meanwhile, textDuration is the length of time a line is on screen, in seconds. My idea was to look at the textDuration entries and cross reference them with time. Once time = first number in the textDuration array, After Effects would add the second entry to work out the total duration. Then, once time = first entry + second entry, the next number in the array would be added, and so on, until all the numbers in the array were added together. For this, I used for loops. The first for loop was created to calculate the totalDuration:

var sum = 0;
var totalDuration = [];

for (i = 0; i < textDuration.length; i++) {
    sum = sum + textDuration[i];
    totalDuration.push(sum);
}

In this loop, the textDuration array entries are added together one by one, using the sum variable to store them in temporarily, and then pushed to the totalDuration array before a new number is added. The loop continues until it cycles through all the numbers in the textDuration array.

I then create a second for loop, using the new totalDurations array:

var entry = 0;
for (i = 0; time >= totalDuration[i] && time < totalDuration[totalDuration.length-1]; i++){
    if (true) entry++;
}

For this loop, I'm telling After Effects to loop only when time is equal to or bigger than the current totalDuration entry, but lower than the very last entry of the totalDuration array. If both of these are true, it will add 1 to the entry variable.

Lastly, I create an if statement telling After Effects what to display in the text layer:

if (time < totalDuration[totalDuration.length-1])textCopy[entry]
    else "Thanks For Watching!"

If time is less than the last entry in totalDuration, it will cycle through the copy, using the for loops to update the array index. However once it reaches the end, it will display "Thanks For Watching!", signifying the end of the loop. This is to stop any errors from appearing, if the timeline is longer than totalDuration's last value. If you simply prefer the text to disappear once it reaches the end, you can delete the text from between the quotes on the else statement.

Now that I had a proof of concept, I was ready to introduce my .csv file.

Setting Up My Spreadsheet

It was time to set up my spreadsheet. I decided I would need 3 columns: "Text", "Text Duration" and "Total Duration". The Total Duration column would mean I could lose the for loop which added up the Text Durations and clean up my script.

I use the Total Duration column to work out the value of my Text Duration, so I can simply scroll through my audio and note down the end of each of the lines. If at any point you want to include a pause, simply leave the Text column empty for that row, and update the Duration columns accordingly. At this point, the Line Duration column seems redundant now that I have a Total Duration column, but I've kept it in the spreadsheet for animation purposes later.

Save the spreadsheet as a .csv file, so it can be imported into After Effects.

Using Data From The .CSV File

Actually using data from the spreadsheet was a little more complicated than I had initially thought. My main hurdle was trying to figure out how to cycle through the rows. I wanted to make this script adaptable so it would work no matter the number of rows in the spreadsheet. Therefore, I needed a way to count the number of rows, to work out the total.

First things first, I needed to reference the .csv file with the expression. I replace my arrays with this:

var data = footage("SPREADSHEET.csv");

SPREADSHEET.csv should be the name of your spreadsheet in the project panel.

Now I was successfully telling After Effects to look at the information in the .csv file, it was time to start pulling information.

But in order to do that, I needed to count the rows in the .csv file. I came up with the idea of turning the data from the .csv file into a string, splitting the string on every line break, then calculating the length to get the number of entries. However, I wasn't quite sure how to turn my .csv file data into a string from within an After Effects parameter. Luckily, thanks to this post on Creative Cow, I was able to find I could do what I needed using the sourceText function. Like so:

var dataSplit = data.sourceText.split(/\n/);
var rows = dataSplit.length-2;

The sourceText function transforms the data in the .csv file into a string. Then, the split function is separating that string line by line, searching for line breaks (represented by "\n"). We can measure how many times our string was split with the length function. To calculate the number of rows correctly, we need to subtract 2 from this number: 1 to account for the headings on our spreadsheet, and 1 because our index starts at 0.

Now that I had calculated the number of rows in the .csv file, I could go ahead and make my for loop:

var entry = 0;
for (i = 0; i <= rows && time >= data.dataValue([2, i]); i++){
    if (true) entry++
};

Similar to the initial tests, while the variable entry is less than the variable rows, and time is more than the current total duration, entry's value increases by 1. This means when time is less then the current total duration, After Effects will look to the next one, until it has cycled through all entries in the column.

Finally, I needed to rewrite the last if statement to complete the expression:

if (time < data.dataValue([2, rows])) data.dataValue([0, entry])
    else "Thanks For Watching!"

Again, like the tests, while time is less than the very last value in the total duration column, the for loop will provide the timings to tick through all instances of the text column in the spreadsheet. Then, once it has gone through all entries, it will finish by flashing up the message, "Thanks For Watching!"

And there it is, the basic expression! Pasted into the sourceText parameter of a text layer, it will allow the text to cut from one line to another, using timings specified in the .csv file:

var data = footage("SPREADSHEET.csv");


//Number of rows
var dataSplit = data.sourceText.split(/\n/);
var rows = dataSplit.length-2;


//For loop 
var entry = 0;
for (i = 0; i <= rows && time >= data.dataValue([2, i]); i++){
    if (true) entry++
};


//Return
if (time < data.dataValue([2, rows])) data.dataValue([0, entry])
    else "Thanks For Watching!"

This is the basic concept which I set out to achieve. However, I wanted to see how far I could push things. So I thought about how I could format the text, and how I could create more interesting motion.

Adding Line Breaks

The first thing I wanted to add was the ability to include line breaks in the copy. Since the expression relies on the line breaks in the .csv file to separate the entries, it would break the expression to include line breaks in the copy of the spreadsheet.

The first work around I could think of was simply applying this code to a layer with a text box, rather than a simple text layer:

This works if you don't mind where your line breaks fall. However, I wanted an option which gave the user control of where to put their line breaks. So I settled on the idea that a symbol could be used in the spreadsheet, and replaced later by the expression.

I decided to use an underscore. I added one to my spreadsheet as an example:

and updated my .csv file in After Effects. To finish, I added the replace function to the end of the dataValue in the final if statement:

if (time < data.dataValue([2, rows])) data.dataValue([0, entry]).replace(/_/g, "\n")
    else "Thanks For Watching!"

For the first argument, I placed an underscore between the slashes to specify the symbol I wanted to replace, and added the g modifier (the global modifier) to replace all instances. The second argument is what the function is replacing it with (again, "/n" meaning a line break). So now the expression searches for "_" and replaces it with a line break.

Because the intention of this expression is to stop the user from editing the code themselves, I felt that having the line breaks be specified in the spreadsheet was the best course of action.

If you want to include spaces on either side of your symbol for better readability in your spreadsheet, you can:

replace(/ _ /g, "\n")

And if you'd rather use a different symbol, simply change the underscore to whatever symbol works best for you.

Aligning The Text

Now that I have line breaks, I have a new formatting issue: aligning my text. While After Effects provides horizontal alignment tools for text, it does not provide vertical alignment tools. Therefore, if our text drops onto extra lines, it will always drop "down" in space, and make our text look off center.

To correct this, I will need to fix the anchor point of the text layer, so no matter the size of the layer, it calculates where it should be to keep the text formatted correctly. I will start with center alignment, or keeping the anchor point in the center of the text layer.

This is fairly straightforward, and requires a simple expression written in the anchor point parameter of the layer:

var copy = thisLayer;

var cWidth = copy.sourceRectAtTime().width;
var cHeight = copy.sourceRectAtTime().height;
var cTop = copy.sourceRectAtTime().top;
var cLeft = copy.sourceRectAtTime().left;

var x = cLeft + cWidth / 2;
var y = cTop + cHeight /2;

[x, y]

With the function sourceRectAtTime, we are able to measure the size of the text layer. As the text changes, its width, height, top, and left values will change. We can find the center of the layer by creating an x and y variable. For the x, I add the left and width values to get the right side of the layer, then divide by 2. For the y, I add the top and the height values to get the bottom of the layer, then divide by 2. When these variables are entered as coordinates for our anchor point, they will always sit in the center of the layer.

This is useful for full screen graphics, and caption style text.

If you need the anchor point to be in a different place, you will need to adjust the equation. Such as:

Top-Center:

x = cLeft + cWidth / 2;
y = cTop;

Bottom-Center:

x = cLeft + cWidth / 2;
y = cTop + cHeight;

Top-Left:

x = cLeft;
y = cTop;

Just remember: Top and left aligned only need the top and left values, right and bottom aligned need the full left + width and top + height values, and center alignment need the full values to be divided by 2.

Other formatting options I was considering was text size. What if I want different lines to be a different size text? Again, a simple way of adjusting this is with keyframes at every line change. However this is a manual, time consuming process. Also, I want to assume the user has very basic After Effects skills. So I wanted to connect the font size to the spreadsheet.

I added another column for text size.

Once I saved a new .csv file, I knew I could cycle through these values in the same way I was cycling through the Text column. But what I needed to figure out was how to format the text. At first, I tried the usual method of formatting text in After Effects:

text.sourceText.style.setFontSize(data.dataValue([3, entry]))

Since our new Font Size column is number 3 in our .csv file (because the first entry starts at 0), the number will change as the copy does. However, because style references sourceText, this does not work with the rest of our expression. If it is placed before our final if statement, it is ignored. If it is placed after, it supersedes the if statement and reverts the text layer to its original source text.

There was a simple fix however. All I had to do was .setText using the data from the spreadsheet. This meant I could add the styling options to the final if statement:

if (time < data.dataValue([2, rows])) text.sourceText.style.setFontSize(data.dataValue([3, entry])).setText(data.dataValue([0, entry]).replace(/_/g, "\n"))
    else "Thanks For\nWatching!"

And it works! However, this changes the font size only. To update the leading, I will have to add that to the style options too:

if (time < data.dataValue([2, rows])) text.sourceText.style.setFontSize(data.dataValue([3, entry])).setLeading(data.dataValue([3, entry])).setText(data.dataValue([0, entry]).replace(/_/g, "\n"))
    else "Thanks For\nWatching!"

I've opted to set the leading to the same value as my font size. Now the font size will change along with the text.

To alter the leading as needed, without editing the expression, I created a slider, to adjust a percentage of the Text Size column. A percentage rather than adding a number will keep the line spacing between different copy consistent.

However, as you can tell, my final if statement is becoming quite long. I needed to start storing information in variables to make this more manageable. The trouble was, if I took the dataValue's out of the if statement, the entry variable would cause an error, its last value ticking up 1 higher than the number of entries in the spreadsheet. This perplexed me for a long time, but the answer to solve this issue was obvious. I could simply clamp the entry value to ensure it never went over the max number of rows. Once I figured this out, I was able to make variables to store data:

var maxDuration = data.dataValue([2, clamp(entry, 0, rows)]);
var copy = data.dataValue([0, clamp(entry, 0, rows)]);
var copySize = data.dataValue([3, clamp(entry, 0, rows)]);
var copyStyle = text.sourceText.style.setFontSize(copySize).setLeading(copySize);

Taking my if statement down to a much more manageable:

if (time < maxDuration) copyStyle.setText(copy.replace(/_/g, "\n"))
    else "Thanks For\nWatching!"

Hooray! Now I'd tidied up my code, I turned my attention back to my slider. I created a new variable for my copyLeading.

var copyLeading = (copySize/100) * effect("Leading Padding")("Slider");
var copyStyle = text.sourceText.style.setFontSize(copySize).setLeading(copySize + copyLeading);

The final thing to consider about text size - the sign off message is not affected by the styling, as it is not from the spreadsheet. So, if you want to have a sign off message, you need to account for that in the else statement.

var signOffStyle = text.sourceText.style.setFontSize(150).setLeading(150);

if (time < maxDuration) copyStyle.setText(copy.replace(/_/g, "\n"))
    else signOffStyle.setText("Thanks For\nWatching!")

Here I have just input the values, but this should also be connected to sliders to make the options editable for the user.

Using The Essential Graphics Panel To Control Formatting Options

Now that sliders have been introduced to the project, I need to make sure the user is able to change their value without being confused. For this, I like to set up my Essential Graphics panel. This panel is fairly new, and is used to create .mogrt files (motion graphics templates) for use in Premiere. However, I think it also does a wonderful job of facilitating After Effects templates, by being a place where all editable values can be placed for the user to find (no more having to search every precomp until you find the layer you need!).

First things first, I want to make sure all the parameters a user could want for changing the sign off message are in place. I create a new text layer, and connect its source text to my expression to create a place for the user to type their own message. Next, I make some more sliders and create more variables to control the sign off font size, and leading. Here is the list of my sign off variables:

var signOffMessage = thisComp.layer("SIGN OFF").text.sourceText;
var signOffSize = effect("Sign Off Font Size")("Slider");
var signOffLeading = (signOffSize/100) * effect("Sign Off Leading Padding")("Slider");
var signOffStyle = text.sourceText.style.setFontSize(signOffSize).setLeading(signOffSize + signOffLeading);

and my updated else statement:

else signOffStyle.setText(signOffMessage)

At this point, I open my Essential Graphics panel (Window > Essential Graphics). I drag in the parameters I want my user to use, such as the sign off message's source text, and all of my sliders. I make some folders to keep my parameters organised. Lastly, I turn off, lock, and shy-guy away my sign off message text layer, so the user isn't distracted.

Now all parameters which need to be editable for the user connected to my code are present in the panel. What a tidy template!

If you want to add more parameters to your Essential Graphics panel, simply drag and drop them in as desired.

Full expression with new formatting:

Source Text

var data = footage("SPREADSHEET.csv");

//Number of rows
var dataSplit = data.sourceText.split(/\n/);
var dataFirstRow = dataSplit[0].split(",");
//dataSplit.length-2 // number of Row
//dataFirstRow.length // number of Columns

var rows = dataSplit.length-2;

//For loop 
var entry = 0;
for (i = 0; i <= rows && time >= data.dataValue([2, i]); i++){
    if (true) entry++
};


//Return
var maxDuration = data.dataValue([2, clamp(entry, 0, rows)]);
var copy = data.dataValue([0, clamp(entry, 0, rows)]);
var copySize = data.dataValue([3, clamp(entry, 0, rows)]);
var copyLeading = (copySize/100) * effect("Leading Padding")("Slider");
var copyStyle = text.sourceText.style.setFontSize(copySize).setLeading(copySize + copyLeading);
var signOffMessage = thisComp.layer("SIGN OFF").text.sourceText;
var signOffSize = effect("Sign Off Font Size")("Slider");
var signOffLeading = (signOffSize/100) * effect("Sign Off Leading Padding")("Slider");
var signOffStyle = text.sourceText.style.setFontSize(signOffSize).setLeading(signOffSize  + signOffLeading);

if (time < maxDuration) copyStyle.setText(copy.replace(/_/g, "\n"))
    else signOffStyle.setText(signOffMessage)

Anchor Point

var copy = thisLayer;

var cWidth = copy.sourceRectAtTime().width;
var cHeight = copy.sourceRectAtTime().height;
var cTop = copy.sourceRectAtTime().top;
var cLeft = copy.sourceRectAtTime().left;

var x = cLeft + cWidth / 2;
var y = cTop + cHeight /2;

[x, y]

Animation: Opacity

Now the basic script is written, and formatting options have been applied, the fun part can begin! Animation.

I decided to start simple. My goal was to create a simple fade in and out for every line, to soften the hard cut. The opacity parameter is also only 1 value, so it will be easier to work with as we start out.

Since we will still need to know when our lines change, we need to keep the start of our code the same:

var data = footage("SPREADSHEET.csv");

//Number of rows
var dataSplit = data.sourceText.split(/\n/);
var dataFirstRow = dataSplit[0].split(",");
//dataSplit.length-2 // number of Row
//dataFirstRow.length // number of Columns

var rows = dataSplit.length-2;

//For loop 
var entry = 0;
for (i = 0; i <= rows && time >= data.dataValue([2, i]); i++){
    if (true) entry++
};

But now, what I want to return is a change in value. Essentially, at the start of every line, the opacity will change from 0 to 100, over a duration set by the user. Then, at the end of the line, the opacity changes from 100 to 0 at the same speed, so there is a smooth transition between each line. This means as one animation brings the line on, and the reverse animation brings it off.

With that reasoning, I set up the variables I would need to make this possible.

var maxDuration = data.dataValue([2, rows]);
var lineDuration = data.dataValue([1, clamp(entry, 0, rows)]);
var totalDuration = data.dataValue([2, clamp(entry, 0, rows)]);

var startAni = totalDuration - lineDuration;
var endAni = totalDuration;
var aniDuration = (1*thisComp.frameDuration) * effect("aniDuration")("Slider");

At last, a reason for the line duration column on our spreadsheet! Having this data accessible in our .csv file means less calculations for After Effects, meaning more efficient code.

lineDuration and totalDuration match their appropriate columns in the spreadsheet. Meanwhile, maxDuration is the last entry of totalDuration, and will be the time it takes to cycle through all of our text.

With these variables set, I can now set the animation on, and animation off times. Since I need the start of the animation to be at the beginning of the line, I set startAni to totalDuration - lineDuration to find that value. Meanwhile, endAni = totalDuration, the time the current line animates off of screen.

Lastly, I create a variable so I can control the speed of the animation. I create a new slider, and multiply it by 1*thisComp.frameDuration. This way, no matter what the composition's frame rate is set to, the slider will always be setting the animation's duration in frames. My composition is at 25fps, so I set my aniDuration to 10 frames.

With all these variables set, it's time to use a trusty ease function to create the move from 0 opacity to 100.

var aniOn = ease(time, startAni, startAni + aniDuration, 0, 100);
var aniOff = ease(time, endAni - aniDuration, endAni, 100, 0);

the aniOn variable will change the opacity parameter from 0 to 100, between the start time of each line, and the start time + the animation duration set by the slider. Meanwhile, the aniOff variable will change the opacity parameter from 100 to 0, between the end time of each line - the animation duration, and the end time.

In order to use both of these animations, we need to set an if statement. I decided that the time the line is on screen should be divided by 2, giving equal time for the line to animate on and off. To work out where the midpoint of each line sits, I just have to add the startAni and endAni together, and divide by 2.

if (time < (startAni + endAni)/2) aniOn
    else aniOff

And with that, we have our first bit of animation!

But I can't celebrate just yet. This current if statement doesn't include the sign off message. At present, the text will animate off after the last line in our spreadsheet, making the sign off message invisible.

To fix this, I need to make a variable for the sign off message to animate:

var signOffAni = ease(time, maxDuration, maxDuration + aniDuration, 0, 100);

and nest my current if statement inside another if statement, to let After Effects know what should happen after all the entries of the spreadsheet have been read.

if (time < maxDuration)
    if (time < (startAni + endAni)/2) aniOn
        else aniOff
    else signOffAni

Now, when the current time is less than the total time it will take to cycle through all entries on the spreadsheet, After Effects then checks whether or not the current time is in the first or second half of the time the current line is on screen. Once it has that information, it chooses whether or not to display the startAni or endAni variable. But - if the current time is equal to or more than the maxDuration, it will display the new signOffAni variable, accounting for the sign off message.

But before I could move on to testing other bits of information, I started to wonder what would happen if the aniDuration was set to 0. Sadly, this breaks things a little bit. The first half of the time it takes a line to display is permanently set to 0 opacity, while the second half is permanently set to 100. True, I could avoid setting the slider to 0, but then again, wouldn't it be cool if setting the slider to 0 turned the animation off, so we could choose whether or not we wanted to use it?

And I can do that! It involves further nesting my if statement:

if (time < maxDuration)
    if (time < (startAni + endAni)/2)
        if (aniDuration == 0) value
            else aniOn
        else
            if (aniDuration == 0) value
                else aniOff
    else
        if (aniDuration == 0) value
            else signOffAni

Breaking this down, everytime the previous if statement gave a value, I created a new condition for After Effects to check. If the duration slider was set to 0, the if statement would set the opacity to it's default value, turning the animation off. However, if it was any other value, it would run as expected.

By setting the opacity to its default value rather than 100, it allows the user to change the opacity of the text layer. After doing this, the thought occurred to me that the ease functions should also be changed to the default layer value, to give the user more customisation options.

var aniOn = ease(time, startAni, startAni + aniDuration, 0, value);
var aniOff = ease(time, endAni - aniDuration, endAni, value, 0);
var signOffAni = ease(time, maxDuration, maxDuration + aniDuration, 0, value);

With that, I have some seriously cool customisation options for the first animatable parameter of the script!

Full Opacity Expression

var data = footage("SPREADSHEET.csv");

//Number of rows
var dataSplit = data.sourceText.split(/\n/);
var dataFirstRow = dataSplit[0].split(",");
//dataSplit.length-2 // number of Row
//dataFirstRow.length // number of Columns

var rows = dataSplit.length-2;

//For loop 
var entry = 0;
for (i = 0; i <= rows && time >= data.dataValue([2, i]); i++){
    if (true) entry++
};


//Return
var maxDuration = data.dataValue([2, rows]);
var lineDuration = data.dataValue([1, clamp(entry, 0, rows)]);
var totalDuration = data.dataValue([2, clamp(entry, 0, rows)]);

var startAni = totalDuration - lineDuration;
var endAni = totalDuration;
var aniDuration = (1*thisComp.frameDuration) * effect("Opacity Animation Duration")("Slider");

var aniOn = ease(time, startAni, startAni + aniDuration, 0, value);
var aniOff = ease(time, endAni - aniDuration, endAni, value, 0);
var signOffAni = ease(time, maxDuration, maxDuration + aniDuration, 0, value);


if (time < maxDuration)
    if (time < (startAni + endAni)/2)
        if (aniDuration == 0) value
            else aniOn
        else
            if (aniDuration == 0) value
                else aniOff
    else
        if (aniDuration == 0) value
            else signOffAni

Animation: Position

While I certainly don't intend to walk through every single parameter in the same way, I do want to write up how I am choosing to animate the parameters with more than 1 value.

However, the position parameter is unique, in that it can be separated.

Because of this, controlling each value was simple. I copy-pasted my code from the opacity parameter, and changed the applicable variables.

Here are the variables under the X Position:

var maxDuration = data.dataValue([2, rows]);
var lineDuration = data.dataValue([1, clamp(entry, 0, rows)]);
var totalDuration = data.dataValue([2, clamp(entry, 0, rows)]);

var startAni = totalDuration - lineDuration;
var endAni = totalDuration;

var aniDuration = (1*thisComp.frameDuration) * effect("X Position Animation Duration")("Slider");
var posMoveIn = effect("X position move in")("Slider");
var posMoveOut = effect("X position move out")("Slider");

var aniOn = ease(time, startAni, startAni + aniDuration, value + posMoveIn, value);
var aniOff = ease(time, endAni - aniDuration, endAni, value, value + posMoveOut);
var signOffAni = ease(time, maxDuration, maxDuration + aniDuration, value + posMoveIn, value);

I created a few more sliders for the position parameter than I did for opacity, to control the movement in and out separately. I made sure to add posMoveIn to the in-animation variables, and posMoveOut to the out-animation.

I then did all of this for the Y Position. If you also want to animate within Z space, make sure to enable 3D on the layer, and do the same for its Z Position.

With that in place, I could now animate the position of my layers in and out for each line.

And, if I wanted, I could combine the position and the opacity animation.

Animation: Scale

Unlike position, we are unable to separate our scale values. This is because we are able to tether and untether our x and y scale values with a switch in our properties panel - which under normal circumstances works perfectly fine.

However, this means we will have to do some more thinking about our expression, if we want to have the option of affecting the x and y scale independently.

Here's how I worked this out.

I started by making a dropdown menu. I made 2 options, combined scale and separated scale.

I then added 9 more sliders. 3 for affecting the animation duration, animation in, and animation out while the scale was unified. 3 for those aspects for the x scale only. And 3 for those aspects for the y scale only.

I then created all my variables. There were considerably more than for position, as effectively, I had to times the number I needed by 3:

var maxDuration = data.dataValue([2, rows]);
var lineDuration = data.dataValue([1, clamp(entry, 0, rows)]);
var totalDuration = data.dataValue([2, clamp(entry, 0, rows)]);

var startAni = totalDuration - lineDuration;
var endAni = totalDuration;
var aniDuration = (1*thisComp.frameDuration) * effect("Scale Animation Duration")("Slider");

var scaleDrop = effect("Scale Dropdown")("Menu");

var scaleUniIn = effect("Scale Unified scale In")("Slider");
var scaleUniOut = effect("Scale Unified scale Out")("Slider");
var scaleXIn = effect("Scale X scale In")("Slider");
var scaleXOut = effect("Scale X scale Out")("Slider");
var scaleYIn = effect("Scale Y scale In")("Slider");
var scaleYOut = effect("Scale Y scale Out")("Slider");

var aniOnUni = ease(time, startAni, startAni + aniDuration, value[0] + scaleUniIn, value[0]);
var aniOffUni = ease(time, endAni - aniDuration, endAni, value[0], value[0] + scaleUniOut);
var signOffAniUni = ease(time, maxDuration, maxDuration + aniDuration, value[0] + scaleUniIn, value[0]);

var aniOnX = ease(time, startAni, startAni + aniDuration, value[0] + scaleXIn, value[0]);
var aniOffX = ease(time, endAni - aniDuration, endAni, value[0], value[0] + scaleXOut);
var signOffAniX = ease(time, maxDuration, maxDuration + aniDuration, value[0] + scaleXIn, value[0]);

var aniOnY = ease(time, startAni, startAni + aniDuration, value[1] + scaleYIn, value[1]);
var aniOffY = ease(time, endAni - aniDuration, endAni, value[1], value[1] + scaleYOut);
var signOffAniY = ease(time, maxDuration, maxDuration + aniDuration, value[1] + scaleYIn, value[1]);

This also includes a variable for the dropdown menu.

From there, I had to extend my if statement again, to check what the dropdown menu was set to. If it was set to option 1, combined scale, it would display the unified variables. If it was anything else, it would display the separated variables.


if (time < maxDuration)
    if (time < (startAni + endAni)/2)
        if (aniDuration == 0) [value[0], value[1]]
            else
                if (scaleDrop == 1) [aniOnUni, aniOnUni]
                    else [aniOnX, aniOnY]
        else
            if (aniDuration == 0) [value[0], value[1]]
                else
                    if (scaleDrop == 1) [aniOffUni, aniOffUni]
                    else [aniOffX, aniOffY]
    else
        if (aniDuration == 0) [value[0], value[1]]
            else
                if (scaleDrop == 1) [signOffAniUni, signOffAniUni]
                    else [signOffAniX, signOffAniY]

Once all these pieces were in place, the template could be toggled between a combined scale animation, and a separated scale animation.

Animation: Other Ideas

Using the techniques above, you could quite easily make a rotation option for your template.

However, why stop there? You could switch your layer to 3D mode (as mentioned before in the Animation: Position section) and introduce a camera. Moving a camera around across your text, while your text animates, can create some really interesting effects!

Alternatively, if you want to keep your layer 2D, you could introduce a null object, and parent your text layer to it. Then, try to move it around in weird and wonderful ways. Since all our expressions reference the original values of our text layer, parenting our layer shouldn't result in any nasty surprises. You could also add expressions to your null layer, so it animates as every line in the spreadsheet comes and goes.

You can introduce shape layers, footage, or colour changes. Perhaps even dive into the text animator and animate your text line by line, or letter by letter (although I found that you will need a separate layer to fix your anchor point for this). The sky is the limit!

Limitations

Well... that isn't strictly true. There are of course some limitations to creating a project this way.

Such as the number of lines the expression can support. The more rows in your .csv file, the more loops and calculations. Meaning the harder After Effects and your computer is going to have to work. This can make things run rather slow.

My suggestion, if you have lots of lines and it's causing too much lag in your project, is to separate your spreadsheet into multiple .csv files, and create videos in sections. You could then render each section separately, and stitch your video together in Premiere, or another editing program of choice.

Also, because this layer is only 1 text layer, there is no way for the transitions between your lines to overlap. If you require that, you will have to write an expression which works with 2 text layers. How I would test this is to have 2 spreadsheets, one with copy in the text column on all odd number rows, and the other with copy in the text column on all even number rows. That way, you could stagger the layers in such a way that the animation of the two overlap.

For similar reasons, adding a delay to the expression is also very tricky. I recommend accounting for the delay in your spreadsheet, rather than factoring it into After Effects, so the expression doesn't get more complex. You could make an extra column to adjust your total durations.

It is also important to note that this is a template project. No matter how much you add, it will never replace the almost limitless potential of a designer creating a project from scratch. If you need something truly unique and special, you're going to have to roll up your sleeves and prepare for creating the project by hand.

Conclusion And Learnings

I learned a lot from this project. This was the first time I ever used a for loop, which this project heavily relies on. It fact, it was a project full of first times: the first time importing data into After Effects using a .csv file; the first time working with text styling options, and the first time crafting complex, if statements. I learned how to turn data into a string in After Effects by using the sourceText function, and learned about the split, clamp and replace functions.

I am still experimenting with what I can do with this template. There may be a follow up article to this, with some of my more complex discoveries around using text animator and expression selector options, and creating variables for changing out the type of easing used to create the animations once I am satisfied.

Overall, this was a great project to boost my knowledge of javascript within After Effects, and I feel I have more than achieved what I set out to do.

If you have any questions, please leave a comment and I'll try to answer them. Alternatively, if you think there is a more efficient way of doing things than I have done them, please let me know.

After Effects: Text Animation And The Expression Selector

Kat — Mon, 12 Aug 2024 08:00:00 +0000

Contents
Introduction
Using The Range Selector
Using The Expression Selector
Advanced Techniques
Conclusion

Introduction

In the first article of this series, After Effects Basics, I briefly mentioned the text animator. It is a tool in After Effects, which allows for animation of independent characters, words, or lines, as opposed to the layer controls, which affect the entire text layer as a whole.

However it isn't the most intuitive to use. Therefore I wanted to go over it again in depth, starting with basic concepts, all the way to advanced techniques.

Let's get started.

Using The Range Selector

From the properties panel, click the +Add Animator button. Select the property you want to animate. For this example, I will be using position.

When you select a property, the layer will have new options open up in the timeline, like so:

You'll see the new property, Animator 1 added. Inside of it, there is Range Selector 1, and a new position stopwatch. This is the basic setup for the text animator.

Change the y coordinate of your position to 100. You'll notice the text shift down 100 pixels. Next, open up the Range Selector property. You'll see start, end and offset parameters (as well as some advanced options). To demonstrate how the range selector works, make a keyframe at the beginning of your timeline for the start parameter, setting it to 0. Then, at 1 second, add another keyframe setting it to 100. As you play this back, you'll see the letters of your text layer animate, one by one, raising back to their default position.

As the name suggests, the start and end parameters of the range selector control how much of the text is affected by all the properties listed inside Animator 1 (in this case, position). With the start set to 0, and the end set to 100, the entire range is selected, so all characters will be affected. However, as we change the start from 0 to 100 over time, it stops affecting the text gradually as the range gets smaller, resulting in none of the text being affected once it reaches 100.

You can also create a similar animation using the offset parameter, instead of the start or end. This allows you to keep your range fixed, but offsets the values from -100 to 100. This allows for a bit more flexibility, and to easily reverse the animation.

Finally, if you explore the advanced options of the range selector, you can find some options to help fine tune the animation. You can change whether or not the range selects the text by character, word or line. Perfect if you have a long sentence or heading. You can also affect the easing of the animation, randomise the order characters are affected, and change the shape of the animation. This will alter how the text transitions, and is worth playing with to achieve different results.

You can also apply multiple Animators to the same text layer with slightly offset keyframes, to achieve some fun effects.

To try this, remove all keyframes currently on your timeline. Set start to 0, end to 100, and animate offset over 1 second, from -100 to 0. Then, duplicate Animator 1. This will create an Animator 2 property. Open this up, and set the position inside Animator 2 to -50. Select the keyframes for Animator 2's range selector, and move them forward 4 frames. You'll notice this creates a small bounce back for your text.

If you want to add additional properties to the same Animator, you can do so by clicking on the add button next to the Animator in the timeline, selecting property, then whatever property you would like to add.

And that covers the range selector. For some projects, this is enough. Stop here for a bit and have a play with this selector. Try using different properties within the same Animator, or create multiple Animators with different effects. Once you're happy you understand how this control works, you can move onto the next step: working with the expression selector.

Using The Expression Selector

The range selector is not perfect. It does not allow us to control the delay between each letter as it animates, but instead limits us to changing the shape of the animation, the offset, and ease. This means that animations can sometimes be hard to time, and often, does not allow for a smooth transition of letters. What if you want to start the animation of the second letter before the first has completely finished?

If you need to be more precise, you will need to use the expression selector.

It took me some time to work out how to use this selector. But now that I have, I much prefer it to the range selector.

First, create a new text layer, add an Animator with a position property like before, and set the y coordinate to 200. This time however, delete the range selector. Then from your timeline, click the add button next to Animator 1. Select Selector/Expression. Opening the property up, you will see it has a lot less options than the range selector. The Based On option allows you to change whether the selector affects characters, words, or lines. Other than this, there is simply an Amount property, which changes how much the Animator applies to the text. By default, there is an expression written in the amount parameter: selectorValue * textIndex/textTotal, and your text layer will look something like this:

This immediately throws 3 variables at us without explanation. Allow me to go through these now, and why they are affecting the text in this way.

selectorValue is referencing the Amount value of this property. By default, it is set to 100, 100, 100.

textIndex assigns an index number to each character, word or line in your text layer (depending on what your based on property is set to), so that each may be affected individually.

textTotal is the total number of characters, words, or lines in your text layer (depending on what your based on property is set to).

With my based on set to Characters, we can now make sense of the expression written in the amount property.

textIndex/textTotal will produce a number between 0 and 1. This in turn is multiplied against the selectorValue. Therefore, the first character in the text layer with an index of 1, will be affected by the Animator only a small fraction. However, as textIndex increases in value, the amount the Animator affects the text also increases. This goes on until we reach the last character of the text layer, which is 100% affected by the effects of the Animator.

Another way to understand it, is to see each letter affected in sequence.

Let's replace the default expression with this one:

if (textIndex == Math.floor(time)) 100
    else 0

Create an if statement. If the textIndex is the same as Math.floor(time), the Animator will be applied to it 100% (Math.floor is applied to ensure the statement only returns integers). Else, it will be applied at a value of 0 (meaning it will have no effect whatsoever).

As you scrub through the timeline, you will see one by one the letters of your text move.

This is how we select our range in the expression selector. This may be a bit confusing at first. But hopefully, I can help demystify the process of writing expressions for dynamic text movement a little bit.

So, we now know textIndex is one of the values we need to consider when writing the expression. Let's now consider the other values we will need.

Go ahead and change the y position property within Animator 1 to -200. This will help us write the expression to come.

Delete the expression from your expression selector, and create the following variables:

var frames = 1 / thisComp.frameDuration;    //comp frame rate
var delay = 1;  //frame delay between each character, in frames
var dur = 6;    //duration of animation per character, in frames

frames is simply the framerate of the current composition. We will need this in order to convert our other values into frames rather than seconds, since working in seconds can be confusing when needing such small increments. This is easily set by dividing 1 by thisComp.frameDuration.

delay is the time between each character in our animation. The lower the number, the less of a delay, therefore the quicker the animation. Setting it to 1 will result in a 1 frame delay between each character - meaning the second letter will start to animate 1 frame after the first letter starts to move, and so on.

dur is the duration of the animation, per character. I've set mine to 6 for a medium speed animation.

Now we have established our variables, we can create an ease function to animate the text. This will provide a gradual change in value to our characters, vs our previous if statement.

Let's take a look at this:

var frames = 1 / thisComp.frameDuration;
var delay = 1;
var dur = 6;

var indexDelay = textIndex*(delay/frames);
var frameDur = dur/frames;

ease(time, indexDelay, indexDelay + frameDur, 100, 0);

As you can see, we start off again with our variables frames, delay, and dur. But there are two more variables we need to create in order to connect them with the textIndex value, and keep the ease function easy to read.

First is indexDelay. This simply multiplies the textIndex with our delay variable (divided by frames, to convert the delay into the correct time increments). This will dictate when each letter begins its animation.

The second is frameDur. This simply divides dur by frames, to convert the animation duration into the correct time increment.

Finally, the ease function. If you are unfamiliar with the ease function, I go into it in depth in this article. I highly recommend making yourself familiar with how this function works before continuing.

I set the first argument to time, so the selector value is remapped to time and will change as the seconds tick by. Next, I set my in and out points to indexDelay, and indexDelay + frameDur. This means each character will animate in turn from its own index specific start point, for as long as our dur value, in frames. Finally, the last 2 arguments will set what values the selector property animates between. These are set to 100 and 0 respectively, meaning the Animator will go from 100% affecting the text, to 0% affecting it, returning the text to its default position.

The result of this expression is this:

Already, we can see a big difference in the timings here vs the range selector. Here, we are able to play with the timings in a much more precise way. Feel free to adjust the numbers of the delay and dur variables, to see what can be achieved.

Like the range selector, you can duplicate Animator 1 to create an Animator 2. By simply adjusting time in Animator 2's ease function, you can create a similar bounce effect as we did for the range selector before:

Animator 2 expression


var frames = 1 / thisComp.frameDuration;
var delay = 1;
var dur = 6;

var indexDelay = textIndex*(delay/frames);
var frameDur = dur/frames;
var inTime = (thisComp.frameDuration * 4);

ease(time - inTime, indexDelay, indexDelay + frameDur, 100, 0);

Result with 2 expression selector animators:

I created the variable inTime to store my 4 frame calculation, to keep the ease function tidy.

For the cherry on top, try adding an opacity property to Animator 1, so the text also fades in as it drops down (remember: you can do this by clicking the add button next to Animator 1, selecting Property/Opacity, and setting it to 0):

Finally, if you want the text to animate on and off, you need only use an if statement to toggle between 2 different ease functions on both your Animators:

Animator 1 expression

var frames = 1 / thisComp.frameDuration;
var delay = 1;
var dur = 6;

var indexDelay = textIndex*(delay/frames);
var frameDur = dur/frames;

var timeOut = linear(time, 2, 4, 0, 2);

var aniIn = ease(time, indexDelay, indexDelay + frameDur, 100, 0);
var aniOut = ease(time - 2, indexDelay, indexDelay + frameDur, 0, 100);

if (time < 2) aniIn
    else aniOut

Animator 2 expression

var frames = 1 / thisComp.frameDuration;
var delay = 1;
var dur = 6;

var indexDelay = textIndex*(delay/frames);
var frameDur = dur/frames;
var inTime = (thisComp.frameDuration * 4);

var aniIn = ease(time - inTime, indexDelay, indexDelay + frameDur, 100, 0);
var aniOut = ease(time - inTime - 2, indexDelay, indexDelay + frameDur, 0, 100);

if (time < 2 - (thisComp.frameDuration * 4)) aniIn
    else aniOut

Result:

I advise you to stop and have a play with this now, to see what you can make before moving onto the advanced techniques.

Advanced Techniques

So, the range selector lets us fine tune our movements, but not control the delay between our letters. Whereas using the expression selector, we can control the delay, but the default linear and ease functions leave us with only two types of interpolation for our animation.

Or, does it?

What if we want more dynamic animation?

Then we need to create our own custom easing functions. Or, we can use functions others have already created, such as Penner's Easing functions.

I have gone into depth about these functions in this article before. In short, they are a collection of equations which, in Penner's own terms, add "flavour to motion." And, thanks to these functions being open source, we can use them in our After Effects templates, or make our own .jsx files to store them in free of charge (click on the previous article for a full rundown of how to do this). This saves us massive amounts of time - so thank you very much once again, Robert Penner.

Importing my .jsx file to my project, I make a new text layer and add an expression selector to it like before. Then, I start by referencing my .jsx file:

const penner = footage("Penner Easing Functions.jsx").sourceData.getFunctions();

If you are not looking to make a .jsx file, but instead are adding custom functions manually to your project each time, I will post the details of the functions I will be using here. My first example will be using the easeInOutSine function, which you can create by adding...

 function easeInOutSine (t, b, c, d) {
            return -c/2 * (Math.cos(Math.PI*t/d) - 1) + b;
        };

...to the start of your expression, instead of calling a .jsx file.

By using the easeInOutSine function, we can make a constantly moving text layer, bobbing up and down following a sine curve.

After calling our .jsx file, or establishing the function, we set up our variables, the same as we did before:

var frames = 1 / thisComp.frameDuration;
var delay = 2;
var dur = 12;

var indexDelay = textIndex * (delay/frames);
var frameDur = dur/frames;

Then, once we are happy, we can write our final expression. Since the Penner Easing functions work slightly differently to the default ease and linear expressions, our variables will be inputted in a slightly different order:

easeInOutSine(time - indexDelay, 100, -100, frameDur)

Using easeInOutSine, the indexDelay is subtracted from time, our first argument, since this function does not establish an in and out point for value remapping. The second argument is the starting value of our selector, which is set to 100. The third argument is the change in value, so this is set to -100, to bring the selector value to 0. The last argument is the duration of the animation. This is simply set to frameDur.

The result:

Wow - what a cool trick! Even though we specified a duration of frameDur, the text will move continuously, as we have not set any boundaries for the custom function to stop its calculations (i'll be getting to this shortly).

By adjusting the delay, we can control the space between each letter like so:
Delay of 3

Delay of 4

Delay of 5

Already, the effect can be varied substantially, just by changing the delay value. But the variations don't have to stop there. What if instead of subtracting the textIndex from time, we added it to our dur value? This would create an animation, where every letter of our text moved at a slightly different speed, depending on its textIndex value.

var frames = 1 / thisComp.frameDuration;
var dur = 12;

var durAlt = (textIndex + dur) / frames;

//Return
easeInOutSine(time, 100, -100, durAlt)

Since we are no longer referencing delay, we can remove this variable and marvel at the results.

This animation was actually the result of a mistake I made testing these expressions. But I really like it! I think it's a great way to add randomness to your work, as it is forever evolving. It is also a testament to the importance of experimentation. I never would have found this possibility if I didn't give myself room to explore and make mistakes.

So, to recap the full advanced expression we've worked with so far:

easeInOutSine full expression with .jsx file

const penner = footage("Penner Easing Functions.jsx").sourceData.getFunctions();

var frames = 1 / thisComp.frameDuration;
var delay = 2;
var dur = 12;

var indexDelay = textIndex * (delay/frames);
var frameDur = dur/frames;
var durAlt = (textIndex + dur) / frames;

//Return
penner.easeInOutSine(time - indexDelay, 100, -100, frameDur) //Evenly timed expression

//or

penner.easeInOutSine(time, 100, -100, durAlt) //Each character animating at different speeds

easeInOutSine full expression without .jsx file

 function easeInOutSine (t, b, c, d) {
            return -c/2 * (Math.cos(Math.PI*t/d) - 1) + b;
        };

var frames = 1 / thisComp.frameDuration;
var delay = 2;
var dur = 12;

var indexDelay = textIndex * (delay/frames);
var frameDur = dur/frames;
var durAlt = (textIndex + dur) / frames;

//Return
easeInOutSine(time - indexDelay, 100, -100, frameDur) //Evenly timed expression

//or

easeInOutSine(time, 100, -100, durAlt) //Each character animating at different speeds

This is all well and good for animating with a sine, but having values go out of bounds may not be as useful for other custom functions. Let's take the easeInOutBack function for example:

function easeInOutBack (t, b, c, d, s) {
            if (s == undefined) s = 1.70158;
            if ((t/=d/2) < 1) return c/2*(t*t*(((s*=(1.525))+1)*t - s)) + b;
            return c/2*((t-=2)*t*(((s*=(1.525))+1)*t + s) + 2) + b;
        };

If we use the previously devised expression for this function:

easeInOutBack(time - indexDelay, 100, -100, frameDur)

We get this:

Here, we have a problem. The animation is only supposed to drop down once. But, because the function is remapping to time, it continues moving after the specified duration and drops down twice - moving the selector value and going out of bounds. This is because we haven't set any boundaries on our time. Even after our specified duration, time continues to tick, giving the function space to continue its calculations.

In order to fix this, we need to clamp the time parameter. Let's make another variable to store this new value in:

var inTime = clamp(time - indexDelay, 0, frameDur);

Here, we clamp time, preventing it from counting higher than the frameDur variable. However, because we are subtracting the indexDelay from time first, each character will hit this limitation in turn, allowing each letter to complete its animation before coming to a halt.

easeInOutBack full expression with .jsx file

const penner = footage("Penner Easing Functions.jsx").sourceData.getFunctions();

var frames = 1 / thisComp.frameDuration;
var delay = 2;
var dur = 12;

var indexDelay = textIndex * (delay/frames);
var frameDur = dur/frames;
var inTime = clamp(time - indexDelay, 0, frameDur);

//Return
penner.easeInOutBack(inTime, 100, -100, frameDur)

easeInOutBack full expression without .jsx file

function easeInOutBack (t, b, c, d, s) {
            if (s == undefined) s = 1.70158;
            if ((t/=d/2) < 1) return c/2*(t*t*(((s*=(1.525))+1)*t - s)) + b;
            return c/2*((t-=2)*t*(((s*=(1.525))+1)*t + s) + 2) + b;
        };

var frames = 1 / thisComp.frameDuration;
var delay = 2;
var dur = 12;

var indexDelay = textIndex * (delay/frames);
var frameDur = dur/frames;
var inTime = clamp(time - indexDelay, 0, frameDur);

//Return
easeInOutBack(inTime, 100, -100, frameDur)

Result:

Nice! Using the easeInOutBack function, we can make a text animation with a bounce, using only one 1 Animator. Much more simple than creating 2 and offsetting the time like before!

You can also control how "bouncy" this expression is by adding the 5th argument to this custom function: s. According to the expression, while undefined it is 1.70158. So if we change it to a much larger value (and increase our dur value to account for the extra animation time), we can make the movement back more pronounced:

easeInOutBack(inTime, 100, -100, frameDur, 5)

Result:

There's one last thing to fix with the easeInOutBack function before we continue. The expression is supposed to ease back at the start and the end of the movement (hence ease in and out) - however currently it only moves back at the end. This is because at the start, our selector is already at max value: 100. If we want to see the move back at the start, we need to leave room for the selector to move back to. Therefore, I should set my starting value to 90 instead.

easeInOutBack(inTime, 90, -90, frameDur)

Result:

Perfect! Now that I have fixed everything for the function to run correctly, I can use it to animate in and out by creating a new aniOut variable, and an if statement like before:

easeInOutBack full expression with .jsx file

const penner = footage("Penner Easing Functions.jsx").sourceData.getFunctions();

var frames = 1 / thisComp.frameDuration;
var delay = 2;
var dur = 10;

var indexDelay = textIndex * (delay/frames);
var frameDur = dur/frames;
var inTime = clamp(time - indexDelay, 0, frameDur);
var outTime = clamp(time - 1.5 - indexDelay, 0, frameDur);

//Functions
var aniIn = penner.easeInOutBack(inTime, 90, -90, frameDur)
var aniOut = penner.easeInOutBack(outTime, 0, 90, frameDur)

if (time < 1.5) aniIn
    else aniOut

easeInOutBack full expression without .jsx file

function easeInOutBack (t, b, c, d, s) {
            if (s == undefined) s = 1.70158;
            if ((t/=d/2) < 1) return c/2*(t*t*(((s*=(1.525))+1)*t - s)) + b;
            return c/2*((t-=2)*t*(((s*=(1.525))+1)*t + s) + 2) + b;
        };

var frames = 1 / thisComp.frameDuration;
var delay = 2;
var dur = 10;

var indexDelay = textIndex * (delay/frames);
var frameDur = dur/frames;
var inTime = clamp(time - indexDelay, 0, frameDur);
var outTime = clamp(time - 1.5 - indexDelay, 0, frameDur);

//Functions
var aniIn = easeInOutBack(inTime, 90, -90, frameDur)
var aniOut = easeInOutBack(outTime, 0, 90, frameDur)

if (time < 1.5) aniIn
    else aniOut

Result:

And with that, we have a good foundation to begin experimenting with Penner's other custom easing functions.

Try using other functions, other properties, and seeing how the delay and dur values can alter the effects. Get creative - and if you've made it this far, congratulations! You are now a master of the After Effects text animator.

Conclusion

All examples covered here in this tutorial are achieved using predominantly 1 property: position (with a little helping hand from opacity), only 2 of Penner's Easing functions, and the range or expression selectors. There is still a lot of room for experimentation - for instance, combining the use of range selectors and expression selectors.

As I said before, the text animator tool is powerful. It can create so many unique and incredible animations, and the best part about using expression selectors is that they leave the text layers keyframe-less, and editable - perfect for creating dynamic templates.

I hope this article has been inspiring, and given you the tools to play with your own animations.

As always, do you have any questions? Perhaps you know of a better way to achieve this? Let me know in the comments. I'd also love to see what you create!

After Effects: For Loops

Kat — Wed, 07 Aug 2024 10:52:09 +0000

Introduction

Have you ever been building an After Effects template, wanting to use expressions to automate your motion, but found it tricky to write your script accounting for the ever changing values your template may contain? For instance, a constantly changing minimum and maximum slider value. Or an array, or a .csv file with a distinctly different number of entries/rows.

One of the hardest things about building template projects is accounting for these mystery parameters. The more limited the template, the shorter its lifespan and functionality. So it's always in our best interests to make it as efficient as possible.

For this reason, I find myself using for loops.

What Are `for` Loops?

for loops allow After Effects to run the same code a set amount of times, each time using a different value.

for (arg 1, arg 2, arg3){
    //execution
    };

The first argument runs before the loop begins, the second argument sets the condition when the loop should run, and the third argument runs every time after the loop is executed. For a more in depth analysis of the function itself, you can read more here where w3school breaks down the function.

Example Of `for` Loop In Action

So, what can for loops be used for in After Effects? They can be used effectively to cycle through array values, but on top of that they can be used to cycle through keyframes, and other such data we may want to access.

Take this example from my character lip sync project:

var audio = thisComp.layer("Audio Amplitude").effect("Both Channels")("Slider");
let maxV = 0;
let minV = 0;
for (let i = 1; i <= audio.numKeys; i++){
    maxV = Math.max(maxV, audio.key(i).value);
    minV = Math.min(minV, audio.key(i).value);
    };

Here, I list my first argument establishing the variable i, and set it to 1. My second argument, which defines when the loop runs, is set to i <= audio.numKeys. This means the loop will only run when i is less than or equal to the number of keyframes present on my audio slider. Finally, the third argument is set to i++, adding 1 to i at the end of every loop.

While the loop is active, it affects the value of my maxV and minV variables. As i increases, the loop checks the value of each keyframe in turn, and adjusts the variables depending on whether or not the value is higher or lower than the current maxV or minV values. Then, once i is more than the number of keyframes present on my audio slider, the loop stops. This leaves my maxV and minV variables equal to the highest and lowest keyframe values on the audio slider respectively.

No matter how many keyframes or how long the timeline is, this loop is able to work out the maximum and minimum values inputted into the audio slider without any errors. This is ideal for this template, as it is designed to be used for many different audio tracks, with varying volume and track lengths.

Using `for` Loops With `time`

for loops can also be used in timers. Take this example:

var copy = ["apple", "banana", "pear", "peach", "melon", "grapes"];
var copyLength = copy.length;
var dur = time;

let num = 0;
for (i = 0; i <= dur; i++){
    if (true) num++;
}

copy[clamp(num, 0, copyLength-1)]

When inputted into the source text parameter, this example will cycle through the text in the copy array, displaying a new entry every second, and stopping on the last entry. Let's go through how it does this.

First, I set up the array. Create the array and input the text to be shown on screen. Make sure the text is inside "" so that After Effects knows it is text, and not a variable. I then create another variable, copyLength, to determine how long the array is. Doing this instead of using a static integer will allow the expression to update, no matter the number of entries in the copy array. I created the variable dur, aka my line duration. Set to time, the text will change every second. Finally, I set my last variable, num, to 0, because array index numbers start at 0.

Now that the variables are all set up, I can create the for loop. First, I create the variable i and set it to 0 (to match the num variable). For the second argument, I specify i <= dur, meaning the loop will be active only when i is less than the specified duration time. My third argument is once again i++, adding 1 to the i variable at the end of every loop.

While the loop is active, it will add 1 to the num variable. Effectively, creating a counter which will increase in value by 1, every second of the composition timeline.

Now that I have my counting variable, I can finish the expression.

However, if I left the expression at:

copy[num]

it could cause an error once the num variable counts higher than the number of values in the copy array. To avoid this, I clamp() the value. clamp() allows me to set the minimum and maximum values of a variable. So, by setting the num variable like so:

copy[clamp(num, 0, copyLength-1)]

it cannot go lower than 0, or higher than copyLength-1. Because array index's start at 0, and the length of a variable is measured starting at 1, I need to -1 from the copyLength to match the last index value of the array.

And there you have it: a way for After Effects to cycle through text (completely without keyframes or sliders).

By changing the dur variable you can adjust the amount of time each array entry is on screen. For instance, setting dur = time / 2 will double the time each entry is on screen, so that each entry is on for 2 seconds.

You can also connect this to a .csv file instead of manually typing an array. However this is slightly more complex, and a topic worthy of its own article.

Conclusion

for loops can be tricky, but are worth understanding when writing your own After Effects expressions. They can enable powerful flexibility when creating templates, and allow us to work around ever changing variables.

Find this article helpful? Have any questions? Know a better way to use for loops in After Effects that I missed? Let me know in the comments.

After Effects: The If Statement

Kat — Sat, 03 Aug 2024 08:54:50 +0000

Introduction

Last time I covered a pretty complex topic, introducing custom functions into After Effects with Penner's easing functions. I'll like to take a big step back now, and talk about if statements.

So, what are if statements?

Basic `if` Statements

First - if you dabble in After Effects expressions or have any sort of coding experience, you more than likely are familiar with if statements. if statements allow you to tell After Effects to check for certain criteria within the project, and execute a command based on that criteria. An example of this could be linking a layer's opacity to a checkbox control:

if (effect("Checkbox Control")("Checkbox") == 1) 100
    else 0

With this statement in place, when the checkbox control is turned on, the layer will be seen at 100% opacity. However, if the control is off, the opacity will be set to 0%, and the layer will be completely transparent. This can be a useful control when making .mogrt files, or, connecting multiple layers to a single, keyframe-able parameter.

The ability to check for criteria is what makes if statements a powerful tool in your arsenal, even at a basic level. But they can also help enable more sophisticated code for more complex situations.

Checking For Additional Criteria

Sometimes, there may be cause for checking more than one argument in order to return a certain value. For instance, what if I only want a drop shadow layer in a template to be visible when a) there is text inputted into a text layer, and b) the drop shadow checkbox control switch is engaged?

This is possible with the and operator: &&. Adding this between the if statement arguments tells After Effects we want both of these things to be true, in order to return a specific result.

if (thisComp.layer("test").text.sourceText != "" && effect("Checkbox Control")("Checkbox") == 1) 100
    else 0

This if statement checks both arguments, making sure the "test" text layer is not empty, and that the checkbox control is on, before returning an opacity value. In this case, if both of those arguments are true, it will return 100, but if neither or both are false, it will return 0.

Another helpful operator to consider is the or operator: ||.

if (thisComp.layer("test").text.sourceText != "" || effect("Checkbox Control")("Checkbox") == 1) 100
    else 0

Using this operator, After Effects will return the first value in the statement if one or both of the statements are true. Only when both are false, will it return the else value.

Nesting `if` Statements

But what if there is a more complex situation, where there are more than 2 potential answers to an argument? If you need to check for an array of criteria, each with its own potential solution, you may need to create a nested if statement.

For example, I have a text layer which should contain a number between 0 and 4. Depending on what number is displayed, the solid layer behind it will change opacity (0 = 0%, 1 = 25%, 2 = 50%, 3 = 75%, 4 = 100%). However, the solid layer should also check to see whether or not a checkbox control is on. If it is not, the layer shouldn't be visible at all, regardless of the text layer's number.

copy = thisComp.layer("text").text.sourceText;
ctrl = effect("Checkbox Control")("Checkbox");

if (ctrl == 1)
    if (copy == "0") 0
            else if (copy == "1") 25
            else if (copy == "2") 50
            else if (copy == "3") 75
            else if (copy == "4") 100
            else value
    else 0

Let's break this down.

First, I make a variable for my text layer, and my checkbox control. Then, I begin my nested if statement. Because there are more than 2 possible outcomes for this scenario, using && in this case would be encumbersome, forcing After Effects to check the checkbox over and over again unnecessarily. Instead, only the first statement checks to see if the checkbox control is on. Then, I create a second if statement inside the first, which checks what number the text layer is displaying. From there, I create enough else if arguments to cover all possible outcomes. Once all text layer outcomes are accounted for, I finish the statement by writing the else argument for the checkbox control.

Conclusion

Scripting decision making possibilities with After Effects if statements allows for unique and tailored templates. Whether these expressions are written to streamline keyframe animation, to create a .mogrt file, or are there to react to data from an external source, they provide a level of dynamic adaptability to projects otherwise not possible.

Was this useful? Any questions? Feel free to ask in the comments.

Project: Using After Effects Expressions To Generate Character Lip Sync

Kat — Fri, 26 Jul 2024 11:17:03 +0000

Introduction
Create Your Lip Flaps
Importing Into After Effects
Convert Audio To Keyframes
Creating The Expression
Working Out The Audio Range
Final if Statements
Accounting For Audio Peaks
Final Step

Introduction

Lip sync can be one of the most painful parts of character animation. But if you're looking for a simple solution to sell in a character speaking, you may find that using expressions in After Effects can help automate the process.

Here's how I do it.

Create Your Lip Flaps

First, create your lip flaps. This can be as simple as a line and 2 stretched out circles, one horizontally and the other vertically. Feel free to add more shape and detail.

Importing Into After Effects

Start a new After Effects project, and import your lip flaps and the audio you want to create lip sync for.

Create a new composition and drag all of these assets into your timeline.

Convert Audio To Keyframes

We have one last thing to do before we can start writing our expression.

Right click on your audio layer, and select Keyframe Assistant > Convert Audio To Keyframes. This will create a new layer called Audio Amplitude. You'll see this layer comes with 3 sliders: Left Channel, Right Channel, and Both Channels. We only need the Both Channels effect, so feel free to delete the other 2. If you open up the effect, you will see that there is a new keyframe for every frame of the composition.

Creating The Expression

Now the fun bit! Writing the expression. It's important to understand what we need to tell After Effects, in order to know how we write our code.

Essentially, we want to work out the range of our audio, from lowest point to highest. We can then use this range to control the opacity of our lip flaps. When the audio is mute, the closed mouth option should be visible. If the audio is in the first half of the audio range, the horizontal mouth option should be visible. And if the audio is in the second half of the audio range, the vertical mouth option should be visible. This will give the illusion of a lip sync.

Working Out The Audio Range

An easy way to work out the range of our audio is to do a quick check. We can run our cursor through our timeline and check the value of all the keyframes in the Both Channels slider manually. However if your audio track is long, or you're working at a high framerate, you can easily miss values. So it would be better in this circumstance if we got After Effects to do the checking for us.

We can do this using some for loops from within the opacity parameter of all of our lip flap layers:

audio = thisComp.layer("Audio Amplitude").effect("Both Channels")("Slider");

maxV = 0;
minV = 0;
for (i = 1; i<=audio.numKeys; i++){
    maxV = Math.max(maxV, audio.key(i).value);
    minV = Math.min(minV, audio.key(i).value);
    };

First, we reference the Both Channels slider. Then, create a variable to store your max and min values in: maxV and minV.

The arguments in our for loop are set to i = 1; i<=audio.numKeys; i++. This creates the variable i for our loop, and uses it to check every keyframe on the Both Channels slider. The loop then stops when it reaches the last keyframe.

Let's start with the maxV value. While looping, the for loop checks maxV. It uses the Math.max() function to compare our current maxV value to the current keyframe value. If the keyframe value is bigger than maxV, it updates maxV to be that value.

We then do the same to work out our minimum value, using Math.min() on the next line in the loop. In most cases this value will be 0, but running this line can account for background noise, or negative values in the audio track.

Final `if` Statements

We now have the values we need to work out our audio range. In order to return the correct opacity value, we need to provide an if statement for our 3 lip flap layers.

First, the statement for our closed mouth layer:

if (audio < .1) 100
    else 0

Here, I have specified that if the value of the audio variable is under 0.1 the audio of this comp should be considered mute. Therefore the closed mouth opacity is set to 100. If the variable's value is higher than 0.1, the opacity will be set to 0. Because our final if statement for this layer doesn't require working out the audio range, the for loops can be deleted from this layer to help with the project's efficiency. Make sure to substitute 0.1 for a value which makes sense for your project, if necessary.

Next, our vertical mouth layer:

if (audio < (maxV - minV)/2) 0
    else 100

This layer will only be visible in the top range of our audio. If the audio variable is less than half of our audio range, this layer's opacity will be set to 0. This accounts for when our audio is mute, and in its first half of the audio range. However, when the audio variable is equal to or higher than half of our audio range, the opacity is set to 100.

Lastly, our horizontal mouth layer:

if (audio < .1) 0
    else
        if (audio < (maxV - minV)/2) 100
    else 0

The horizontal mouth layer needs to account for when the vertical mouth layer and the closed mouth layer is on. Therefore, the if statement needs to check for both of these possibilities. Combining our last 2 if statements into 1 achieves this, making sure we set the correct argument to 100. Since we want the layer to be visible in the first half of our audio range, we want to set the argument if (audio < (maxV - minV)/2) to 100, and all others to 0.

Accounting For Audio Peaks

You might at this point there is less variation in the horizontal and vertical mouth flaps than you would like. This may mean there are points in the Both Channels slider which are skewing the range, since we take the maximum and minimum values of the entire audio track. Because of this, we might want to finesse the scale a little bit to account for peaks.

I did this by adding a slider to my expression. I made a null layer and added the slider there, then named it Max Value Adjust. I made a variable to store the slider in both the horizontal and vertical mouth layers:

endV = thisComp.layer("SLIDERS").effect("Max Value Adjust")("Slider");

And added it to their if statements like so:
Horizontal if statement

if (audio < .1) 0
    else
        if (audio < ((maxV + endV) - minV)/2) 100
    else 0

Vertical if statement

if (audio < ((maxV + endV) - minV)/2) 0
    else 100

Now the slider is in place, it can be used to adjust the maxV of our audio range. You can do it by eye, dragging the slider into minus values until you're happy with the look of your lip flaps.

You can also follow the same process to add a slider to the minV value of the audio range, if you need that flexibility. To do this, create another slider and add it to the if statements of your closed mouth and horizontal mouth layers:

Closed Mouth If Statement

if (audio < .1 + startV) 100
    else 0

Horizontal If Statement

if (audio < .1 + startV) 0
    else
        if (audio < ((maxV + endV) - minV)/2) 100
    else 0

Final Step

Now, you should have your lip flaps moving in time to your audio. However, you may find that there are some flash frames, given that the Both Channels slider has a keyframe on every frame of the composition. To mitigate this, create an adjustment layer and add the Posterize Time effect to it. Set the value to half of your composition's frame rate to start. Then, if you still feel there is some flashing, gradually take the number down until you're happy with the rate the lip flaps change. In my composition set to 25fps, I tend to set Posterize Time to 10.

And that's it! Generated, simple lip sync for when you need to spend your time elsewhere in your project.

Please leave a comment if you have any questions, or know of a more efficient way of achieving this.

DEV Community: Kat

Scripting: Creating Windows For Your After Effects Scripts

Introduction

Windows

Groups

Panels

Text

Buttons

Options

Example

Conclusion

After Effects: The Modulo Operator (%)

Introduction

Looping Expressions

Example: Digital Clock

Example: Analog Clock

Conclusion

Scripting: After Effects Projects and Compositions

Introduction

Application

Project

Folders And Compositions

Example

Quick Tips

Conclusion

Scripting: Beginner's Guide To Creating After Effects Scripts

Introduction

Why Scripts?

Extendscript Toolkit

Conclusion

After Effects: The Essential Graphics Panel

Contents

Introduction

Setting Up Your Precomps

Adding To Your Essential Graphics Panel

Adding A Dropdown Menu

Advanced Text Options

Changing Fill Options

Limitations

Other Ideas

Conclusion

After Effects: While Loops

Contents

Introduction

while Loops Vs if Statements

while Loops Vs for Loops

When To Use while Loops

Conclusion

Project: Random Number Generator But Excluding The Previous Entry

Introduction

random()

Creating An Array

while Loop

Applying It To Things Other Than Numbers

Conclusion

Project: Spreadsheet To Video, Kinetic Text

Contents

Introduction

Initial Testing With Arrays

Setting Up My Spreadsheet

Using Data From The .CSV File

Adding Line Breaks

Aligning The Text

Text Size

Using The Essential Graphics Panel To Control Formatting Options

Animation: Opacity

Animation: Position

Animation: Scale

Animation: Other Ideas

Limitations

Conclusion And Learnings

After Effects: Text Animation And The Expression Selector

Introduction

Using The Range Selector

Using The Expression Selector

Advanced Techniques

Conclusion

After Effects: For Loops

Introduction

What Are for Loops?

`while` Loops Vs `if` Statements

`while` Loops Vs `for` Loops

When To Use `while` Loops

`random()`

`while` Loop

What Are `for` Loops?

Example Of `for` Loop In Action

Using `for` Loops With `time`

Basic `if` Statements

Nesting `if` Statements

Final `if` Statements