Variables

A Stream Deck caption is normally fixed: whatever was typed in the editor stays on the key until somebody changes it. Variables turn a caption into a template. A caption containing $name renders the current value of that variable, and repaints as soon as the value changes.

Caption in the editor         on the key
CUE $sys_cue            →     CUE Blackout
CHAN $ch                →     CHAN 12
$sys_tc                 →     01:12:44:07

There are two kinds:

Form	Meaning	Writable
`$name`	Your own variable in the device's store	yes
`$sys_name`	Device value — mode, cue, timecode, IP …	no, the device fills it

Display text only

Variables apply to captions: Stream Deck keys, plus the push, left and right captions of the Stream Deck + encoders. Macro parameters, preset names, timeline labels and network targets are not substituted.

Where the values come from

Your own variables are written from outside — the device does not invent them. Four routes lead into the same store:

Route	How
OSC	`/fpress/var <name> <value>`
Macro step	Protocol Variable in the step editor
Companion module	Action Set device variable, or the Sync variable to FrenschPress feedback
HTTP API	`POST /api/variables` with `{name, value}` (login required)

The "Variable" macro step

Pick Variable as the protocol in the step editor. The step writes one name and one value.

The value may itself contain $name or $sys_name. That reference is resolved when the macro fires, so a step carrying $sys_cue freezes the cue name of that moment instead of tracking it. That is exactly how a "what went last" readout is built.

From Companion

The Companion module offers two routes, both described on the Companion module page: an action that writes a value on press, and a feedback that mirrors a Companion variable continuously. Either way the FrenschPress receives only the finished string — it knows nothing about Companion.

Device values (`$sys_…`)

These names are reserved. They are always available without anyone writing them, and a write to one of them is refused.

Name	Contents
`$sys_mode`	Control mode: `qlab`, `macro` or `companion`
`$sys_set`	Active button set: `A`, `B` or `C`
`$sys_set_buttons`	Set letter per button, eight letters in the order stop, go, pause, encoder push, left, right, push+left, push+right
`$sys_name`	Device name
`$sys_fw`	Firmware version
`$sys_ip`	IP address of the active interface
`$sys_peers`	How many FrenschPress peers are on the network
`$sys_cue`	Name of the running QLab cue. Empty while nothing runs
`$sys_standby`	Name of the cue QLab is standing by on — what GO fires next
`$sys_remaining`	Time left on the running cue. Empty while nothing runs
`$sys_running`	How many QLab cues are running
`$sys_paused`	How many QLab cues are paused
`$sys_tc`	Incoming MTC timecode, `hh:mm:ss:ff`. Empty without timecode
`$sys_tc_hh`	Timecode hours, two digits
`$sys_tc_mm`	Timecode minutes, two digits
`$sys_tc_ss`	Timecode seconds, two digits
`$sys_tc_ff`	Timecode frames, two digits

Timecode on four keys

$sys_tc_hh through $sys_tc_ff exist for the case where timecode should not run as a display row but on keys you pick yourself — minutes and seconds only, large, somewhere readable from the house.

The QLab values need an OSC connection to QLab (see QLab Mode); MIDI/MSC has no return channel.

Inserting a variable into a caption

In the key editor of the Streamdeck page, the $ button sits next to Button text.

$ opens the list of every name the device can currently resolve — your own and the sys_ ones, each with its current value beside it. The filter field searches that list.
A click inserts $name at the cursor.
Below the input field is the preview: the caption exactly as the deck would paint it at this moment.

The list keeps updating while it is open, so you pick the variable that reads 12 rather than having to remember it is called ch.

Rules

A name is 1–24 characters of A-Z, a-z, 0-9 and _.
A value is at most 48 characters — the same ceiling a key caption already has. Anything longer is truncated without warning.
The device holds 64 of your own variables.
A $ starts a name only when a name character follows. 100$, US$ and $ 5 are left alone, so there is no escape character and no existing caption that suddenly looks different.
An unknown name expands to nothing. CUE $cue with no cue gives CUE , and a caption that is only $cue goes blank.
No recursion: a value that itself contains $ is drawn literally.
$$ is reserved for peer-shared variables that do not exist yet and is refused when saving — with a message in the editor rather than as silent nonsense on a key.

Variables do not survive a reboot

The store lives in RAM and is not persisted. After a restart every one of your variables is empty until it is written again. That is deliberate: a value from last night on a key is worse than a blank key.

The Companion feedback Sync variable to FrenschPress reasserts its mappings slowly on its own, so a device reboot is caught up again shortly afterwards.

How often the deck repaints

A key carrying a variable is rewritten at most every 200 ms, and only when its expanded text has actually changed. Nothing changing means no traffic to the deck at all.

In Companion satellite mode the FrenschPress paints no captions: there the deck belongs to Companion, and Companion sends its own text.

Setting and clearing over OSC

/fpress/var "cue" "Blackout"
/fpress/var "ch" 12
/fpress/var/clear "cue"
/fpress/var/clear

/fpress/var takes a name and a value. The value may be a string, an integer, a float or a bool; numbers are formatted into text.
/fpress/var/clear with a name clears that one, without an argument clears everything.
Names beginning with sys_ are refused, as are malformed names — both with a log message, never silently.

Details and the remaining commands are under OSC remote control.

Over the HTTP API

Call	Effect
`GET /api/variables`	Every variable including the `sys_` values, as JSON
`POST /api/variables` `{"name":"ch","value":"12"}`	Set
`POST /api/variables` `{"name":"ch"}`	Clear — the missing `value` key is the clear signal

Both calls need a logged-in session. An empty string as value is a legitimate value and is stored; clearing happens only when the key is absent.

Where the values come from​

The "Variable" macro step​

From Companion​

Device values ($sys_…)​

Inserting a variable into a caption​

Rules​

How often the deck repaints​

Setting and clearing over OSC​

Over the HTTP API​