Unit concepts

Letting through events

ReaLearn by default "eats" incoming MIDI events for which there’s at least one active mapping with that source. In other words, it doesn’t forward MIDI events which are used to control a target parameter. However, unmatched MIDI events are forwarded! You can change this using Let through section.

The exact behavior differs depending on what you choose as Input menu:

  • If input is set to MIDI: <FX input>

    • MIDI events arrive from ReaLearn’s FX input. If they get forwarded, they get forwarded to the FX output, usually to the plug-in which is located right below ReaLearn FX. The default setting often makes much sense here, especially if you put ReaLearn right above another instrument plug-in.

  • If input is set to a MIDI hardware device

    • MIDI events arrive directly from the MIDI hardware device. If they get forwarded, they get forwarded to REAPER’s tracks as they would usually do without ReaLearn. If they don’t get forwarded, it means they get filtered and will never make it to the tracks. ReaLearn completely eats them, globally! That means, ReaLearn can act as global MIDI filter.

    • Please note, with input set to a real MIDI device, MIDI events coming from FX input are always forwarded to the FX output.

    • Also, MIDI events captured from a real MIDI device input are never forwarded to ReaLearn’s FX output.

      This global MIDI filter feature is only available in REAPER v6.36+.

  • If input is set to an OSC device

    • You won’t see the checkboxes because they don’t make sense for OSC.

  • The checkboxes don’t have any effect on computer keyboard input. Keys are always passed through when doing text entry and never passed through if a mapping matches.

Auto-load

If you activate Auto-load based on unit FX, ReaLearn will start to observe the Unit FX of this ReaLearn unit and keep loading main presets according to which FX-to-preset links you have defined. By default, the unit FX is set to <Focused>, which means, it will reflect whatever FX is currently focused. Whenever the unit FX changes, it will check if you have linked a compartment preset to it and will automatically load it. Whenever the unit FX switches to an unlinked FX or the FX loses focus, ReaLearn falls back to the mapping list or preset that was active before activating auto-load.

Of course this makes sense only if you actually have linked some presets. Section Unit FX-to-preset link describes how to do that.

A link between a FX and a Main preset. Used in Auto-load.

A link saved as part of a Unit.

This is like a Unit FX-to-preset link but the link is saved globally. This is useful if you have only one controller or if you have x controllers (= and therefore x ReaLearn units) and want both of them to always auto-load the same preset if the unit FX points to the same plug-in.

  • All links will be saved globally, not just within this project!

  • Location: REAPER resource directory (Options  Show REAPER resource path in explorer/finder) at Data/helgoboss/realearn/auto-load-configs/fx.json.

Unit key

Each ReaLearn unit has a key that’s used to address this particular ReaLearn unit when using the Projection feature. By default, the unit key is a random cryptic string which ensures that every unit is uniquely addressable. The result is that scanning the QR code of this ReaLearn unit will let your mobile device connect for sure with this unique unit, not with another one - remember, you can use many units of ReaLearn in parallel. This is usually what you want.

But a side effect is that with every new ReaLearn unit that you create, you first have to point your mobile device to it in order to see its Projection (by scanning the QR code). Let’s assume you have in many of your projects exactly one ReaLearn unit that lets your favorite MIDI controller control track volumes. By customizing the unit key, you can tell your mobile device that it should always show the Projection of this very ReaLearn unit - no matter in which REAPER project you are and even if they control the volumes of totally different tracks.

You can achieve this by setting the unit key of each volume-controlling ReaLearn unit to exactly the same value, in each project, using Unit data… button. Ideally it’s a descriptive name without spaces, such as "track-volumes". You have to do the pairing only once et voilà, you have a dedicated device for monitoring your volume control ReaLearn units in each project.

Make sure to not have more than one ReaLearn unit with the same unit key active at the same time because then it’s not clear to which your mobile device will connect!

At the moment, the unit key is part of the ReaLearn preset! That means, opening a preset, copying/cutting a ReaLearn FX, importing from clipboard - all of that will overwrite the unit key. This might change in future in favor of a more nuanced approach!

Unit track

The second line of the bottom panel shows the current track chosen as Unit track for this unit of ReaLearn. This can be something like "Track 3" or "The currently selected track". Mappings in this ReaLearn unit can refer to this track by choosing the track selector Unit selector.

The unit track can be changed via Target "Track".

Unit FX

The second line of the bottom panel also shows the current FX chosen as Unit FX for this unit of ReaLearn. This can be something like "FX 5 on track 3" or "The currently focused track". Mappings in this ReaLearn unit can refer to this FX by choosing the FX selector Unit selector.

The unit FX can be changed via Target "FX".

Unit tag

Each unit can have arbitrarily many tags.

Tags are important if you want to dynamically enable or disable instances using the Target "ReaLearn: Enable/disable instances".

Projection

Projection is a quite unique feature that allows you to project a schematic representation of your currently active controller to a mobile device (e.g. a tablet computer). You can put this device close to your controller in order to see immediately which control element is mapped to which parameter. This is an attempt to solve an inherent problem with generic controllers: That it’s easy to forget which control element is mapped to which target parameter.

Logging

Logging can be enabled or disabled via Logging Menu.

Logging of real control messages

Each log entry contains the following information:

  • Timestamp in seconds

  • Helgobox Instance ID

  • Message purpose

    • Real control: A message used for controlling targets.

    • Real learn: A message used for learning a source.

  • Actual message (MIDI messages will be shown as hexadecimal byte sequence, short MIDI messages also as decimal byte sequence and decoded)

  • Match result

    • unmatched: The message didn’t match any mappings.

    • matched: The message matched at least one of the mappings.

    • consumed: Only for short MIDI messages. This short message is part of a (N)RPN or 14-bit CC message and there’s at least one active mapping that has a (N)RPN or 14-bit CC source. That means it will not be processed. The complete (N)RPN or 14-bit CC message will be.

Logging of real feedback messages

The log entries look similar to the ones described above, with the following notable differences.

Superior units

When a unit is made superior via menu entry Make unit superior, this unit is allowed to suspend other units which share the same input and/or output device (hardware devices only, not FX input or output!).

Making units superior is rarely needed!

This option was initially introduced in order to add more flexibility to the Auto-load feature. The idea was to let a controller fall back to some default behavior if the currently focused FX is closed. Multiple instances were necessary to make this work with one of them (the auto-load instance) being superior.

However, since ReaLearn 2.14.0, falling back to initial mappings when the FX loses focus in auto-load mode became much easier and doesn’t require multiple units anymore! Your initial mappings or initial preset will be memorized and reloaded once the FX loses focus. See Auto-load for more information.

Behavior:

  • By default, ReaLearn units are not superior, just normal. This is most of the time okay, even if you have multiple units that share the same input and output …​ as long as you don’t have any conflicting mappings active at the same time.

  • For example, if 2 units use the same input or output device, and they use different control elements, they can peacefully coexist. And even if they share a control element for the control direction, they are still fine with it. The same control element will control 2 mappings, why not!

  • Things start to get hairy as soon as 2 units want to send feedback to the same control elements at the same time. You should avoid this. You should not even do this within one ReaLearn unit. This can’t work.

  • Sometimes you want one unit to suspend/cover/cancel/mute another one! You can do this by making this unit superior. Then, whenever this unit has at least one active mapping, all non-superior units with the same control and/or feedback device will be disabled for control and/or feedback.

  • You can have multiple superior units. Make sure they get along with each other :)