The templater-options.json file is the whole control panel for Templater’s command line. It holds three kinds of settings: the root settings that say which project to open and where the data lives, a prefs group that mirrors the preferences dialog, and a tasks setting that says what to do. This page is a reference to what each part controls, what the defaults are, and which settings can cost you a batch if you leave them alone.
We wrote it so you can keep it open next to the file. It does not assume you have read any other page, though if you want the hands-on steps for launching a run, we have a separate explainer on command line rendering. The details below come from Dataclay’s own help pages for the command line, and where those pages disagree with each other, we say so instead of picking a winner.
How the file is organized
You write the file as JSON, a plain text format, and save it in the same directory as the After Effects project you want to version. If you have never written JSON, json.org shows how to format an object so Templater can read it. A mistake in the format is the first thing to rule out when a run does nothing.
The file has a flat set of root keys, then nested groups. The sample file in our docs follows this shape.
- Root keys: log_location, data_source, aep, source_footage, output_location, render_settings, output_module, output_prefix, row_start, row_end, save_on_completion, quit_on_completion, quit_on_errors and tasks.
- A prefs group holding single preference keys such as default_target and missing_footage.
- Groups inside prefs for remote_json, spot_checking, que and bot.
Two facts about versions matter before you copy anything. As of Templater 3.0, Dataclay’s GitHub repository holds different example options files for Templater 2 and Templater 3, and each has a different set of properties. The sample files are sorted by operating system and by Templater version. So start from the sample that matches the Templater you installed. Do not paste keys from a Templater 3 sample into a file that Templater 2 will read.
The second fact is about missing keys. If you leave out a required key or give a key an invalid value, Templater logs an error or a warning. Some keys have default values, which is why a short file can still run. We list the defaults below. A default is not a recommendation, though, and a few of them deserve a second look.
Paths need their own syntax. On Windows, write every backslash twice, so a path reads C:\\enter\\paths\\with\\double\\backslashes. On macOS, use a plain forward slash path. The reason is the JSON format. A single backslash starts an escape sequence inside a JSON string, so Windows paths written the usual way will not parse as you meant.
Before your first run
Things to do before running templater-options.json
- Start from the sample file that matches the Templater version you installed
- Write Windows paths with every backslash doubled (e.g. C:\\folder\\name)
- Set log_location on every file so you can read templater.log when a run fails
- Set placeholder_audio when missing_footage is 3
- Set save_on_completion and quit_on_completion, both are marked required
- Check the log folder after your first run to see what Templater reported
One last point on structure, and it is a rule the docs state flatly. Only one of the task keys can be true at a time. All the others must be false. We come back to this under the tasks section, where the docs describe the setting in two shapes.
Root keys, one by one
These are the keys the docs list for basic Templater operation. Every one of them is a string unless noted, and the documented default for the string keys is empty.
log_location. A path to a directory where Templater writes templater.out and templater.log. The docs say do not point it at a file. Give it a folder. Set it on every file you write, because the sample instructions tell you to make sure a logging location is specified. When a run fails, these files are where the explanation lives. templater.out is for programs that can examine a text buffer, and you can follow it live on macOS with tail -f templater.out. templater.log is the one to open in an ordinary text editor.
data_source. An absolute path to a TSV file, or a URL to a Google Sheets feed. The sample file also shows a QUE campaign URL as an option in the comment for this key. To get a Google Sheets feed URL, use the Google button in the Templater panel and open the Google Spreadsheet Setup dialog. The Feed URL shown there has the form of a sheets.googleapis.com address that includes the document key and the worksheet name. Copy it from the dialog and do not type it by hand.
aep. An absolute path to the project file Templater will version using the data source. The docs add that the project should have no missing dependencies and should not provoke any After Effects error or message dialogs when you open it through the interface. A dialog that needs a click is a job that stalls, because nobody is there to click it.
source_footage. An absolute path to where Templater imports source footage from. Footage that is not local to the machine is downloaded into a subfolder named TEMPLATER DOWNLOADS inside this path. Plan the disk space for that subfolder on the machine that runs the batch.
output_location. An absolute path where Templater outputs every render from the After Effects render queue. The note on this key is worth quoting in spirit. Avoid making a syncing folder the render destination. If you can, avoid Dropbox, Google Drive and similar services as output destinations. The docs give the advice without a reason, so the practical route is to render to a plain drive and copy afterward.
render_settings and output_module. Strings that must match the names in After Effects’ Render Settings Templates and Output Module Templates dialogs. Both keys are case sensitive. They are applied when Templater loads versioned compositions into the render queue.
output_prefix. A string added to the start of every output file name. It is useful for telling which files belong to which batch from inside a file explorer. A run on Monday and a run on Tuesday will be easy to separate if each uses a different prefix.
row_start and row_end. Integers. The defaults are 2 and 7. Row start is the first row of the data source to version and row end is the last. For Google Sheets and TSV files, row start must be greater than 1, since row 1 holds your headers. For JSON object arrays, it must be greater than 0. Row end must be greater than row start. Notice that the defaults describe a six row run, which is a sensible smoke test and the wrong size for a real batch. Change them on purpose.
save_on_completion and quit_on_completion. Booleans, both defaulting to false, and both marked required in the docs. Save on completion decides whether Templater saves the versioned project after its tasks finish. Quit on completion decides whether Templater quits after running its tasks. A scheduled job that should release the machine wants quit on completion set to true. A Bot that should keep watching wants it false. The tasks section explains why.
quit_on_errors. An array of Templater error codes. If Templater meets any code in the array, it force quits the task and After Effects. The default is empty. Codes come from the troubleshooting page. For example, code 1003 means a footage file could not be found on the network. Listing it makes the job stop at the first missing file instead of finishing with placeholders.
prefs and tasks. The prefs key is an object, and the tasks key is an array of strings, with a default of render. Both get their own sections below.
The prefs group: what each preference controls
The prefs keys mirror settings in the Templater preferences dialog. Defaults below are the ones the docs print. Our sample file sometimes shows a different value, because a sample is an example and a default is what you get when you leave the key out.
default_target. String, empty by default. The name of the composition to version and process for output. If you are choosing the target composition by name, set it here. We cover the reasoning behind target choice in our page on choosing the target composition.
fix_layer_exp. Boolean, false. Controls whether Templater fixes references in layer expressions when it replicates comps. The docs warn that on a complex project, setting it to true could slow versioning. So turn it on if your replicated comps have broken expression references and leave it off otherwise.
missing_footage. Integer, default 3. It decides how Templater handles a faulty footage reference in your spreadsheet. The values are 0 for ask me what to do, 1 for let me find the footage asset, 2 for skip the row, 3 for use my branded placeholder, and 4 for cancel the process. The numbers match the order of the choices in the Footage group of the preferences dialog. The docs say to avoid 0 and 1 to prevent interruptions, and the reason is plain. Both values ask a person a question, and an unattended machine has no person. Value 3 uses a branded placeholder that ships with the installer. For the full reasoning on this setting, see our page on missing and remote footage.
placeholder_visual and placeholder_audio. Absolute paths to a visual file and an audio file that Templater uses when it cannot import a footage reference. The audio key is required when missing_footage is 3. If your project maps audio layers to footage references in your spreadsheet, set the audio placeholder so the batch stays intact. The same goes for image and video layers and the visual placeholder. The sample file points both at files in a Dataclay folder under ProgramData.
missing_footage values
What each missing_footage value does
| Value | Action | Safe unattended? |
|---|---|---|
| 0 | Ask me what to do | No, asks a person |
| 1 | Let me find the footage asset | No, asks a person |
| 2 | Skip the row | Yes |
| 3 (default) | Use my branded placeholder | Yes, audio key required |
| 4 | Cancel the process | Yes |
empty_is_faulty. Boolean, true. When it is on, an empty cell or a null value mapped to a footage layer is treated as a faulty footage reference, which triggers whichever action missing_footage selects. In practice, a blank cell in a footage column gets the placeholder, or skips the row, depending on your other setting. Turn this off only if a blank cell should mean no footage and you have handled that in the template.
unique_downloads. Boolean, false. Controls whether Templater downloads cloud-based footage references to unique files. Turn it on to be sure every footage reference in the data source gets its own download.
replica_comps_to_ame and replica_comps_to_queue. Booleans, both false. The first saves a copy of the current project each time a target comp is versioned and replicated with data. Copies go to the output location, and you can add that folder as an Adobe Media Encoder watch folder so Media Encoder renders them. The second loads each replicated composition into the After Effects render queue. If this is your plan, our page on rendering a batch through Adobe Media Encoder goes through it step by step.
remove_templater_effects. Boolean, false. Removes the Templater Settings effects from all dynamic layers in a replicated project file when replica_comps_to_ame is true. The docs note a rename. In Templater 2 the property was called remove_replicas_ame, which is now deprecated, and Templater 3 renamed it. It can be used to render replicated projects with Media Encoder or with the command line aerender.
import_data_as_json. Boolean, false. Imports Templater’s job and batch data as JSON footage files in the Project panel. The docs label it experimental. If the structure of the imported JSON changes from job to job, After Effects raises an error dialog that needs someone to dismiss it. That is exactly the dialog an unattended run cannot survive, so test it carefully. Our page on using Templater data in expressions covers the warnings.
tsv_from_excel. Boolean, false. Says whether the TSV was exported from Microsoft Excel or Apple Numbers. If text layers show unexpected results, flip this setting and see whether it fixes the issue. Our sample file shows it true, so check which value matches how your file was exported.
suppress_ae_dialogs. Boolean, true. Suppresses notices, warnings and error dialogs from After Effects. The docs say to leave it alone unless you are troubleshooting, and they add that it only helps with problems inside the After Effects interface.
use_engine_layout and use_engine_time. Booleans, both true. The first lets Templater’s internal layout engine run. The second lets its Time Sculpting logic run. Set the layout key to false when you want to rely on expression-based layouts. Set the time key to false when you do not want the Time Sculpting rules to execute.
purge_caches. Boolean, false. Purges all caches after each job. The docs suggest turning it on if Templater consumes too much RAM over the course of a batch. In the sample file there is also a purge_footage key, shown as true. The key tables we have do not describe it, so we do not claim what it does.
silence_logging. Boolean, false. Silences all logging output. The docs say it should normally never be true, and that the one reason to use it is processing a large batch where skipping the logging speeds things up. Remember the cost. With logging silenced, you lose the files you would read to find out why a job failed.
Spot checks, remote JSON, QUE and the Bot
The rest of prefs is made of four groups.
spot_checking. Settings for exporting still frames from target compositions. The documented keys are spot_samples, on_render, on_replicate, render_settings and output_module. Spot samples is an integer, default 3, and it sets how many spot checks Templater renders when the target composition has no markers. On render and on replicate are booleans, both false, and they decide whether spot checks are exported during a render batch or a replicate batch. The render settings default is Best Settings and the output module default is Photoshop. The docs advise sequence output modules such as Photoshop, PNG, TIFF or JPG for single-frame markers, and video modules such as MOV or AVI for markers that have a duration. Spot checks themselves are covered in our page on preview modes and spot checks.
remote_json. Settings for a remote JSON data source that needs credentials. The keys are username, password and headers. Username and password are strings, empty by default, for a source secured with Basic Authentication. Headers is an object of any extra headers your server needs. You enter the header name as the key and the header content as the value, and Templater adds each one to the request it sends to a server that returns a properly formatted JSON object array. This file is plain text. Anything you put in the password field sits on disk in readable form, so keep the file out of shared folders and out of version control, and treat that as a general practice and not a documented rule.
que. Settings for the QUE integration. The sample shows two sub-groups. A job_filter group controls which campaign jobs Templater picks up, with keys for id, status, properties, creation dates, sort rank and direction, extra pages, page number and jobs per page. A satellite group holds an org key, an all-campaigns switch and an output naming setting. We list the keys from the sample and leave their defaults to Dataclay’s own QUE property keys page. To see how a QUE machine joins an account, read our page on QUE Satellites, and see the QUE page for the product.
bot. Settings for the Templater Bot, which map to the Bot Settings area of the Templater Preferences panel. The sample file shows a name, a Google Sheets check frequency and a JSON feed check frequency, a maximum queue size, three action switches for render, replicate and spot check, and a long list of command and script hooks. Those hooks come in pre and post forms for stages named data, batch, job, update, spot and output, plus enable and shutdown hooks. Each command hook has a matching async switch. One caution from the saved sample: one pre-stage async key appears spelled with a missing letter, so copy the sample for your Templater version from GitHub and compare it against the key list before you rely on a hook. Our page on the Bot settings that matter goes deeper.
The tasks setting
The tasks setting decides what Templater does when it launches. In the root key table it is an array of strings with a default of render. The possible values are render, replicate, bot_enable, spot_check, and four satellite tasks. Those are sat_register, sat_auth, sat_deauth and sat_remove. They register, authorize, deauthorize and remove the current machine as a QUE Satellite.
You can list more than one task, though the docs say a single task is the most common choice. Their examples of two at once are registering and authorizing a machine, written as sat_register then sat_auth, and de-authorizing and removing one, written as sat_deauth then sat_remove.
The task you pick changes how you launch. If you use bot_enable, the docs say to launch with the -ui switch, since enabling the Bot needs the After Effects interface, and to set quit_on_completion to false. A Bot that quits when its first pass ends is not monitoring anything. There is also no bot_disable value. The docs explain that you disable the Bot by clicking Disable Bot, or by force quitting the command prompt or terminal window you launched from.
If you want spot checks only, use spot_check by itself. If you want spot checks during a render or a replicate, keep render or replicate as the task and switch on on_render or on_replicate inside the spot_checking group. One wrinkle: the spot check command line page calls those two settings on_rendering and on_replication, while the preferences key table says on_render and on_replicate. Go with the names in the sample file for your version.
Here is the disagreement we promised to flag. The separate tasks page describes a group of true and false keys instead of an array: spot check, render, replicate, bot_enable, bot_deactivate and bot_activate. It says only one may be true and the rest must be false. That page also spells the first key spot_sheck in its table, which looks like a typo, and the other pages use spot_check. The last two keys are for reseller downloads only and were deprecated in Templater 2.6.0. The Templater 3 sample uses the array form. The docs also say the sample files differ between Templater 2 and 3. So treat the one-task rule as the part that holds in either shape, and take the exact shape from the sample file for your version.
Tasks setting shape
Array form vs. true/false form of tasks
- Format
- Array formList of string values
- True/false formOne key per task, boolean
- Multiple tasks
- Array formCan list several string values
- True/false formOnly one may be true; all others must be false
- Templater version
- Array formTemplater 3 sample uses this form
- True/false formDescribed on the separate tasks page
Treat the one-task rule as the part that holds in either shape, and take the exact shape from the sample file for your version.
A hypothetical file, and the bottom line
Suppose a producer wants a small test render of a weather template on a Mac. This is a labeled hypothetical, built from the keys above.
{
"log_location" : "/Users/shared/weather/logs"
, "data_source" : "/Users/shared/weather/forecast.tsv"
, "aep" : "/Users/shared/weather/FiveDay.aep"
, "source_footage" : "/Users/shared/weather/footage"
, "output_location" : "/Volumes/Renders/weather"
, "render_settings" : "Draft Settings"
, "output_module" : "High Quality"
, "output_prefix" : "test_"
, "row_start" : 2
, "row_end" : 4
, "save_on_completion" : false
, "quit_on_completion" : true
, "quit_on_errors" : [1003]
, "prefs" : {
"missing_footage" : 3
, "placeholder_visual" : "/Users/shared/weather/placeholder.png"
, "placeholder_audio" : "/Users/shared/weather/placeholder.wav"
, "empty_is_faulty" : true
}
, "tasks" : ["render"]
}
Each choice has a reason. Rows 2 to 4 render three rows, enough to see the pipeline work. The output goes to a plain volume and not a syncing folder. The error list stops the job on the first missing footage file, which is the right call when a test should fail loudly. The placeholders are set because value 3 needs the audio one. The task is a single render.
The bottom line is this. The file looks long, but a working run needs only the root keys, a log folder and a single task. Learn the root keys first. Learn missing_footage and its placeholders second, because they decide what happens when your data is imperfect. Leave the rest at their defaults until a specific problem tells you to touch them. And before you copy any sample, check its Templater version, because a file written for the wrong version is a quiet way to get a wrong result.
Getting a run working
Learn root keys first, then handle missing footage
-
Root keys firstLearn the root keys first.
-
Log folderSet log_location on every file you write; when a run fails, these files are where the explanation lives.
-
missing_footage and placeholdersLearn missing_footage and its placeholders second, because they decide what happens when your data is imperfect.
-
Check the sample versionBefore you copy any sample, check its Templater version, because a file written for the wrong version is a quiet way to get a wrong result.
-
Single taskThe simple case is one task.
That is the whole file. Here are specific questions a reader has when sitting down with it for the first time.
Frequently Asked Questions
Where does templater-options.json go?
Save it in the same directory as the After Effects project file you want to version. Our docs also show the launcher script in that folder, so the project, the options file and the launcher sit together. Create the file as plain JSON text named exactly templater-options.json. If you want a starting point, download a sample from Dataclay’s GitHub repository that matches your operating system and your Templater version.
Do I have to include every key in the file?
No. Some keys have default values, so a shorter file can run. Save on completion and quit on completion are marked as required keys, and the audio placeholder is required when missing_footage is 3. If you leave out a required key or give a key an invalid value, Templater logs an error or a warning, so check the log folder after your first run to see what it reported.
Can I set more than one task to true?
No for the true and false form. The tasks page says only one task key can be true and all others must be false. The array form can list several string values, and the docs give examples such as registering and authorizing a QUE Satellite together. The simple case is one task. If you are unsure which shape your version reads, download the sample file for your Templater version.
What does missing_footage value 3 do?
It tells Templater to use your branded placeholder when a footage reference in the spreadsheet is faulty. The default is 3. The other values are 0 to ask what to do, 1 to let you find the asset, 2 to skip the row and 4 to cancel the process. Values 0 and 1 ask a person, so avoid them on an unattended machine. Set placeholder_audio when you use 3, and placeholder_visual for image or video layers.
Why should the output folder not be a synced folder?
The docs say to avoid making a syncing folder the render destination and to avoid services such as Dropbox or Google Drive as output destinations when you can. Render to a plain drive and copy finished files afterward. The key involved is output_location, which holds the path where Templater outputs all renders from the After Effects render queue.
How do I write Windows paths in the file?
Write each backslash twice, so a path with three folder names carries six backslashes. On macOS, use ordinary forward slashes. The doubled backslashes are needed because JSON treats a single backslash as the start of an escape sequence. Applying this to every path key, including log_location, aep, source_footage, output_location and the placeholder paths, avoids a parsing mistake.
How do I turn on spot checks along with a render?
Keep render as the task and set on_render to true inside the spot_checking group. For a replicate run, keep replicate as the task and set on_replicate to true. For spot checks alone, make spot_check the only task. The spot_checking group also holds the sample count, with a default of 3 when the target composition has no markers, plus the render settings and output module used for the stills.
