# Combinator layouts

> Name a Combinator's rotaries and buttons, hide the ones you don't use and set colours and artwork, with one small file per patch.

Source: https://www.reasonremote.com/guide/combinator-layouts/  
Applies to: Reason Remote 1.4.0, Reason Remote Lite 1.3.0

A **layout** tells the deck what a Combinator's controls are called. It's one small JSON file per patch or family of patches, with your labels, which controls to show, and optionally colours and artwork.

Layouts live outside the plugin, so they survive plugin updates and reinstalls:

```
%APPDATA%\Automate Pros\Reason Remote\layouts\
```

You often don't need to write one. When nothing matches a patch, the plugin reads the patch file and builds a layout from it. See [Layouts built from the patch](#layouts-built-from-the-patch).

## The Layout key

The **Layout** key on the [Combinator page](https://www.reasonremote.com/guide/combinator/) shows which layout is in use.

| Gesture | What it does |
|---|---|
| Press once | Opens the layout file in your editor |
| Press twice | Creates a layout for the selected Combinator and opens it |
| Hold | Opens the layouts folder |

## Making a layout

1. Select the Combinator in Reason.
1. Press **Layout** twice. The plugin writes a file named after the Combinator, filled in with Reason's names, and opens it.
1. Change the labels and save. The deck redraws straight away. There's no need to reinstall anything or restart Reason.

You can also edit a layout from the Stream Deck app. Select any Combinator dial and its settings list that dial's eight rotaries, with a label, a show/hide setting and a ring colour for each. A pad's settings edit the button it shows. Both write to the same layout file.

## The file

Field by field, including `pinDevice` and what happens when the JSON is wrong, is the [layout file reference](https://www.reasonremote.com/guide/combinator-layout-file/). The sample below is the same one that page annotates.

```
{
  "v": 1,
  "name": "co-operator",
  "match": { "patch": ["co-operator - 0 init"], "prefix": ["co-operator"] },
  "rotaries": [
    { "n": 1, "label": "Speed", "ring": "#3CB371" },
    { "n": 2, "label": "Pattern" },
    { "n": 9, "visible": false }
  ],
  "buttons": [
    { "n": 1, "label": "Seq On" },
    { "n": 4, "visible": false }
  ],
  "theme": { "ring": "#e8a33c", "padFace": "#2a2e33" },
  "backdrop": "co-operator.png",
  "art": { "strip": "co-operator.png", "pads": true }
}
```

| Key | What it does |
|---|---|
| `rotaries`, `buttons` | One entry per control you want to change, by Reason's number `n` (1–32). Controls you leave out keep Reason's name. |
| `label` | The name the deck shows |
| `visible` | `false` always hides the control, `true` always shows it. Leave it out to let Reason decide. |
| `ring` | A rotary's ring colour. Buttons take `color` and `onColor`. |
| `theme` | Colours for the whole layout: `ring`, `ringTrack`, `dialBg`, `pointer`, `titleFg`, `valueFg`, `selected`, `padFace`, `padLit`, `padText` |
| `backdrop` | A PNG next to the layout file. The plugin takes a colour scheme from it. Colours in `theme` win. |
| `art.strip` | A PNG drawn behind the four dials. `art.pads: true` puts a piece of it on each pad too. |

If the file has a mistake, the **Layout** key says so, for example `Layout error: line 12`. The deck keeps using the last version that worked.

## Which controls are shown

Reason tells the deck which rotaries and buttons the patch uses, and the deck hides the rest. A layout can override that for each control:

| In the file | Result |
|---|---|
| No `visible` | Shown when the patch uses the control |
| `"visible": true` | Always shown |
| `"visible": false` | Always hidden |

When every rotary in a row is hidden, the row disappears from the dials. Hidden buttons close up, so the pads read left to right with no gaps.

> **Note:** Reason reports which controls a patch uses when you select the Combinator, not when you load a patch. After changing patch, click another device and back to refresh it. Or turn on **Re-target the Combinator after a patch change** in the **Layout** key's settings, and the plugin does it for you. You may see the track selection blink.

## Which layout is used

Layouts are matched by **patch name**, because the patch is what draws the panel. The first of these wins:

1. A layout that lists the patch name in `match.patch`
1. The layout with the longest `match.prefix` that the patch name starts with. `co-operator` matches `co-operator - beat berlin`.
1. A layout whose `pinDevice` is the Combinator's name in the rack
1. A layout built from the patch file
1. Reason's names

A new layout's prefix is the part of the patch name before its last ` - `, which is how most preset families are named.

`pinDevice` ties a layout to one Combinator in the rack, whatever patch it has. It's handy for a Combinator you never load a different kind of patch into. If you do, its labels will be wrong until a patch rule takes over.

## Layouts built from the patch

When no layout matches, the plugin looks for the patch's `.cmb` file and builds a layout from its Programmer: the labels, which controls are on the panel, and the panel backdrop if it has one. The **Layout** key shows it as *generated*.

It looks in these folders, including their subfolders:

- `%USERPROFILE%\Music\Reason Studios\User Library`
- `%APPDATA%\Propellerhead Software\Packs`

Add other folders in the **Layout** key's settings, one per line. Patches in Reason's Factory Sound Bank can't be read, so they keep Reason's names.

A built layout is an ordinary file. Edit it like any other, and the plugin won't overwrite it. To build it again, for example after changing the patch, press **Generate from patch file** in the **Layout** key's settings. Delete it to go back to Reason's names. To stop building layouts, turn off **Generate layouts from the patch file**.

## Sharing a layout

Copy the `.json` file, and any images it uses, next to the `.cmb` you share. On another computer they go in the same layouts folder. Matching is by patch name, so the layout works for anyone who loads that patch.

---

Not affiliated with, or endorsed by, Reason Studios AB or Elgato. Reason and all Reason device names are trademarks of their respective owners.