An event script is a small program that Templater runs for you at a specific moment in a render. You register it against an event such as “After Job,” and when Templater broadcasts that event, your script fires. You need one when the work you care about happens outside the After Effects project, like moving a file, compressing output, or telling another system that a video is done.
You may never need to write one. If your job is to rig a template, point it at data and collect the videos, the product already does that. Event scripts matter at the edges. They matter when a finished render has to land somewhere, when something has to be checked before a batch starts, or when a layer needs a tweak that no setting offers. This article explains what the events are, the two kinds of script you can hook to them, how to decide whether you need one, and what to check when a script does not run.
What an event is, and what a script does with it
Templater re-versions your After Effects project in a loop. For each row of data it updates the layers, brings in footage, and renders. As of version 3.4, Templater broadcasts an event at each stage of that loop. Our documentation puts it this way. You can treat those events as an opportunity to run your own scripts wherever it makes sense within the re-versioning process.
A script, in our definition, is a file of commands in a programming language that a computer can run. An event script is one that runs when Templater broadcasts an event. These scripts hook into Templater’s processes and extend what it can automate. Nothing about the hook is magic. Templater reaches a stage, announces it, and runs whatever you registered for that announcement.
There are two types, and the difference is what each one can touch.
Shell scripts work with the world around the project. They interact with assets such as files, and they do things like moving or transferring files, sending notifications, updating databases, transcoding output files and sending emails. You can write a shell script in any language available in your system’s environment.
ExtendScripts work inside the project. They interact with objects in the After Effects file, such as project assets, compositions, layers, keyframes and effect parameters. You must write them in the ExtendScript language, using its toolkit along with the Templater ExtendScript API.
You can register both on the same event. When you do, the shell script always runs first, and then the ExtendScript. That ordering is documented and it is useful, because a shell script can prepare a file that the ExtendScript then expects to find.
A requirement that catches people
Event scripts are only supported in Templater Bot. Templater Bot must be installed and activated for them to work. If you are running Pro and you register a script, do not expect it to fire. Our licensing guide is the place to check which edition fits your work.
The events, in the order Templater broadcasts them
The documentation groups the events into four parts. Reading them in order is the fastest way to decide where a script of yours belongs.
Part one is task invocation. You start the process by invoking one of Templater’s three main tasks, which are Preview, Render or Replicate. This part has no script event of its own. It is the trigger that starts the others.
Part two is data retrieval. The Before Data event is the first one Templater broadcasts. It fires as soon as any of the three tasks is invoked, and it also fires immediately before the Bot queries the data source for ready data. The After Data event fires once Templater finishes retrieving data from any type of data source. Scripts registered here can immediately access or manipulate the data held in Templater’s internal memory. That makes After Data the place to adjust or check data before any job uses it.
Part three is the batch process. Before Batch fires immediately before Templater starts its main loop, and it fires even if the batch is only one job. After Batch fires once the loop has finished. Scripts here can work on all of the output the loop produced. Our documentation gives one example: a script that stitches every output file into a single video file.
Inside the batch, each job has its own events. Before Job fires just before Templater begins one job. After Job fires just after Templater finishes one job, and a job counts as complete once output has been generated. Within a job there are smaller stages, each with a before and an after:
- Footage Download covers remote footage being downloaded for the update.
- Footage Processing covers AE or Templater processing local or remote footage.
- Update covers mapped data being injected into the layers of your compositions.
- Spot Check covers marked frames being loaded into the render queue and exported as still images.
- Output covers the rendering itself, from just before any output begins to just after it finishes.
Part four is Bot operation. There is an event when the Bot becomes enabled and another when it becomes disabled, both broadcast immediately after the change.
One detail is worth pointing out. The After Update event is the one our documentation recommends for ExtendScripts that change layers. Register your ExtendScript there if you want to manipulate layers after Templater has performed its layout and Time Sculpting logic. Registering there means your change comes after the layout work, not before it.
The order inside a single job
It helps to hold the sequence of one job in your head, because the order decides which event a script belongs on. In the order our documentation lists them, a job runs through Before Job, then the footage events, then the update events, then the spot check events if you use spot checks, then the output events, and finally After Job. The list puts the remote footage download before footage processing, the update after both, and output after the update. Each of those hand-offs has a before and an after event, so you can slot a script on either side.
That tells you where to look for the thing you want. A script that needs the rendered file belongs on After Output or After Job, because the file does not exist before then. A script that needs the data belongs on or after After Data. A script that changes a layer belongs on After Update, for the reason above. When a script seems to run too early, check whether the thing it needs exists yet at the event you picked.
Dataclay also keeps sample shell scripts and ExtendScripts in its code repository on GitHub, written to run on specific events. If you are starting from nothing, read one of those before you write your own. It is faster to change a working script than to build one from a blank file.
One scenario from start to finish
Take a batch of two hundred personalized videos for an email campaign. Each finished file has to be compressed, uploaded to a streaming provider, and the resulting link written somewhere a marketer can use it.
With no event scripts, a person does that after the render. With event scripts, the pieces line up with the events. A shell script on After Job runs once per finished video. It can call a command line tool to compress that one file, and it can upload the result. Our documentation names the kinds of destination: an FTP site, or a YouTube, Vimeo or JWPlatform account. A second shell script on After Batch runs once when all two hundred are done and sends a notification by email or text message so the person who started the batch knows. Documentation lists notifications explicitly as something a shell script can do.
Notice the split. Per-file work goes on a job event. Whole-batch work goes on a batch event. Choosing the wrong one is a design mistake to avoid. A script that sends a notification, registered on After Job, would send two hundred messages.
Our general guide to webhook callbacks from a render service covers a related pattern for telling another application that a render is done, and the article on getting automated video output into a CMS or DAM looks at where finished files end up.
Shell script or ExtendScript, and when you need neither
The documentation’s answer is short. Use shell scripts when you need to do something with Templater’s output, or when you want Templater to fit into an existing automated workflow. Use ExtendScripts when you want to extend Templater’s feature set to meet a business need or workflow goal.
Ask what the thing you want to change is. If it is a file, a folder, a database, a message or an upload, it is a shell script. If it is a layer, a keyframe or an effect parameter inside the project, it is an ExtendScript.
Information gets to each type in a different way. For shell scripts, you append arguments to the registered command. For ExtendScripts, you use the Templater ExtendScript API. Argument passing is its own topic, and the Templater help pages cover it under Using Job Details in Shell Scripts.
The change that broke older setups
One warning has a date on it. As of Templater 2.7, the preference called “For all commands, use job details as arguments” is deprecated. If your application relied on that preference, your registered event scripts will fail. You must now explicitly append arguments to any shell script that needs them. This matters most for people using the command line interface. In the templater-options.json file, you can no longer use the “job_detail_args” property inside the “bot” object within the “prefs” object. If you inherit an old setup and the scripts have stopped working after an upgrade, look here first.
Logging is yours to add
Shell scripts do not write to a log file by default. If you want a record, you add code that redirects standard output and standard error to a file you choose. In an ExtendScript, you call the $D.log() method in the Templater ExtendScript API, which writes messages and errors to Templater’s own log files, templater.log and templater.err. Decide on your logging before you put a script into a nightly job, because a script that fails silently on the five hundredth video is a bad thing to discover in the morning.
When to skip event scripts
Skip them if you are on Pro, since they are not supported there. Skip them if the whole job is rigging a template and collecting renders by hand. And think twice before using a script to patch a template problem that a layout rule or a data fix would solve more simply. A script is code that someone has to own. A setting in the template is not.
For the wider view of what Templater does without any scripting, start with the Templater page or our complete guide to automating After Effects from data.
When a script does not run
Our troubleshooting page has a method, and it works in order from the cheapest check to the most thorough.
Start by finding the exact command Templater used. Open the templater.log file and search for the phrases EVENT SCRIPT ERROR or EXEC SHELL SCRIPT. You can also search for the string you used as the first parameter of a $D.log.msg() call in an ExtendScript. Look for the log line that begins “Full command line.” Highlight only the full command line as Templater reports it and copy it.
Then open a new command line session, paste the line at the prompt and press Enter. Check whether the script does what you expect. This one step helps separate two kinds of problem. If the command fails in a plain terminal, the script or its arguments are the likely cause. If it works in the terminal and still fails inside Templater, check the script file permissions next.
Next, make the script talk. Inside the script file, write messages to a text file. The documentation gives examples for three languages. In a Bash script on macOS, you can append to a file named debug.txt on the desktop with printf. In a Windows Batch script, you do the same with echo and the USERPROFILE variable. In an ExtendScript, you write to Templater’s own log with $D.log.msg and a label such as EVENT SCRIPT DEBUG. After Templater finishes its tasks, open the file and see whether your message appears. If it does, the script ran. If it does not, check whether the script started at all.
Finally, check permissions. The script file must be executable by the user who is running After Effects. If that user lacks permission, an administrator should set it. On macOS, the example in our documentation is chmod u+x myPostJob.sh, which makes the file executable for the current user. On Windows, use the Security tab in the script file’s Properties dialog.
If your batch stops partway through and you are not sure why, our article on what happens when a Templater batch fails mid-queue covers the batch side of the question.
The bottom line
An event script is a hook. Templater announces a stage of the render, and your script runs. Shell scripts handle everything around the project, such as files, uploads, notifications and transcoding. ExtendScripts handle what is inside it. Both need Templater Bot. Put per-video work on a job event and whole-batch work on a batch event, give your scripts a way to log, and test the full command line in a terminal when something misbehaves.
If you have no reason to touch files or layers outside what Templater already does, you do not need one. If you do, it is the cleanest way to make a render fit the rest of your workflow.
A few of the questions we hear most often follow.
Frequently Asked Questions
These come up whenever someone registers their first script.
Can I use event scripts with Templater Pro?
No. Event scripts are only supported in Templater Bot, and Bot must be installed and activated for them to work. If you want scripts to move files, notify people or transcode output after each job, you need Bot.
What languages can I write event scripts in?
Shell scripts can be written in any language available in your system’s environment, such as Bash on macOS or Batch on Windows. ExtendScripts are different. You must write them in the ExtendScript language using its toolkit, along with the Templater ExtendScript API, because they run inside After Effects and work with the objects in the project.
What happens if I register both a shell script and an ExtendScript on one event?
Both run, and the registered shell script always executes before the ExtendScript. That order lets a shell script prepare something, such as a file or a folder, that the ExtendScript then uses. You do not need to choose one type for the whole project.
Which event should I use to change a layer after layout?
Use the After Update event with an ExtendScript. After Update fires right after Templater injects mapped data into the layers of your compositions. Our documentation says to register ExtendScripts there if you want to manipulate layers after Templater performs its layout and Time Sculpting logic. That keeps your change after the layout work.
Do event scripts write to a log file?
Shell scripts do not log to a file by default. Inside the script you can redirect standard output and standard error to a file you choose. ExtendScripts can call the $D.log() method in the Templater ExtendScript API to write messages and errors to Templater’s own log files, templater.log and templater.err. Searching templater.log for EVENT SCRIPT ERROR is the first step when something does not run.
My script worked before and fails after an upgrade. What changed?
Check the argument setup. As of Templater 2.7 the preference “For all commands, use job details as arguments” is deprecated, and scripts that depended on it fail. You must append arguments to your shell scripts explicitly. In templater-options.json you can no longer use the “job_detail_args” property inside the “bot” object within “prefs”. Add the arguments your script needs to the registered command itself.