Home

Awesome

yabridge

Automated builds Discord

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.

yabridge screenshot

Table of contents

Tested with

Yabridge has been tested under the following hosts using Wine Staging 9.21. See #368 for information about GUI problems with Wine 9.22..

HostVST2VST3CLAP
Bitwig Studio 5.3 beta:heavy_check_mark::heavy_check_mark::heavy_check_mark:
REAPER 7.12:heavy_check_mark::heavy_check_mark::heavy_check_mark:
Carla 2.5.5:heavy_check_mark::heavy_check_mark:Does not support CLAP
Qtractor 0.9.29:heavy_check_mark::warning: VST3 editor windows may not have the correct size:warning: Qtractor may not support every CLAP plugin
Renoise 3.4.3:heavy_check_mark::heavy_check_mark:Does not support CLAP
Waveform 12.1.3:heavy_check_mark::heavy_check_mark:Does not support CLAP
Ardour 8.1:heavy_check_mark::warning: Some plugins may cause Ardour 7.3-8.1 to freezeDoes not support CLAP
Mixbus 7.0.140:heavy_check_mark::heavy_check_mark:Does not support CLAP

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

<sup> *Bitwig Studio's Flatpak version will not work with yabridge. You'll need to use the .deb found on the release notes page instead. </sup>

Usage

  1. 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.

  2. 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.

    <a href="https://repology.org/project/yabridge/versions" target="_blank" rel="noopener" title="Packaging status"><img align="right" src="https://repology.org/badge/vertical-allrepos/yabridge.svg"></a>

    • 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 <kbd>Ctrl+H</kbd>. 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.

  3. 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.
  4. 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 <kbd>Space</kbd> 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 <kbd>Shift</kbd> 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:

Installing a development build

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

After updating yabridge's files, you will need to rerun yabridgectl sync to finish the upgrade.

Configuration

Yabridge can be configured on a per plugin basis to host multiple plugins within a single process using plugin groups, and there are also a number of compatibility options available to improve compatibility with certain hosts and plugins.

Configuring yabridge is done by creating a yabridge.toml file located in either the same directory as the bridged plugin .so or .clap file you're trying to configure, or in any of its parent directories. In most cases, this file should be created as either ~/.vst/yabridge/yabridge.toml, ~/.vst3/yabridge/yabridge.toml, or ~/.clap/yabridge/yabridge.toml depending on the type of plugin you want to configure.

Configuration files contain several sections. Each section can match one or more plugins using case sensitive glob patterns that match paths to yabridge .so and .clap files relative to the yabridge.toml file, as well as a list of options to apply to the matched plugins. These glob patterns can also match entire directories, in which case the settings are applied to all plugins under that directory or one of its subdirectories. To avoid confusion, only the first yabridge.toml file found and only the first matching glob pattern within that file will be considered. See below for an example of a yabridge.toml file. To make debugging easier, yabridge will print the used yabridge.toml file and the matched section within it on startup, as well as all of the options that have been set.

Plugin groups

OptionValuesDescription
group{"<string>",""}Defaults to "", meaning that the plugin will be hosted individually.

Some plugins have the ability to communicate with other instances of that same plugin or even with other plugins made by the same manufacturer. This is often used in mixing plugins to allow different tracks to reference each other without having to route audio between them. Examples of plugins that do this are FabFilter Pro-Q 3, MMultiAnalyzer and the iZotope mixing plugins. In order for this to work, all instances of a particular plugin will have to be hosted in the same process.

Yabridge has the concept of plugin groups, which are user defined groups of plugins that will all be hosted inside of a single process. Plugins groups can be configured for a plugin by setting the group option of that plugin to some name. All plugins with the same group name will be hosted within a single process. Of course, plugin groups with the same name but in different Wine prefixes and with different architectures will be run independently of each other. See below for an example of how these groups can be set up.

Note that because of the way VST3 and CLAP work, multiple instances of a single VST3 or CLAP plugin will always be hosted in a single process regardless of whether you have enabled plugin groups or not. The only reason to use plugin groups with those plugins is to get slightly lower loading times the first time you load a new plugin.

Compatibility options

OptionValuesDescription
disable_pipes{true,false,<string>}When this option is enabled, yabridge will redirect the Wine plugin host's output streams to a file without any further processing. See the known issues section for a list of plugins where this may be useful. This can be set to a boolean, in which case the output will be written to $XDG_RUNTIME_DIR/yabridge-plugin-output.log, or to an absolute path (with no expansion for tildes or environment variables). Defaults to false.
editor_coordinate_hack{true,false}Compatibility option for plugins that rely on the absolute screen coordinates of the window they're embedded in. Since the Wine window gets embedded inside of a window provided by your DAW, these coordinates won't match up and the plugin would end up drawing in the wrong location without this option. Currently the only known plugins that require this option are PSPaudioware E27 and Soundtoys Crystallizer. Defaults to false.
editor_disable_host_scaling{true,false}Disable host-driven HiDPI scaling for VST3 and CLAP plugins. Wine currently does not have proper fractional HiDPI support, so you might have to enable this option if you're using a HiDPI display. In most cases setting the font DPI in winecfg's graphics tab to 192 will cause plugins to scale correctly at 200% size. Defaults to false.
editor_force_dnd{true,false}This option forcefully enables drag-and-drop support in REAPER. Because REAPER's FX window supports drag-and-drop itself, dragging a file onto a plugin editor will cause the drop to be intercepted by the FX window. This makes it impossible to drag files onto plugins in REAPER under normal circumstances. Setting this option to true will strip drag-and-drop support from the FX window, thus allowing files to be dragged onto the plugin again. Defaults to false.
editor_xembed{true,false}Use Wine's XEmbed implementation instead of yabridge's normal window embedding method. Some plugins will have redrawing issues when using XEmbed and editor resizing won't always work properly with it, but it could be useful in certain setups. You may need to use this Wine patch if you're getting blank editor windows. Defaults to false.
frame_rate<number>The rate at which Win32 events are being handled and usually also the refresh rate of a plugin's editor GUI. When using plugin groups all plugins share the same event handling loop, so in those the last loaded plugin will set the refresh rate. Defaults to 60.
hide_daw{true,false}Don't report the name of the actual DAW to the plugin. See the known issues section for a list of situations where this may be useful. This affects VST2, VST3, and CLAP plugins. Defaults to false.
vst3_prefer_32bit{true,false}Use the 32-bit version of a VST3 plugin instead the 64-bit version if both are installed and they're in the same VST3 bundle inside of ~/.vst3/yabridge. You likely won't need this.

These options are workarounds for issues mentioned in the known issues section. Depending on the hosts and plugins you use you might want to enable some of them.

Example

All of the paths used here are relative to the yabridge.toml file. A configuration file for VST2 plugins might look a little something like this:

# ~/.vst/yabridge/yabridge.toml

["FabFilter Pro-Q 3.so"]
group = "fabfilter"

["MeldaProduction/Tools/MMultiAnalyzer.so"]
group = "melda"

# Matches an entire directory and all files inside it, make sure to not include
# a trailing slash
["ToneBoosters"]
group = "toneboosters"

["PSPaudioware"]
editor_coordinate_hack = true

["Analog Lab 3.so"]
editor_xembed = true

["Chromaphone 3.so"]
hide_daw = true

["sforzando VST_x64.so"]
editor_force_dnd = true
frame_rate = 24

["Loopcloud*"]
disable_pipes = true

# Simple glob patterns can be used to avoid unneeded repetition
["iZotope*/Neutron *"]
group = "izotope"

# Since this file has already been matched by the above glob pattern, this won't
# do anything
["iZotope7/Neutron 2 Mix Tap.so"]
group = "This will be ignored!"

# Of course, you can also add multiple plugins to the same group by hand
["iZotope7/Insight 2.so"]
group = "izotope"

# This would cause all plugins to be hosted within a single process. Doing so
# greatly reduces the loading time of individual plugins, with the caveat being
# that plugins are no longer sandboxed from each other.
#
# ["*"]
# group = "all"

For VST3 plugins you should just match the directory instead of the .so file deep within in, like this:

# ~/.vst3/yabridge/yabridge.toml

["FabFilter*.vst3"]
group = "fabfilter"
editor_disable_host_scaling = true

["Chromaphone 3.vst3"]
hide_daw = true

["Misstortion2.vst3"]
editor_disable_host_scaling = true

["*/*Spectral*.vst3"]
vst3_prefer_32bit = true

# These options would be applied to all plugins that do not already have their
# own configuration set
["*"]
editor_force_dnd = true
editor_disable_host_scaling = true

With CLAP plugins, you match on the Linux .clap plugin file, just like matching on .so files for a VST2 config file:

# ~/.clap/yabridge/yabridge.toml

["fb799964.clap"]
hide_daw = true

Known issues and fixes

Any plugin should function out of the box, although some plugins will need some additional dependencies for their GUIs to work correctly. Notable examples include:

Aside from that, these are some known caveats:

There are also some (third party) plugin API extensions for that have not been implemented yet. See the roadmap for a list of future plans.

Troubleshooting common issues

If your problem is not listed here, then feel free to post on the issue tracker or to ask about it in the yabridge Discord. Also check the known issues and fixes section above for help with plugin-specific issues.

Performance tuning

Running Windows plugins under Wine should have a minimal performance overhead, but you may still notice an increase in latency spikes and overall DSP load. Luckily there are a few things you can do to get rid of most or all of these negative side effects:

Environment configuration

This section is relevant if you want to configure environment variables in such a way that they will be set when you launch your DAW from the GUI instead of from a terminal. You may want to enable WINEFSYNC for fsync support with a compatible Wine version and kernel, or you may want to change your search PATH to allow yabridge to find the yabridge-*.exe binaries if you're using yabridge directly from the build directory. To do this you'll need to change your login shell's profile, which is different from the configuration loaded during interactive sessions. And some display manager override your login shell to always use /bin/sh, so you need to be careful to modify the correct file or else these changes won't work. You can find out your current login shell by running echo $SHELL in a terminal.

Make sure to log out and log back in again to ensure that all applications pick up the new changes.

Building

To compile yabridge, you'll need Meson and the following dependencies:

The following dependencies are included in the repository as a Meson wrap:

The project can then be compiled with the command below. You can remove or change the unity size argument if building takes up too much RAM, or you can disable unity builds completely by getting rid of --unity=on at the cost of slightly longer build times.

meson setup build --buildtype=release --cross-file=cross-wine.conf --unity=on --unity-size=1000
ninja -C build

After you've finished building you can follow the instructions under the usage section on how to set up yabridge.

32-bit bitbridge

It is also possible to compile a host application for yabridge that's compatible with 32-bit plugins such as old SynthEdit plugins. This will allow yabridge to act as a bitbridge, allowing you to run old 32-bit only Windows plugins in a modern 64-bit Linux plugin host. For this you'll need to have installed the 32 bit versions of the XCB library. This can then be set up as follows:

# Enable the bitbridge on an existing build
meson configure build -Dbitbridge=true
# Or configure a new build from scratch
meson setup build --buildtype=release --cross-file cross-wine.conf -Dbitbridge=true

ninja -C build

This will produce a second plugin host binary called yabridge-host-32.exe. Yabridge will detect whether the plugin you're trying to load is 32-bit or 64-bit, and will run either the regular version or the *-32.exe variant accordingly.

32-bit libraries

It also possible to build 32-bit versions of yabridge's libraries, which would let you use both 32-bit and 64-bit Windows VST2, VST3, and CLAP plugins from a 32-bit Linux plugin host. This is mostly untested since 32-bit only Linux applications don't really exist anymore, but it should work! The build system will still assume you're compiling from a 64-bit system, so if you're compiling on an actual 32-bit system you would need to comment out the 64-bit yabridge-host and yabridge-group binaries in meson.build:

meson setup build --buildtype=release --cross-file=cross-wine.conf --unity=on --unity-size=1000 -Dbitbridge=true -Dbuild.cpp_args='-m32' -Dbuild.cpp_link_args='-m32'
ninja -C build

Like the above commands, you might need to tweak the unity size based on the amount of system memory available. See the CI build definitions for some examples on how to add static linking in the mix if you're going to run this version of yabridge on some other machine.

Debugging

Wine's error messages and warning are usually very helpful whenever a plugin doesn't work right away. However, with some hosts it can be hard read a plugin's output. To make it easier to debug malfunctioning plugins, yabridge offers these two environment variables to control yabridge's logging facilities:

See the bug report template for an example of how to use this.

Wine's own logging facilities can also be very helpful when diagnosing problems. In particular the +message, +module and +relay channels are very useful to trace the execution path within the loaded plugin itself.

Attaching a debugger

To debug the plugin, you can just attach gdb to the host. Debugging the Wine plugin host is a bit trickier. Wine comes with a GDB proxy for winedbg, but it requires a little bit of additional setup and it expects the command line arguments to be a valid Win32 command line. You'll also need to launch winedbg in a seperate detached terminal emulator so it doesn't terminate together with the plugin, and winedbg can be a bit picky about the arguments it accepts. I've already set this up behind a feature flag for use in KDE Plasma. Other desktop environments and window managers will require some slight modifications in src/plugin/host-process.cpp. To enable this, simply run the follow and then rebuild yabridge:

meson configure build --buildtype=debug -Dwinedbg=true