OSC Control
OSC lets you control the FrenschPress from outside: from QLab, a lighting console, Companion or your own script. Send the commands over UDP to the FrenschPress's IP address, on its OSC Listen Port.
| Parameter | Value |
|---|---|
| Namespace | /fpress |
| Protocol | OSC over UDP |
| Port | 53001 (default) |
| Target | IP address of the FrenschPress |
You can change the port in Settings or directly on the Stream Deck. The FrenschPress also receives QLab feedback on this port.
Command overview
The Saved column shows whether the FrenschPress stores the change. Commands marked “No” only act at runtime.
| Command | Arguments | Saved |
|---|---|---|
/fpress/mode | 1, 2, 3 | Yes |
/fpress/set | A, B, C + optional mask | Yes |
/fpress/preset | preset ID (string) | Yes |
/fpress/button | button + optional action | No |
/fpress/macro | macro name or ID + optional action | No |
/fpress/timeline/arm | timeline selector | Yes |
/fpress/timeline/disarm | timeline selector | Yes |
/fpress/timeline/arm_all | – | Yes |
/fpress/timeline/disarm_all | – | Yes |
/fpress/led | r g b or target r g b | No |
/fpress/led/release | – or target | No |
/fpress/var | name value | No |
/fpress/var/clear | – or name | No |
/fpress/streamdeck/button | row col [action] | No |
/fpress/streamdeck/feedback | button state | No |
/fpress/streamdeck/feedback/all | state | No |
/fpress/streamdeck/feedback/clear | – | No |
/fpress/query | – or a group name | No |
/fpress/mode
Changes the device mode. The number and the name do the same thing.
| Value | Mode |
|---|---|
1 / "qlab" | QLab Mode |
2 / "macro" / "custom" | Custom Mode (macros) |
3 / "companion" | Companion Mode |
/fpress/mode 1
/fpress/mode 2
/fpress/mode 3
/fpress/set
Changes the active button set. Works only in Custom Mode.
First argument: the target set.
| Value | Set |
|---|---|
"A" / 1 | Set A |
"B" / 2 | Set B |
"C" / 3 | Set C |
Second argument (optional): a mask. It decides which controls move to the new set. Without a mask, all of them do.
/fpress/set "A"
/fpress/set "B"
/fpress/set "C" "stop,go,pause"
/fpress/set "A" 7
Mask dictionary
The mask is an integer bitmask, a selector string or "all". In a selector string, separate tokens with ,, ;, | or spaces.
| Selector token | Bitmask |
|---|---|
stop, 0 | 1 << 0 |
go, 1 | 1 << 1 |
pause, 2 | 1 << 2 |
enc, encoder, push, 3 | 1 << 3 |
left, prev, ccw, 4 | 1 << 4 |
right, next, cw, 5 | 1 << 5 |
push_left, combo_left, combo_prev, 6 | 1 << 6 |
push_right, combo_right, combo_next, 7 | 1 << 7 |
all | 0xFF |
/fpress/set "B" "stop,go,pause"
/fpress/set "C" "all"
/fpress/set "A" 255
/fpress/set "A" 7
/fpress/preset
Loads a preset. The command takes the preset ID, not the display name. You can find the ID in the preset picker in the web interface.
| Preset type | Format |
|---|---|
| User preset | "my-preset-12ab" |
| Plugin preset | "pluginId:presetId" |
| Clear | "empty" |
/fpress/preset "my-user-preset-12ab"
/fpress/preset "osc-qlab-basics:transport"
/fpress/preset "empty"
/fpress/button
Triggers a FrenschPress button as if you had pressed it on the unit. This also lets you run macros with separate press and release actions remotely.
First argument: the button.
| Value | Button |
|---|---|
"stop" / 0 | STOP |
"go" / "play" / 1 | GO |
"pause" / 2 | PAUSE |
Second argument (optional): the action. The default is "tap".
| Action | Effect |
|---|---|
"tap" / "trigger" / "go" | Press and release immediately |
"press" / "on" / "1" | Press only (the button stays logically held) |
"release" / "off" / "0" | Release only |
/fpress/button "go"
/fpress/button "stop" "press"
/fpress/button "stop" "release"
/fpress/button 1 "tap"
If you send press, follow it with release. Otherwise the logically held button blocks release sequences and toggle states.
/fpress/macro
Runs a macro by name or ID. The macro does not need to be assigned to a button.
First argument: the exact macro name or the macro ID. If a name matches more than one macro, the FrenschPress rejects the command. Use the ID instead.
Second argument (optional): the action. The default is "trigger".
| Action | Effect |
|---|---|
"trigger" / "tap" / "start" | Run the macro once |
"on" / "press" / "1" | Turn a snapshot macro on; behaves like trigger for all other macros |
"off" / "release" / "0" | Turn a snapshot macro off |
"toggle" | Toggle a snapshot macro |
/fpress/macro "House Lights"
/fpress/macro "House Lights" "toggle"
/fpress/macro "macro-7f3a" "trigger"
off, release and toggle exist for snapshot macros only (Art-Net/sACN DMX snapshots). Only these have a persistent on/off state.
/fpress/timeline/arm & /fpress/timeline/disarm
Arms or disarms a single timeline.
Argument: the timeline selector, in one of three forms:
| Form | Example |
|---|---|
| Visible number from the dropdown | "1" |
| Display name | "Main Timeline" |
| Internal ID | "main" |
/fpress/timeline/arm "1"
/fpress/timeline/arm "Main Timeline"
/fpress/timeline/disarm "main"
/fpress/timeline/arm_all & /fpress/timeline/disarm_all
Arms or disarms all timelines at once. No arguments.
/fpress/timeline/arm_all
/fpress/timeline/disarm_all
These commands are idempotent. If the state is already in place, the FrenschPress writes nothing to the filesystem. Changes to all timelines are saved atomically.
/fpress/led
Sets a runtime RGB colour for all LEDs or for a single one. The colour is not saved.
Range: 0–255 per channel
Targets:
| Target | Description |
|---|---|
"all" / "*" / 0 | All LEDs |
"stop" / "btn0" / "button0" / 1 | Stop button |
"go" / "btn1" / "button1" / 2 | Go button |
"pause" / "btn2" / "button2" / 3 | Pause button |
"encoder" / "enc" / "push" / "btn3" / 4 | Encoder |
/fpress/led 255 0 0
/fpress/led "all" 255 0 0
/fpress/led "stop" 255 0 0
/fpress/led "go" 0 255 0
/fpress/led "pause" 255 140 0
/fpress/led "encoder" 0 80 255
The colour stays until another /fpress/led changes it or /fpress/led/release clears it. Mode and feedback colours keep updating in the background. After the release you see the current colour again.
/fpress/led/release
Releases the colours you set. The LEDs return to their current live colour. Without an argument all are released; with a target, only that one. The targets are the same as for /fpress/led.
Alias: /fpress/led/clear
/fpress/led/release
/fpress/led/release "all"
/fpress/led/release "stop"
/fpress/var
Writes a variable on the FrenschPress. Stream Deck captions containing $name show its value.
| Argument | Meaning |
|---|---|
| 1 | Name – 1–24 characters of A-Z, a-z, 0-9, _ |
| 2 | Value – string, integer, float or bool |
/fpress/var "cue" "Blackout"
/fpress/var "ch" 12
/fpress/var "level" 0.5
/fpress/var "armed" true
Numbers are stored as text: integers in decimal, floats to three decimal places, bools as 1 or 0. HTTP does the same, so both routes store the same value.
Values longer than 48 characters are cut off without a warning. The FrenschPress holds up to 64 variables. Once the table is full, new names are refused.
Names starting with sys_ belong to the device (sys_mode, sys_cue, sys_tc …). The FrenschPress refuses them here and reports it. The full list is under Variables.
/fpress/var/clear
Clears variables: one with an argument, all of them without.
/fpress/var/clear "cue"
/fpress/var/clear
A caption that uses a cleared variable only loses that $name. CUE $cue becomes CUE . The stored caption text stays as it is.
Stream Deck over OSC
These commands only work while a Stream Deck is connected.
/fpress/streamdeck/button
Triggers a deck key. Row and column count from 0.
Both forms do the same:
/fpress/streamdeck/button 1 2
/fpress/streamdeck/button/1/2
You can add an action as the last argument. The default is "tap".
| Action | Effect |
|---|---|
"tap" / "trigger" / "go" | Press and release |
"press" / "on" / "1" | Press only |
"release" / "off" / "0" | Release only |
/fpress/streamdeck/button 0 0 "tap"
/fpress/streamdeck/button/0/0 "press"
/fpress/streamdeck/button/0/0 "release"
Keys reserved for the timecode display and the tools key do not run macros over OSC either.
/fpress/streamdeck/feedback
Sets the feedback colour of a deck key from outside, for example to show the state of another system on the deck.
State values:
| Value | Meaning |
|---|---|
1, "on", "true", "active", true | Force the active/feedback colour |
0, "off", "false", "idle", false | Force the idle colour |
"clear", "auto", "local", "release" | Drop the override; local logic takes over again |
Floats between 0.0 and 1.0 are rounded at 0.5.
Addressing by key number (1–32, counts from 1):
/fpress/streamdeck/feedback 5 1
/fpress/streamdeck/feedback/5 1
/fpress/streamdeck/5/feedback 1
Addressing by grid (row/column, counts from 0):
/fpress/streamdeck/feedback/1/2 1
/fpress/streamdeck/1/2/feedback "clear"
/fpress/streamdeck/feedback/all
Sets every key to the same state.
/fpress/streamdeck/feedback/all 1
/fpress/streamdeck/feedback/all "clear"
/fpress/streamdeck/feedback/clear
Drops all OSC overrides. No arguments.
/fpress/streamdeck/feedback/clear
/fpress/query
Asks the FrenschPress for its state. It replies with one or more /fpress/status/… messages, sent back to the address and port the request came from. Your receiver listens on the port it sent from.
/fpress/query
/fpress/query "mode"
With no argument you get all four replies. With a group name (device, mode, set or qlab) you get only that one.
Replies
| Message | Arguments |
|---|---|
/fpress/status/device | Device name · firmware version · MAC address · IP address |
/fpress/status/mode | Mode (qlab / macro / companion) · QLab transport (osc / msc) · internal transport code |
/fpress/status/set | Active button set (A / B / C) · the set per button as a letter sequence |
/fpress/status/qlab | Cue running (0/1) · paused (0/1) · QLab feedback subscribed (0/1) |
The FrenschPress replies at most once every 100 ms per sender and drops faster requests. It ignores requests from its own address.
If you drive the FrenschPress from Bitfocus Companion, you do not need to build these messages yourself. The Companion module handles querying and parsing.
Quick reference
/fpress/mode 2
/fpress/set "B"
/fpress/set "B" "stop,go,pause"
/fpress/preset "my-user-preset-12ab"
/fpress/preset "osc-qlab-basics:transport"
/fpress/button "go"
/fpress/button "stop" "press"
/fpress/macro "House Lights" "toggle"
/fpress/timeline/arm "Main Timeline"
/fpress/timeline/disarm_all
/fpress/led "stop" 255 0 0
/fpress/led 255 80 0
/fpress/led/release
/fpress/var "cue" "Blackout"
/fpress/var/clear
/fpress/streamdeck/button/0/0
/fpress/streamdeck/feedback/1/2 1
/fpress/streamdeck/feedback/clear
/fpress/query
/fpress/query "qlab"
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| No command arrives | Wrong port or wrong IP address | Check the port in Settings (default 53001) and send to the FrenschPress's IP address. |
/fpress/set does nothing | The FrenschPress is not in Custom Mode | Send /fpress/mode 2 first. |
/fpress/macro is rejected | The name matches more than one macro | Send the macro ID instead of the name. |
A button no longer behaves normally after press | The release is missing | Send /fpress/button … "release". |
/fpress/var is refused | The name starts with sys_, or all 64 slots are in use | Choose another name or clean up with /fpress/var/clear. |
/fpress/query gets no reply | The receiver listens on the wrong port, or requests arrive faster than every 100 ms | Listen on the sending port and query less often. |