# Combinator layout file

> A field-by-field reference for the JSON file that names, hides and colours a Combinator's rotaries and buttons.

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

A layout is one JSON file per patch, or per family of patches. It lives outside the plugin, so a plugin update does not delete it:

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

How to create one, and how matching works, is in [Combinator layouts](https://www.reasonremote.com/guide/combinator-layouts/). This page is the file itself.

## Creating and editing

- **Press **Layout** twice** on the Combinator page. The plugin writes a file named after the Combinator, filled with Reason's names, and opens it.
- **Press once** to open the current file. **Hold** to open the folder.
- In the Stream Deck app, select a Combinator dial. Its settings list that dial's eight rotaries, each with a label, a show or hide switch, and a ring colour. A pad's settings edit the button it shows. Both write this same file.
- When no file matches, the plugin can build one from the `.cmb` patch file. The **Layout** key shows that as *generated*. Edit it and the plugin will not overwrite your copy. **Generate from patch file** builds it again. Delete the file to go back to Reason's names.

Factory Sound Bank patches can't be read. Add other folders in the **Layout** key's settings, one path per line. The two folders it always searches are:

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

## An annotated file

This is the shape the guide's [layouts page](https://www.reasonremote.com/guide/combinator-layouts/#the-file) already uses. Comments below the sample are the fields. JSON itself has no comments, so don't paste the notes into the file.

```
{
  "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 }
}
```

| Field | What it does |
|---|---|
| `v` | File version. The plugin writes `1`. |
| `name` | A name for the layout. Matching does not use it. Matching uses `match` and `pinDevice`. |
| `match.patch` | Patch names this layout wins for, exactly. Checked first. |
| `match.prefix` | If the patch name starts with one of these, this layout matches. The longest prefix wins. `co-operator` matches `co-operator - beat berlin`. A new file's prefix is the patch name before its last ` - `. |
| `rotaries` | Rotaries you want to change. `n` is Reason's number, 1–32. A rotary you leave out keeps Reason's name. |
| `buttons` | The same, for the 32 buttons. |
| `label` | The name on the dial or the pad. |
| `visible` | Leave it out and the deck shows the control when the patch uses it. `true` always shows it. `false` always hides it. |
| `ring` | A rotary's ring colour, `#RRGGBB`. |
| `color`, `onColor` | A button's colours. Buttons don't use `ring`. |
| `theme` | Colours for the whole layout. The keys the plugin reads are `ring`, `ringTrack`, `dialBg`, `pointer`, `titleFg`, `valueFg`, `selected`, `padFace`, `padLit` and `padText`. |
| `backdrop` | A PNG in the layouts folder. The plugin takes a colour scheme from it. Anything you set in `theme` wins. |
| `art.strip` | A PNG drawn behind the four dials. |
| `art.pads` | `true` puts a piece of that image on each pad. |

`pinDevice` is not in the sample. It is a string, the Combinator's name in the rack. A layout with `pinDevice` applies to that device whatever patch it holds, but only after patch and prefix rules have failed. Use it for a Combinator that stays on one kind of patch.

```
{ "v": 1, "name": "my rack unit", "pinDevice": "Bass Combo", "rotaries": [] }
```

## What you see on the deck

Hidden buttons close up, so the pads read left to right with no gaps. When every rotary in a row is hidden, that row drops off the dials. A row is four rotaries: 1–4, then 5–8, and so on. See [the Combinator dials](https://www.reasonremote.com/guide/combinator/#the-dials).

If the JSON is wrong, the **Layout** key says so, for example `Layout error: line 12`. The deck keeps the last file that parsed.

Reason tells the deck which controls the patch uses when you **select** the Combinator, not when you load a patch. After a patch change, click another device and back, or turn on **Re-target the Combinator after a patch change** in the Layout key's settings. The track selection may blink.

## Sharing and updates

Copy the `.json` and any PNGs it names. On another computer they go in the same layouts folder. Matching is by patch name, so the file works for anyone who loads that patch.

Reinstalling or updating the plugin does not touch this folder. Exporting a Stream Deck profile does not include it either. Back the folder up yourself if you care about the files.

---

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