Variables and Inputs
Variables are how external control reaches WATCHOUT's rendering engine. Every external protocol — Art-Net, OSC, MIDI, HTTP, or another — writes values to the show's variables. Those variables then drive tween expressions, conditional cues, and timeline triggers.
This page covers the external-control specifics: per-protocol key formats, Learn mode, and the path an incoming value takes from reception to the Runners. The variable model itself — properties, interpolation types, default values, and variable cues — is documented in Variables and Variable Cues.
Matching by Key
Each variable has a Key. External protocols address a variable by its key, not by its name. When a value arrives, the Director looks up the variable with the matching key. If no variable has that key, the value is ignored.
The Properties panel field is labeled Key. The Variables window list shows it in the External Key column.
Per-Protocol Key Formats
Each protocol writes its key in its own format. Set the variable's Key to match the format for the protocol you use. In the formats below, replace N with the number you need — a channel, a universe, or a tracker ID. To avoid typing the key by hand, use Learn mode to capture it from a live signal.
| Protocol | Key format | What the parts mean | Example |
|---|---|---|---|
| OSC | osc.addr("/your/address/0") | The OSC address, then the argument index. | osc.addr("/brightness/0") |
| Art-Net | artnet.universe(N).ch(N) | The DMX universe and channel. | artnet.universe(1).ch(5) |
| MIDI | midi.ch(N).cc(N) | The MIDI channel and control change number. | midi.ch(0).cc(7) |
| PosiStageNet | psn.N.pos.x | The tracker ID, then the data field. | psn.1.pos.x |
PosiStageNet provides several fields per tracker: position, speed, orientation, and acceleration (each with .x, .y, and .z), plus status and target position. See PosiStageNet for the full field list, and each protocol page for the complete key syntax it supports.
Learn Mode
Learn mode captures a key from a live signal instead of typing it. Open the Variable Properties panel for a variable. Click Learn next to the Key field. Send a signal from your device — move a fader or send an OSC message. WATCHOUT captures the incoming key and assigns it to the variable. Click Cancel to stop without capturing.
Input Flow
When an external value arrives, it passes through this chain:
- Reception — The protocol handler receives the raw message.
- Key extraction — The handler converts the protocol-specific address into a key string.
- Matching — The Director matches the key against the show's variables.
- Clamping — The value is clamped to the variable's min/max range. Clamping applies only when the min or max bound is enabled.
- Interpolation — The value interpolates over the variable's interpolation window. The default is 50 ms when the protocol supplies no duration.
- Distribution — The Director broadcasts the value to all Runners. It then drives tween expressions, conditional cue evaluations, and other variable consumers.
Interpolation
The Interpolation selector sets how a variable transitions to a new value. Three modes are available:
- None — The value jumps instantly to the new value.
- Linear — The value ramps evenly over the interpolation window.
- Circular — The value wraps around the min/max range, taking the shortest path. Use it for cyclic values like hue or rotation angle.
Interpolation modes are documented in full in Variables and Variable Cues.
Default Values
Each variable has a default value. Variables return to it on show load and on reset. To update the defaults, set the variables to the values you want, then choose Save as Default Value.
Default values are covered in Variables and Variable Cues.
Using Variables in the Show
A variable's value can be referenced throughout the show:
- Bind a cue property to a variable with tween expressions.
- Gate a cue's visibility on a variable with conditional cues.
- Set variable values from the timeline with Variables and Variable Cues.
Related
- External Control Overview — architecture connecting protocols to variables.
- Variables and Variable Cues — the variable model, interpolation, and defaults.
- OSC Protocol, Art-Net Input, MIDI Bridge, PosiStageNet — per-protocol key formats.