README and scripts for managin BitWig with Wine 9.21 to support Windows VSTs via yabridge.

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

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" "$@"

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 <<EOF
+Wine 9.21 was not found under:
+  $wine_root
+
+Install it by extracting the Arch Linux Archive package there, for example:
+  mkdir -p "$wine_root"
+  curl -L -o /tmp/wine-staging-9.21-1-x86_64.pkg.tar.zst \\
+    "https://archive.archlinux.org/packages/w/wine-staging/wine-staging-9.21-1-x86_64.pkg.tar.zst"
+  bsdtar -C "$wine_root" -xf /tmp/wine-staging-9.21-1-x86_64.pkg.tar.zst
+EOF
+  exit 127
+fi
+
+export PATH="$wine_root/usr/bin:$PATH"
+if [[ -n "${WINEDLLPATH:-}" ]]; then
+  export WINEDLLPATH="$wine_root/usr/lib:$WINEDLLPATH"
+else
+  export WINEDLLPATH="$wine_root/usr/lib"
+fi
+export WINESERVER="$wine_root/usr/bin/wineserver"
+
+case "${1:-}" in
+  wine|wine64|wineboot|winecfg|wineconsole|winedbg|winefile|winepath|wineserver|regedit|msiexec)
+    command="$1"
+    shift
+    exec "$wine_root/usr/bin/$command" "$@"
+    ;;
+esac
+
+exec "$wine_root/usr/bin/$wine_loader" "$@"