This is a guide aimed at providing some understanding about
MidiBridge (and CoreMIDI) and how to use that knowledge to your advantage to
interconnect apps, hardware and network sessions. Once the basics are
covered, some step-by-step recipes for connecting up less obvious situations
are provided.

Don't forget to turn on the 'Run in Background' option in the
MidiBridge Preferences panel. This is off by default (and purposefully as we
want the user to consciously be aware that they are allowing MidiBridge to
keep on runnin' in the background)

The above applies to MidiBridge 1.3 and earlier. As of version 1.4,
background processing is on by default (with a 15 minute idle timeout). The
idle timeout value can be changed in the Options tab of the Preferences
page. Setting it to 0 minutes turns backgrounding off completely.

First a little about CoreMIDI - port advertising

When an app runs it can register virtual ports in CoreMIDI that can be
seen by other apps and on which other apps can send or receive events. There
are two types of virtual ports (also known as endpoints) - sources
and destinations. An app doesn't have to advertise its own
virtual ports. It may choose to use the virtual ports of other apps instead.
Here's something to remember:

Just because an app doesn't advertise any ports of its own doesn't mean
that it can't be controlled via MidiBridge!

It just won't show up in:

The Interface Tab - Sources to the left of you, destinations to the right

This is the main tab in MidiBridge and from where you create connections
between sources (inputs) and destinations (outputs). These ports are usually
(but not always) in pairs and are one of the following type:

A physical device port, like Midi Mobilizer I, SynthStation25...

A CoreMIDI physical device port, like Midi Mobilizer II, iRig MIDI...

The CoreMIDI network port (send/receive over wifi)

MidiBridge's own virtual input/output ports that it advertises

Virtual input/output ports advertised by other apps

MidiBridge can route events from any of these types to any other type,
but the routing must be between a source and a destination
from MidiBridge's point of view.

To connect source A to destinations B and C, you touch input/source port
A on the left and then touch B and C on the right and green lines will be
drawn between them to show they are connected. Touch port A again to tell
MidiBridge you're done interconnecting to that port.

Here's a screenshot of MidiBridge with just about every type of port,
connection and option set:

The above screenshot shows the following:

A CoreMIDI network session is active (CoreMIDI Net in is yellow and the
badge '1' on the Interfaces tab button is shown)

Arctic Keys is up and running (Arctic Keys virtual ports shown)

Midi Mobilizer I is present and a filter on its input is active
(Midi Mobilizer ports shown and 'On' badge over filter button displayed on
input port)

MidiBridge's own virtual ports have been created and any events received
from another app on the port MidiBridge will be passed to MidiBridge's own
output (that other apps could be listening to) and the Midi Mobilizer's
output. (Green lines going from MidiBridge to MidiBridge & Midi Mobilizer)

Both MidiBridge and Arctic Keys ports are virtual ports (V-Cable symbol
in port)

Events received from the Midi Mobilizer's input will be sent to Arctic
Keys and the Network session. (Grey lines running from Midi Mobilizer in to
CoreMIDI net out and Arctic Keys out - they're grey, because currently the
MidiBridge input port is selected for connection)

You can fast switch straight to Arctic Keys by double tapping either its
input or output port (Green double arrow in port)

The Fast-switchable Applications Panel (As of version 1.4, this panel
has been renamed from 'Compatible Applications') tells you that both Arctic Keys and MidiVision are
installed on this device, but Loopy, NLog and ThumbJam are not (can't afford
them). Touching
Arctic Keys on the App Panel will fast-switch to Arctic Keys (since we know
that is running). Touching MidiVision on the App Panel will launch
MidiVision (not currently running, but installed). Touching any of the other
apps in the App Panel (the unticked ones) will redirect you to the App Store
to see if this app is of any interest to you. IMPORTANT: The Fast-switchable Applications
panel is for fast-switching compatibility only. It is not an indicator of an
app's MIDI connectivity.

The App Panel can be dragged around the screen using the top bar of the
panel. It can be dismissed by either pressing the 'X' at the top of the
panel or touching the 'Applications' tab that has a badge marked 'X'.

To summarise:

An input from MidiBridge's view is a source of MIDI events
from other apps, physical devices or the CoreMIDI network.

An output from MidiBridge's view is a destination that
MIDI events can be sent to and can be other apps, physical interfaces
or the CoreMIDI network.

Connecting different kinds of apps

Apps can either generate MIDI events, receive MIDI events or do both.

Apps fall into one or more of the following categories:

The app advertises its own virtual destination and accepts input from
it. Examples: Animoog and Sunrizer.

The app advertises its own virtual source and writes events to it.
Examples: Genome

The app doesn't advertise anything, but will read from all
sources in the system, Example: Gadget, GarageBand

The app doesn't advertise anything, but will write to all
destinations in the system. Example: SoundPrism Pro

The app only supports CoreMIDI networking (don't know of a current
example, but
early versions of Genome were like this and possibly NanoStudio)

The app advertises both a source and destination and reads/writes
to those. Examples: Arctic Keys, NLog

Categories 1,2 and 6 are easy. You just connect your desired
source/destination to the app's virtual port in MidiBridge and away you go.
You may need to tweak something in the other app to tell it you want it to
accept/send MIDI on its virtual ports (and tell it to continue working in
the background).

Category 3 apps will not show up as a separate port in MidiBridge, but
will read from MidiBridge's virtual output. To control these types of apps,
just connect your desired source to the MidiBridge destination.

Category 4 apps are the reverse of category 3. They don't show up in
MidiBridge but to use them as sources, you connect MidiBridge's virtual
source(input) to the destination you want the events to go to.

Finally, category 5 apps require a little trick to make them work. In
MidiBridge prefs, enter the word 'localhost' (without quotes) in the
CoreMIDI Network Destination field and press the Connect button. You can
also choose 'Connect Automatically' to re-start the connection when
MidiBridge launches. Essentially you are hi-jacking the CoreMIDI network to
run like a virtual port. To send events to the app that supports CoreMIDI
network, you connect a source to the CoreMIDI net destination. Vice-versa
for receiving events into MidiBridge from a category 5 app.

Application start/connect order

Now you know how to interconnect different types of apps, what about the
order in which you launch the apps? It all depends upon when each app
refreshes its view of the CoreMIDI world.

MidiBridge for example refreshes its view when it starts, when it is
returned from the background, when a physical device is connected/removed,
when a virtual port appears/disappears and when a CoreMIDI network session
starts/stops. Basically all the time. What's more is that it will
automatically re-establish any prior connections that you had set for that
port. So far, so good.

Other apps may not refresh their view so much (some just at launch or
need the user to manually refresh), so these are the rules of thumb when
setting up your connections:

Launch MidiBridge first, so that its virtual ports are available
if need be.

Unfortunately the world isn't perfect and sometimes even these rules are
not enough. If it doesn't work, you may need to switch to certain apps as
well to re-invogorate their engines. It's not exact and some trial and error
may be involved.