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.

Start

When a patch becomes active, two things happen. First its start named message, if any, is sent to the all of this patch's output instruments as-is. In particular, status bytes' channels are not changed. Second, 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 the 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:

• Program bank numbers (optional)
• Program change number (optional)
• Keyboard zone (low/high keys, default is all notes from 0-127)
• Transpose (default is 0)
• Velocity curve (default is linear)
• Sysex filter on/off (on by default, meaning sysex messages are filtered out)
• 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, bank and program change messages, if defined, are sent to the output instrument, but only if the output instrument has a defined output channel number (not "all"). That's because bank and program change messages are channel messages so we need to know what channel to send them on.

Finally, the connection is attached to its input instrument, so that the input instrument starts 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).

Velocity Curves

The default velocity curve is linear. The initially available curves are

• Linear ("lin")
• Exponential ("exp") - rises slowly at first, then quicker later
• Half Exponential ("exp/2") - halfway between exponential and linear
• Inverse Exponential ("-exp") - rises quickly at first, then slower later
• Half Inverse Exponential ("-exp/2" - halfway between inverse exponential and linear

You can also create your own exponential curves. Unfortunately, there is as of yet no way to do so from within KeyMaster. You'd have to encode it as a string containing 128 two-digit hex values that are the output values at each step. Take a look at the existing values in any KeyMaster database.

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:

• 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 by a connection (the input channel "all"), then all incoming data is accepted.

• Note-type messages (note on, note off, and polyphonic pressure) are first checked to see if they are in the current zone. If not, they are filtered out. Next, they are 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.