Configuring the Stream Deck
On the Streamdeck page of the web interface you map the deck's keys, choose its displays and save complete mappings as layouts. The page appears in the navigation as soon as a supported Stream Deck is detected; without a deck it is hidden. How to connect the deck is described under USB Host & Supported Devices.
The grid in the browser is built from the geometry the deck reports. It is not tied to one model.
Device card
| Control | Function |
|---|---|
| Deck / LEDs | Two brightness faders, 0–100 %, linkable with the link button |
| Logo backdrop (under Display options) | Draws the FrenschConnection logo across unmapped, unlabelled keys as one continuous graphic |
| Timecode display | Reserves a key row as a timecode readout, with row selection, digit colours and display size |
| STOP/GO/PAUSE display | Mirrors the three device buttons onto the deck |
| QLab standby display | Shows the standby cue and the running cue from QLab, with row selection |
The brightness faders are to the right of the grid. The displays are under Display options below the grid and are described under Display rows. Changes to these deck settings save immediately.
By default, the deck and the panel LEDs share one value. Every control then changes the same brightness: the faders here, the LED slider in Settings, hold STOP + turn the encoder, the BRT+/BRT- keys in the tools menu, and a Companion BRIGHTNESS message.
The link button next to the two faders breaks that coupling. The deck and the LEDs then each keep their own level. This is meant for a deck sitting under a work light while the LEDs run in a blacked-out house.
The deck maps the value onto its own 0–100 scale with a floor of 10 %, so its EXIT key stays readable even when the LEDs are dimmed further.
Layouts
A layout is the complete deck configuration as a named state. It contains:
- every page with its key and encoder mappings, labels, colours, image references and feedback settings,
- the display rows with their row selection, timecode colours and size,
- the logo backdrop and the last touchbar view.
Not included are brightness and anything that is not about the deck. A layout swaps the deck's mapping, not the state of the FrenschPress.
The controls are to the right of the grid under Layouts:
| Control | Function |
|---|---|
| Name field | Shows the current layout name and opens the layout list with Apply, Rename, Delete. New Layout there means the current state is not saved. |
| Save as Layout | Stores the current state under a new name |
| Update Layout | Overwrites the loaded layout with the current state. Greyed out on New Layout. |
| Image storage | Opens the management of the key images on the USB 2 board |
The list also has a New Layout entry. It resets the deck to an empty state without changing any stored layout.
Recalling a layout
| Route | How |
|---|---|
| Web interface | Click the name field → pick a layout → Apply |
| Stream Deck | Tools menu → DISP → LOAD LAY → tap a layout |
A layout loads on one tap. It replaces the entire deck configuration. The previous state is gone unless you saved it as a layout first.
Limits
- Twelve layouts per device family. Beyond that, the FrenschPress refuses to save and shows a message.
- Layouts belong to a device family. A layout you stored for a Stream Deck Mk.2 does not appear on a Stream Deck + and cannot be loaded there. A different geometry would scatter the macros across unrelated keys.
- Key images do not travel with a layout. They live in the shared image store on the USB 2 board, and a layout only references them. That is why Delete unused images removes only images used neither by the current configuration nor by any stored layout.
Mapping keys
- Click a key in the grid. The key editor opens.
- Under Key action, choose what the key does. For a macro, leave it on Macro.
- Choose a Macro and enter the Button text.
- Set a colour or image for Idle and Active / Feedback, and an Icon if you like.
- Confirm with Save.
| Field | Meaning |
|---|---|
| Key action | Macro, Next page, Previous page, Go to page or Switch Set. The page actions step through the pages and wrap around at the end. Switch Set switches all FrenschPress buttons and encoders to set A, B or C without changing the deck page. |
| Destination page / Target button set | Target for Go to page or Switch Set |
| Apply to this key on all pages | Puts the action on the same position of every page. Display keys are not replaced. New pages inherit these actions. |
| Macro | Select a macro or create one via Quick Create / Multi-Step, exactly as in Custom Mode |
| Button text | Label. The field accepts up to 48 characters, but far less fits on a key, see Text rendering. The $ button beside it inserts a variable. |
| Idle | Colour or image for the resting state |
| Active / Feedback | Colour for the active state, or the inverted idle image via Invert idle |
| Invert idle | Derives the feedback image from the idle image, inverted, see Key images |
| Icon | One of 89 built-in symbols (play, pause, mute, arrows, feature groups, grandMA3 console keys …) instead of an image. The text then sits in the upper third and the icon fills the lower two thirds. Icons from “gobo” onwards need the current USB 2 firmware. |
| Show fade progress | Shows a running Art-Net/sACN fade as a bar on the key, see Fade display |
| Feedback | Turns state switching for this key on or off |
The grid preview shows each key's label, background and feedback. Coordinates start at 0,0 in the top-left corner.
- Moving: drag a key to another position. If that position is already assigned, the two swap.
- Reserved displays cannot be moved.
- The tools key (logo) can be dragged to another position. It stays reserved and sits in the same place on every page. Whatever was there moves to its old position.
- Moves apply immediately; key-editor changes only apply with Save.
Hold an unassigned key for 2 seconds. The macro list for that key opens on the deck. Keys that already carry a macro are changed or cleared in the tools menu under MAP.
Colour and feedback model
| Situation | Behaviour |
|---|---|
| Feedback off | The key stays idle at all times |
| Normal macro, feedback on | Active while the key is held, back to idle on release |
| Toggle macro / toggle sequence | Active is retained after release and returns to idle when toggled off |
| Unmapped or failed | Stays idle. There is no separate error colour. |
A Stream Deck loses its display contents when disconnected. That is why the FrenschPress rewrites the full state to the deck after every reconnect.
Setting feedback over OSC
You can also set a deck key's state from outside. This is useful when the target system, not the FrenschPress, knows whether something is on or off. A lighting console can colour the key that fires its scene.
The commands are documented under OSC remote control: /fpress/streamdeck/feedback for one key, /fpress/streamdeck/feedback/all for all of them, and /fpress/streamdeck/feedback/clear to hand control back to the key itself. A page switch drops any overrides in place.
Variables in a label
A label may contain a $name, for example CUE $sys_cue. The key then shows the current value. This also applies to the Stream Deck + encoder labels. How to insert variables with the $ button is described under Inserting a variable into a caption.
Text rendering
- One word per line, at most 6 lines, so six words maximum. Wrapping happens on spaces.
- Realistically about 5 characters fit per line in the large face, three such lines on a 72 px key. A longer word drops the whole label to the small face (around 11 characters per line), so short words stay considerably more readable.
- A space is a deliberate line break. That is how you put a caption over a value.
- A word that does not fit even at the smallest size is truncated, not wrapped.
- ASCII 32–126 is supported, including lowercase. Any other character becomes
?. - Text colour follows the background luminance automatically, so contrast stays correct.
- Keys in a group (macro labels, the menu) render at one shared glyph size, so a page is not built from five different sizes.
If a host cannot transfer images, the key is filled with the background colour instead. The configuration remains valid either way.
Key images
- On the Idle card, switch from Colour to Image.
- Select a file with Choose image….
- For Active / Feedback, choose a colour or Invert idle. Invert idle derives the feedback image from the idle image, with no second file needed.
You can check and remove existing image assignments through their previews.
All the preparation happens in the browser:
- Any image format the browser can open (PNG, JPG, …) is accepted.
- The image is cropped square from the centre (never squashed) and scaled to the key's pixel size.
- Transparent areas of a PNG take the colour of that slot as their background.
- The label is rendered into the image: light on dark, dark on light, each with an outline. You can change the text later without picking the file again.
- The result is stored as a JPEG, compressed automatically until it fits the 8 KB per key limit.
Fade display
With Show fade progress enabled in the key editor, the key fills from the bottom while an Art-Net or sACN fade belonging to that macro runs.
The bar's height is the current output level, not elapsed time:
| Situation | Bar |
|---|---|
| Fading in | rises |
| Fading out | falls |
| Pressed mid-fade | reverses from its current height instead of jumping |
| Fade finished | The key returns to its normal look |
It is drawn in the key's own colours: idle colour as the background, active colour as the fill. The label stays readable. Snapshot fades are shown the same way.
The option is off by default. It is greyed out as soon as the key carries an image, because a bar cannot be drawn over a picture.
The bar also appears when you use the encoder as a master fader. While you turn, the key shows the level you have set.
Display rows
Three readouts can claim keys on the deck: timecode, STOP/GO/PAUSE and QLab standby.
- Open Display options below the grid.
- Turn on the readout you want.
- Under Pages, choose which deck pages show it.
- Under Row, choose its key row, where the readout offers this.
Reserved keys run no macros, neither from the deck nor over OSC. Their stored mappings stay intact and return as soon as you switch the readout off or move it to another row.
On the Stream Deck +, STOP/GO/PAUSE and QLab standby claim no keys. They appear on the touchbar instead.
Timecode
With the timecode display on, the selected row reserves its keys as a readout:
| Deck width | Layout |
|---|---|
| 4 columns | HH MM SS FF |
| 5+ columns | STATUS/SOURCE HH MM SS FF |
- The status/source field has a white background with black text and names the source: USB 1, USB 2, MTC Master or Art-Net.
- The four numeric fields are black. The digits are white (stopped), green (running) or orange (paused).
- USB 2 updates the values locally from the running MTC stream. Only digits that changed are redrawn.
The last row is not offered: by default it holds the key for the tools menu. Displays never cover the tools key, even after you have moved it.
Colours and style
You can set the digit colours for Stopped, Running and Paused freely. Reset restores the defaults.
Size selects the rendering:
| Setting | Rendering |
|---|---|
| Medium | Standard face |
| Large | Large face |
| Digital clock | Clock-style digits |
| Digital clock large | Clock style, large face |
STOP/GO/PAUSE
By default, the middle three keys of the last row mirror the three FrenschPress device buttons. Use Row to select another available row. Each of the three keys takes the LED colour of its device button and, in Custom Mode, also the name of the macro mapped to it.
That way you see on the deck what the FrenschPress is doing without looking over at it.
The readout needs a deck at least five columns wide. On the Stream Deck + it appears on the touchbar.
QLab standby
Three keys of the selected row show what QLab is doing:
| Field | Content |
|---|---|
| Link | Whether QLab is reachable |
| Standby | The cue on standby, with number and name, in that cue's own colour |
| Running | The running cue with its remaining time |
The readout only works when the FrenschPress is connected to QLab over OSC (see QLab Mode – network connection). MIDI/MSC has no return channel.
If QLab stops answering for more than 1.5 seconds, the Link field turns red. The other two fields hold their last state. That way you can tell a lost connection from a show that is simply standing still.
The readout needs a deck at least four columns wide. On the Stream Deck + it appears on the touchbar.
Stream Deck +
The Stream Deck + adds four knobs and a touch strip.
| Control | Can be mapped to |
|---|---|
| Encoder push | Its own macro (press/release like a key) |
| Encoder CW / CCW | One macro each, executed per detent |
| Touch strip | Four fields with text labels; tap, long tap, swipe left/right |
Each touch strip field shows only the zones actually in use. An encoder used only for turning gets the full height for its two directions instead of a blank band:
push + turns turns only push only
+----------------+ +--------+-------+ +----------------+
| PUSH | | CCW | CW | | |
+--------+-------+ | | | | PUSH |
| CCW | CW | +--------+-------+ | |
+--------+-------+ +----------------+
Touch gestures are deliberately additional: every gesture is also reachable from a knob or a key. Glass gives no tactile feedback, and a mis-touch during a show is expensive.
Touchbar views (carousel)
The touchbar always shows exactly one view. A swipe left or right steps to the next one:
| View | Appears when |
|---|---|
| Encoder labels | an encoder on the active page is mapped |
| Timecode | the timecode readout is switched on |
| STOP/GO/PAUSE | the STOP/GO/PAUSE readout is switched on |
| QLab standby | the QLab standby readout is switched on |
Only enabled views are in the carousel. With just one enabled, swiping does nothing. Small chevrons at the edges show that there are more views to swipe to.
The selected view is remembered. It comes back after a restart, after closing the tools menu, and after unlocking.
On the Stream Deck +, STOP/GO/PAUSE and QLab standby cost no keys; the touchbar is their place. On every other deck they claim a row.
Pages
A deck can hold up to four pages. Pages work on every supported deck.
| Property | Per page | Shared |
|---|---|---|
| Key and encoder mappings | ✔ | |
| Key images | ✔ | |
| Brightness | ✔ | |
| Display rows | Selected pages | Settings shared across pages |
| Reserved keys | ✔ |
Paging
- To page, assign any key the Key action Next page, Previous page or Go to page. With Apply to this key on all pages they sit in the same place on every page. Former fixed
PG+/PG-keys become such assignments automatically on update and can then be moved or changed. - What a short press on the tools key does is set under Display options → Tools button short press: None, Change page (one page forward) or Switch button set (set A → B → C). Holding for 2 seconds always opens the tools menu.
What happens on a page switch
- Keys that are held are released: their release action runs. Pending encoder actions and OSC feedback overrides are cleared so nothing triggers accidentally on the new page.
- Toggle states are retained per page. A toggled-on key is active again when you page back to it. That state lives in RAM only, so a restart or a deck reconnect clears it.
- The selected page is saved 1.5 s after the last switch. After a restart, the deck comes back on the same page.
Adding and removing pages: new pages are appended at the end. Only the last one can be removed.
In the browser you always edit the active page. If you select a different page in the browser, the deck switches with it. What you edit is always what the deck shows.
Lock mode
The FrenschPress lock mode has priority over everything happening on the deck.
- Entering lock releases held deck macros and cancels pending actions.
- The normal key display disappears.
LO CK EDis shown across the middle three keys. - Keys, encoders and virtual OSC actions are ignored until you unlock.
- After unlocking, the FrenschPress restores mappings, retained feedback, timecode and the tools key from their current state.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The Streamdeck page is missing from the navigation | No supported deck detected | Check the connection, power and USB host mode, see USB Host & Supported Devices |
| A key does not fire its macro | The key is reserved for a readout | Turn the readout off or move it to another row, see Display rows |
| Show fade progress is greyed out | The key carries an image | Choose a colour instead of an image for Idle |
| Update Layout is greyed out | No layout is loaded (New Layout) | Use Save as Layout |
| Saving a layout is refused | The limit of twelve layouts for this device family is reached | Delete or overwrite a layout |
| A layout is missing from the list | It belongs to another device family | Load it on a matching deck, see Limits |
| The QLab Link field is red | QLab has not answered for more than 1.5 seconds | Check the OSC connection to QLab |