PatchBay manual (V1.1)

Introduction
PatchBay is a powerful app to route audio and midi throughout your macOS system:


Interface
PatchBay's intuitive interface is easy to use:

Step 1
Create a new patch
Step 2
Insert audio/midi elements and wire connections
Step 3
Run the patch and hear/see audio and midi being routed!
Details and additional options are listed below.
Elements
A wide variety of elements can be inserted in a patch:

Hardware devices
  • Audio inputs and outputs
  • Midi sources and destinations
PatchBay tools
  • Wires
  • Audio recorders
  • Annotation texts
Audio Units
  • Instruments (midi to audio)
  • Effects (audio to audio)
  • Midi-controlled Effects (audio+midi to audio)
And optionally

Inputs, outputs, sources and destinations in PatchBay
For audio device elements, PatchBay uses the words input and output, following Apple macOS. In e.g. System Settings/Sound, a microphone is an "input" and a speaker is an "output". In a patch, an audio input acts as an audio source, while an audio output acts as an audio destination.

For midi device elements, PatchBay uses the words source and destination, as the words input and output are ambiguous. A midi keyboard connected to your mac uses a cable from the keyboard's "midi out" to your mac's "midi in", and acts as a midi source in PatchBay. An app's "virtual midi out" (such as e.g. created by Logic Pro) also acts as a source in PatchBay. Source elements appear with a male 5-pin plug, while midi destinations appear as a female 5-pin plug.
Channels and Volume
Double click on any wire to:
  • Select input/output channels (audio)
  • Select source/destination channels (midi)
  • Adjust volume (audio only)

For midi, 16 channels are available, all of which are selected by default. For audio, up to 64 channels are available to support extensive multichannel audio interfaces. Audio channels 1+2 are selected by default for stereo sound.

When your input/output (or source/destination) channel selections are not the same, they are automatically mapped as one-to-many (e.g. mono to stereo), many-to-one (e.g. stereo to mono), or many-to-many. If you require a mapping different from the automatic one, you can just add more wires to specify the mapping, even up to one wire for each channel.

When multiple audio or midi wires are connected towards one element, audio or midi over the same channel will be mixed (added for audio, and multiplexed for midi).

Double click on any audio input or output device element to adjust its volume. Nearly all audio devices have output volume setting (normally controlled by the keyboard F10-F12), while many devices provide some sort of (mic) gain setting.
Audio Recorder
The audio recorder element provides:
  • Multitrack audio recording
  • From 1 up to 16 channels
  • Import audio files

  • Export as one multitrack or multiple mono/stereo files
  • Export lossless WAV or compressed M4A

  • Supports multiple samples rates and conversion
  • Audio thru and play-repeat
Audio Units
PatchBay supports three types of audio units in patches:
  • Instruments (midi to audio)
  • Effects (audio to audio)
  • Midi-controlled Effects (audio+midi to audio)
Audio Units are always used in stereo audio format via channels 1-2. Double-click any audio unit element to open its user interface. Any audio unit can be temporally bypassed by the power button.
App Audio
Optionally, PatchBay allows for the integration of apps in patches. This requires the installation of PatchBay's so-called virtual (non-hardware) audio device.

Installer and Deinstaller
Apple allows virtual audio devices to be shipped only outside of the Mac App Store; therefore the installer is offered here as a free download.
Download
Installer.pkg
Download
Deinstaller.pkg

Security
When you open the downloaded .pkg file, Apple's system app "Installer" will handle the (de-) install.

Both installer and deinstaller have been security-checked and code-signed ('notarised') by Apple. You can verify this by clicking the lock at top-right of the Installer window (Rodotti = Peter-André Redert).

During the entire (de-) install, no security warning popups will occur. "Installer" will ask your password to authorize the (de-) install.

Virtual audio device
After installation, PatchBay appears as a new audio input and output in your mac's System Settings/Sound, next to the built-in mic and speakers, and possibly your other external audio interfaces.

Even though PatchBay is virtual and has no hardware, apps in a patch can use it to send and receive audio. The PatchBay audio device works together with the PatchBay app; without the app, the audio device streams silence.

Automatic audio device selection
PatchBay will select itself in System Settings automatically during the run of a patch. Whenever you stop the patch, or the PatchBay app, your normal audio input and output are restored. In case you accidentally did select PatchBay in System Settings/Sound by hand, it will just stream silence and you can reselect your normal audio input and output.

Manual audio device selection
Most apps use the audio device selected in System Settings, which is managed by PatchBay when running a patch. Some apps however (FaceTime, Garageband, Logic Pro, ...) provide manual audio device selection. Ensure that you select PatchBay or "System Setting" manually in those apps if you use them in a patch.

Limitations
There are limitations to the use of App Audio. First, although very rare, individual apps may actively refuse to connect to PatchBay's audio device. One known example is Whatsapp (Mac App Store V24.23, dec 2024) whose audio output is available in PatchBay, but its audio input refuses to listen to PatchBay. Thus, PatchBay cannot send audio to Whatsapp. If you encounter a similar case, please ask for support to see if we can solve it for your specific case.

Secondly, while audio from each app connected to PatchBay's audio device can be individually received and rerouted, audio is sent to all apps together. Apple macOS ties all app audio inputs together. In a patch, this is indicated by orange channel numbers.
Especially for this reason, the PatchBay audio device has been equipped with no less than 16 channels. Apps that do not offer channel selection typically use channels 1+2, which thus share their audio inputs. Apps that allow manual input channel selection (e.g. Logic Pro, Garageband, JamKazam, ...) can use channels 3-16 for independent audio input routing.

The net effect is that the audio of several apps can only be concatenated (chained) by using increasing channels, e.g. first app receives audio on channels 1+2, the second app on channels 3+4, third app channels 5+6, etc. This requires for all but the first app that its input channels can be selected.

Lastly, App Audio depends on Apple macOS's continued support for virtual audio devices. This support has been available for decades, and many other well-known software packages rely on virtual audio devices (e.g. Microsoft Teams). With future macOS updates, app audio functionality may change.

Typical use
App audio has very appealing types of use, e.g.:
App Midi
When midi is sent to an app in a patch, PatchBay automatically creates a software midi port for that app, e.g. "PatchBay to Garageband", "PatchBay to Logic Pro", etc. These ports can be selected and used within the respective apps.
Settings
In PatchBay's settings, audio rate and latency can be adjusted:
  • Audio sampling rate from 44.1 to 96 kHz
  • Audio latency from 8 msec downto 1 msec

Audio sample rate is applied to all audio devices, audio units and apps in the running patch. Latency relates to PatchBay's processing only, which adds to the native latency of hardware, units, apps, and macOS. A high sample rate combined with low latency may cause cpu overload resulting in audio crackling.

The use of App Audio is optional, and enabled/disabled by installing/deinstalling PatchBay's virtual audio device.

App Midi is always enabled.
Contact and Support
Feel free to contact me at contact@rodotti.nl with any questions, issues and suggestions!

Happy patching!

André Redert
Rodotti