Vendor helgoboss/helgobox (ReaLearn) as basis for custom UI fork

Stripped upstream git history; starting point for replacing the native SWELL/Win32 mapping UI with something more suited to bulk editing. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-15 17:38:29 -04:00
parent 583ed77a67
commit e58f06d9fa
2232 changed files with 685575 additions and 1 deletions
@@ -0,0 +1,169 @@
+= 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.