# 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](https://github.com/fraillt/bitsery). TODO: Rewrite this after the socket changes are done Actually sending and receiving the events happens in the `EventHandler::send()` and `EventHandler::receive()` 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.