Chapter 13: Variables

Variables enable dynamic, personalized content in your video templates. Use variables to create templates that can be customized for different audiences, products, or contexts.

What Are Variables?

Variables are placeholders in your content that get replaced with actual values when the video is rendered:

Hello {firstName}!
Your order #{orderNumber} is ready for pickup.

Becomes:

Hello Sarah!
Your order #12345 is ready for pickup.

Variable Syntax

Variables use curly brace syntax:

{variableName}

Naming Rules

• Start with a letter or underscore
• Contain only letters, numbers, underscores, and hyphens
• Case-sensitive ({Name} ≠ {name})
• No spaces inside braces

Hyphens are supported mainly for templates imported from the classic editor, which names variables like {first-name}. For new templates, camelCase ({firstName}) reads better and matches the rest of the documentation.

Valid Examples

{firstName}
{product_name}
{Order123}
{_private}
{first-name}    // Classic-editor style

Invalid Examples

{first name}    // No spaces
{123start}      // Can't start with number
{-leading}      // Can't start with a hyphen

Transforming a Value

A placeholder can change how it shows a value without changing the variable itself. Add one or more transforms after the name, separated by |:

{firstName|upper}
{firstName|title}
{firstName|substr(0,1)|upper|possessive}

Transform	What it does	firstName = “ada lOVELACE”
upper	All capitals	ADA LOVELACE
lower	All lowercase	ada lovelace
title	Capitalizes every word, lowercases the rest	Ada Lovelace
substr(start,length)	Part of the value, counting from 0; leave out length to keep the rest (substr(4))	substr(0,3) → ada
possessive	Adds 's, or just ' when the value already ends in s	ada lOVELACE's, and “James” → James'

Transforms apply left to right, so {firstName|substr(0,1)|upper|possessive} takes the first letter, capitalizes it and adds the possessive: A's.

A transform belongs to that one placeholder. Hi {firstName|title}, {firstName} shows the capitalized and the raw value side by side, and the Variables panel still lists a single firstName variable that takes the same untransformed data. The panel shows every transformed form in use beneath the value, so you can check what each will render as.

The canvas preview (with Show values on) and the rendered video apply the transforms identically. Only the transforms above exist: {name|shout} is not a placeholder and stays literal text. The start of substr must be 0 or greater.

Transforms work wherever placeholders work: text, lists and tables, media and sound paths, and TTS text.

Where Variables Work

Variables can be used in:

Location	Example
Text elements	Hello {name}!
Voiceover transcript	Welcome, {company}...
Image, video and audio paths	logos/{brand}.png
Image backgrounds and layout media	backgrounds/{season}.jpg
Pattern sound URLs	audio/{language}/intro.mp3
Subtitle paths	subs/intro-{language}.vtt
TTS text	Your code is {code}
Conditions (scenes and layers)	Show only when {tier} equals gold

Variables used inside imported scene layers show up in the panel as well, under the scene that holds the layer.

Using Variables in Text

Adding a Variable

1. Double-click a text element to edit
2. Type the variable with braces: {variableName}
3. Click outside to confirm
4. The variable appears with braces in the editor

In Preview

During preview, variables show their set values:

• If value is set: Shows the value
• If no value: Shows the variable name

The Variables Panel

Access the Variables panel to manage all variables:

1. Click Variables in the top toolbar
2. The panel shows all detected variables
3. Set default values for each variable
4. See where each variable is used

Variable List

The panel displays:

• Variable name
• Current default value
• The transformed forms in use (for example |title → Ada Lovelace)
• Usage count and locations
• Edit/delete controls

Setting Default Values

1. Find the variable in the list
2. Click the value field
3. Enter a default value
4. Press Enter or click outside

Default values are used in preview and when no override is provided.

Variable Usages

FX Express tracks where each variable is used:

Text Usages

Shows which scenes and elements contain the variable:

• Scene number
• Element type
• Click to navigate to usage

Voiceover Usages

Shows timestamp in the voiceover:

• Time position (e.g., “1:23”)
• Click to jump to that point

Creating Variables

Variables are auto-detected when you type them:

1. Type {newVariable} in any text element
2. The variable automatically appears in the Variables panel
3. Set its default value

You can also pre-create variables:

1. Open Variables panel
2. Click “Add Variable”
3. Enter name and default value

Common Variable Patterns

Personalization

Hi {firstName}!
Welcome back, {username}.
Dear {customerName},

Product Information

{productName}
${price}
{description}
SKU: {sku}

Dynamic Data

Date: {currentDate}
Time: {appointmentTime}
Location: {venue}

Conditional Content

Combined with Optional scenes:

Scene shows only if {hasCoupon} is "true"
Coupon code: {couponCode}

Variable Best Practices

Naming Conventions

• Use descriptive names: {customerFirstName} not {n}
• Be consistent: {productName} everywhere, not mixed with {product_name}
• Use camelCase or snake_case consistently

Default Values

• Set realistic defaults for preview
• Use typical-length text to test layout
• Consider longest expected values

Documentation

• Keep a list of variables and their purposes
• Note expected formats (dates, currency)
• Document any required vs optional variables

Testing

• Preview with different value lengths
• Test empty values (if possible)
• Verify all variables have values before export

Variable Workflow

Template Creation

1. Design with placeholder text
2. Replace placeholders with variables
3. Set default values for preview
4. Test with various value lengths

Template Usage

1. Load the template
2. Provide variable values via API or interface
3. Render with actual data
4. Each render can have different values

Variables and Scene Modes

Variables work with conditional scenes:

Optional Scenes

Show scene only when condition is met:

Variable: {showPromo}
Condition: equals "true"
Scene appears only when {showPromo} = "true"

Choice Scenes

Select variant based on variable value:

Variable: {language}
Variants: en, es, fr
Scene shows matching language variant

If the value is empty or matches no variant, the choice scene is skipped: nothing plays for it, even if a variant is marked Default (that only affects what the editor shows). See Chapter 25 for what happens to transitions around a skipped scene.

Values and Pre-encoding

When you publish, the render service can prepare scenes in advance (pre-encode them) so viewers get their video faster. It can only do that for scenes whose variables take a known, small set of values — a choice between three offers, say, or one of five languages. A scene showing a viewer’s name can’t be prepared: there is no list of every name. It renders live, which is just as correct, only slower to start.

FX Express works out what it can on its own, and you can tell it the rest.

Telling FX Express a variable’s values

Open a variable from the Variables panel. Under Values, choose:

Option	Use it for
Auto	The default. Shows what FX Express worked out itself — see below
List	A variable with a known set of values: tiers, product codes, regions. Type values one at a time (Enter adds one), or click Paste list and paste one per line or comma separated — long lists are fine, but see the budget below
Free text	Anything goes: names, greetings, dates. Scenes using it are always rendered live

Auto already knows:

• the variant values of a choice scene;
• the values your scene and layer conditions test for (equals, not equals, in set);
• the file names an image, video or sound path picks from, when the files sit beside the template: logos/{brand}.png with logos/acme.png and logos/globex.png in the folder gives acme and globex. A path that is nothing but a variable ({logo}) isn’t guessed.

Anything Auto can’t work out is treated as free text.

Values are matched exactly, capital letters and spaces included: list them the way the data you render with spells them. A list never restricts what a render may use — a value that isn’t on it just renders live.

The Known values under the Value field fill it in with one click; Save to preview with it (with Show values on).

What gets prepared

At the bottom of the Variables panel, Pre-encoding shows how many scenes can be prepared in advance. Open it to see each scene:

Mark	Meaning
✓	Prepared in advance (once, if it uses no variables; otherwise once per combination of values)
~	More combinations than the budget; the render service may still prepare it in parts
–	Rendered live, with the reason: a free-text variable, spoken text or live content, a variable with more values than the budget, or a scene that only plays with values nobody listed (a “not equals” scene — list the values it plays with)

Click a scene to go to it, or a variable to open its values.

The budget (10 unless you change it, up to 250) is the most combinations prepared per scene. A scene using two variables with four values each needs 16. A higher budget prepares more but costs more background work on every publish (publishing itself doesn’t take longer).

The movie’s background sound and voiceover are prepared like a scene, once per combination of the variables they use; Pre-encoding shows them as Movie audio when they use any. If a render’s scenes add up to a different length than a prepared version, that render’s sound is made live instead.

Scenes from an imported scene keep the value lists their original template had.

File ▸ Optimize for Rendering (Chapter 26) shows the same verdict for every scene beside what pre-composing would add, and lets you set a variable’s values from there.

Troubleshooting

Variable Not Replacing

• Check spelling exactly matches
• Verify braces are correct { and }
• Ensure variable has a value set
• Check for extra spaces inside braces

Variable Not Detected

• Must use exact syntax: {name}
• No spaces: { name } won’t work
• Check for invisible characters
• Re-type the variable

Wrong Value Showing

• Check default value in Variables panel
• Verify no duplicate variable names
• Check if override value is provided
• Check the placeholder’s transforms ({name|upper} shows the value in capitals)

Transform Not Applied

• Only upper, lower, title, substr(start,length) and possessive exist
• No spaces around |: {name | title} is literal text
• substr needs whole numbers, and the start must be 0 or greater

Variable Shows in Output

• Variable name appears = no value set
• Set a default value
• Or ensure value is provided at render time

API Integration

When rendering videos programmatically, provide variable values:

{
  "variables": {
    "firstName": "Sarah",
    "orderNumber": "12345",
    "productName": "Widget Pro"
  }
}

Each render can have different values, enabling:

• Personalized videos at scale
• Dynamic content based on data
• Localized versions from one template

---

← Previous: Animations and Keyframes | Next: Smart Objects →