yabridge/docs/architecture.md

Architecture

The project consists of two components: a Linux native VST plugin (libyabridge.so) and a VST host that runs under Wine (yabridge-host.exe/yabridge-host.exe.so, and yabridge-host-32.exe/yabridge-host-32.exe.so if the bitbirdge is enabled). I'll refer to the copy of or the symlink to libyabridge.so as the plugin, the native Linux VST host that's hosting the plugin as the native VST host, the Wine VST host application that's hosting a Windows .dll file as the Wine VST host, and the Windows VST plugin that's being loaded in the Wine VST host as the Windows VST plugin. The whole process works as follows:

1. Some copy of or a symlink to libyabridge.so gets loaded as a VST plugin in a Linux VST host. This file should have been renamed to match a Windows VST plugin .dll file in the same directory. For instance, if there's a Serum_x64.dll file you'd like to bridge, then there should be a symlink to libyabridge.so named Serum_x64.so.

2. The plugin first attempts to locate and determine:

   • The Windows VST plugin .dll file that should be loaded.

   • The architecture of that VST plugin file. This is done by inspecting the headers if the .dll file.

   • The location of the Wine VST host. This will depend on the architecture detected for the plugin. If the plugin was compiled for the x86_64 architecture or the 'Any CPU' target, then we will look for yabridge-host.exe. If the plugin was compiled for the x86 architecture, when we'll search for yabridge-host-32.exe.

     We will first search for this file alongside the actual location of libyabridge.so. This is useful for development, as it allows you to use a symlink to libyabridge.so directly from the build directory causing yabridge to automatically pick up the right version of the Wine VST host. If this file cannot be found, then it will fall back to searching through the search path.

   • The Wine prefix the plugin is located in. If the WINEPREFIX environment variable is specified, then that will be used instead.

3. The plugin then sets up several Unix domain socket endpoints to communicate with the Wine VST host somewhere in a temporary directory and starts listening on them. We'll use multiple sockets so we can easily handle multiple data streams from different threads using blocking synchronous operations. This greatly simplifies the way communication works without compromising on latency. The different sockets will be described below. We communicate over Unix domain sockets rather than using shared memory directly because this way we get low latency communication without any manual synchronisation for free, while being able to send messages of arbitrary length without having to split them up first. This is useful for transmitting audio and preset data which can be any arbitrary size.

4. The plugin launches the Wine VST host in the detected wine prefix, passing the name of the .dll file it should be loading and the base directory for the Unix domain sockets that are going to be communciated over as its arguments.

5. The Wine VST host connects to the sockets and communication between the plugin and the Wine VST host gets set up. The following types of events each get their own socket:

   • Calls from the native VST host to the plugin's dispatcher() function. These get forwarded to the Windows VST plugin through the Wine VST host.

   • Calls from the native VST host to the plugin's dispatcher() function with the effProcessEvents opcode. These also get forwarded to the Windows VST plugin through the Wine VST host. This has to be handled separately from all other events because of limitations of the Win32 API. Without doing this the plugin would not be able to receive any MIDI events while the GUI is being resized or a dropdown menu or message box is shown.

   • Host callback calls from the Windows VST plugin through the audioMasterCallback function. These get forwarded to the native VST host through the plugin.

     Both the dispatcher() and audioMasterCallback() functions are handled in the same way, with some minor variations on how payload data gets serialized depending on the opcode of the event being sent. See the section below this for more details on this procedure.

   • Calls from the native VST host to the plugin's getParameter() and setParameter() functions. Both functions get forwarded to the Windows VST plugin through the Wine VST host using a single socket because they're very similar and don't need any complicated behaviour.

   • Calls from the native VST host to the plugin's processReplacing() and processDoubleReplacing() functions. These functions get forwarded to the Windows VST plugin through the Wine VST host. In the rare event that the plugin does not support processReplacing() and only supports The deprecated commutative process() function, then the Wine VST host will emulate the behavior of processReplacing() instead. Single and double precision audio go over the same socket since the host will only call one or the other, and we just use a variant to determine which one should be called on the Wine host side.

   • And finally there's a separate socket for control messages. At the moment this is only used to transfer the Windows VST plugin's AEffect object to the plugin and the current configuration from the plugin to the Wine VST host on startup.

   The operations described above involving the host -> plugin dispatcher()and plugin -> host audioMaster() functions are all handled by first serializing the function parameters and any payload data into a binary format so they can be sent over a socket. The objects used for encoding both the requests and the responses for theses events can be found in src/common/serialization.h, and the functions that actually read and write these objects over the sockets are located in src/common/communication.h. The actual binary serialization is handled using bitsery.

   Actually sending and receiving the events happens in the send_event() and receive_event() functions. When calling either dispatch() or audioMaster(), the caller will oftentimes either pass along some kind of data structure through the void pointer function argument, or they expect the function's return value to be a pointer to some kind of struct provided by the plugin or host. The behaviour for reading from and writing into these void pointers and returning pointers to objects when needed is encapsulated in the DispatchDataConverter and HostCallbackDataCovnerter classes for the dispatcher() and audioMaster() functions respectively. For operations involving the plugin editor there is also some extra glue in Vst2Bridge::dispatch_wrapper. On the receiving end of the function calls, the passthrough_event() function which calls the callback functions and handles the marshalling between our data types created by the *DataConverter classes and the VST API's different pointer types. This behaviour is separated from receive_event() so we can handle MIDI events separately. This is needed because a select few plugins only store pointers to the received events rather than copies of the objects. Because of this, the received event data must live at least until the next audio buffer gets processed so it needs to be stored temporarily.

6. The Wine VST host loads the Windows VST plugin and starts forwarding messages over the sockets described above.

7. After the Windows VST plugin has started loading we will forward all values from the Windows VST plugin's AEffect struct to the plugin, and the plugins configuration gets sent back over the same socket to the Wine VST host. After this point the plugin will stop blocking and the initialization process is finished.

Plugin groups

When using plugin groups, the startup and event handling behavior is slightly different.

• First of all, instead of directly spawning a Wine process to host the plugin, yabridge will either:

  • Connect to an existing group host process that matches the plugin's combination of group name, Wine prefix, and Windows VST plugin architecture, and ask it to host the Windows VST plugin.
  • Spawn a new group process and detach it from the process, then proceed as normal by connecting to that process as described above. When two yabridge instances are initialized simultaneously and both try to launch a new group process, then the process that manages to listen on the group's socket first will handle both instances.

• Events, both Win32 messages and dispatcher() events, are handled slightly differently when using plugin groups. Because most of the Win32 API cannot be used from multiple threads, all plugin initialization and all event handling has to be done from the same thread. To achieve this, yabridge will use a slightly modified version of the dispatcher() handler that executes the actual events for all plugins within a single Boost.Asio IO context.

• Win32 messages are now also handled on a timer within the same IO context so mentioned above. This behavior is different from individually hosted plugins, where the message loop can simply be run after every event. If any of the plugins within the plugin group is in a state that would cause the message loop to fail, such as when a plugin is in the process of opening its editor GUI, then the message loop will be skipped temporarily.