Timeline Triggers and Expressions

Timeline triggers are Expression-based rules that start, pause, or stop a Timeline in response to show Variable values. A trigger fires when its Expression changes to a non-zero value. Use triggers for reactive, data-driven show logic without a Control Cue at a fixed time.

What Timeline Triggers Are

Each Timeline has three trigger Expressions:

Play Expression — fires when the Expression changes to true. The Timeline starts or resumes.
Pause Expression — fires when the Expression changes to true. The Timeline pauses at its current position.
Stop Expression — fires when the Expression changes to true. The Timeline stops.

Triggers are properties of the Timeline, not cues placed on it. They evaluate against the current values of show Variables. This differs from Control Cues, which fire at fixed points in time.

An empty trigger Expression has no effect. It does not change the Timeline's playback state.

How Expressions Work

A built-in engine parses and evaluates expressions at runtime. The rules:

Case-insensitive — expressions are lowercased before parsing. MyVariable, myvariable, and MYVARIABLE reference the same Variable.
Numeric result — every expression produces a number.
Truth rule — a result greater than 0 is true. A result of 0 or less, or an evaluation error, is false.
Unknown Variables resolve to 0 — a Variable name not defined in the show returns 0, which is false.

A misspelled Variable name resolves to 0 at runtime, so the trigger never fires. No runtime error appears. Use Expression validation to catch typos at edit time.

Expression Syntax

Expressions follow standard mathematical syntax. The supported operators are:

Operator	Description	Example
`+`	Addition	`a + b`
`-`	Subtraction	`a - 5`
	Multiplication	`a b`
`/`	Division	`a / 2`
`%`	Modulo (remainder)	`a % 2`
`^`	Exponentiation	`a ^ 2`
`()`	Grouping	`(a + b) * c`
`>`	Greater than	`score > 100`
`<`	Less than	`temperature < 0`
`==`	Equal to	`mode == 3`
`>=`	Greater than or equal	`level >= 50`
`<=`	Less than or equal	`count <= 10`
`!=`	Not equal	`state != 0`
`&&` or `and`	Logical AND	`a > 0 && b > 0`
`\`	\	or `or`	Logical OR	`a > 0 \`	\	b > 0

Comparison operators return 1.0 for true and 0.0 for false, which integrates naturally with the truth rule.

The && and || operators are value operators, not strict boolean operators. A && B returns A when A is 0, otherwise B. A || B returns A when A is non-zero, otherwise B. Under the truth rule (result > 0 is true), both behave as expected for AND and OR logic.

Functions and Constants

Expressions support these built-in functions and constants:

Function	Description
`abs(x)`	Absolute value
`min(a, b, ...)`	Smallest of the arguments
`max(a, b, ...)`	Largest of the arguments
`floor(x)`	Round down to a whole number
`ceil(x)`	Round up to a whole number
`round(x)`	Round to the nearest whole number
`log(x)` or `log(base, x)`	Logarithm (base 10 by default)
`sin(x)`, `cos(x)`, `tan(x)`	Trigonometry (argument in radians)
`pi()`	The constant π (3.14159...)
`e()`	Euler's number (2.71828...)

Function names are case-insensitive, the same as variable names.

Variable references are bare names — write the variable name directly in the expression without any prefix or delimiter. For example, if you have a show variable named "SceneSelect", the expression SceneSelect == 2 references that variable.

Expression Examples

Expression	Evaluates to True When
`GoSignal`	The variable "GoSignal" is greater than 0
`SceneMode == 3`	The variable "SceneMode" equals exactly 3
`Temperature > 25`	The variable "Temperature" exceeds 25
`ButtonA * ButtonB`	Both "ButtonA" and "ButtonB" are greater than 0 (logical AND)
`SensorA + SensorB`	At least one sensor is positive and their sum is positive
`Emergency != 0`	The variable "Emergency" is anything other than 0

For reliable AND/OR logic, combine explicit comparisons with the logical operators: A > 0 && B > 0 is true only when both are positive, and A > 0 || B > 0 is true when either is positive. You can also multiply for AND (A * B) or add for OR (A + B), but negative values can produce unexpected results with these arithmetic forms. Prefer the comparison-based form.

Configuring Triggers

Configure triggers in the Timeline properties:

Open the Timelines window.
Select the Timeline.
Open Properties for the Timeline.
Open the Triggers section.
Enter expressions in the fields:

Play Expression
Pause Expression
Stop Expression

Each Expression is validated as you type. Correct validation errors before closing.

Set any combination of the three triggers on one Timeline. For example, a play trigger on one Variable and a stop trigger on another, with no pause trigger.

Trigger Properties

Property	Expression Type	Default	Purpose
Play Expression	Trigger Expression	Empty (no trigger)	When the expression evaluates to true, the timeline begins or resumes playback
Pause Expression	Trigger Expression	Empty (no trigger)	When the expression evaluates to true, the timeline pauses at its current position
Stop Expression	Trigger Expression	Empty (no trigger)	When the expression evaluates to true, the timeline stops and resets

An empty expression means no trigger is active for that action — the timeline's playback state is not affected by that trigger slot.

Expression Validation

WATCHOUT validates trigger expressions as you edit them:

Syntax validation — malformed expressions are rejected.
Variable reference validation — references to Variable names not defined in the show are flagged as errors. This prevents silent failures from typos or deleted Variables.

Validation rejects references to non-existent variable names at edit time. If you rename or delete a show variable, any trigger expression referencing that variable will fail validation the next time it is edited. Review all trigger expressions after modifying the variable list.

Expression Types in WATCHOUT

Timeline triggers are one of several expression types. All share the same engine but serve different purposes:

Expression Type	Default Variable	Usage Context
Tween Expression	`tweenValue`	Tween curves — the expression receives the current tween value as input
Trigger Expression	None	Timeline play/pause/stop triggers — evaluated against show variables
Audio Cue Route Expression	`cueVolume`	Audio cue routing — expression receives the cue's volume level
Audio Device Route Expression	`masterVolume`	Audio device routing — expression receives the master volume level
Cue Expression	None	Per-cue conditions — determines whether a cue renders or fires (see Conditional Cues)

All five types use identical syntax and the same truth rule (result > 0.0 = true). The difference is the context in which they are evaluated and whether a default variable is injected into the expression namespace.

For Cue Expressions specifically, an empty expression evaluates to true (the cue is always active), which differs from Trigger Expressions where an empty expression has no effect.

Reserved Variable Names

Two names cannot be used as show Variable names:

Reserved Name	Used By
`tweenValue`	Tween Expression — the current tween interpolation value
`cueVolume`	Audio Cue Route Expression — the cue's audio volume

The check is case-insensitive. You cannot create a Variable named "tweenValue", "tweenvalue", or "TWEENVALUE". The name validator rejects it. masterVolume is a default show Variable and is not reserved.

Auto-Run vs. Triggers

Timelines have an Auto Run property, disabled by default. It is separate from trigger expressions:

Mechanism	When It Activates	Behavior	Continuous?
Auto-run	On show load	Starts the timeline automatically when the show is loaded or opened	No — fires once at load time
Trigger expressions	During show runtime	Starts, pauses, or stops the timeline whenever the expression evaluates to true	Yes — evaluated continuously

Auto-run and triggers are independent and can be used together. A timeline with Auto Run enabled will start on show load. If the same timeline also has trigger expressions, those triggers continue to evaluate during playback and can pause or stop the timeline based on variable state.

Auto-run is a one-time event at show load. If a timeline is stopped by a trigger or control cue after auto-run starts it, auto-run does not re-fire. Only the play trigger expression (or a control cue) can restart it.

Trigger Interaction

A trigger fires when its Expression value changes to non-zero on an input change. The triggers are state-gated: the play trigger fires only when the Timeline is not already playing, the pause trigger only when it is playing, and the stop trigger only when the Timeline is active. On a single input change, the engine checks play, then pause, then stop, and applies the first match.

Design your expressions so conflicting triggers do not change to true at the same moment. Use mutually exclusive Variable ranges or distinct Variables for each trigger.

Scope

Trigger expressions are a Timeline-only feature. The Triggers section is not shown for compositions. Timelines are top-level playback containers. Compositions are reusable content blocks embedded within Timelines and inherit their parent's playback state.

For conditional behavior within a composition, use Conditional Cues on individual cues.

Use Cases

External start signal: A lighting console sends an OSC message that sets a "GoTimeline3" variable to 1. The timeline's play trigger expression is GoTimeline3, and it begins playing immediately when the variable goes positive.

Sensor-driven pause: A proximity sensor feeds a "VisitorPresent" variable. A media timeline uses VisitorPresent == 0 as its pause trigger — when no visitor is detected, playback pauses. A play trigger of VisitorPresent > 0 resumes playback when a visitor returns.

Emergency stop across multiple timelines: An "EmergencyStop" variable is connected to a physical kill switch via the HTTP API. Every content timeline has EmergencyStop as its stop trigger expression. When the variable goes to 1, all triggered timelines stop simultaneously.

Scene selection: A "CurrentScene" variable is set by an external show controller. Timeline A has a play trigger of CurrentScene == 1, Timeline B has CurrentScene == 2, and so on. Each timeline also has a stop trigger of its inverse — Timeline A stops when CurrentScene != 1. Changing the Variable transitions between scenes.

Time-gated playback: A "ShowHour" variable is updated by an external clock system. A daytime content timeline uses ShowHour >= 9 * (ShowHour <= 17) as its play trigger and ShowHour > 17 as its stop trigger, creating time-windowed playback.

Best Practices

Keep expressions simple and readable. Complex nested expressions are hard to debug. If the logic requires more than two or three operators, consider breaking it into multiple variables controlled externally.
Use explicit comparison operators. Write Mode == 1 instead of relying on Mode alone, unless you specifically want "any positive value" behavior. Explicit comparisons make the intent clear.
Test triggers in rehearsal with controlled variable changes. Use the Variables window to manually adjust variable values and verify that each trigger fires as expected before relying on external input sources.
Document trigger logic. Record which variables drive which timeline triggers, especially in shows with many timelines. This is critical for show handoff and troubleshooting during live events.
Avoid overlapping true conditions on conflicting triggers. If a timeline's play and stop triggers can both be true at the same time, the stop trigger always wins — but this creates confusing behavior. Design variable ranges so only one trigger is active at a time.
Version and review trigger expressions. Treat trigger expressions as show logic. After major variable or timeline edits, review all trigger expressions to ensure they still reference valid variables and produce the intended behavior.
Prefer triggers over polling control cues for variable-driven logic. If a timeline should start or stop based on a variable value, a trigger expression is more direct and reliable than a looping timeline with conditional control cues.

Duration Field Unit Shortcuts

In duration or time fields, append a unit suffix to set the unit directly:

Suffix	Unit	Example
s	Seconds	`5s` = 5 seconds
m	Minutes	`2m` = 2 minutes
h	Hours	`1h` = 1 hour

Longer forms also work (ms, sec, min, hr). Without a suffix, the value uses the field's default unit. These shortcuts work in any duration or time input field.

FAQ

How do I use triggers with three timelines and Always on Top?

Consider a show with three timelines controlled by a single SceneSelect variable:

Timeline	Content	Play Expression	Stop Expression	Stacking
Background	Ambient loop	(none — Auto Run)	`Emergency`	Timeline Order
Content A	Scene 1 video	`SceneSelect == 1`	`SceneSelect != 1`	Timeline Order
Overlay	Branding graphics	`SceneSelect > 0`	`SceneSelect == 0`	Always on Top

In this setup:

Background starts on show load via Auto Run and plays continuously unless an emergency stop fires.
Content A starts when an external controller sets SceneSelect to 1, and stops when the variable changes to any other value.
Overlay is set to Always on Top, so its branding graphics render above Background and Content A regardless of panel order. It plays when any scene is active (SceneSelect > 0) and stops when the Variable returns to 0.

Overlay uses Always on Top, so you reorder Background and Content A in the Timelines panel without affecting the overlay.

Troubleshooting

For trigger and expression problems (trigger never fires or fires unexpectedly, validation rejects an expression, timeline does not auto-start), see Timeline and Cue Issues → Triggers and Expressions.

Variables and Variable Cues — show variables that drive trigger expressions
Conditional Cues — per-cue condition expressions for conditional rendering and triggering
Control Cues — cue-based alternative for controlling timeline playback state
Compositions — reusable content blocks (triggers are not available for compositions)

Previous Next