# RackSanity — MIDI controller setup

This guide covers programming MIDI knobs and faders on controllers and keyboards
for RackSanity 0.2.4. Use your hardware's configuration software to choose its CC
numbers, then assign them to RackSanity with MIDI Learn.

## All available MIDI Learn targets

Each rack slot offers these nine assignable targets. The CC numbers below are
a suggested layout, not automatic fixed assignments. You may use other CC numbers
supported by your hardware; complete MIDI Learn for each target.

| RackSanity target | Suggested hardware control | Suggested CC | Values |
| --- | --- | --- | --- |
| Attack | Knob 1 | 1 | 0-127 |
| Decay | Knob 2 | 2 | 0-127 |
| Sustain | Knob 3 | 3 | 0-127 |
| Release | Knob 4 | 4 | 0-127 |
| Reverb | Knob 5 | 5 | 0-127 |
| Delay | Knob 6 | 6 | 0-127 |
| Detune | Knob 7 | 7 | 0-127 |
| Pitch | Knob 8 | 8 | 0-127 |
| Slot Volume | Fader or knob 9 | 9 | 0-127 |

The first eight targets control the plugin parameters assigned to those rack
knobs. Labels do not guarantee a matching parameter exists in every plugin;
assign the underlying parameter in RackSanity as needed. Slot Volume controls
that rack slot's level.

## Program and learn a controller

1. Configure each hardware knob/fader to send an absolute 7-bit MIDI CC with
   values 0-127. Use a distinct CC number for each target.
2. Connect the device and enable/select its MIDI input in RackSanity.
3. Load an instrument in the rack slot you want to control.
4. Right-click the RackSanity knob or slot-volume control and choose
   **Learn MIDI CC...** (or **Learn New MIDI CC...**).
5. Move the corresponding hardware knob/fader. Wait for the assignment message,
   then move it again to verify the intended control.
6. Repeat for the remaining targets and save the rack to retain its assignments.

To remove a mapping, right-click the target and choose **Clear Assignment**.
Learning the same CC onto another target in the same slot moves the assignment
to that target.

## Channels, multiple slots and plugin MIDI

Keyboard notes follow the rack slot's MIDI input and receive-channel settings.
Generic MIDI Learn currently identifies controls by CC number; it does not store
a separate controller/device or MIDI channel for each learned target. Use distinct
CC numbers across slots when you want independent hardware control. The same
learned CC on multiple slots can change all those slots; changing the hardware
channel alone does not isolate learned controls.

Learned CC messages also continue to the hosted plugin's ordinary MIDI path.
Choose CCs that do not conflict with that plugin's own MIDI assignments, or
configure the plugin accordingly.

The current generic Learn path has no automatic motor/display feedback and
does not learn rack-slot selection, snapshot navigation, Editor or Panic actions.
Those actions require an implemented controller profile; assigning their CC
numbers to an arbitrary keyboard/controller does not activate them.

## Controller profiles and future controller/keyboard list

Manual MIDI Learn provides the controller-neutral setup described above.
A list of MIDI controllers and keyboards is future work; its exact UI and
profile scope remain to be defined.

The existing
[Roto-Control setup and complete native CC reference](https://www.racksanity.com/downloads/ROTO_CC_REFERENCE.md)
is a separate device-specific profile with motor feedback and command buttons.
Its fixed addresses apply to the recognized Roto-Control input. Keep that
hardware profile separate from generic MIDI Learn assignments.

## Keyboard shortcuts

Use the Mac **Control** key, not Command. Use the minus and equals keys without
Shift for slot navigation. These shortcuts use the tested US Mac keyboard layout.

| Shortcut | Action |
| --- | --- |
| Control+P | MIDI Panic |
| Control+B | Open instrument browser / load highlighted instrument |
| Control+N | Add and select an empty slot |
| Control+Minus / Equals | Previous / next existing slot |
| Control+Shift+Left / Right | Previous / next saved Sound Snapshot |
| Control+E | Open / close selected instrument editor |
| Control+S | Save Rack dialog |
| Control+L | Load Rack dialog |
| Escape | Cancel instrument browser |

These shortcuts apply to RackSanity windows; Control+P also works in protected
plugin editor windows. Exact modified combinations are reserved even in search
fields; ordinary typing remains available. Held shortcuts trigger once. Save and
Load open the existing dialogs and are ignored while the instrument browser is
open. Slot/snapshot navigation, Add Slot and Editor are also blocked during
browsing. Press Escape to cancel first. Snapshot navigation uses RackSanity's
saved Sound Snapshots, not a plugin's factory-preset bank.

## Release files

[Release notes](https://www.racksanity.com/release-notes.html) · [Roto CC reference](https://www.racksanity.com/downloads/ROTO_CC_REFERENCE.md) · [Roto 0.2.3 profile](https://www.racksanity.com/downloads/RackSanity-0.2.3-Roto.json) · [Checksums](https://www.racksanity.com/downloads/SHA256SUMS)

RackSanity 0.2.4 is a Developer ID signed, notarized Universal macOS build.
Public Beta access requires approval; approved testers receive the download link
and a 21-day authorization key by email.