Repository files navigation

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

• 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

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

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

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

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

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

   

   • OnArch andManjaro, yabridge and yabridgectl can be installed fromthe official repositories using theyabridge andyabridgectlpackages.

   • OnFedora, you can install yabridge and yabridgectl from aCOPR.

   • On theOpenSUSE distros, yabridge and yabridgectl are packaged byGeekosDAW.

   • OnNixOS, yabridge and yabridgectl are in the repositories.

   • OnUbuntu,Debian,Linux Mint,Pop!_OS, and any otherdistro, you can simply download and install a prebuilt version of yabridge:

     1. First download the latest version of yabridge from thereleasespage. These binariescurrently target Ubuntu 20.04, and should work on any other distrothat's newer than that.

     2. Extract the contents of the downloaded archive to~/.local/share, suchthat the file~/.local/share/yabridge/yabridgectl exists afterextracting. You can extract an archive here from the command line withtar -C ~/.local/share -xavf yabridge-x.y.z.tar.gz. If you'reextracting the archive using a GUI file manager or archive tool, thenmake sure that hidden files and directories are visible by pressingCtrl+H. You should also double check that your archiveextraction tool didn't create an additional subdirectory in~/.local/share. Dragging and dropping theyabridge directory fromthe archive directly to~/.local/share is the best way to make surethis doesn't happen.

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

        Alternatively, you can also add that directory to your shell's searchpath. That way you can runyabridgectl directly. If you don't knowwhat that means, then addexport 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 theyabridgectl command line utility. The basic idea is that you first installyour Windows plugins to their default locations within a Wine prefix justlike you would on regular Windows. and yabridgectl then manages those plugindirectories for you. You then tell yabridgectl where it can find thoseplugins so it can manage them for you. That way you only ever need to run asingle command whenever you install or remove a plugin. Both yabridge andyabridgectl will automatically detect your yabridge installation if you usedone of the installation methods from step 1.

   To tell yabridgectl where it can find your Windows VST2, VST3, and CLAPplugins, you can use yabridgectl'sadd,rm andlist commands to add,remove, and list the plugin directories yabridgectl is managing for you. Youcan also useyabridgectl status to get an overview of the current settingsand the installation status for all of your plugins.

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

3. Finally, you'll need to runyabridgectl sync to finish setting up yabridgefor all of your plugins. After doing so, your VST2, VST3, and CLAP pluginswill 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 begood to go.

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

It is also possible to use yabridge with multiple Wine prefixes at the sametime. Yabridge will automatically detect and use the Wine prefix the Windowsplugin's.dll,.vst3, or.clap file is located in. Alternatively, you canset theWINEPREFIX environment variable to override the Wine prefix forallyabridge plugins.

Yabridge supports drag-and-drop both from a native (X11) Linux application toplugins running under yabridge, as well as from yabridge plugins to native X11applications like your DAW or your file browser. When dragging things from aplugin to your DAW, then depending on which DAW you're using it may look likethe 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 areactive at the same time. If you're using yabridge inREAPER orCarla, thenyou may need to enable acompatibility option toprevent those hosts from stealing the drop.

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

For the very specific situations where you may want to focus the plugin's editordirectly so that all keyboard input goes to Wine, you can hold down theShift key while entering the plugin's GUI with your mouse. This willlet you type spaces in text fields inBitwig Studio, type text into thesettings and license dialogs inVoxengo plugins, and it will also allow youto navigate dropdowns with the keyboard.

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

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

  version=9.21variant=stagingcodename=$(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" eq6.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, thenyou can do so with:

  sudo apt-mark hold winehq-staging

  Running the same command withunhold instead ofhold will enable updatesagain.

• On Arch and Manjaro, you can install thedowngrade tool from the reposor 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 fromthe list. After installing downgrade will ask if you want to add the packagetoIgnorePkg. If you selectyes, the package will be added to theIgnorePkg field in/etc/pacman.conf and it won't be updated againautomatically.

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

• On Arch and Manjaro, you can install the latest master branch version ofyabridge by installing theyabridge-git andyabridgectl-git AURpackages.
• Otherwise, you can find development builds on theautomated buildpage.Before you can download these files, you need log in to GitHub. Then simplyselect the latest commit with a green checkmark next to it, scroll down thebuild page, and download the latest yabridge and yabridgectl binaries thatmatch your system. You can also access the very latest build fromthispagewithout logging in to GitHub. You'll need to extract these files twice, sinceGitHub automatically puts the tarball inside of a .zip archive. Then simplyoverwrite the existing files in~/.local/share/yabridge with the ones fromtheyabridge directory, and replace~/.local/share/yabridge/yabridgectlwith the newyabridgectl/yabridgectl binary. It's also possible to use thesebuilds if you're using a distro package, but then you should remove thepackage first in order to avoid conflicts.

After updating yabridge's files, you will need to rerunyabridgectl sync tofinish the upgrade.

Yabridge can be configured on a per plugin basis to host multiple plugins withina single process usingplugin groups, and there are also anumber ofcompatibility options available to improvecompatibility with certain hosts and plugins.

Configuring yabridge is done by creating ayabridge.toml file located ineither the same directory as the bridged plugin.so or.clap file you'retrying to configure, or in any of its parent directories. In most cases, thisfile should be created as either~/.vst/yabridge/yabridge.toml,~/.vst3/yabridge/yabridge.toml, or~/.clap/yabridge/yabridge.toml dependingon the type of plugin you want to configure.

Configuration files contain severalsections. Each section can match one ormore plugins using case sensitiveglob patterns thatmatch paths to yabridge.so and.clap files relative to theyabridge.tomlfile, as well as a list of options to apply to the matched plugins. These globpatterns can also match entire directories, in which case the settings areapplied to all plugins under that directory or one of its subdirectories. Toavoid confusion, only the firstyabridge.toml file found and only the firstmatching glob pattern within that file will be considered. See below for anexample of ayabridge.toml file. To make debugging easier,yabridge will print the usedyabridge.toml file and the matched section withinit on startup, as well as all of the options that have been set.

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

Yabridge has the concept ofplugin groups, which are user defined groups ofplugins that will all be hosted inside of a single process. Plugins groups canbe configured for a plugin by setting thegroup option of that plugin to somename. All plugins with the same group name will be hosted within a singleprocess. Of course, plugin groups with the same name but in different Wineprefixes and with different architectures will be run independently of eachother. See below for anexample of how these groups can be set up.

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

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

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

# ~/.vst/yabridge/yabridge.toml["FabFilterPro-Q3.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["AnalogLab3.so"]editor_xembed =true["Chromaphone3.so"]hide_daw =true["sforzandoVST_x64.so"]editor_force_dnd =trueframe_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/Neutron2MixTap.so"]group ="This will be ignored!"# Of course, you can also add multiple plugins to the same group by hand["iZotope7/Insight2.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 filedeep within in, like this:

# ~/.vst3/yabridge/yabridge.toml["FabFilter*.vst3"]group ="fabfilter"editor_disable_host_scaling =true["Chromaphone3.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 =trueeditor_disable_host_scaling =true

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

# ~/.clap/yabridge/yabridge.toml["fb799964.clap"]hide_daw =true

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

• If plugins have missing, invisible, or misaligned text, then installingcorefonts orallfonts throughwinetricks may help.

• If a plugin seems to work fine except for the fact that the GUI never seems toupdate when you interact with it, then try installingDXVK. Many recent JUCE-based pluginsdon't redraw anymore when using WineD3D. Make sure you also install Vulkandrivers if you don't already have those set up.

• Serum requires you to disabled2d1.dll inwinecfg and to installgdiplus throughwinetricks. You may also want to disable the tooltips bygoing to the global settings tab, unchecking 'Show help tooltips', andclicking on the save icon next to 'Preferences'.

• Native Instruments plugins work, but the latest version of Native Accessneeds some extra work to run under wine. See thewineHQ pagefor information on how to get it running.

  The legacy version1.X still can be installed directly. You can find it on thelegacy installerspage on Native Instruments' website. To get the installer to finish correctly,openwinecfg and set the reported Windows version to Windows 10. Otherwisethe installer will be stuck on installing an ISO driver. To work around thisyou can open the .iso file downloaded to your downloads directory and run theinstaller directly.

  Some plugins or sound libraries will install as expected, but if you get an'Error while mounting disk image' installation failure, then you will need toinstall the plugin or sound library manually. You will find a .iso file inyour downloads directory that you can mount and then run the installer from.However some of those Native Instruments .iso files contain hidden files, andthe installer on the .iso file will fail to install unless you mount the .isofile with the correct mounting options to unhide those files. To do this,first runudisksctl loop-setup -f ~/Downloads/<filename>.iso to load the.iso file, and then useudisksctl mount -t udf -o unhide -b /dev/loopX where/dev/loopX corresponds to the loop device printed by theloop-setupcommand to mount the .iso file to a directory in/run/media.

  If you're using an older distro and you're getting aMount option 'unhide' is not allowed error when trying to mount the file,then you may need to manually create or edit/etc/udisks2/mount_options.conffirst, adding the following to the file:

  [defaults]udf_allow=uid=$UID,gid=$GID,iocharset,utf8,umask,mode,dmode,unhide,undelete

• IfSpitfire Audio plugins likeBBC Symphony Orchestra andLABS areunable to load their sample libraries (Error #X: Something went wrong), thenyou can try reinstalling those plugins to a new, clean Wine prefix. To avoidpotential confusion, make sure to uninstall the Spitfire software along withthe VST2 and VST3 plugins from your main Wine prefix first.

• SeveralJUCE based plugins have an issue under Wine where the mouse cursorwill disappear after interacting with certain UI elements. This can usually befixed by mousing over the resize handle in the bottom right corner.

• Several (JUCE-based) plugins likeArturia's plugins, Sonic Academy'sKick 2 and Cytomic'sThe Drop have an issue where the GUI freezes whenit's trying to display a tooltip. This can be fixed by enabling the 'HideWine version from applications' option in the Staging tab of winecfg. If aplugin seems to function normally but then freezes when clicking on something,then try enabling this option.

• The GUI inSforzando may appear to not respond to mouse clicks dependingon your Wine and system configuration. This is actually a redrawing issue, andthe GUI will still be updated even if it doesn't look that way. Dragging thewindow around or just clicking anywhere in the GUI will force a redraw andmake the GUI render correctly again.

• MeldaProduction plugins have minor rendering issues when GPU accelerationis enabled. This can be fixed by disabling GPU acceleration in the pluginsettings. I'm not sure whether this is an issue with Wine or the pluginsthemselves. Notable issues here are missing redraws and incorrect positioningwhen the window gets dragged offscreen on the top and left sides of the screen.

• Knobs inTokyo Dawn Records plugins may not behave as expected whendragging long distances. Setting the 'Continuous Drag' option in the plugin'soptions to 'Linear' fixes the issue.

• Similarly, the knobs inVoxengo plugins behave better when you enable the'Radial knob mode' setting in the global settings.

• IfScaler 2's interface lags, blacks out, or otherwise renders poorly,then you can try enablingsoftwarerenderingto fix these issues.

• ujam plugins and other plugins made with the Gorilla Engine, such as theLoopCloud plugins, will throw aJS_EXEC_FAILED error when trying to loadthe plugin. Enabling thedisable_pipescompatibilityoption for those plugins will fix this.

• Plugins byKiloHearts have file descriptor leaks whenesync is enabled,causing Wine and yabridge to eventually stop working after the system hits theopen file limit. To fix this, either unsetWINEESYNC while using yabridge orswitch to usingfsync instead.

• PSPaudioware andSoundtoys plugins with expandable GUIs, such as E27and Crystallizer, may have their GUI appear in the wrong location after theGUI has been expanded. You can enable an alternativeeditor hostingmode to fix this.

• When using recentApplied Acoustics plugins likeChromaphone 3 underBitwig Studio, text entry will cause the plugin to crash because Chromaphoneuses a different text entry method when it detects Bitwig. You can use thehide_dawcompatibility option to work around this.

• VST2 plugins likeFabFilter Pro-Q 3 that can share data between differentinstances of the same plugin plugins have to be hosted within a single processfor that functionality to work. See theplugin groupssection for instructions on how to set this up. This is not necessary for VST3plugins, as multiple instances of those plugins will always be hosted in asingle process by design.

• Some hosts, particularlyArdour,REAPER,Qtractor, will by default notunload VST3 modules after you close the last plugin. This means that theassociatedyabridge-host.exe process will keep running until you close theproject. For REAPER there's an option calledAllow complete unload of VST plug-ins in theVST tab of the settingsdialog to disable this behaviour.

• Drag-and-drop to the plugin window underREAPER doesn't work because ofa long standing issue in REAPER's FX window implementation. You can use acompatibility option toforce drag-and-drop to workaround this limitation.

Aside from that, these are some known caveats:

• iZotope plugins can't be authorized because of missing functionality inWine's crypt32 implementation.
• D16 Group plugins also can't be authorized in current versions of Wine asthey don't recall their authorization status correctly.
• Waves V13 VST3 plugins have memory issues, at least under Wine. They willlikely randomly crash at some point. If you can avoid Waves, that would be forthe best. Otherwise, try the V12 versions of the plugins if you still have alicense for them.
• MIDI key labels for VST2 plugins (commonly used for drum machines andmultisamplers) will not be updated after the host first asks for them sinceVST 2.4 has no way to let the host know that those labels have been updated.Deactivating and reactivating the plugin will cause these labels to be updatedagain for the current patch.
• The Cinnamon desktop environment has some quirks with its window managementthat affect yabridge's plugin editor embedding. Most notably some plugins mayflicker while dragging windows around, and there may berenderingissues when using multiplemonitors depending on which screen has been set as primary. Enabling theXEmbedcompatibility option may help, but Wine'sXEmbed implementation also introduces other rendering issues.

There are also some (third party) plugin API extensions for that have not beenimplemented yet. See theroadmap for a list of future plans.

If your problem is not listed here, then feel free to post on theissuetracker or to ask about it inthe yabridgeDiscord. Also check theknownissues and fixes section above for help withplugin-specific issues.

• Wine 9.22 and Wine 10.x currently don't work with yabridge. You will have todowngrade to Wine 9.21 for the time being.

• Both yabridgectl and yabridge try to diagnose many common issues for you. Ifyou're running into crashes or other issues, then try launching your DAW froma terminal and reading the log output for any clues. Bitwig Studio writesplugin output to~/.BitwigStudio/log/engine.log, so you may need to lookthere instead.

• Try to use a clean Wine prefix when testing misbehaving plugins. Eithertemporarily rename~/.wine to something else, or set theWINEPREFIXenvironment variable to a directory path to have Wine use that as a prefix.Don't forget to unset it before starting your DAW or all plugins will use thatprefix.

• If you have theWINEPREFIX environment variable set and youdon't want allof your plugins to use that specific Wine prefix, then you should unset it toallow yabridge to automatically detect Wine prefixes for you.

• If you get a warning about a lowRLIMIT_RTTIME value of 200000 microseconds,then your DAW is running in an environment wherertkit is active. Rtkit isused to grant realtime scheduling privileges to applications in environmentswhere users can't do that themselves, but it also imposes severe limitationson what those applications can do. Applications known for doing this are:

  • PipeWire. With PipeWire versions above 0.3.44, you simply need to makesure your user has realtime priviliges. Follow the instructions from thesection below to enable this and then reboot your system.
  • GNOME 45+. Recent GNOME shell versions started using rtkit in the shellitself. As far as I'm aware, this happens unconditionally, and masking thertkit service to prevent it from running is the only workaround. Make sureyour user has realtime priviliges set up according to the instructions fromthe section below, and then runsudo systemctl mask rtkit-daemon.service.The warning should disappear after rebooting. Please let me know if anyoneknows a better solution for this problem!

• If yabridge prints errors or warnings about memory locking limits, then thatmeans that you have not yet set up realtime privileges for your user. Settingthe memlock limit to unlimited (or -1) is usually part of this process. Howyou should do this will depend on your distro. OnArch andManjaro, youwill need to install therealtime-privileges package, add your user to therealtime group withsudo gpasswd -a "$USER" realtime, and then reboot.Fedora does the same thing with theirrealtime-setup package, which alsosets up arealtime group that you will need to add your user to. OnDebian,Ubuntu, and distros based on those, thejackd2 package usuallysets this up for theaudio group instead. If/etc/security/limits.d/audio.conf exists, then you can simply add yourselfto theaudio group and reboot. In any other case you may need toset thisup yourself.

• If you're seeing errors related to Wine either when runningyabridgectl syncor when trying to load a plugin, then it can be that your installed version ofWine is much older than the version that yabridge has been compiled for.Yabridgectl will automatically check for this when you runyabridgectl syncafter updating Wine or yabridge. You can also manually verify that Wine isworking correctly by running one of the Wine plugin host applications.Assuming that yabridge is installed under~/.local/share/yabridge, thenrunning~/.local/share/yabridge/yabridge-host.exe directly (sonotwine ~/.local/share/yabridge/yabridge-host.exe, that won't work) in a terminalshould print a few messages related to Wine's startup process followed by thefollowing line:

  Usage: yabridge-host.exe <plugin_type> <plugin_location> <endpoint_base_directory>

  If you're seeing a002b:err:module:__wine_process_init error instead, thenyour version of Wine is too old for this version of yabridge and you'll haveto upgrade your Wine version. Instructions for how to do this on Ubuntu can befound on theWineHQ website.

  If you're getting a0024:err:process:exec_process error, then your Wineprefix is set to 32-bit only and it won't be possible to run 64-bitapplications likeyabridge-host.exe.

• Sometimes left over Wine processes can cause problems. Runwineserver -k toterminate Wine related in the current or default Wine prefix.

• If plugin windows show up as a large overlay over the entire screen, coveringup other windows and making it impossible to interact with anything elsewithout Alt+Tabbing to them, then make sure the 'Allow the window manager tocontrol the windows' checkbox in winecfg's Graphics tab is checked.

• If you're using alot of plugins and you're unable to load any new plugins,then you may be running into Xorg's limit of 256 clients. The exact number ofplugins it takes for this to happen will depend on your system and the otherapplications running in the background. An easy way to check if this is thecase would be to try and runwine cmd.exe from a terminal. If this prints amessage about the maximum number of clients being reached (or if you are notable to open the terminal at all), then you might want to consider usingplugin groups to run multiple instances of your mostfrequently used plugins within a single process. And if you're using manyinstances of a single VST2 plugin, using the VST3 or CLAP version of thatplugin may also help since they'll share a single process.

  Alternatively you can try increasing Xorg's limit itself.First, check what your current limit is:In a terminal, run:less /var/log/Xorg.0.1 (or use any other text editor)Search for a line containing "MaxClients". This then states the currently setlimit.Then check if higher values are supported:In a terminal, run:/usr/lib/Xorg -maxclients 9999This should give an error message and show some information like this:

  maxclients must be one of 64, 128, 256, 512, 1024 or 2048

  Let's say we pick 1024. Here's how to apply it.Create this file (will require sudo):/etc/X11/xorg.conf.d/99-maxclients.confAdd this content:

  Section "ServerFlags"    Option "MaxClients" "1024"EndSection

  Save and reboot your system. Once you are logged back in, you can verify thatthe setting has been applied by using the same approach for checking thepreviously set limit (see above). Now it should be less likely to run into theprevious issue regarding "too many clients" when opening lots of plugins.

• If you're using aWINELOADER that runs the Wine process under a separatenamespace while the host is not sandboxed, then you'll have to use theYABRIDGE_NO_WATCHDOG environment variable to disable the watchdog timer. Ifyou know what this means then you probably know what you're doing. In thatcase, you may also want to useYABRIDGE_TEMP_DIR to choose a differentdirectory for yabridge to store its sockets and other temporary files in.

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 thesenegative side effects:

• First of all, you'll want to make sure that you can run programs with realtimescheduling. Note that on Arch and Manjaro this does not necessarily require arealtime kernel as they include thePREEMPT patch set in their regularkernels. You can verify that this is working correctly by runningchrt -f 10 whoami,which should print your username, and runninguname -a should printsomething that containsPREEMPT in the output.

  If theuname -a output containsPREEMPT_DYNAMIC, then run eitherzgrep PREEMPT /proc/config.gz orgrep PREEMPT "/boot/config-$(uname -r)"depending on your distro. IfCONFIG_PREEMPT is not set, then either add thepreempt=full kernel parameter or better yet, switch to a kernel that'soptimized for low latencies.

• You can also try enabling thethreadirqs kernel parameter and using whichcan in some situations help with xruns. After enabling this, you can usertirq to increase the priority ofinterrupts for your sound card.

• Make sure that you're using the performance frequency scaling governor, aschanging clock speeds in the middle of a real time workload can cause latencyspikes. Since Linux 5.9 it's possible to do this by setting thecpufreq.default_governor=performance to the kernel's command line in yourboot loader configuration.

• The last but perhaps the most important thing you can do is to use a build ofWine compiled with Proton's fsync or FUTEX2 patches. This can improveperformance significantly when using certain multithreaded plugins. If you arerunning Arch or Manjaro, then you can useTk-Glitch's Winefork for a customizableversion of Wine with the fsync patches included. Make sure to follow theinstructions in the readme to build a version of wine-tkg using the defaultprofile and don't try to use the prebuilt releases as they will have fshackenabled which tends to break many plugins that use Direct3D for theirrendering. You'll also want to make sure you're running Linux kernel 5.16 ornewer as those include support the_fsync_futex_waitv option that's enabledby default though wine-tkg'scustomization.cfg. Finally, you'll have to settheWINEFSYNC environment variable to1 to enable fsync. See theenvironment configuration section below for moreinformation on where to set this environment variable so that it gets pickedup when you start your DAW.

• If you have the choice, the VST3 version of a plugin will likely performbetter than the VST2 version. And if there is a CLAP version, then that mayperform even better.

• If the plugin doesn't have a VST3 or CLAP version, thenplugingroups can also greatly improve performance when manyinstances of same VST2 plugin.VST3 and CLAP plugins have similarfunctionality built in by design. Some plugins, like the BBC Spitfireplugins, can share a lot of resources between different instances of theplugin. Hosting all instances of the same plugin in a single process can inthose cases greatly reduce overall CPU usage and get rid of latency spikes.

This section is relevant if you want to configure environment variables in sucha way that they will be set when you launch your DAW from the GUI instead offrom a terminal. You may want to enableWINEFSYNC for fsync support with acompatible Wine version and kernel, or you may want to change your searchPATHto allow yabridge to find theyabridge-*.exe binaries if you're using yabridgedirectly from thebuild directory. To do this you'll need to change yourlogin shell's profile, which is different from the configuration loaded duringinteractive sessions. And some display manager override your login shell toalways use/bin/sh, so you need to be careful to modify the correct file orelse these changes won't work. You can find out your current login shell byrunningecho $SHELL in a terminal.

• First of all, if you're using GDM, LightDM or LXDM as your display manager(for instance if you're using GNOME, XFCE or LXDE), then your display managerwon't respect your login shell and it will always use/bin/sh. In that caseyou will need to add the following line to~/.profile to enable fsync:

  export WINEFSYNC=1

• If you are using the defaultBash shell and you're not using any of theabove display managers, then you will want to add the following line to~/.bash_profile (or~/.profile if the former does not exist):

  export WINEFSYNC=1

• If you are usingZsh, then you can add the following line to~/.zprofile(~/.zshenv should also work, but some distros such as Arch Linux overwritethe environment after this file has been read):

  export WINEFSYNC=1

• If you are usingfish, then you can add the following line to either~/.config/fish/config.fish or some file in~/.config/fish/conf.d/:

  set -gx WINEFSYNC 1# Or if you're changing your PATH:set -gp fish_user_paths~/directory/with/yabridge/binaries

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

To compile yabridge, you'll needMeson andthe following dependencies:

• GCC 10+
• A Wine installation withwinegcc and the development headers. The latestcommits contain a workaround for a winelibcompilationissue with Wine 5.7+.
• libxcb

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

• Asio
• bitsery
• function2
• ghc::filesystem
• tomlplusplus
• Version 3.7.7 of theVST3 SDK withsomepatchesto allow Winelib compilation
• Version 1.1.9 of theCLAP headers.

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

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

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

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

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

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

It also possible to build 32-bit versions of yabridge's libraries, which wouldlet you use both 32-bit and 64-bit Windows VST2, VST3, and CLAP plugins from a32-bit Linux plugin host. This is mostly untested since 32-bit only Linuxapplications don't really exist anymore, but it should work! The build systemwill still assume you're compiling from a 64-bit system, so if you're compilingon an actual 32-bit system you would need to comment out the 64-bityabridge-host andyabridge-group binaries inmeson.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 theamount of system memory available. See the CI build definitions for someexamples on how to add static linking in the mix if you're going to run thisversion of yabridge on some other machine.

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

• YABRIDGE_DEBUG_FILE=<path> allows you to write yabridge's debug messages aswell as all output produced by the plugin and by Wine itself to a file. Forinstance, you could launch your DAW withenv YABRIDGE_DEBUG_FILE=/tmp/yabridge.log <daw>, and then usetail -F /tmp/yabridge.log to keep track of the output. If this option is notpresent then yabridge will write all of its debug output to STDERR instead.

• YABRIDGE_DEBUG_LEVEL={0,1,2}{,+editor} allows you to set the verbosity ofthe debug information. You can set a debug level, optionally followed by+editor to also get more debug output related to the editor window handling.Each level increases the amount of debug information printed:

  • A value of0 (the default) means that yabridge will only log the outputfrom the Wine process and some basic information about theenvironment, the configuration and the plugin being loaded.
  • A value of1 will log detailed information about most events and functioncalls sent between the plugin host and the plugin. This filters out somenoisy events such aseffEditIdle() andaudioMasterGetTime() since thoseare sent multiple times per second by for every plugin.
  • A value of2 will cause all of the events to be logged without anyfiltering. This is very verbose but it can be crucial for debuggingplugin-specific problems.

  More detailed information about these debug levels can be found insrc/common/logging.h.

See thebug reporttemplatefor an example of how to use this.

Wine's ownlogging facilities can alsobe very helpful when diagnosing problems. In particular the+message,+module and+relay channels are very useful to trace the execution pathwithin the loaded plugin itself.

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

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