virtual-controller/plugin-reaper-relearn/doc/helgobox/modules/ROOT/pages/installation.adoc

= Installation
:plugin-name: "VSTi: Helgobox - ReaLearn & Playtime (Helgoboss)"
:package-name: "Helgobox: ReaLearn & Playtime"

Helgobox is provided as https://reapack.com/[ReaPack] package.
ReaPack is a popular 3rd-party package manager for REAPER that makes installing add-ons easy and keeps your installation up to date effortlessly.

== System requirements

Please check below system requirements before attempting to install Helgobox!

=== REAPER

* Playtime needs REAPER 7.23 or later
* ReaLearn works acceptably with older REAPER versions, but it works better with REAPER 7.23 or later

[[windows]]
=== Windows

* xref:plug-in.adoc[] needs Windows 7 or later
* xref:app.adoc[] needs Windows 8 or later

[[macos]]
=== macOS

* xref:plug-in.adoc[] needs macOS 10.12 or later
* xref:app.adoc[] needs macOS 10.15 or later
* For macOS 10.14 or later, all below-mentioned installation options should work
* **For macOS 10.13 or earlier, installation via installer is not supported.
You need to install via ReaPack!**

[[linux]]
=== Linux

* On x64 architecture: Needs at least glibc v2.31 (for example, Ubuntu 20+, Debian 11+)
* On arm64 architecture: Needs at least glibc v2.35 (for example, Ubuntu 22+, Debian 12+)
* **Installation via installer is not supported.
You need to install via ReaPack!**
* Needs libxdo.
You can install it like this:
+
[source,shell]
.Debian, Ubuntu
----
sudo apt-get install -y libxdo-dev
----
+
[source,shell]
.openSUSE
----
sudo zypper install xdotool
----
* Other dependencies that you might need to install manually, depending on your Linux distribution: `libx11`, `libstdc++`, `libudev`
* If {plugin-name} isn't available after installation, REAPER failed to scan it. And that is most likely due to a missing dependency. In that case, please link:https://github.com/helgoboss/helgobox/issues/503#issuecomment-1320964181[try this to analyze the issue] and send the result to info@helgoboss.org.

IMPORTANT: If you want to use a _Stream Deck_ controller with ReaLearn on Linux, xref:realearn::sources/stream-deck.adoc#linux[more setup] is necessary.

NOTE: A more detailed system compatibility table can be found link:https://www.helgoboss.org/projects/helgobox#requirements[here].

== Installing Helgobox

Please choose:

[loweralpha]
. <<installer>>
. <<i-have-reapack>>
. <<i-want-to-install-reapack>>
. <<install-without-reapack>>

[[installer]]
=== I want an installer 👍

For users who don't have ReaPack installed already, there's a **convenient installer** that automatically installs both ReaPack and Helgobox.
It gets you up and running in no time, supporting even portable REAPER installations!

You can use it if you have Windows 7+ or macOS 10.14+.

Simply press the following link and follow the instructions: link:https://reaboot.com/install/https%3A%2F%2Fraw.githubusercontent.com%2Fhelgoboss%2Fhelgobox%2Fmaster%2Freaboot.json[Install Helgobox]

[[i-have-reapack]]
=== I have ReaPack and want to use it to install Helgobox

Here's how you can install Helgobox via ReaPack:

. In REAPER, select menu:Extensions[ReaPack > Import repositories…]
. Copy and paste the following repository URL into the text area:
+
 https://github.com/helgoboss/reaper-packages/raw/master/index.xml
+
. Select menu:Extensions[ReaPack > Browse packages…]
. Search for `helgobox`
. Right mouse click on the package {package-name} and choose menu:Install…[]
. Press btn:[OK] or btn:[Apply]
. Restart REAPER

[[i-want-to-install-reapack]]
=== I don't have ReaPack but want to use it to install Helgobox

. Install ReaPack, following the link:https://reapack.com/user-guide[installation section of its user guide]
. Restart REAPER
. Follow the instructions in <<i-have-reapack>>

[[install-without-reapack]]
=== I want to install Helgobox manually, without ReaPack

If you are more the download type of person, you can find the latest `dll`, `dylib` and `so` files here at GitHub on the https://github.com/helgoboss/helgobox/releases[releases page] for manual installation.

You also must install Helgobox manually if you plan to use it in both REAPER for Windows 32-bit and REAPER for Windows 64-bit because then it's important to use two separate VST plug-in directories.

== Validating the installation

You know that Helgobox is installed successfully if you see the menu menu:Extensions[Helgobox].

In addition, you should see a plug-in entry {plugin-name} after right-clicking the empty area of REAPER's track panel and choosing menu:Insert virtual instrument on new track...[].

NOTE: On Helgobox for Linux, the extension menu entry doesn't exist yet.
But the plug-in should be there.

== Troubleshooting

=== Helgobox plug-in doesn't appear in the list of plug-ins

If the plug-in {plugin-name} doesn't appear in the list of plug-ins, please proceed as follows:

. If you are on Linux, make sure to follow the <<linux, installation instructions for Linux>>!

. Make sure that Helgobox runs as native plug-in!
** By default, each plug-in runs as native plug-in.
If not, you probably changed the configuration at some point.
** You can fix that by right-clicking {plugin-name} in the plug-in list and select menu:Run as[Native only (prevent bridging)].
** It's technically impossible to run Helgobox as a bridged plug-in!

TIP: If none of these suggestions help, link:https://github.com/helgoboss/helgobox/issues/new/choose[please report a bug]!

[[updating-helgobox]]
== Updating Helgobox

Helgobox development moves fast!
To take advantage of the latest features, improvements and fixes, you should check the link:https://www.helgoboss.org/projects/helgobox[Helgobox homepage] for updates from time to time.

Here's how you can install the latest stable Helgobox version:

. Run menu:Extensions[ReaPack > Synchronize packages]
** ReaPack will show you a summary at the end, which tells you whether a new Helgobox version has been installed.
. Restart REAPER

If <<installer,supported on your system>>, you can alternatively just run the link:https://www.helgoboss.org/projects/helgobox#download[Helgobox installer app] again.

[[downgrading-helgobox]]
== Downgrading Helgobox

Downgrading is easily possible via ReaPack as well.

.Be careful when saving projects after updates or downgrades!
[CAUTION]
====
It is not guaranteed that projects saved with newer versions can still be opened with older versions of Helgobox! Even if it works, saving a project with that older version might overwrite changes that you made in the newer version. That's why Helgobox will warn you in this case.

If your project is crucial, it is recommended to make a backup before re-saving it with another version.
====

. menu:Extensions[ReaPack > Browse packages...]
. Right-click the package {package-name} and navigate to the submenu menu:Versions[]
. Select the desired old version
. Press btn:[OK] or btn:[Apply]
. Restart REAPER


[[pre-releases]]
== Testing new features and improvements

If you want to get access to cutting-edge but untested versions of Helgobox, you can install Helgobox pre-releases.

=== Install a specific pre-release of Helgobox

. menu:Extensions[ReaPack > Browse packages...]
. Right-click the package {package-name} and navigate to the submenu menu:Versions[]
. Select the desired pre-release version (versions containing `-pre` or `-rc`)
. Press btn:[OK] or btn:[Apply]
. Restart REAPER

=== Enable pre-releases globally

. menu:Extensions[ReaPack > Manage repositories]
. menu:Options…[Enable pre-releases globally (bleeding edge)]
. After that, whenever you synchronize packages, you will get the latest stuff.