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,22 @@
+= Source "Keyboard"
+
+This source reacts to pressing or releasing a key on your computer keyboard.
+It emits a value of 100% when the key is pressed and 0% when released.
+
+In order to set the key, simply click the btn:[Learn] button and press the key of your choice.
+
+In addition to the key label, ReaLearn might show some warnings regarding the portability of your keystroke.
+This helps you to avoid keyboard shortcuts that don't reliably work cross-platform (in other operating systems) or on other keyboard layouts.
+You can ignore portability warnings if you use just this operating system and don't plan to share your keyboard presets with other users.
+
+[TIP]
+====
+* This only works if xref:user-interface/main-panel/input-output-section.adoc#computer-keyboard[] is enabled in the xref:user-interface/main-panel/input-output-section.adoc#input[].
+* If you hold a key, it will not keep firing.
+This is by design!
+Use xref:user-interface/mapping-panel/glue-section.adoc#fire-after-timeout-keep-firing[] instead.
+* Key combinations are not supported.
+This is by design!
+Use xref:further-concepts/mapping.adoc#conditional-activation[] instead.
+* Matching keys are automatically consumed by ReaLearn, so that they will not reach the rest of REAPER (unless a text field is focused). Check out xref:user-interface/main-panel/menu-bar.adoc#match-even-inactive-mappings[] to fine-tune matching behavior.
+====
@@ -0,0 +1,9 @@
+= MIDI sources
+
+Most types in the MIDI category have the following UI elements in common.
+
+Channel menu::
+Optionally restricts this source to messages from a certain MIDI channel.
+Only available for sources that emit MIDI channel messages.
+
+The remaining UI elements in this section depend on the chosen source type.
@@ -0,0 +1,17 @@
+= Source "CC value"
+
+This source reacts to incoming MIDI control-change messages.
+
+== CC menu
+
+Optionally restricts this source to messages with a certain MIDI control-change controller number.
+
+== Character menu
+
+See xref:further-concepts/source.adoc#midi-source-character[].
+
+== 14-bit values checkbox
+
+If unchecked, this source reacts to MIDI control-change messages with 7-bit resolution (usually the case).
+If checked, it reacts to MIDI control-change messages with 14-bit resolution.
+This is not so common but sometimes used by controllers with high-precision faders.
@@ -0,0 +1,4 @@
+= Source "Channel after touch"
+
+This source reacts to incoming MIDI channel-pressure messages.
+The higher the pressure, the higher the absolute control value.
@@ -0,0 +1,33 @@
+= Source "Display"
+
+This is a feedback-only source used to display text on MIDI-controllable hardware displays (LCDs, OLED displays, 7-segment displays, ...).
+
+== Protocol menu
+
+Lets you choose the display protocol, which tells ReaLearn how it should communicate with the hardware display and which options it supports.
+
+Mackie LCD:: Use this for MCU-compatible LCDs.
+Depending on your particular control surface, there can be up to 8 LCDs, each of which has up to 2 lines.
+Mackie XT LCD:: Use this to control the displays of MCU XT devices (= control surface extenders, which provide additional faders and displays).
+X-Touch Mackie LCD:: Like _Mackie LCD_ but also supports colors on certain X-Touch devices.
+X-Touch Mackie XT LCD:: Like _Mackie LCD XT_ but also supports colors on certain X-Touch devices.
+Mackie 7-segment display:: Use this for MCU-compatible 7-segment displays (you know, the ones which only show digits).
+There's usually one small assignment display and a larger one for showing the time code.
+SiniCon E24:: Use this with the https://www.sinicon.io/[SiniCon E24 controller].
+Launchpad Pro - Scrolling text:: Displays looped scrolling text on a Novation Launchpad Pro.
+Only seems to work if you set _Output_ to `MIDIOUT2 (Launchpad Pro)`.
+Studiologic SL Keyboard display:: Displays text on the display of Studiologic SL keyboards (tested with SL88).
+
+== Display menu
+
+Choose the particular display or display portion to which you want to send text.
+
+== Line menu
+
+Choose the line number.
+
+CAUTION: For controllers with multiple displays and lines, ReaLearn allows you to spread your text over all available displays and lines.
+This is great if you need to display a lot of text but one display doesn't provide enough space.
+But be aware: xref:further-concepts/general.adoc#feedback-relay[] doesn't work nicely anymore if you make use of this feature.
+
+If you want to know how to define which text shall be sent to the displays, please see xref:further-concepts/glue.adoc#text-feedback[textual feedback] in the xref:user-interface/mapping-panel/glue-section.adoc[].
@@ -0,0 +1,14 @@
+= Source "MIDI clock tempo"
+
+This source reacts to incoming MIDI clock (MTC) tempo messages.
+These are metronome-beat-like messages which can be regularly transmitted by some DAWs and MIDI devices.
+The frequency with which this message is sent dictates the tempo.
+
+The higher the calculated tempo, the higher the absolute control value.
+A tempo of 1 bpm will be translated to a control value of 0%, a tempo of 960 bpm to 100% (this corresponds to REAPER's supported tempo range).
+
+This source can be used in combination with the xref:targets/project/set-tempo.adoc[] to obtain a "poor man's" tempo synchronization.
+
+Be aware: MIDI clock naturally suffers from certain inaccuracies and latencies - that's an issue inherent to the nature of the MIDI clock protocol itself.
+E.g. it's not really suitable if you need super accurate and instant tempo synchronization.
+Additionally, ReaLearn's algorithm for calculating the tempo could probably be improved (that's why this source is marked as experimental).
@@ -0,0 +1,8 @@
+= Source "MIDI clock transport"
+
+This source reacts to incoming MIDI clock (MTC) transport messages.
+These are simple start, continue and stop messages which can be sent by some DAWs and MIDI devices.
+
+== Message menu
+
+The specific transport message to which this source should react.
@@ -0,0 +1,23 @@
+= Source "MIDI Script"
+
+[[source-midi-script]]
+This source is feedback-only and exists for enabling more complex feedback use cases such as controlling LCDs that are not yet supported by the xref:sources/midi/display.adoc[].
+It lets you write an EEL or Luau script that will be executed whenever ReaLearn "feels" like it needs to send some feedback to the MIDI device.
+
+== Kind menu
+
+Whether to use the EEL or Luau language.
+
+== Script field
+
+The script.
+Is disabled if the script contains more than one line.
+
+See xref:further-concepts/source.adoc#midi-source-script[] for details.
+
+== More button (…)
+
+Opens the script in a separate window (for multi-line scripts).
+
+TIP: Prefer the xref:sources/midi/display.adoc[] over this one whenever possible.
+It's easier to use.
@@ -0,0 +1,6 @@
+= Source "Note number"
+
+This source reacts to incoming MIDI note-on messages.
+The higher the note number (= key on a MIDI keyboard), the higher the absolute control value.
+
+This essentially turns your MIDI keyboard into a "huge fader" with the advantage that you can jump to any value at any time.
@@ -0,0 +1,9 @@
+= Source "Note velocity"
+
+This source reacts to incoming MIDI note-on and note-off messages.
+The higher the velocity of the incoming note-on message, the higher the absolute control value.
+Note-off messages are always translated to 0%, even if there's a note-off velocity.
+
+== Note menu
+
+Optionally restricts this source to messages with a certain note number (note numbers represent keys on the MIDI keyboard, e.g. 60 corresponds to C4).
@@ -0,0 +1,28 @@
+= Source "(N)RPN value"
+
+This source reacts to incoming non-registered (NRPN) or registered (RPN) MIDI parameter-number messages.
+The higher the emitted value, the higher the absolute control value.
+
+(N)RPN messages are not widely used.
+If they are, then mostly to take advantage of their ability to transmit 14-bit values (up to 16384 different values instead of only 128), resulting in a higher resolution.
+
+== RPN checkbox
+
+If unchecked, this source reacts to unregistered parameter-number messages (NRPN).
+If checked, it reacts to registered ones (RPN).
+
+== Number field
+
+The number of the registered or unregistered parameter-number message.
+This is a value between 0 and 16383.
+
+== 14-bit values checkbox
+
+If unchecked, this source reacts to (N)RPN messages with 7-bit resolution, including increment/decrement messages.
+
+If checked, it reacts to those with 14-bit resolution.
+In practice, this if often checked.
+
+== Character menu
+
+See xref:further-concepts/source.adoc#midi-source-character[].
@@ -0,0 +1,5 @@
+= Source "Pitch wheel"
+
+This source reacts to incoming MIDI pitch-bend change messages.
+The higher the pitch-wheel position, the higher the absolute control value.
+The center position corresponds to an absolute control value of 50%.
@@ -0,0 +1,8 @@
+= Source "Polyphonic after touch"
+
+This source reacts to incoming MIDI polyphonic-key-pressure messages.
+The higher the pressure, the higher the absolute control value.
+
+== Note menu
+
+Optionally restricts this source to messages with a certain note number.
@@ -0,0 +1,4 @@
+= Source "Program change"
+
+This source reacts to a range of incoming MIDI program-change messages.
+The higher the program number, the higher the absolute control value.
@@ -0,0 +1,10 @@
+= Source "Raw MIDI / SysEx"
+
+[[source-midi-raw]]
+This source primarily deals with system-exclusive MIDI messages.
+It supports both control and feedback direction!
+
+== Pattern field
+
+Pattern describing the raw MIDI message.
+See xref:further-concepts/mapping.adoc#raw-midi-pattern[].
@@ -0,0 +1,5 @@
+
+= Source "Specific program change"
+
+This source reacts to MIDI program-change messages with a specific program.
+This is a trigger-only source, that means it always fires 100% (whenever the program number corresponds to the configured one).
@@ -0,0 +1,6 @@
+= Source "None"
+
+A special kind of source that will never emit any events.
+It's intended to be used on mappings which are not supposed to be controlled directly but only via xref:user-interface/mapping-panel/glue-section.adoc#group-interaction[].
+
+[split=1]
@@ -0,0 +1,66 @@
+= Source "OSC"
+
+OSC sources allow configuration of the following aspects:
+
+== Address field
+
+This needs to correspond exactly to the address of the corresponding control element on your OSC device.
+
+Example: `/1/fader1`
+
+You don't need to figure that out yourself, just use the btn:[Learn] button.
+
+== Argument section
+
+Each OSC message consists of an arbitrary number of arguments.
+In most cases, e.g. with faders, knobs or buttons, it's just one argument.
+X/Y controls often send 2 arguments, one for each axis.
+There are rare cases in which messages have even more arguments.
+
+=== Argument number menu
+
+The first dropdown menu allows you to choose the number of the argument that ReaLearn should look at and process. `1` denotes the first argument, `2` the second one, and so on.
+
+=== Argument type menu
+
+The second dropdown menu lets you choose the argument type which ReaLearn should use to construct a proper feedback message.
+
+This is usually the same type as the one used for control direction.
+For control direction, choosing an explicit type is irrelevant because ReaLearn handles whatever type arrives automatically in the best possible way.
+
+If you use _Learn_, the type is filled automatically.
+* The value to be sent will be derived from the type (see <<feedback-arguments>>):
+
+[cols="m,m"]
+|===
+| Type | Property
+
+| Float | value.float
+| Double | value.double
+| Int | value.int
+| Long | value.long
+| Bool | value.bool
+| Nil | nil
+| Inf | inf
+| String | value.string
+| Color | style.color
+|===
+
+If you want more control over what feedback values are sent, use the <<feedback-arguments>> field.
+
+== Range field
+
+Values of argument types _Float_ and _Double_ are by default interpreted as decimal values between 0.0 and 1.0. You can change that by entering a different value range here.
+Even negative numbers are allowed.
+
+Customizing the value range is especially important for argument types _Int_ and _Long_ because they don't have a standard value range.
+
+== Is relative checkbox
+
+Some messages transmitted by OSC devices are meant to be interpreted as relative increments/decrements instead of absolute values, e.g. jog wheels.
+When you enable this checkbox, ReaLearn will treat each received _1_ value as an increment and _0_ value a decrement.
+
+[#feedback-arguments]
+== Feedback arguments field
+
+Allows you to modify the xref:further-concepts/source.adoc#osc-feedback-arguments-expression[].
@@ -0,0 +1 @@
+= REAPER sources
@@ -0,0 +1,4 @@
+= Source "MIDI device changes"
+
+This source emits a value of 100% whenever any MIDI device is connected and 0% whenever any MIDI device is disconnected.
+You can map this to the REAPER action "Reset all MIDI devices" to achieve true plug and play of MIDI devices (provided the corresponding device has been enabled at least once in REAPER's MIDI device preferences).
@@ -0,0 +1,8 @@
+= Source "ReaLearn parameter"
+
+This source fires whenever a selected xref:further-concepts/compartment.adoc#compartment-parameter[] changes its value.
+
+One of many ways to use this is to create macro parameters which control multiple parameters of multiple other plug-ins.
+
+CAUTION: This is one of the sources that can't participate in rendering.
+So it's important to write down automation *before* rendering.
@@ -0,0 +1,4 @@
+= Source "ReaLearn unit start"
+
+This source fires (emits a value of 100%) when ReaLearn starts.
+It can be used to execute an actions or restore certain states on REAPER startup or project load.
@@ -0,0 +1,11 @@
+= Source "Speech"
+
+This source works for xref:key-concepts.adoc#feedback[] only.
+It uses the native Windows or macOS text-to-speech engine to speak out any feedback value.
+
+== Troubleshooting
+
+If you don't hear anything, check the xref:user-interface/main-panel/bottom-section.adoc[] if unit-wide feedback is currently off.
+If yes, maybe xref:user-interface/main-panel/menu-bar.adoc#send-feedback-only-if-track-armed[] is enabled but your track is not armed.
+
+Also keep in mind that ReaLearn only resends feedback when it changed. Therefore, the speech source will only say something when the target value actually changes.
@@ -0,0 +1,3 @@
+= Source "Timer"
+
+This source fires (emits a value of 100%) repeatedly every _n_ milliseconds.
@@ -0,0 +1,156 @@
+= Source "Stream Deck"
+
+With this source, you can leverage your Stream Deck with ReaLearn, for example the link:https://www.elgato.com/en/en/p/stream-deck-mk2-black[Elgato Stream Deck MK.2].
+This includes reacting to buttons and sending xref:key-concepts.adoc#feedback[] to the button displays.
+
+CAUTION: This source is experimental. Behavioral changes are still possible!
+
+== Supported devices
+
+The following StreamDeck devices are currently supported:
+
+* Original
+* Original v2
+* Mini
+* Revised Mini
+* XL
+* MK.2
+
+== Setup
+
+=== General
+
+**Make sure that the official Stream Deck software is not running!**
+
+ReaLearn connects to your Stream Deck directly via USB.
+Only one software can connect to the device, so it's _either_ ReaLearn _or_ the Stream Deck software.
+
+[[linux]]
+=== Linux
+
+If you use Stream Deck on Linux, you also need to explicitly allow normal users access to the device, otherwise ReaLearn won't be able to connect to it.
+
+==== 1. Find the Vendor and Product ID
+
+Plug in the Stream Deck and identify its vendor and product IDs:
+
+[source,bash]
+----
+lsusb
+----
+
+Look for a line similar to:
+
+`Bus 001 Device 002: ID 0fd9:0080 Elgato Systems GmbH`
+
+In this example, `0fd9` is the vendor ID, and `0080` is the product ID (these may vary).
+
+==== 2. Create a udev Rule
+
+Create a new udev rule file in `/etc/udev/rules.d/`:
+
+[source,bash]
+----
+sudo nano /etc/udev/rules.d/99-streamdeck.rules
+----
+
+Add the following rule, replacing `0fd9` and `0080` with the correct vendor and product IDs if necessary:
+
+[source]
+----
+SUBSYSTEM=="usb", ATTR{idVendor}=="0fd9", ATTR{idProduct}=="0080", MODE="0660", GROUP="plugdev"
+KERNEL=="hidraw*", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0080", MODE="0660", GROUP="plugdev"
+----
+
+This rule sets permissions to `0660`, allowing the device owner and users in the `plugdev` group access to the device with the specified vendor and product IDs.
+
+==== 3. Reload udev Rules
+
+Reload the udev rules to apply changes:
+
+[source,bash]
+----
+sudo udevadm control --reload-rules
+----
+
+==== 4. Unplug and Replug the Device
+
+Unplug the Stream Deck and plug it back in to apply the new rule.
+Alternatively, you can execute `sudo udevadm trigger`.
+
+== User interface
+
+=== Button menu
+
+Select the button that you want to use to control or display something.
+
+=== Back menu
+
+Allows you to choose the desired button backgrounds.
+Unlike the button foreground, the button background is always static.
+It doesn't react to feedback value changes.
+
+Color::
+Uses a solid color as button background, by default black.
+You can change the color via xref:user-interface/mapping-panel/glue-section.adoc#feedback-style[], that means the background color can even be dynamic, e.g. reflect the currently selected track's color.
+
+Image::
+Uses a PNG image as button background.
+
+The image should ideally be a square.
+If not, some parts of the image will not be visible.
+The ideal dimensions of that square depends on your specific device.
+On most Stream Decks, it's 72x72 pixels.
+But ReaLearn will automatically scale the image.
+If in doubt, prefer _larger_ image sizes.
+Scaling down gives you a better quality than scaling up.
+
+If the image has transparent parts, the color defined in xref:user-interface/mapping-panel/glue-section.adoc#feedback-style[] will shine through.
+
+TIP: When picking images to be displayed on your Stream Deck, prefer images that are somewhere within your REAPER resource path (REAPER → Options → Show REAPER resource path in explorer/finder), e.g. toolbar icons.
+That makes ReaLearn save it as relative path, so your mapping becomes more portable (which is important if you want to share presets).
+
+=== Front menu
+
+Allows you to choose the desired button foreground, if desired.
+A foreground is usually dynamic, that means it can change depending on the target value.
+
+None::
+No foreground.
+Choose this if all you want to display is a static background.
+
+Color fade::
+Paints a color over the background with an opacity that depends on the target value.
+For example, if the target value is at 10%, the color will be almost transparent.
+It will fade depending The color is defined in xref:user-interface/mapping-panel/glue-section.adoc#feedback-style[].
+
+Image fade::
+Paints an image over the background with an opacity that depends on the target value.
+In terms of sizing, it behaves exactly like a background image.
+
+Image slide::
+Paints the portion of an image over the background.
+Which portion, depends on the target value.
+Landscape images slide horizontally, portrait images slide vertically.
+
+This type of foreground is perfect for making use of REAPER's toolbar images.
+They are actually sprites, that means they contain multipe images in one file, at different horizontal positions.
+
+Full bar::
+Paints a full-sized bottom-up half-transparent bar over the background, indicating the current target value.
+
+Good in combination with targets that have a continuous range, such as xref:targets/track/set-volume.adoc[] or xref:targets/track/peak.adoc[].
+
+Knob::
+Paints a knob over the background, indicating the current target value.
+
+=== Default text field
+
+Here you can enter static text that should be displayed over the background and foreground.
+ReaLearn will automatically choose a contrast color or dim the background so that the text always stays readable.
+
+You can press btn:[...] to enter multi-line text.
+ReaLearn supports up to 4 lines of text.
+
+You can also display dynamic text from the target!
+See xref:user-interface/mapping-panel/glue-section.adoc#feedback-style[].
@@ -0,0 +1,20 @@
+= Source "Virtual"
+
+See xref:further-concepts/source.adoc#virtual-source[].
+
+== Type menu
+
+See xref:further-concepts/compartment.adoc#virtual-control-element-type[].
+
+== ID section
+
+See xref:further-concepts/compartment.adoc#virtual-control-element-id[].
+
+=== Pick menu
+
+The convenient picker provides IDs from standardized xref:further-concepts/compartment.adoc#virtual-control-scheme[virtual control schemes].
+It also contains a category for accessing the virtual control elements that are currently exposed by the xref:key-concepts.adoc#controller-compartment[].
+
+=== ID field
+
+Lets you enter the ID manually.