From 8b625ab8fe4e76e117a32cda9771743c111153e3 Mon Sep 17 00:00:00 2001 From: Jonathan Bernard Date: Wed, 10 Jun 2026 17:16:19 -0500 Subject: [PATCH] README and scripts for managin BitWig with Wine 9.21 to support Windows VSTs via yabridge. --- README.md | 193 +++++++++++++++++++++++++ scripts/bitwig-studio-yabridge-9.21.sh | 21 +++ scripts/wine-staging-9.21.sh | 37 +++++ 3 files changed, 251 insertions(+) create mode 100755 scripts/bitwig-studio-yabridge-9.21.sh create mode 100755 scripts/wine-staging-9.21.sh diff --git a/README.md b/README.md index 354ee23..161f5e6 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,12 @@ below so the old setup can still be recovered from Git history. ## Current Contents +- `scripts/bitwig-studio-yabridge-9.21.sh` - launcher for native Bitwig Studio + that forces yabridge to use the local Wine Staging 9.21 wrapper. - `scripts/set-pipewire-latency.sh` - helper for checking, forcing, and clearing PipeWire graph quantum/rate metadata. +- `scripts/wine-staging-9.21.sh` - isolated Wine Staging 9.21 wrapper for + yabridge and VST maintenance without replacing the system Wine package. - `sounds.txt` - notes about useful electric piano, piano, brass, pad, organ, string, mallet, and synth sounds. - `soundfounts/` - archived SoundFont resources. @@ -40,6 +44,195 @@ This override is not expected to be necessary when working in Bitwig Studio. Bitwig is the DAW for the new workflow, so latency should normally be handled inside that DAW/session rather than forced globally through this helper. +## Windows VSTs With Wine And yabridge + +Windows VST plugins should be installed into a dedicated Wine prefix and then +exposed to Bitwig Studio through yabridge. The prefix itself should live on +Linux-native storage, while large sample libraries can live on the larger NTFS +music-production drive. + +Use the native Bitwig Studio package for this workflow. The launcher below +execs `/usr/bin/bitwig-studio`; Flatpak Bitwig installations should be avoided +for yabridge-hosted plugins because they do not run in the same host filesystem +and library environment. + +### Paths + +Use these paths as the standard layout: + +```sh +export VST_WINEPREFIX="$HOME/.local/share/wineprefixes/music-production-vst" +export VST_SAMPLE_LIBRARIES="/mnt/e/music-production/sample-libraries" +``` + +- `VST_WINEPREFIX` stores the Windows plugin installations, Wine registry, user + profile, authorization tools, and plugin binaries. +- `VST_SAMPLE_LIBRARIES` stores large mostly-read-only sample content, such as + the Keyscape/Spectrasonics libraries. +- yabridge-managed Linux plugin wrappers are created outside the prefix under + the normal Linux plugin locations, such as `~/.vst/yabridge` and + `~/.vst3/yabridge`. + +Make sure `/mnt/e` is mounted and writable before installing or using plugins +that depend on sample libraries from that drive. + +Keep installers and downloads outside the prefix. A useful convention is: + +```sh +mkdir -p "$HOME/Music/Production/Installers" +mkdir -p "$HOME/Music/Production/Backups" +``` + +### Isolated Wine 9.21 + +This repo uses a local Wine Staging 9.21 wrapper for yabridge instead of +replacing the system Wine package. The wrapper expects Wine to be extracted at: + +```sh +$HOME/.local/opt/wine-staging-9.21 +``` + +Verify the wrapper before using it: + +```sh +scripts/wine-staging-9.21.sh --version +``` + +Expected output: + +```text +wine-9.21 (Staging) +``` + +The system Wine package remains independent: + +```sh +/usr/bin/wine --version +``` + +The wrapper defaults to `wine64`, which matches the current 64-bit yabridge +setup. Override paths only when testing or moving the local Wine install: + +```sh +WINE_STAGING_921_ROOT="$HOME/.local/opt/wine-staging-9.21" \ + scripts/wine-staging-9.21.sh --version + +WINE_STAGING_921_LOADER=wine64 \ + scripts/wine-staging-9.21.sh --version +``` + +### First-Time Prefix Setup + +Create the prefix and sample-library directory: + +```sh +export VST_WINEPREFIX="$HOME/.local/share/wineprefixes/music-production-vst" +export VST_SAMPLE_LIBRARIES="/mnt/e/music-production/sample-libraries" + +mkdir -p "$HOME/.local/share/wineprefixes" +mkdir -p "$VST_SAMPLE_LIBRARIES" +WINEPREFIX="$VST_WINEPREFIX" WINEARCH=win64 \ + scripts/wine-staging-9.21.sh wineboot -u +``` + +Open Wine configuration once to finish initialization and review settings: + +```sh +WINEPREFIX="$VST_WINEPREFIX" scripts/wine-staging-9.21.sh winecfg +``` + +If an installer asks for a sample-library location, point it at the NTFS sample +library path through Wine's `Z:` drive: + +```text +Z:\mnt\e\music-production\sample-libraries +``` + +For vendor-specific libraries, prefer a subdirectory: + +```text +Z:\mnt\e\music-production\sample-libraries\Spectrasonics +``` + +If an installer insists on putting a large library inside `C:\`, install the +plugin first, then move the library to `VST_SAMPLE_LIBRARIES` and replace the +original location with a symlink from the prefix to the real library path. Do +not move Wine registry files, authorization tools, or plugin binaries this way. + +### Initializing A Maintenance Shell + +For plugin installation and maintenance, start a shell with the dedicated prefix +variables set: + +```sh +export VST_WINEPREFIX="$HOME/.local/share/wineprefixes/music-production-vst" +export VST_SAMPLE_LIBRARIES="/mnt/e/music-production/sample-libraries" +export WINEPREFIX="$VST_WINEPREFIX" +``` + +Then run installers from that shell: + +```sh +scripts/wine-staging-9.21.sh "$HOME/Music/Production/Installers/Plugin Installer.exe" +``` + +Common maintenance commands should also go through the wrapper: + +```sh +scripts/wine-staging-9.21.sh winecfg +scripts/wine-staging-9.21.sh regedit +scripts/wine-staging-9.21.sh winepath 'C:\Program Files\Common Files\VST3' +``` + +After installing, removing, or updating plugins, sync yabridge: + +```sh +yabridgectl add "$VST_WINEPREFIX/drive_c/Program Files/Common Files/VST3" +yabridgectl add "$VST_WINEPREFIX/drive_c/Program Files/Steinberg/VstPlugins" +WINELOADER="$PWD/scripts/wine-staging-9.21.sh" yabridgectl sync +yabridgectl status +``` + +Only the `add` commands need to be repeated when a new plugin directory should +be managed by yabridge. For normal plugin updates, run the installer in the +maintenance shell and then run: + +```sh +WINELOADER="$PWD/scripts/wine-staging-9.21.sh" yabridgectl sync +yabridgectl status +``` + +### Launching Bitwig With yabridge + +Launch Bitwig through the repo wrapper when using bridged Windows plugins: + +```sh +scripts/bitwig-studio-yabridge-9.21.sh +``` + +That script sets: + +```sh +WINELOADER=/absolute/path/to/this/repo/scripts/wine-staging-9.21.sh +``` + +and then execs the native Bitwig launcher at `/usr/bin/bitwig-studio`. It also +unsets `WINEPREFIX` before launching Bitwig so the DAW itself does not impose a +global Wine prefix on plugin scanning. yabridge should use the prefix implied by +the managed plugin paths. + +Override the launcher paths only for testing: + +```sh +BITWIG_STUDIO=/usr/bin/bitwig-studio \ +YABRIDGE_WINELOADER="$PWD/scripts/wine-staging-9.21.sh" \ + scripts/bitwig-studio-yabridge-9.21.sh +``` + +Close Bitwig before installing, removing, updating, or syncing bridged plugins. +After syncing, reopen Bitwig and rescan plugins if it does not pick up the +changes automatically. + ## Legacy JACK Migration Notes The mainline branch in this checkout is named `main`. At the time these diff --git a/scripts/bitwig-studio-yabridge-9.21.sh b/scripts/bitwig-studio-yabridge-9.21.sh new file mode 100755 index 0000000..7840bbc --- /dev/null +++ b/scripts/bitwig-studio-yabridge-9.21.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash +set -euo pipefail + +script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" +wine_loader="${YABRIDGE_WINELOADER:-$script_dir/wine-staging-9.21.sh}" +bitwig="${BITWIG_STUDIO:-/usr/bin/bitwig-studio}" + +if [[ ! -x "$wine_loader" ]]; then + printf 'Wine loader is not executable: %s\n' "$wine_loader" >&2 + exit 127 +fi + +if [[ ! -x "$bitwig" ]]; then + printf 'Bitwig Studio launcher is not executable: %s\n' "$bitwig" >&2 + exit 127 +fi + +export WINELOADER="$wine_loader" +unset WINEPREFIX + +exec "$bitwig" "$@" diff --git a/scripts/wine-staging-9.21.sh b/scripts/wine-staging-9.21.sh new file mode 100755 index 0000000..0f06095 --- /dev/null +++ b/scripts/wine-staging-9.21.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +wine_root="${WINE_STAGING_921_ROOT:-${WINE921_ROOT:-$HOME/.local/opt/wine-staging-9.21}}" +wine_loader="${WINE_STAGING_921_LOADER:-wine64}" + +if [[ ! -x "$wine_root/usr/bin/$wine_loader" || ! -x "$wine_root/usr/bin/wineserver" ]]; then + cat >&2 <