music-production/README.md

# Music Production Setup

This repository holds scripts, patch banks, sound resources, and notes for a
Linux-based music production setup.

The current direction is a PipeWire-based system centered around Bitwig Studio.
Older QJackCtl patchbay files, Jack Rack presets, and JACK startup/recording
scripts are being removed from the working tree, but the migration is recorded
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.
- `yoshimi-patches/` - archived Yoshimi banks and patch collections.

## PipeWire And Bitwig Studio

The new setup should prefer PipeWire as the shared audio graph instead of
manually starting JACK through QJackCtl profiles and wiring sessions with
QJackCtl patchbays.

For standalone low-latency work outside the DAW, use:

```sh
scripts/set-pipewire-latency.sh status
scripts/set-pipewire-latency.sh on 128 48000
scripts/set-pipewire-latency.sh off
```

The script writes PipeWire settings metadata with `pw-metadata -n settings`.
`on` defaults to a quantum of `128` at `48000` Hz, which is about 2.7 ms per
block. `off` clears `clock.force-quantum` and `clock.force-rate` so PipeWire
can return to normal behavior.

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
```

Install that local Wine tree from the Arch Linux Archive package:

```sh
mkdir -p "$HOME/.local/opt/wine-staging-9.21"

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 "$HOME/.local/opt/wine-staging-9.21" \
  -xf /tmp/wine-staging-9.21-1-x86_64.pkg.tar.zst
```

This intentionally does not install or downgrade the system Wine package. The
archive is unpacked into a private directory with the package's normal `usr/`
layout:

```text
$HOME/.local/opt/wine-staging-9.21/usr/bin/wine64
$HOME/.local/opt/wine-staging-9.21/usr/bin/wineserver
$HOME/.local/opt/wine-staging-9.21/usr/lib/wine
```

Do not add this Wine directory to the global shell `PATH`. Use
`scripts/wine-staging-9.21.sh` so only plugin installation, plugin maintenance,
yabridge syncs, and the Bitwig yabridge launcher use this Wine version.

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
legacy files were staged for deletion, the current `main` / `origin/main`
commit was:

```text
ee169b0e013496b177195a6719295b40f9c932dd
```

That commit is the last mainline commit where the old QJackCtl, Jack Rack, and
script-based JACK workflow is available. To inspect one of the removed files:

```sh
git show ee169b0e013496b177195a6719295b40f9c932dd:<path>
```

### Files Staged For Deletion

```text
jack-rack-presets/home/fender-jazz
jack-rack-presets/home/headphones
jack-rack-presets/home/sr505zw
jack-rack-presets/newlife/bass2
jack-rack-presets/newlife/drums
jack-rack-presets/newlife/headphones
jack-rack-presets/newlife/headphones2
jack-rack-presets/newlife/m48-mix
jack-rack-presets/newlife/yamaha-trb
jack-rack-presets/onboard/headphones
jack-rack-presets/onboard/sg200
jack-rack-presets/onboard/sr505zw
jack-rack-presets/onboard/yamaha-trb
qjackctl-routing-settings/FastTrack-Practice.xml
qjackctl-routing-settings/K6-Bass+System.xml
qjackctl-routing-settings/church-eq-bass-with-synth.xml
qjackctl-routing-settings/church-eq-mix-ears-only.xml
qjackctl-routing-settings/church-eq-mix-splitchannel-with-headphone-mix.xml
qjackctl-routing-settings/church-eq-mix-splitchannel.xml
qjackctl-routing-settings/church-eq-mix.xml
qjackctl-routing-settings/church-eq-two-bass-setup.xml
qjackctl-routing-settings/keyboard-qsynth.xml
qjackctl-routing-settings/maudio-fasttrack.xml
qjackctl-routing-settings/onboard.xml
qjackctl-routing-settings/studio.xml
scripts/nl-prepare-raw-files-synth.sh
scripts/nl-prepare-raw-files.sh
scripts/nl-rec
scripts/nl-rec-1
scripts/nl-rec-service
scripts/nl-rec-service-synth
scripts/nl-split-rec
scripts/start-church-session
scripts/start-church-session-bass-with-synth
scripts/start-church-session-two-bassists
scripts/start-home-session
scripts/start-onboard-session
```

### Jack Rack Presets

The `jack-rack-presets/` files were gzip-compressed Jack Rack XML presets at
48 kHz. They store LADSPA plugin IDs, enabled/disabled state, wet/dry settings,
and raw control values.

- `home/` contained home practice chains for Fender Jazz bass, SR505ZW bass,
  and headphones.
- `onboard/` contained onboard audio chains for headphones, SG200, SR505ZW,
  and Yamaha TRB bass.
- `newlife/` contained New Life church chains for Yamaha TRB bass, a second
  bass, M48 mix, drums, and one or two headphone mixes.

The bass presets were mono chains for instrument tone/level processing. The
headphone, M48, and drum presets were stereo or monitor-oriented chains used by
the old patchbay and session launcher scripts.

### QJackCtl Patchbays

The `qjackctl-routing-settings/` XML files were QJackCtl patchbay definitions.
They described JACK and MIDI clients, expected ports, and cables to restore
session routing.

- `FastTrack-Practice.xml` routed a FastTrack practice setup with bass through
  Jack Rack, Hydrogen, QSynth, PulseAudio JACK sink/source, and meters.
- `K6-Bass+System.xml` routed a Komplete Audio 6 setup with Jack Rack,
  PulseAudio JACK, zita-at1, bridge meters, and MIDI control.
- `maudio-fasttrack.xml` routed FastTrack bass/headphones/QSynth practice use,
  including zita-at1, meters, and a JACK-to-ALSA MIDI bridge.
- `keyboard-qsynth.xml` connected Oxygen 61 and jack-keyboard MIDI into
  QSynth, with system and PulseAudio JACK audio routing.
- `onboard.xml` connected QSynth, MDA ePiano, jack-keyboard, Alesis Recital,
  LPK25, a2j/ALSA MIDI, PulseAudio JACK, and headphone routing.
- `studio.xml` routed a studio setup with bass, mic, MDA ePiano, Alesis
  Recital, LPK25, meter ports, and system outputs.
- `church-eq-mix.xml`, `church-eq-mix-ears-only.xml`,
  `church-eq-mix-splitchannel.xml`,
  `church-eq-mix-splitchannel-with-headphone-mix.xml`,
  `church-eq-two-bass-setup.xml`, and
  `church-eq-bass-with-synth.xml` described New Life church routings for bass,
  M48 mix/drum feeds, monitors, meters, tuner input, second-bass variants, and
  synth/MDA ePiano variants.

### Legacy Scripts

The removed scripts were tightly coupled to JACK client names, QJackCtl
profiles, Jack Rack session names, and specific capture/playback ports.

- `start-home-session` started QJackCtl profile `Onboard48K`, loaded home bass
  and headphone Jack Rack presets, and started `j2amidi_bridge`.
- `start-onboard-session` started QJackCtl profile `Onboard48K` and loaded
  onboard Yamaha TRB and headphone Jack Rack presets.
- `start-church-session` started QJackCtl profile `Church48K`, loaded New Life
  bass, M48 mix, drums, and headphone Jack Rack presets, started `meterbridge`,
  and ran `devilspie`.
- `start-church-session-bass-with-synth` extended the church session with
  `yoshimi`, `a2jmidid`, and separate bass/M48 meter bridges.
- `start-church-session-two-bassists` extended the church session with second
  bass and second headphone Jack Rack chains plus separate meters.
- `nl-rec` recorded three JACK capture ports with `jack_capture`.
- `nl-rec-1` recorded the sermon channel from `system:capture_3`.
- `nl-rec-service` recorded worship, sermon, and altar files from the church
  capture ports.
- `nl-rec-service-synth` recorded the same service files while also capturing
  Yoshimi left/right outputs.
- `nl-split-rec` split one `.wavex` file into M48, drums, and bass WAV files.
- `nl-prepare-raw-files.sh` split `worship.wavex` and `altar.wavex` into M48,
  drums, and bass WAV files with `ffmpeg`.
- `nl-prepare-raw-files-synth.sh` did the same split while also extracting
  synth left/right WAV files.

These files document the old JACK-era workflow but are no longer the active
direction for this repository.