> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gridshift.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Controller Profiles

> Map a whole MIDI controller in one guided pass. The wizard learns your knobs, buttons, and encoders into a named per-device profile that follows the focused track and syncs across your Macs.

[MIDI Bindings](/features/midi-bindings) learn one control at a time from the Command Palette. **Controller Profiles** are the other way in: a guided **wizard** maps a whole controller in a single pass and saves the result as a **named, per-device profile** that activates automatically whenever that controller is connected.

Any class-compliant MIDI controller works — no vendor scripts, no config files.

## Bindings or a profile?

|               | [MIDI Bindings](/features/midi-bindings)                     | Controller Profiles                                             |
| ------------- | ------------------------------------------------------------ | --------------------------------------------------------------- |
| Setup         | One control at a time, from the palette                      | The whole controller in one guided pass                         |
| Knobs control | The exact parameter you learned                              | The **focused track's** mixer controls — follows your selection |
| Buttons run   | Any single command you pick                                  | A fixed set of transport / edit / navigation commands           |
| Stored as     | Command bindings (global) + parameter bindings (per project) | One named profile per device                                    |
| Turns on      | Always                                                       | Whenever that device is connected                               |

Use bindings for a one-off ("this knob drives that plugin's cutoff"). Use a profile to set a controller up once and have it drive whatever track you're working on.

## Creating a profile

<Steps>
  <Step title="Open Settings ▸ MIDI">
    Every connected controller is listed under **Connected MIDI Devices**.
  </Step>

  <Step title="Click “Create Profile for <device>…”">
    The wizard opens. **Only touch the controller you're mapping** — while the window is open, input from *all* MIDI devices is captured, so nothing you press leaks through to instruments or existing bindings.
  </Step>

  <Step title="Work through the steps">
    For each control, do what the instruction says — press the button, or slowly turn the knob or encoder. The step captures the first control it sees, marks it with a green check, and moves on.
  </Step>

  <Step title="Skip what you don't have">
    **Skip** passes on a single control; once you reach the optional extras, **Skip Rest** jumps straight to the end. A two-knob controller isn't forced to click through fourteen optional steps. **Back** redoes the previous step.
  </Step>

  <Step title="Name it and Save Profile">
    The summary shows how many controls were mapped. Give the profile a name (defaults to the device name) and save. It's pinned to that device right away.
  </Step>
</Steps>

<Note>
  The wizard watches each turning control and tells an **endless encoder** (relative) from a **fixed-range knob** (absolute) on its own, labelling each as it's captured. Either kind works — if a device fools the detector, press **Back** and redo the step.
</Note>

## What the wizard maps

The flow covers the essentials first, then an optional block of extras. Everything acts on the **focused track** — whichever track you have selected (or, in [Focus Mode](/features/focus-mode), the focused clip's track).

### Buttons → commands

|               | Control                                                              | Command                               |
| ------------- | -------------------------------------------------------------------- | ------------------------------------- |
| **Essential** | Play / Stop, Record, Loop, Undo                                      | Transport & edit                      |
| **Optional**  | Mute, Solo, Quantize, Redo, Metronome, Octave up / down              | Focused track & edit                  |
| **Optional**  | Browse open / confirm, Browse back / close, Connect automation track | Navigation (see below)                |
| **Optional**  | Cursor forward / backward                                            | Move the edit cursor by one grid step |

### Knobs → the focused track's mixer

|               | Knob role                                                           |
| ------------- | ------------------------------------------------------------------- |
| **Essential** | Volume, Pan                                                         |
| **Optional**  | Mid gain, Side gain, Mono-below cutoff, Ceiling, Clip-mode selector |

Because these are **roles**, not fixed parameters, the same volume knob always rides the track you're currently on — select a different track and the knob follows.

### Encoders → navigation

The main encoder is **context-aware**:

* With nothing open, turning it **selects tracks** — right for next, left for previous.
* With the [Command Palette](/features/command-palette) or a picker open, it **scrolls that list**.
* The **Browse: open / confirm** button opens the palette and confirms the highlighted entry; **Browse: back / close** steps back a level or closes it.
* **Connect automation track** opens the automation picker for the last-touched parameter — browse it with the encoder, confirm to bind.

Together these let you select a track, open the palette, scroll to a command, and run it without touching the keyboard. An optional **Cursor jump** encoder moves the edit cursor by grid steps the same way.

## Managing profiles

Back in **Settings ▸ MIDI**:

**Connected MIDI Devices** — each device shows a picker and its current state:

| Picker choice                 | Effect                                                                                                    |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Auto-detect** (recommended) | Uses the installed profile whose name matches the device. The label shows what it matched, or "no match". |
| **No profile**                | The device routes as plain MIDI — instruments and Learn bindings only.                                    |
| A specific profile            | Pins that profile to this device explicitly.                                                              |

The row reads **"N binding(s) active"** or **"Routes as plain MIDI"**, and notes **"N ports"** for controllers that expose several (many do — a single device often shows up as separate DAW / MIDI / plugin ports). A profile is applied across all of a device's ports at once, and is only active while the device is connected.

**Installed Profiles** — lists every profile with its binding count and an **Active** badge when it's in use. Delete your own profiles with the trash button. Re-running "Create Profile…" for a device **replaces** its profile of the same name, so refining a mapping is just running the wizard again.

## How profiles rank against MIDI Learn

When a control arrives, Gridshift resolves it in order:

1. The **wizard**, but only while it's open (so setup never fires anything).
2. **[MIDI Learn](/features/midi-bindings) command bindings**, then learned parameter bindings.
3. The device's **controller profile**.
4. The **focused instrument** (the control plays as ordinary MIDI).

So an explicit MIDI Learn binding always wins over the same control in a profile — handy for overriding one button without editing the profile.

## Sync across your Macs

Controller profiles live in [iCloud](/features/icloud). A profile you create on one Mac appears on the others while both are signed in — and, like presets and monitor profiles, a profile saved on one machine shows up on another that's already open.

## Requirements & limits

* **Class-compliant controllers only.** Any knob/button/pad controller that appears as a standard MIDI device works.
* **No LED / motor feedback.** Profiles send nothing back to the controller, so LED rings and motorised faders won't reflect Gridshift's state. Bidirectional "DAW mode" needs per-vendor support and isn't offered.
* **7-bit resolution.** Standard CC values; high-resolution 14-bit CC isn't used.
* MCU / HUI control surfaces aren't supported — profiles target the knob-and-button class of controller.