= Key concepts

This section offers brief descriptions of ReaLearn's key concepts.
A solid understanding of these concepts is essential for effectively using ReaLearn, regardless of which features you plan to utilize.

[[control]]
== Control

In ReaLearn, the term _control_ typically refers to the process of triggering or adjusting something in REAPER, such as executing an action or modifying an FX parameter.

[[feedback]]
== Feedback

In ReaLearn, the term _feedback_ refers to controlling LEDs, motorized faders, or displays on your device in response to events in REAPER, such as a track volume change.

== Controller

Most of the time, when talking about _controllers_ in the documentation, we are talking about controllers in the _general_ sense.

[[controller,Controller]]
=== Controller in the general sense

A _controller_ in the general sense is the device you use to control REAPER.
It is usually a hardware device, such as a MIDI keyboard or control surface, but it can also be software, like an OSC app.

Controllers are normally not specifically managed within ReaLearn, because you just need to set an <<input-port>> and and <<output-port>>, and that's all ReaLearn needs to know. An exception are <<managed-controller,managed controllers>>.

[[managed-controller]]
=== Managed controller

Only recently, ReaLearn introduced the concept of xref:further-concepts/instance.adoc#auto-units[], in which controllers can actually be managed in a xref:user-interface/settings-dialog.adoc#controllers[list]. ReaLearn then automatically creates <<unit,units>> depending on which of these controllers are connected. Such controllers are called _managed controllers_.

[[control-element]]
== Control element

A control element is any component you can use to control something.
In most cases, it's a physical part of your hardware <<controller>>.

Examples include knobs, encoders, faders, buttons, keys, pads, pitch wheels and acceleration sensors.

[[control-element-interaction]]
== Control element interaction

A control element _interaction_ is the act of using a <<control-element>>.

Typically, each control element has one primary interaction type:

* _Turning_ a knob
* _Pressing/releasing_ a button
* _Moving_ a fader

However, some control elements allow multiple interactions:

* _Moving_ a touch-sensitive fader
* _Touching/releasing_ a touch-sensitive fader

In this reference, <<control-element>> often implies <<control-element-interaction>>, as they are usually synonymous.

[[feedback-element]]
== Feedback element

A _feedback element_ is any part of your <<controller>> that can indicate or display information.

Examples includes LEDs, motor faders and displays.

Very frequently, control elements and feedback elements are combined:

- Button with an integrated LED
- Encoder with an LED ring
- Motorized fader

For this reason, this reference sometimes uses <<control-element>> to refer to both the <<control-element>> and the corresponding <<feedback-element>>.

[[input-port]]
== Input port

To enable control, ReaLearn needs to respond to events from your <<controller>>.
It achieves this by listening to events from an _input port_, which can be a MIDI device port, an OSC port or your computer keyboard.

You can change the input port using the xref:user-interface/main-panel/input-output-section.adoc#input[].

[[output-port]]
== Output port

To send <<feedback>> back to your <<controller>>, ReaLearn transmits instructions through an _output port_, which can be a MIDI device port or an OSC port.

You can change the output port using the xref:user-interface/main-panel/input-output-section.adoc#output[].

[[instance]]
== ReaLearn Instance

The terms _ReaLearn Instance_ and xref:helgobox:ROOT:key-concepts.adoc#instance[Helgobox instance] are interchangeable — they both refer to the same concept.

[[unit]]
== Unit

Each ReaLearn <<instance>> contains at least one _unit_, known as the _main unit_, but it can also contain an arbitrary number of additional units.

Units function like "mini instances" within a single ReaLearn <<instance>>, allowing that instance to manage multiple controllers simultaneously.
Each unit has its own <<input-port>>, <<output-port>>, <<controller-compartment>>, <<main-compartment>>, xref:further-concepts/compartment.adoc#controller-preset[], xref:further-concepts/compartment.adoc#main-preset[], and more.

[[compartment]]
== Compartment

Each unit consists of two compartments.
A compartment is a self-contained list of mappings that can be saved as an independent preset.
The two compartments in each unit are:

[[main-compartment]] Main compartment::
This is the primary compartment.
Its purpose is to define what the controller device should do, e.g., allowing a fader to control track volume or displaying the name of an FX parameter on a hardware display.
+
We refer to the mappings in this compartment as [[main-mapping,Main mapping]] _main mappings_ and to the presets as _main presets_.

[[controller-compartment]] Controller compartment::
The controller compartment is optional and serves two main purposes: Describing all control elements of the controller, assigning them descriptive names and enabling xref:further-concepts/compartment.adoc#virtual-control[].
+
We refer to the mappings in this compartment as [[controller-mapping,Controller mapping]] _controller mappings_ and to the presets as _controller presets_.

[#mapping]
== Mapping

Each compartment contains a list of mappings.

A _mapping_ connects a <<control-element>> and/or <<feedback-element>> on your <<controller>> with an action or parameter in REAPER.

Each mapping consists of <<source>>, <<glue>> and <<target>>.

[[source]]
== Source

A _source_ is the part of a <<mapping>> that typically describes a <<control-element>> and/or <<feedback-element>> on the <<controller>>.
More generally, it can be anything that emits xref:further-concepts/mapping.adoc#control-value[control values].

Examples: MIDI source, OSC source

[[glue]]
== Glue

A _glue_ is the part of a <<mapping>> that sits between <<source>> and <<target>>, filtering and transforming <<control>> and <<feedback>> streams.

This is a very powerful feature of ReaLearn, as can be seen by looking at the xref:glue-signal-flow.adoc[].

[[target]]
== Target

A _target_ is the part of the <<mapping>> that describes the thing which should be controlled and/or provides feedback data.

Examples: Track volume, cursor position, REAPER action

[[learning]]
== Learning

This section wouldn't be complete without mentioning the concept that inspired ReaLearn's name: _Learning_.
Learning simply means that you press a btn:[Learn] button instead of performing manual setup, saving you valuable time!

In ReaLearn, you can learn <<source, sources>> and <<target, targets>>.

[[learn-source]]
=== Learn source

Sources can be learned by pressing the xref:user-interface/main-panel/mapping-row.adoc#learn-source[] and then touching a <<control-element>> on your controller.
This saves you from the tedious job of setting up MIDI or OSC sources manually.

[[learn-target]]
=== Learn target

Targets can be learned by pressing the xref:user-interface/main-panel/mapping-row.adoc#learn-target[] and then invoking a <<target>> within REAPER.
This saves you from choosing xref:further-concepts/target.adoc#target-object-selectors[] and other stuff manually.
