Variables and Variable Cues

Variables store numeric values that drive show behavior. External control protocols (HTTP, OSC, Art-Net, MIDI, LTC) set them, or variable cues on the timeline automate them. Expressions, conditional cues, and timeline triggers reference variables to make shows reactive.

What variables are

A variable is a named numeric value inside the show. Each variable holds a single floating-point value that changes at runtime. Reference the value by name from any expression, any conditional cue, and any variable cue tween curve.

Variables are defined in Producer and synchronized to the Director during playback. External control systems address a variable by its key — a protocol-specific identifier that maps incoming messages to the variable. When no external input is active, a variable holds its default value.

Variables serve two roles in a show:

• Reactive input — an external system pushes values into the variable via its key. Expressions and conditional cues respond.
• Timeline automation — a variable cue drives the variable through a tween curve over a set duration.

Both mechanisms can coexist. An Art-Net channel might drive a variable during rehearsal, and a variable cue during the live show.

Variable properties

The Properties panel shows these fields when a variable is selected:

Field	Purpose
Name	Variable name shown in the Variables window, expressions, and cue properties. Must be unique (case-insensitive) and a valid identifier.
Key	External protocol address used by HTTP, OSC, Art-Net, MIDI, or LTC to target this variable. A Learn button captures it from an incoming signal.
Min Value	Lower bound of the value range.
Max Value	Upper bound of the value range.
Default Value	The value the variable starts at when the show loads.
Interpolation Type	How incoming external values are smoothed over time. See Interpolation types.

A new variable gets these defaults: name Variable1 (auto-incremented), empty key, range 0.0--1.0, default value 0.5, Linear interpolation. Clamping defaults to on and Protected defaults to off, but neither is exposed in the Properties panel.

Interpolation types

The interpolation type sets how the variable transitions from its current value to a newly received external input value.

The interpolation time is 50 ms.

Type	Behavior	Typical Use
None	Value jumps instantly to the new input. No smoothing.	Binary triggers, button presses, mode selectors
Linear	Value moves linearly to the new input over the interpolation period. Default.	Faders, sliders, gradual parameter changes
Circular	Value interpolates along the shorter arc. 350 to 10 travels through 0 rather than the long way.	Rotational encoders, pan angles, hue values

Interpolation applies only to external input. Variable cues use their own tween curves and ignore the interpolation type.

Creating and managing variables

Open the Variables window. Use the add menu to create and manage variables:

1. Add a variable — choose Add Variable. A new variable appears with the defaults above.
2. Edit properties — select a variable and edit its name, key, range, default value, and interpolation in the Properties panel.
3. Adjust the live value — use the slider in the Variables window to change the current value during testing.
4. Save as default — choose Save As Default Value to store the current live value as the variable's default.
5. Copy/Paste — copy and paste variables within the Variables window.
6. Remove — protected variables and variables in use cannot be removed.

Naming rules

Variable names must follow these rules:

• Valid identifier — a name starts with a letter or underscore, then letters, digits, or underscores. No spaces.
• Unique — no two variables may share a name. The check is case-insensitive, so "MyVar" and "myvar" are identical.
• Reserved names — tweenValue and cueVolume are reserved and cannot be assigned to a variable. The check is case-insensitive.
• In-use restriction — a variable referenced by an expression, a variable cue tween curve, or an audio route cannot be renamed or removed. Remove the references first.

Protection

A variable's protected flag blocks removing or cutting it. Protected variables can still be edited and their values still change at runtime.

The Properties panel has no toggle for this flag. When a variable is protected, its Name field is disabled.

Default values at runtime

The default value is the variable's baseline. The variable shows its default value until an external input or a variable cue changes it.

To set a predictable starting state:

1. Set each variable to the value you want at show start.
2. Use Save As Default Value.

External key and Learn mode

The Key field sets how external control protocols address the variable. Each protocol uses its own key format. A variable without a key cannot receive external input.

Supported protocols and key formats

Protocol	Key Format Example	Notes
HTTP	Any string key	POST /v0/inputs accepts a JSON object mapping keys to values.
OSC	osc.addr(/path/index)	Maps an OSC address and argument index to the variable. The index selects which argument to read.
Art-Net	artnet.net(1).subnet(2).uv(3).ch(4)	Append .normalize() to map the 0--255 DMX range to the variable's min/max range. Without it, the raw 0--255 value is used.
MIDI	Protocol-specific key	Maps MIDI messages to the variable.
LTC	Protocol-specific key	Maps Linear Timecode values to the variable.

Learn mode workflow

Instead of typing a key, use Learn mode to capture it from an incoming signal:

1. Select the variable.
2. Click Learn in the variable properties. The key field clears.
3. Send the external control signal (move a fader, send an OSC message, send an Art-Net channel). Learn captures the first key after the signal releases.
4. The captured key is assigned. Learn mode turns off.

HTTP input example

POST /v0/inputs sets multiple variables in one request:

POST /v0/inputs
Content-Type: application/json

{
  "brightness": 0.8,
  "color_temp": 6500,
  "emergency": 0
}

Each key in the JSON object is matched against variable keys. Variables without matching keys are unaffected.

Input interpolation

When a variable receives a new value from an external source, it transitions over 50 ms using the configured interpolation type, unless the type is None. Then it jumps instantly.

Smoothing prevents visible jumps when control surfaces send rapid discrete steps. For instant response, set the interpolation type to None.

The smoothing window feels responsive for interactive control and smooths out the step artifacts common in 7-bit MIDI or 8-bit Art-Net inputs.

Variable cues

Variable cues automate a variable's value over time on the timeline. A variable cue uses tween data to drive one variable through an animation curve over a set duration.

Variable cue fields

A variable cue contains the following data:

Field	Purpose
Duration	The time span over which the tween animation runs.
Name	Optional name for the cue on the timeline.
Tween Data	The animation curve that drives the variable's value over the cue's duration. Uses the same tween system as Media cue property animations.

Creating variable cues

To create a variable cue, drag a variable from the Variables window onto a timeline layer.

Variable cue behavior

During playback, a variable cue emits updated values every 28 ms (about 35 per second) over its duration, plus one final value at the end. The variable's value is set to the tween output at the playhead position.

Variable cues are duration-based: they start when the playhead enters the cue and stop when it exits. Unlike Media cues, variable cues do not render visual content. They only update the numeric value of their target variable.

Limitations

• Cannot be placed inside compositions. Variable cues do not produce renders or events inside compositions. Place them on a regular timeline. For automation tied to a composition, place the variable cue on the parent timeline.
• Target variable must exist. WATCHOUT blocks deleting a variable that a cue references.

Expressions and variables

Variables are the data source for the expression system. Expressions in timeline triggers and conditional cues reference variables by name.

• Variable names in expressions are case-insensitive. MyVar, myvar, and MYVAR resolve to the same variable.
• An expression that references a name with no matching variable is rejected as an "Unknown input". Check spelling.

Examples of variable usage in expressions:

Expression	Meaning
Brightness	Evaluates to the current value of the "Brightness" variable
Brightness > 0.5	True when Brightness exceeds 0.5, false otherwise
Mode == 2	True when Mode equals 2
SensorA * SensorB	Nonzero only when both SensorA and SensorB are nonzero

For complete expression syntax and operator reference, see Timeline Triggers and Expressions.

Variables and Conditional Cues

Variables are the primary mechanism for enabling conditional cues. A conditional cue evaluates an expression against current variable values to decide whether to render (media cues) or trigger (control/output cues). This creates a feedback loop:

1. An external system or variable cue sets a variable value.
2. A conditional cue evaluates an expression referencing that variable.
3. The cue renders or fires only when the expression is true (result > 0).

This pattern enables interactive installations, show branching, emergency overrides, and any scenario where content must appear or disappear based on runtime state. See Conditional Cues for detailed syntax and use cases.

Best practices

• Use descriptive, stable names. Choose clear names early. Avoid renaming once expressions reference a variable.
• Set min/max bounds before building automation. A range of 0.0--1.0 works for normalized parameters. Use domain-specific ranges (0--360 for angles, 0--100 for percentages) for physical quantities.
• Save defaults before rehearsals and shows. Use Save As Default Value to capture a known-good starting state.
• Use Learn mode for physical controllers. Typing Art-Net or OSC key strings manually is error-prone. Learn captures the exact key from the incoming signal.
• Use the Art-Net .normalize() suffix. Append .normalize() to the Art-Net key so the 0--255 DMX range maps to the variable's min/max range automatically.
• Document variable usage with marker cues. Place marker cues near variable cues so operators can identify each automation segment.
• Test with the Variables window slider. Before connecting external controllers, verify that changing a value produces the expected results. This isolates show logic from protocol configuration.

Troubleshooting

For variable and variable-cue problems (no response to input, value jumps, cannot delete or rename, unknown input, reserved names), see Timeline and Cue Issues → Variables and Variable Cues.

Related

• Timeline Triggers and Expressions — automate playback from variable values
• Conditional Cues — gate cues on variable values
• Art-Net Fixture Cues — drive DMX channels from variables