Mapping concepts

Imagine someone tells you: "Change the volume to -6 dB!" You go ahead and move the fader to -6 dB.

That’s absolute control in a nutshell! Absolute control uses absolute control values.

Imagine someone tells you: "Raise the volume by 2 dB!" You go ahead and move the fader up by 2 dB. Before it was -6 dB, that means it’s -4 dB now.

That’s relative control! Relative control uses relative control values.

A Control element is absolute if it emits absolute values. You can think of an absolute value as a percentage: The value is something between 0% and 100%, where 0% represents the minimum possible value and 100% the maximum.

A Control element is relative if it emits relative values. You can think of a relative value as an instruction. It can be one of the following two instructions:

An absolute control value is conceptually a percentage between 0.0% and 100.0%.

Internally, it is represented by a high-precision floating point number between 0.0 and 1.0. E.g. 0.25 is 25%.

A relative control value is a number of increments or decrements.

Internally, it is represented as a positive or negative integer. E.g. control value -2 means a decrement of 2.

This mode is comparable to modifier keys on a computer keyboard. For example, when you press Ctrl+V for pasting text, Ctrl is a modifier because it modifies the meaning of the V key. When this modifier is "on" (= pressed), it activates the "paste text" and deactivates the "write the letter V" functionality of the V key.

In ReaLearn, the modifier is one of the FX parameters. It’s considered to be "on" if the parameter has a value greater than 0 and "off" if the value is 0.

You can choose up to 2 modifier parameters, "Modifier A" and "Modifier B". If you select "<None>", the modifier gets disabled (it won’t have any effect on activation). The checkbox to the right of the dropdown lets you decide if the modifier must be "on" for the mapping to become active or "off".

Example: The following setting means that this mapping becomes active only if both "Parameter 1" and "Parameter 2" are "on".

Now you just have to map 2 controller buttons to "Parameter 1" and "Parameter 2" via ReaLearn (by creating 2 additional mappings - in the same ReaLearn instance or another one, up to you) et voilà, it works. The beauty of this solution lies in how you can compose different ReaLearn features to obtain exactly the result you want. For example, the absolute mode of the mapping that controls the modifier parameter decides if the modifier button is momentary (has to be pressed all the time) or toggled (switches between on and off everytime you press it). You can also be more adventurous and let the modifier on/off state change over time, using REAPER’s automation envelopes.

This is the correct activation mode if you want control surface "bank-style" mapping.

You can tell ReaLearn to only activate your mapping if a certain parameter has a particular value. The particular value is called "Bank". Why? Let’s assume you mapped 2 buttons "Previous" and "Next" to increase/decrease the value of the parameter (by using "Incremental button" mode, you will learn how to do that further below). And you have multiple mappings where each one uses "When bank selected" with the same parameter but a different "Bank". Then the result is that you can press "Previous" and "Next" and it will switch between different mappings within that parameter. If you assign the same "Bank" to multiple mappings, it’s like putting those mappings into one group which can be activated/deactivated as a whole.

Switching between different programs via "Previous" and "Next" buttons is just one possibility. Here are some other ones:

In previous versions of ReaLearn you could use other methods to achieve a similar behavior, but it always involved using multiple ReaLearn instances:

With Conditional activation you can do the same (and more) within just one ReaLearn unit.

This is for experts. It allows you to write a formula in EEL2 language that determines if the mapping becomes active or not, based on potentially all parameter values. This is the most flexible of all parameter-based activation modes. The other modes can be easily simulated. The example modifier condition scenario mentioned above written as formula would be:

y represents the result. If y is greater than zero, the mapping will become active, otherwise it will become inactive. p1 to p100 contain the current parameter values. Each of them has a value between 0.0 (= 0%) and 1.0 (= 100%).

This activation mode accounts for ReaLearn’s philosophy to allow for great flexibility instead of just implementing one particular use case. If you feel limited by the other activation modes, just use EEL.

This is very similar to the previous EEL activation mode. But instead of EEL, it lets you use the same expression language as used in dynamic selectors to express the activation condition.

The equivalent expression to above EEL example is:

p[0] > 0 && p[1] > 0

This is different from all the other activation condition types in that it doesn’t look at ReaLearn’s internal parameter values. Instead, it looks at the target of another mapping (the so-called "lead mapping") and switches our mapping (the so-called "follow mapping") on or off depending on the target value of the lead mapping.

It works like this:

You can detect an inactive target by using y == none.

In its most basic form, the pattern is a sequence of bytes notated as hexadecimal numbers. This is typical notation, especially for system-exclusive MIDI messages.

Remarks:

ReaLearn also supports binary notation of a byte. You need to enclose the binary digits of one byte in brackets.

Remarks:

For the Feedback direction, the examples I’ve shown you so far aren’t real-world examples, because there’s no point in sending the same MIDI message to the device over and over again! If you really would want to send a constant MIDI message to the device, you would be much better off using a Mapping lifecycle action, which allow you to send raw MIDI messages once when a mapping is initialized, not on every target value change.

But even for the Control direction, you might want to react to a whole range of system-exclusive messages, not just a fixed one. One part of your message might represent a variable value. You might want to extract it and control the target with it.

Fortunately, ReaLearn offers a uniform way to extract a variable value from the raw MIDI message (control) or encode the current target value into the raw MIDI message (feedback). Bytes which contain a variable value (or a part of it) must be expressed using binary notation.

Each letter represents one bit of the variable value:

The resolution of the variable value always corresponds to the letter in the whole pattern which represents the highest bit number. In the example above, the resolution is 4 bit because there’s no letter greater than d in the pattern.

Remarks:

This form of notation is slightly unconventional, but I think it’s very flexible because it gives you much control over the resulting MIDI message. This amount of control seems appropriate considering the many different ways hardware manufacturers used and still use to encode their MIDI data.

When a number is expressed within more than one byte, manufacturers sometimes put the most significant byte first and sometimes the least significant one, there’s no rule. This notation supports both because you decide where the bits end up: