Using Job Details in Shell Scripts

You can pass versioning data to a registered shell script by making use of argument macros. An argument macro is essentially a word, prefixed with a $ symbol that is substituted by another string of text when Templater broadcasts an event. Templater ships with a predefined set of argument macros, but you can also create your own custom macros.

NOTE  You can only use arguments to pass job-specific data after that data is read from your data source; in other words, once the After Data Event has been broadcast.

For example, consider that C:\compress.bat is registered with Templater's "After Job" event, and that Templater processed a job with the following versioning data.

[
  {
	"ID": "json_target",
	"title": "Create Targeted Video Ads",
	"caption-1": "Deliver sets of renders",
	"caption-2": "for agencies",
	"album-cover": "yes-oceans.jpg",
	"disc-face": "discs/yes-oceans.png",
	"tint": "2D3A1D"
  }
]

In this case, you can register the following command with Templater's "After Job" event to send the title property value, Create Targeted Video Ads, to the Batch file as an argument in the following manner.

C:\dev\compress.bat $title

You can also use as many argument macros as needed.

C:\dev\compress.bat $title $caption-1 $caption-2 $tint

Additionally, you can use predefined argument macros to pass information about a processed job. For example, if your script needs the path to the output file that After Effects rendered, the job's id, and the path to the processed After Effects file, you can use the following:

C:\dev\compress.bat $id $out_file $aep

You can register any command line incantation as if you were entering it in a terminal session.

node C:\dev\concatenate.js $aep $out_dir $id $title

In the above example, concatenate.js will be executed via the node interpreter when Templater's "After Batch" event is broadcast, and it will have access to the values of the argument macros.

Pre-defined argument macros

Templater ships with a number of pre-defined argument macros that you can pass as arguments into your registered shell scripts. The following table lists available argument macros for shell scripts.

NOTE  Some argument macros are not available to scripts registered to specific events and might cause Templater to error. For example, if you pass the $id argument macro into a script registered to the "Before Data" event Templater will log an error

The following tables show variables that can be used as arguments for your event scripts or commands.

Pre-defined argument macros available in Templater 2.7 and later

Argument Macro Expands to
$log Path to the templater.log file
$log_dir Path to where the templater.log file exists
$aep Path to the processed template file
$aep_dir Path to where the processed template file exists
$sources Path to the footage source directory
$out_dir Path to the output directory
$data_uri Path or URL to the versioning data
$data_start Start index used in data retrieval
$data_end End index used in data retrieval
$data_batch Path to a JSON file with versioning data for the batch process
$data_job Path to a JSON file with versioning data for the job process
$spot.label The path to the still image export of the spot check named according to label
$spot[n] The path to the still image export of a spot check where "n" refers to the spotcheck's ordinal position.
$id Value of the 'id' column or property for the job
$idx Ordinal position of the job within the batch
$out_name Name of the job's output
$out_file Path to the job's output file
$bot_name Name of the Bot
$machine_name Name of the host machine
$user_name Name of the user running After Effects
$now Current time as on the machine's clock
$event String identifier of the most recently broadcast event

Pre-defined argument macros available in Templater 3.4 and later

These arguments are associated with the Footage Download and Footage Processing events introduced in Templater 3.4.

This example is of a relatively small Templater project. However, it can help you understand the processing power and time impacts if you plan a larger scale project that includes custom scripting both before and after these new events.

Dorian is working on a comp that incorporates many assets, including these 10 footage assets:

  • Five assets downloaded from a remote source. He has configured Templater for unique downloads.
  • Three assets on his local machine
  • Two assets that are other comps in After Effects

For each version of his comp, the Footage Download event will fire 5 times. The Footage Processing event will fire 10 times. If Dorian writes scripts to run both before and after Footage Download, the scripts will be called 10 times. Likewise, if he writes scripts to run both before and after Footage Processing, those scripts will run 20 times.

Key facts about Footage Events

Footage Download:

  • Fires for every download of remote footage references
  • Fires for remote references that are cached locally
  • Argument macros begin with $dl

Footage Processing:

  • Fires for all footage assets in your comp
  • Arguments begin with $ftg
  • Are available for local and remote footage
Argument Macro Expands to When available
$dl_file_uri Path or URL to the location of the footage for download. Before footage download event.
$dl_file_name Name Templater assigns to the downloaded file (minus the file extension). Before footage download event.
$dl_file_dir Directory to which the downloaded footage will be saved. Before footage download event.
$dl_file_mime MIME type of the downloaded file. After footage download event.
$dl_file_ext Extension Templater assigned to the file. After footage download event.
$dl_file Complete path to the downloaded file, including file name with extension. After footage download event.
$ftg_layer Name of the layer into which the footage will be injected. Before footage processing event.
$ftg_name Name of the footage file. Before footage processing event.
$ftg_file Complete file path for the source footage file. If the footage is itself an AE comp, this value is shown as undefined. Before footage processing event.
$ftg_dir Complete file path for the footage asset. If the footage is itself an AE comp, this value is shown as undefined. Before footage processing event.
$ftg_ext Extension Templater has assigned to the footage asset file. If the footage is itself an AE comp, this value is shown as undefined. Before footage processing event.

Accessing argument values within shell scripts

When passing arguments to your registered scripts, your code will need to access their values. The way you access an argument's value within a script depends on the language you are coding in. In general, however, you always use the ordinal position of the argument to access its value in the script it is passed to.

ClosedAccessing arguments in Bash on macOS

Assume the following is registered to an event in Templater:

/Users/me/Dev/upload.sh $aep $data_uri $now $out_file

To access the any of the argument values within the upload.sh script, use the ordinal position of the argument like with a $ sign like so:

ae_project_file="$1"
templater_data_source="$2"
current_timestamp="$3"
templater_output="$4"

If you have more than nine arguments in a Bash script, you need to enclose its position number within braces like so:

tenth_arg_val="${10}"
eleventh_arg_val="${11}"
twelfth_arg_val="${12}"

ClosedAccessing argument values in Batch Script on Windows

Assume the following is registered to an event in Templater:

C:\Users\me\Dev\upload.bat $aep $data_uri $now $out_file

To access any of the argument values within the upload.bat script, use the ordinal position of the argument like so:

ae_project_file=%1
templater_data_source=%2
current_timestamp=%3
templater_output=%4

TIP If you have more than nine arguments passed to a Batch script, it becomes more involved to access them. Refer to this documentation on the topic of passing arguments to Batch scripts. Using Batch scripts for complex scripting tasks is not recommended.

ClosedAccess argument value in NodeJS

Assume the following is registered to an event in Templater:

 node /Users/me/Dev/upload.js $aep $data_uri $now $out_file

To access any of the argument values within the upload.js script use the ordinal position of the argument plus two in the index of process.argv array like so:

var ae_project_file = process.argv[3],
    templater_data_source=process.argv[4],
    current_timestamp=process.argv[5],
    templater_output=process.argv[6]

TIP The reason you add 1 to the argument's ordinal position is that the process.argv array holds the term node in position 0 and the script name upload.js in position 1. Therefore, it's recommended to use the minimist pacakge in your own scripts to read arguments.

ClosedAccess argument values in PHP

Assume the following is registered to an even in Templater:

php C:\Users\me\Dev\upload.php $aep $data_uri $now $out_file

To access any of the argument values within the upload.php script use the ordinal position of the argument the index of the $argv array like so:

$ae_project_file = $argv[1]
$templater_data_source = $argv[2]
$current_timestamp = $argv[3]
$templater_output = $argv[4]

Related Topics

Using ExtendScripts

Event Scripts

Templater Events

Using Shell Scripts

Troubleshooting Event Scripts