vanja/yabridge
1
0
Fork 0
mirror of https://github.com/robbert-vdh/yabridge.git synced 2026-05-10 04:30:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite parts of the readme

Browse Source
This commit is contained in:
Robbert van der Helm
2020-04-30 18:59:53 +02:00
parent 8f4288dc02
commit c8a663335f
1 changed files with 38 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+38 -43
View File
@@ -1,9 +1,10 @@
# yabridge # yabridge
Yet Another way to use Windows VST2 plugins in Linux VST hosts, including an Yet Another way to use Windows VST plugins in Linux VST hosts. Yabridge
optional bitbridge to run 32-bit Windows plugins in 64-bit Linux hosts. This seamlessly supports running both 64-bit Windows VST2 plugins as well as 32-bit
project aims to be as transparent as possible to achieve the best possible Windows VST2 plugins in a 64-bit Linux VST host. This project aims to be as
plugin compatibility while also being easy to debug and maintain. transparent as possible to achieve the best possible plugin compatibility while
also staying easy to debug and maintain.
## TODOs ## TODOs
@@ -14,8 +15,8 @@ There are a few things that should be done before releasing this, including:
- Add missing details if any to the architecture section. - Add missing details if any to the architecture section.
- Rewrite parts of this readme. - Rewrite parts of this readme.
- Briefly verify that this also works fine in Reaper and Ardour. - Briefly verify that this also works fine in Reaper and Ardour.
- Finish 32-bit bitbridge. - Upstream the updated `lib32-boost-libs` PKGBUILD needed for building the
- Upstream the updated `lib32-boost-libs` PKGBUILD. bitbridge.
## Tested with ## Tested with
@@ -36,15 +37,16 @@ There are two ways to use yabridge.
### Symlinking (recommended) ### Symlinking (recommended)
The recommended way to use yabridge is through symbolic links. This allows you The recommended way to use yabridge is through symbolic links. This allows you
to update yabridge for all of your plugins in one go, and it also avoids having to update yabridge for all of your plugins in one go, as well as avoiding having
to install it globally. to install it globally.
You can either use the precompiled binaries from the GitHub releases section, or You can either use the precompiled binaries from the GitHub releases section, or
you could build yabridge directly from source. If you use the precompiled you could build yabridge directly from source. If you use the precompiled
binaries, then simply extract them to `~/.local/share/yabridge` or any other binaries, then you can simply extract them to `~/.local/share/yabridge` or to
place in your home directory. If you choose to build from source, then you can any other location in your home directory. If you choose to build from source,
directly use the binaries from the `build/` directory. For the section below I'm then you can use the compiled binaries directly from the `build/` directory. For
going to assume you've placed the files in `~/.local/share/yabridge`. the section below I'm going to assume you've placed the files in
`~/.local/share/yabridge`.
To set up yabridge for a VST plugin called To set up yabridge for a VST plugin called
`~/.wine/drive_c/Program Files/Steinberg/VstPlugins/plugin.dll`, simply create a `~/.wine/drive_c/Program Files/Steinberg/VstPlugins/plugin.dll`, simply create a
@@ -55,10 +57,10 @@ symlink from `~/.local/share/yabridge/libyabridge.so` to
ln -s ~/.local/share/yabridge/libyabridge.so "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins/plugin.so" ln -s ~/.local/share/yabridge/libyabridge.so "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins/plugin.so"
``` ```
For instance, if you wanted to set up yabridge for any of the VST plugins under As an example, if you wanted to set up yabridge for any of the VST plugins under
`~/.wine/drive_c/Program Files/Steinberg/VstPlugins`, you could run this `~/.wine/drive_c/Program Files/Steinberg/VstPlugins`, you could run the
oneliner in Bash. This will also skip any `.dll` files that are not actually VST following script in Bash. This will also skip any `.dll` files that are not
plugins. actually VST plugins.
```shell ```shell
find "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins" -type f -iname '*.dll' -print0 | find "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins" -type f -iname '*.dll' -print0 |
@@ -69,19 +71,20 @@ find "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins" -type f -iname '*.
### Copying ### Copying
It's also possible to use yabridge by making copies of `libyabridge.so` instead It is also possible to use yabridge by creating copies of `libyabridge.so`
of creating symlinks. This is not recommended as it makes updating a hassle. If instead of making symlinks. This is not recommended as it makes updating a
you choose to do this, then you'll have to make sure `yabridge-host.exe` and hassle, but it may be required if your host has issues using symlinks. If you
choose to do this, then you'll have to make sure `yabridge-host.exe` and
`yabridge-host.exe.so` are somewhere in your search path as otherwise yabridge `yabridge-host.exe.so` are somewhere in your search path as otherwise yabridge
won't know where to find them. Either copy them to `/usr/local/bin` (not won't be able to find them. Either copy them to `/usr/local/bin` (not
recommended) or to `~/.local/bin` and make sure that the directory is in your recommended) or to `~/.local/bin` and make sure that the directory is in your
`PATH` environment variable. `PATH` environment variable.
## Runtime dependencies and known issues ## Runtime dependencies and known issues
Any VST2 plugin should function out of the box, although some plugins will need Any VST2 plugin should function out of the box, although some plugins will need
some additional dependencies for their editor GUIs to work correctly. Notable some additional dependencies for their GUIs to work correctly. Notable examples
examples include: include:
- **Serum** requires you to disable `d2d1.dll` in `winecfg` and to install - **Serum** requires you to disable `d2d1.dll` in `winecfg` and to install
`gdiplus` through `winetricks`. `gdiplus` through `winetricks`.
@@ -152,9 +155,9 @@ to load is 32-bit or 64-bit, and will run either `yabridge-host.exe` or
## Debugging ## Debugging
Wine's error messages and warning are typically very helpful whenever a plugin Wine's error messages and warning are generally very helpful whenever a plugin
doesn't work right away. Sadly this information is not always available. For doesn't work right away. Sadly this information is not always available. Bitwig,
instance Bitwig hides a plugin's STDOUT and STDERR streams from you. To make it for instance, hides a plugin's STDOUT and STDERR streams from you. To make it
easier to debug malfunctioning plugins, yabridge offers two environment easier to debug malfunctioning plugins, yabridge offers two environment
variables: variables:
@@ -167,13 +170,13 @@ variables:
- `YABRIDGE_DEBUG_LEVEL={0,1}` allows you to set the verbosity of the debug - `YABRIDGE_DEBUG_LEVEL={0,1}` allows you to set the verbosity of the debug
information. Every level increases the verbosity of the debug information: information. Every level increases the verbosity of the debug information:
- A value of `0` (the default) means that yabridge will only output messages - A value of `0` (the default) means that yabridge will only write messages
from the Wine process and some basic information such as the plugin being from the Wine process and some basic information such as the plugin being
loaded and the wineprefix being used. loaded and the wineprefix being used.
- A value of `1` will log information about most events and function calls - A value of `1` will log information about most events and function calls
being sent between the VST host and the plugin. This filters out some events sent between the VST host and the plugin. This filters out some events such
such as `effEditIdle()` and `audioMasterGetTime()` since those are sent tens as `effEditIdle()` and `audioMasterGetTime()` since those are sent tens of
of times per second by for every plugin. times per second by for every plugin.
- A value of `2` will cause all of the events to be logged, including the - A value of `2` will cause all of the events to be logged, including the
events mentioned above. This can be very verbose but it can be crucial for events mentioned above. This can be very verbose but it can be crucial for
debugging plugin-specific problems. debugging plugin-specific problems.
@@ -181,10 +184,10 @@ variables:
More detailed information about these levels can be found in More detailed information about these levels can be found in
`src/common/logging.h`. `src/common/logging.h`.
Wine's own [logging facilities](https://wiki.winehq.org/Debug_Channels) enabled Wine's own [logging facilities](https://wiki.winehq.org/Debug_Channels) can also
through the `WINEDEBUG` environment variable can also be very helpful when be very helpful when diagnosing problems. In particular the `message` and
diagnosing problems. In particular the `message` and `relay` channels are very `relay` channels are very useful to trace the execution path within the loading
useful to trace the execution path within the loading VST plugin itself. VST plugin itself.
### Attaching a debugger ### Attaching a debugger
@@ -198,22 +201,14 @@ env YABRIDGE_DEBUG_FILE=/tmp/yabridge.log YABRIDGE_DEBUG_LEVEL=1 carla --gdb
Doing the same thing for the Wine VST host can be a bit tricky. You'll need to Doing the same thing for the Wine VST host can be a bit tricky. You'll need to
launch winedbg in a seperate detached terminal emulator so it doesn't terminate launch winedbg in a seperate detached terminal emulator so it doesn't terminate
together with the plugin, and winedbg can be a bit picky in the arguments it together with the plugin, and winedbg can be a bit picky in the arguments it
accepts. I've already set this up behind a feature flag for KDE Plasma. Other accepts. I've already set this up behind a feature flag for use in KDE Plasma.
desktop environments and window managers will require some slight modifications Other desktop environments and window managers will require some slight
in `src/plugin/host-bridge.cpp`. To enable this, simply run: modifications in `src/plugin/host-bridge.cpp`. To enable this, simply run:
```shell ```shell
meson configure build --buildtype=debug -Duse-winedbg=true meson configure build --buildtype=debug -Duse-winedbg=true
``` ```
## Rationale
I started this project because the alternatives were either unmaintained, not
self-contained or very difficult to work with. With this implementation I'd like
to prioritize maintainability and correctness, with performance being a
secondary goal. Please let me know if you have any suggestions on how to improve
this!
## Architecture ## Architecture
The project consists of two components, a Linux native VST plugin The project consists of two components, a Linux native VST plugin