Reorganize top-level directories with clearer naming convention

app -> app-desktop-macos, presets -> app-presets, server -> remote-server, daw-config-reaper -> osc-config-daw, plugin-reaper-realearn -> plugin-reaper-relearn. Updated run.py and presets.py path references accordingly. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-15 17:51:05 -04:00
parent e58f06d9fa
commit 7ecc718f5d
2256 changed files with 11 additions and 5 deletions
@@ -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[].