Patches

A wandering minstrel I -
A thing of threads and patches,
Of ballads, songs and snatches,
And dreamy lullaby!

-- Sir William Gilbert, The Mikado

A patch is a named collection of connections that can modify the MIDI data.

When a patch becomes active it is called the current patch.

Instrument Program Changes

A patch holds a list of instrument program changes that are sent to output instruments when the patch starts. Each entry specifies an output instrument, a MIDI channel, and optionally a bank MSB, bank LSB, and program number. Bank changes are sent before the program change (MSB first, then LSB). Program changes are only sent when both an output channel and a program number are specified.

Start

When a patch becomes active, three things happen in order:

1. Its start named message, if any, is sent to all of this patch's output instruments as-is (status bytes' channels are unchanged).
2. Each instrument program change is sent to its output instrument.
3. Each connection in the patch is started (described below).

Stop

When a patch is stopped, two things happen. First each connection in the patch is stopped (described below). Second its stop named message, if any, is sent to all of this patch's output instruments as-is. As with the start message, status bytes' channels are not changed.

Connections

A connection connects an input instrument to an output instrument. The simplest connection connects one MIDI input device directly to a MIDI output device, making it a simple MIDI through.

Connections have an input instrument and (optional) input channel, output instrument and (optional) output channel, and the following values:

• Keyboard zone (low/high keys, default is all notes from 0-127)
• Transpose (default is 0)
• Velocity curve (default is linear)
• Message filter (controls which MIDI message types pass through)
• Controller mappings

If the input instrument's channel is not specified then all input from that instrument is run through the connection. If the channel is specified then any incoming MIDI bytes on other channels are ignored.

If an output instruments' channel is not specified then all messages sent to it are unchanged. If a channel is specified then all messages are changed to go out on the output channel no matter what the input channel was.

When talking about the "notes" that a connection modifies, this means all MIDI messages that have note values: note on, note off, and polyphonic pressure.

MIDI Channels

If an output uses one channel then all MIDI messages that come from the input, unless they are filtered out by the connection, are changed to go out on the output channel no matter what the input channel was. If an output uses all channels then the input's messages's channels are unchanged when they are sent to the output.

Here are a few examples.

All channels, both input and output:

• Input: all channels
• Output: all channels
• Input message comes in on channel 3, it will be sent out on channel 3

One channel for input, all channels for output:

• Input: channel 3
• Output: all channels
• Any input message coming in on channel 3 is sent out to the output on channel 3 (unless it has been filtered out by the connection) because the channel is unchanged by the output
• Any input message on any other channel is not sent to this output

One channel for input, one channel for output:

• Input: channel 3
• Output: channel 4
• Any input message coming in on channel 3 is sent out to the output on channel 4 (unless it has been filtered out by the connection)
• Any input message on any other channel is not sent to this output

All channels for input, one channel for output:

• Input: all channels
• Output: channel 4
• Any input message on any channel is sent to the output on channel 4 (unless it has been filtered out first)

Start

When a connection is started, it is attached to its input instrument so that the input instrument begins sending its messages through the connection.

Stop

When a connection is stopped, the connection is detatched from its input instrument, so that the input instrument stops sending its messages through the connection.

Controller Mappings

Each controller number 0-127 may be subject to a controller mapping. By default, all controller messages are passed through unchanged.

A controller mapping has the following values:

• Input controller number
• Output controller number (by default, the same as the input controller number)
• A "filtered" switch (off by default; if on then the controller is filtered out)
• A range (optional):
  • Minumum input value (default 0)
  • Maximum input value (default 127)
  • Minumum output value (default 0)
  • Maximum output value (default 127)
  • An "always pass through 0" switch (default on)
  • An "always pass through 127" switch (default on)

The "always pass through" switches exist because many controllers use 0 to mean "all the way off" and 127 to mean "all the way on" or, for simple switch controllers, simply "off" and "on". Even if you scale the range of controller values, these switches can ensure that the off and on values are always sent.

A controller mapping subjects an incoming controller message to the following processing:

First, if the input value is either 0 or 127, we look at the corresponding "always pass through" switch and, if it is on, the controller message is passed through unchanged.

Next, if the input value is out of range (lower than the input minimum or higher than the output maximum), then the controller message is filtered out.

Finally, the input value is mapped to an output value by scaling its value between the minimum and maximum output values. Here is a silly but hopefully illustratvie example:

• Min input value: 90
• Max input value: 110
• Min output value: 30
• Max output value: 40

In this case, if the input value was 100 (halfway between 90 and 110) then the output value would be 35 (half way between 30 and 40).

Message Filter

Each connection has a message filter that controls which types of MIDI messages pass through it. The filter has an independent on/off toggle for each message type:

• Notes (note on, note off)
• Polyphonic pressure
• Channel pressure
• Program change
• Pitch bend
• Controller
• Song pointer
• Song select
• Tune request
• Sysex
• Clock
• Start/continue/stop
• System reset

By default, sysex is filtered out and all other types pass through.

Velocity Curves

The default velocity curve is linear. Built-in curves are:

• Linear
• Exponential — rises slowly at first, then faster
• Half Exponential — halfway between exponential and linear
• Inverse Exponential — rises quickly at first, then slower
• Half Inverse Exponential — halfway between inverse exponential and linear

Custom curves are stored as a 128-entry lookup table (one output value for each possible input value 0–127).

Processing Incoming MIDI Data

While the current patch is running, MIDI data that comes in from an instrument causes these things happen:

• The data is sent to the instrument's triggers. Each trigger looks at the data and decides if it should act.

• If the data is a note on message or a sustain pedal "on" controller message, the instrument remembers what connections it is currently targeting.

• If the data is a note off message or sustain pedal "off" message, the instrument looks up the connections that were targeted for the earlier note on or sustain pedal "on" message and send the data to those connections. This ensures that note on/off and sustain on/off messages are always sent to the same connections, even if the patch has changed in the mean time.

• The data is then sent to each of the connections connected to the instrument (or, in the case of a note off, the connections that the note on used).

An input instrument can be used by more than one connection. Each connection can modify the data separately and send it to a different MIDI instrument:

• The connection's message filter is applied first. Any message type that is disabled in the filter is discarded.

• Channel messages (note on, note off, polyphonic pressure, controller, program change, channel pressure, and pitch bend) are ignored if they are not on the input instrument's selected channel for that connection. If no input channel is specified (the input channel "all"), then all incoming data is accepted.

• Note-type messages (note on, note off, and polyphonic pressure) are checked against the current zone. If the note is outside the zone it is filtered out. Next, the note is transposed. If the transposed value is out of range (below 0 or above 127) the note message is filtered out.

• Controller messages are processed by the corresponding controller mapping.

• All channel messages have their channel changed to the output instrument's selected channel, unless it is "all" in which case the channel remains unchanged.

• The resulting MIDI messages are sent to the output instrument.