Using Shell Scripts
You can register script files or commands to listen for specific events that are broadcast by Templater. You can do this through the Templater Preferences dialog or the templater-options.json file if using the command line interface. Follow the steps under Registering shell scripts within the Templater Preferences dialog or Register shell scripts within the CLI options file.
Sample shell scripts are available at Dataclay's code repository on GitHub.
WARNING Breaking Changes
As of Templater 2.7 the “For all commands, use job details as arguments” preference is deprecated. If your application makes use of the deprecated preference, your registered event scripts will fail. You must explicitly append arguments to shell scripts if they are necessary. Verify that you are explicitly passing arguments to your scripts, especially if you are using Templater’s 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.
WARNING MacOS Mojave 10.14 or later
MacOS has implemented security changes as of Mojave 10.14 to prevent unauthorized programs from running. This can interfere with running event shell scripts via Terminal. You may receive a Operation not permitted error message. If you receive this message when running an event script, you can try the following to resolve the issue: Pull down the Apple menu and choose ‘System Preferences’; Choose “Security & Privacy” control panel; select the “Privacy” tab, then from the left-side menu select “Full Disk Access”; Click the lock icon in the lower left corner of the preference panel and authenticate with an admin level login; Click the [+] plus button to add an application with full disk access; Navigate to the /Applications/Utilities/ folder and choose “Terminal” to grant Terminal with Full Disk Access privileges. (via OSXDaily)
View image
NOTE The following image shows the dialog from Templater 3.4.0 and later. If you have an earlier version, your dialog will look different.
- In the Templater preferences dialog, in the Bot Settings group, click Setup Shell Commands.
-
Select a Templater event group to show available events associated with that group.
NOTE The Footage Processing and Footage Download event groups are only available in Templater 3.4 or later. Earlier versions have the Footage Retrieval event group instead.
- Select a checkbox to specify whether your script should run Before or After the chosen event. If the checkbox is cleared, the script is disabled. Once disabled, a script written directly in this dialog cannot be edited (see the next step).
- In the text box below the checkbox, do one of the following:
-
If arguments must be passed to the script, do one or more of the following:
- Explicit values: Enter each value, separated by spaces, after the path or command within the event field. The following example shows how you would pass Integer
512 and String 08-24-2018 values as arguments to the registered Windows Batch script timestamp.bat.
C:\Users\dev\event-scripts\timestamp.bat 512 '08-24-2018'
- Pre-existing information: Select an option from the Append drop-down, then click Append. Templater will append the selected argument macro to the contents within the event field. The following example illustrates appending three arguments to the registered NodeJS script update-job.js: (1)
$aep — the path to the currently processed After Effects project file, (2) $data_uri — the full URL or absolute path to the connected data source, and (3) $now — a timestamp derived from the host machine's internal clock.
node C:\Users\dev\event-scripts\update-job.js $aep $data_uri $now
- Values from the connected data source: Prefix column names or property keys with the
$ symbol to create custom macros. Then append those macros to the script path or full command within the event field. The following example illustrates passing the values of the album-name and release-date columns from a connected data source to the registered Windows Batch script setup-folder.bat.
C:\Users\dev\event-scripts\setup-folder.bat $album-name $release-date
- Select the Asynchronous checkbox if the script must execute as a detached process.
TIP By default, Templater executes registered commands and scripts synchronously. This causes After Effects to wait until the script finishes executing.
- To add shell scripts for other Templater events, repeat steps 2 through 6.
- When you are finished adding script information, click OK to register the scripts.
WARNING If Templater sends compositions to Adobe Media Encoder (AME) for rendering, shell scripts are executed after the target composition is versioned in AE, not after AME finishes rendering.
- In the templater-options.json file, in the
bot object, set the specific event property to the absolute path of the file you want to run for that particular event. Alternatively, you can input any command as you would if you were in a terminal session, although this is not recommended for complex scripts.
Refer to the following table for events that you can register a shell script to in the bot object. For detailed descriptions of each event, see Templater Events.
| "pre_cmd_data" |
Before data |
...before data is retrieved |
| "post_cmd_data" |
After data |
...after data is retrieved |
| "pre_cmd_batch" |
Before batch |
...before main iteration loop starts |
| "post_cmd_batch" |
After batch |
...after main iteration loop completes
|
| "pre_cmd_job" |
Before job |
...before job processing starts |
| "post_cmd_job" |
After job |
...after job processing completes |
| "pre_cmd_udpate" |
Before update |
...before layer updating starts |
| "post_cmd_update" |
After update |
...after layer updating completes |
| "pre_cmd_output" |
Before output |
...before rendering process starts |
| "post_cmd_output" |
After output |
...after rendering process completes |
| "enable_cmd" |
Bot enabled |
...when Bot is enabled |
| "shutdown_cmd" |
Bot disabled |
...when Bot is disabled
|
- If the registered command or script must execute asynchronously as its own detached process, set the appropriate asynchronous property key in the
bot object to true.TIP By default, Templater executes registered commands and scripts synchronously which causes After Effects to wait until the script is done executing.
Refer to the following table for determining which asynchronous property to set for the event that the script is registered to:
| "pre_cmd_data_async" |
Before data |
| "post_cmd_data_async" |
After data |
| "pre_cmd_batch_async" |
Before batch |
| "post_cmd_batch_async" |
After batch |
| "pre_cmd_job_async" |
Before job |
| "post_cmd_job_async" |
After job |
| "pre_cmd_udpate_async" |
Before update |
| "post_cmd_update_async" |
After update |
| "pre_cmd_output_async" |
Before output |
| "post_cmd_output_async" |
After output |
| "enable_cmd_async" |
Bot enabled |
| "shutdown_cmd_async" |
Bot disabled |
- To pass arguments to registered shell scripts in the templater-options.json file, do one or more of the following.
- For passing explicit values, append each value, separated by spaces, to the script's absolute path or full command. The following example shows how you would pass Integer
512 and String 08-24-2018 as arguments to the registered Windows Batch script setup-folder.bat.NOTE On Microsoft Windows, in the templater-options.json file, the backslash character and other special characters must be escaped using am additional backslash.
{
"prefs" : {
"bot" : { "pre_cmd_data" : "C:\\Users\\dev\\event-scripts\\setup-folder.bat 512 '08-24-2018'" }
}
} - For passing pre-existing information to the script, refer to the table under Pre-defined argument macros and append the corresponding arguments to script's absolute path or full command. Appended argument macros should be separated with spaces. The following example shows how you would pass three pre-existing pieces of information as arguments to the registered NodeJS script update-job.js: (1)
$aep — the path to the currently processed After Effect project file, (2) $data_uri — the full URL or absolute path to Templater's connected data source, and (3) $now— a timestamp derived from the host machine's internal clock.
{
"prefs" : {
"bot" : { "post_cmd_job" : "node C:\\Users\\dev\\event-scripts\\update-job.js $aep $data_uri $now" }
}
} - For passing information from Templater's data source, enter a custom argument macro by prefixing a column name or property key with a $ symbol, and append that macro to the script's absolute path or full command. See Using job details to event scripts below for more information. The following example shows how you would pass the values of the album-name and release-date columns from Templater's connected spreadsheet to the registered Windows Batch script setup-folder.bat.
{
"prefs" : {
"bot" : { "post_cmd_job" : "node C:\\Users\\dev\\event-scripts\\update-job.js $aep $data_uri $now" }
}
}
