Variables

A Stream Deck caption is normally fixed: what you type in the editor is what appears on the key. Variables turn a caption into a template. If the caption contains $name, the key shows 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 FrenschPress fills it

Display text only

Variables only apply to captions: Stream Deck keys, and 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

You write your own variables from outside; the FrenschPress does not create them by itself. 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

In the step editor, choose Variable as the protocol. 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. A step carrying $sys_cue therefore captures the cue name of that moment instead of tracking it. This is how you build a "what went last" readout.

From Companion

The module for Bitfocus Companion offers two routes: an action that writes a value on press, and a feedback that mirrors a Companion variable continuously. Both are described under Setting a device variable from Companion. Either way, the FrenschPress only receives the finished text.

Device values (`$sys_…`)

These names are reserved. They are always available without anyone writing them, and any attempt to write one 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`	Number of FrenschPress peers on the network
`$sys_cue`	Name of the running QLab cue. Empty while nothing is running
`$sys_standby`	Name of the cue QLab is standing by on, i.e. what GO fires next
`$sys_remaining`	Time left on the running cue. Empty while nothing is running
`$sys_running`	Number of running QLab cues
`$sys_paused`	Number of paused QLab cues
`$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 keys of your choice

Use $sys_tc_hh to $sys_tc_ff when timecode should not run as a display row but on keys you pick yourself. For example minutes and seconds only, large and 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 on the Streamdeck page, the $ button sits to the right of Button text.

Choose $. The list shows every name the FrenschPress can currently resolve, your own and the sys_ ones, each with its current value beside it. Use the filter field to search it.
Click an entry. $name is inserted at the cursor.
Check the preview below the input field. It shows the caption exactly as the deck would paint it at this moment.

The list keeps updating while it is open. You pick the variable that currently reads 12 and do not have to remember that it is called ch.

Rules

A name has 1–24 characters from A-Z, a-z, 0-9 and _.
A value has at most 48 characters, the same limit as a key caption. Anything longer is truncated without warning.
The FrenschPress holds up to 64 of your own variables.
A $ only starts a name when a name character follows. 100$, US$ and $ 5 stay as they are. So there is no escape character, and existing captions do not suddenly change.
An unknown name expands to nothing. CUE $cue without a variable cue gives CUE , and a caption that is only $cue stays blank.
No recursion: a value that itself contains $ is drawn literally.
$$ is reserved for future peer-shared variables and is refused when saving. The editor shows a message.

Variables do not survive a restart

The store lives in RAM and is not saved. After a restart all your own variables are empty until they are written again. This is deliberate: last night's value on a key is worse than a blank key.

The Companion feedback Sync variable to FrenschPress rewrites its mappings at slow intervals on its own. After the FrenschPress restarts, those values are back 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. If nothing changes, nothing is sent to the deck.

In Companion satellite mode the FrenschPress paints no captions. The deck then 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 converted to text.
/fpress/var/clear with a name clears that variable, without an argument it clears all of them.
Names beginning with sys_ and malformed names are refused, each with a message in the log.

Details and the remaining commands are under OSC remote control.

Over the HTTP API

Call	Effect
`GET /api/variables`	All variables 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 valid value and is stored. A variable is only cleared when the key is missing.

Troubleshooting

Symptom	Cause	Fix
Key shows nothing where the variable should be	Name unknown or misspelt	Insert the variable from the `$` list instead of typing it
All your own variables are empty	The FrenschPress has restarted	Write the values again, e.g. over OSC or with the Companion feedback
`$sys_cue`, `$sys_standby` etc. stay empty	No OSC connection to QLab, or no cue is running	Set up the OSC connection; MIDI/MSC gives no feedback
Value is cut off	More than 48 characters	Shorten the value
Caption cannot be saved	It contains `$$`	Remove `$$`
Writing over OSC or HTTP is refused	Name starts with `sys_` or is malformed	Use 1–24 characters from `A-Z`, `a-z`, `0-9`, `_`
Deck does not show the FrenschPress caption	Companion satellite mode: Companion paints the deck	Set the text in Companion

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​

Troubleshooting​