yabridge

Yet Another way to use Windows audio plugins on Linux. Yabridge seamlessly supports using both 32-bit and 64-bit Windows VST2, VST3, and CLAP plugins in 64-bit Linux plugin hosts as if they were native plugins, with optional support for plugin groups to enable inter-plugin communication for VST2 plugins and quick startup times. Its modern concurrent architecture and focus on transparency allows yabridge to be both fast and highly compatible, while also staying easy to debug and maintain.

Table of contents

• Tested with
• Usage
  • Bitbridge
  • Wine prefixes
  • Drag-and-drop
  • Input focus grabbing
  • Downgrading Wine
  • Installing a development build
• Configuration
  • Plugin groups
  • Compatibility options
  • Example
• Known issues and fixes
• Troubleshooting common issues
• Performance tuning
  • Environment configuration
• Building
  • 32-bit bitbridge
  • 32-bit libraries
• Debugging
  • Attaching a debugger

Tested with

Yabridge has been tested under the following hosts using Wine Staging 9.8. Wine 9.5-9.7 will not work with yabridge because of a Wine bug, either upgrade to Wine 9.8 or downgrade to Wine 9.4.

Please let me know if there are any issues with other hosts.

Usage

0. First of all, yabridge requires a recent-ish version of Wine (Staging). Users of Debian, Ubuntu, Linux Mint and Pop!_OS should install Wine Staging from the WineHQ repositories as the Wine versions provided by those distro's repositories may be too old to be used with yabridge. On other distros you should be able to just install wine-staging using your distro's package manager.

   For a general overview on how to use Wine to install Windows applications, check out Wine's user guide.

1. Depending on your distro you can install yabridge and its yabridgectl companion utility through your distro's package manager or by using a binary archive from the GitHub releases page. Keep in mind that the distro packages mentioned below may not always be up to date, and some may also not be compiled with support for 32-bit plugins.

   

   • On Arch and Manjaro, yabridge and yabridgectl can be installed from the official repositories using the yabridge and yabridgectl packages.

   • On Fedora, you can install yabridge and yabridgectl from a COPR.

   • On the OpenSUSE distros, yabridge and yabridgectl are packaged by GeekosDAW.

   • On NixOS, yabridge and yabridgectl are in the repositories.

   • On Ubuntu, Debian, Linux Mint, Pop!_OS, and any other distro, you can simply download and install a prebuilt version of yabridge:

     1. First download the latest version of yabridge from the releases page. These binaries currently target Ubuntu 20.04, and should work on any other distro that's newer than that.

     2. Extract the contents of the downloaded archive to ~/.local/share, such that the file ~/.local/share/yabridge/yabridgectl exists after extracting. You can extract an archive here from the command line with tar -C ~/.local/share -xavf yabridge-x.y.z.tar.gz. If you're extracting the archive using a GUI file manager or archive tool, then make sure that hidden files and directories are visible by pressing Ctrl+H. You should also double check that your archive extraction tool didn't create an additional subdirectory in ~/.local/share. Dragging and dropping the yabridge directory from the archive directly to ~/.local/share is the best way to make sure this doesn't happen.

     3. Whenever any step after this mentions running yabridgectl <something>, then you should run ~/.local/share/yabridge/yabridgectl <something> instead.

        Alternatively, you can also add that directory to your shell's search path. That way you can run yabridgectl directly. If you don't know what that means, then add export PATH="$PATH:$HOME/.local/share/yabridge" to the end of ~/.bashrc and reopen your terminal.

2. Setting up and updating yabridge for your plugins is done though the yabridgectl command line utility. The basic idea is that you first install your Windows plugins to their default locations within a Wine prefix just like you would on regular Windows. and yabridgectl then manages those plugin directories for you. You then tell yabridgectl where it can find those plugins so it can manage them for you. That way you only ever need to run a single command whenever you install or remove a plugin. Both yabridge and yabridgectl will automatically detect your yabridge installation if you used one of the installation methods from step 1.

   To tell yabridgectl where it can find your Windows VST2, VST3, and CLAP plugins, you can use yabridgectl's add, rm and list commands to add, remove, and list the plugin directories yabridgectl is managing for you. You can also use yabridgectl status to get an overview of the current settings and the installation status for all of your plugins.

   1. To add the most common VST2 plugin directory in the default Wine prefix, use yabridgectl add "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins". This directory may be capitalized as VSTPlugins on your system, and some plugins may also install themselves to a similar directory directly inside of Program Files.
   2. VST3 plugins under Windows are always installed to C:\Program Files\Common Files\VST3, and you can use yabridgectl add "$HOME/.wine/drive_c/Program Files/Common Files/VST3" to add that directory to yabridge.
   3. CLAP plugins under Windows are always installed to C:\Program Files\Common Files\CLAP, and you can use yabridgectl add "$HOME/.wine/drive_c/Program Files/Common Files/CLAP" to add that directory to yabridge.

3. Finally, you'll need to run yabridgectl sync to finish setting up yabridge for all of your plugins. After doing so, your VST2, VST3, and CLAP plugins will be set up in ~/.vst/yabridge, ~/.vst3/yabridge, and ~/.clap/yabridge respectively. Make sure your DAW searches ~/.vst, ~/.vst3, and ~/.clap for VST2, VST3, and CLAP plugins and you will be good to go.

Bitbridge

Yabridge can also load 32-bit Windows plugins so you can use them in your 64-bit Linux DAW. Yabridge will automatically detect whether a plugin is 32-bit or 64-bit on startup and it will handle it accordingly. If you've installed yabridge through a distro package, then it may be possible that your distro has disabled this feature.

Wine prefixes

It is also possible to use yabridge with multiple Wine prefixes at the same time. Yabridge will automatically detect and use the Wine prefix the Windows plugin's .dll, .vst3, or .clap file is located in. Alternatively, you can set the WINEPREFIX environment variable to override the Wine prefix for all yabridge plugins.

Drag-and-drop

Yabridge supports drag-and-drop both from a native (X11) Linux application to plugins running under yabridge, as well as from yabridge plugins to native X11 applications like your DAW or your file browser. When dragging things from a plugin to your DAW, then depending on which DAW you're using it may look like the drop is going to fail while you're still holding down the left mouse button. That's expected, since yabridge's and Wine's own drag-and-drop systems are active at the same time. If you're using yabridge in REAPER or Carla, then you may need to enable a compatibility option to prevent those hosts from stealing the drop.

Input focus grabbing

Yabridge tries to be clever about the way grabbing and releasing input focus for a plugin works. One important detail here is that when grabbing input focus, yabridge will always focus the parent window passed by the host for the plugin to embed itself into. This means that hosts like Bitwig Studio can still process common key bindings like Space for play/pause even while you are interacting with a plugin's GUI. The downside of this approach is that this also means that in those hosts you simply cannot type a space character, as the key will always go to the host.

For the very specific situations where you may want to focus the plugin's editor directly so that all keyboard input goes to Wine, you can hold down the Shift key while entering the plugin's GUI with your mouse. This will let you type spaces in text fields in Bitwig Studio, type text into the settings and license dialogs in Voxengo plugins, and it will also allow you to navigate dropdowns with the keyboard.

Downgrading Wine

If you run into software or a plugin that does not work correctly with the current version of Wine Staging, then you may want to try downgrading to an earlier version of Wine. This can be done as follows:

• On Debian, Ubuntu, Linux Mint and other apt-based distros, you can use the command below to install Wine Staging 7.20 after you add the WineHQ repositories linked above. This command is a bit cryptic because on these distros the Wine package is split up into multiple smaller packages, and the package versions include the distros codename (e.g. focal, or buster) as well as some numeric suffix. Change the version to whatever version of Wine you want to install, and then run these commands under Bash:

  version=7.20
  variant=staging
  codename=$(shopt -s nullglob; awk '/^deb https:\/\/dl\.winehq\.org/ { print $3; exit 0 } END { exit 1 }' /etc/apt/sources.list /etc/apt/sources.list.d/*.list || awk '/^Suites:/ { print $2; exit }' /etc/apt/sources.list /etc/apt/sources.list.d/wine*.sources)
  suffix=$(dpkg --compare-versions "$version" ge 6.1 && ((dpkg --compare-versions "$version" eq 6.17 && echo "-2") || echo "-1"))
  sudo apt install --install-recommends {"winehq-$variant","wine-$variant","wine-$variant-amd64","wine-$variant-i386"}="$version~$codename$suffix"
  

  If you want to prevent these packages from being updated automatically, then you can do so with:

  sudo apt-mark hold winehq-staging
  

  Running the same command with unhold instead of hold will enable updates again.

• On Arch and Manjaro, you can install the downgrade tool from the repos or the AUR, then run:

  sudo env DOWNGRADE_FROM_ALA=1 downgrade wine-staging
  

  Then select the package for the wine-staging version you want to isntall from the list. After installing downgrade will ask if you want to add the package to IgnorePkg. If you select yes, the package will be added to the IgnorePkg field in /etc/pacman.conf and it won't be updated again automatically.

Installing a development build

If you want to try to a development version of yabridge, then you can do so as follows:

• On Arch and Manjaro, you can install the latest master branch version of yabridge by installing the yabridge-git and yabridgectl-git AUR packages.
• Otherwise, you can find development builds on the automated build page. Before you can download these files, you need log in to GitHub. Then simply select the latest commit with a green checkmark next to it, scroll down the build page, and download the latest yabridge and yabridgectl binaries that match your system. You can also access the very latest build from this page without logging in to GitHub. You'll need to extract these files twice, since GitHub automatically puts the tarball inside of a .zip archive. Then simply overwrite the existing files in ~/.local/share/yabridge with the ones from the yabridge directory, and replace ~/.local/share/yabridge/yabridgectl with the new yabridgectl/yabridgectl binary. It's also possible to use