User Guides

Sys-ex Patterns

Sys-ex Patterns are used to extract data from and to generate MIDI System-Exclusive messages (aka: "Sys-ex" messages).

MIDI sys-ex messages consist of a sequence of bytes formatted in a manner specific to the hardware manufacturer. The MIDI standard defines several standard sys-ex messages but hardware manufacturers are also free to define their own formats.

Rather than build in sys-ex support for every possible piece of hardware, Cantabile uses sys-ex patterns as a flexible way to extract data from just about any fixed length sys-ex message. They can also be used to generate sys-ex messages.

Currently the use of sys-ex patterns is limited to use in the Sysex Encoder and Sysex Decoder MIDI Filters - see below for more details.

A sys-ex pattern consists of a sequence characters that define the format of a sys-ex message. The following describes the syntax of these patterns.

Hex and Binary

The simplest form of a sys-ex pattern is an exact, byte for byte representation of the sys-ex data.

eg: 

F0 00 00 00 F7

This would match (or generate) the exact 5 bytes shown where each byte is hex encoded. Note that sys-ex patterns must always include the leading F0 and trailing F7 bytes that are part of the MIDI standard.

You can also use binary encoding by enclosing the binary digits in square brackets.

eg: this is identical to the above.

[11110000] 00 00 00 F7

Binary digits can't cross a byte boundary so the following are illegal:

0[11110000]
[1111000011110000]

Whitespace

White space between bytes is optional - but must be between bytes. Whitespace in the middle of a byte will generate an error:

This is valid:

F0000000F7

This is not:

F 0000000F7

Nor is this:

F0 [00] [111111] 00 00 00 F7

Wildcard Characters

Sometimes when matching sys-ex data you might not care about the value of a particular byte. In these cases you can use '?' in place of any digit:

This:

F0 00 ?? 00 F7

Would match any of these:

F0 00 00 00 F7
F0 00 10 00 F7
F0 00 01 00 F7

But not this:

F0 10 00 00 F7

You can also use wildcards for one half of the byte:

F0 00 0? 00 F7

and in binary numbers:

[00??00??00]

If you use a wildcard character in a pattern used to generate sys-ex data it will be replaced with zero.

Variables

Variables can be used to capture bits from a sys-ex message being decoded or to substitute bits into a sys-ex message being generated.

This sys-ex pattern will capture the 3rd byte into the val variable (where it can be used later in generating a standard controller message).

F0 00 $(val) 00 F7

When generating sys-ex data the opposite applies and $(val) will be substituted with the data from the variable.

You can also capture (or generate) a sub-set of bits from a byte in a sys-ex message using bit ranges. Bit ranges are specified using a high and low bit number separated by two periods (..). Bit zero is the least significant bit and bit 7 would be the most significant bit in a byte.

eg: [3..0] means bits 3 to 0

eg:

F0 00 0$(val[3..0]) 0$(val[7..4]) F7

The above pattern would capture:

  • The lowest 4 bits from the third byte into the lowest three bits of the val variable
  • The lowest 4 bits from the forth byte into the highest three bits of the val variable.

eg:

F0 00 [0]$(val[6..0]) 00 F7

would capture the lowest 7 bits of the third byte into the lowest 7 bits of the val variable. Note the leading [0] to keep correct alignment.

You can also capture a single bit using $(val[5]) (for example).

Note that the order of the bit numbers in a range is important and must always have the higher bit number first. $(val[4..7]) is not valid.

Sys-ex MIDI Filters

The sys-ex encoder and decoder MIDI filters use these patterns to convert sys-ex messages to and from other standard MIDI messages such as CC and NRPN/RPN messages.

In both of these filters the following variables are available:

  • $(ch) - the MIDI channel number
  • $(cc) - the MIDI controller number or (N)RPN parameter number
  • $(val) - the value of controller or (N)RPN parameter

Sys-ex Encoder Filter

The sys-ex encoder filter takes a standard MIDI controller message and generates a sys-ex message.

Sysex Encoder

The filter looks for incoming MIDI messages with the following settings:

  • MIDI Channel - which MIDI channels to monitor
  • Controller Kind - the kind of incoming MIDI message to convert
  • Controller Number - the controller number (or parameter number for (N)RPN messages) to match, or "Any" to match any
  • Controller Value - the controller value to match, or "Any" to match any value

Once matched, the values from the matched message are stored in the variables described above and the sys-ex pattern is used to generate a sys-ex message.

If the Suppress option is turned on, the original MIDI message is suppressed otherwise both the original message and the sys-ex message are sent.

In the above example, the filter is only matching on CC #7. You could however change this to "any" and then use the $(cc) in the sys-ex pattern to include the cc number in the generated sys-ex message.

Sys-ex Decoder Filter

The sys-ex decoder filter is essentially the opposite of the the encoder filter:

Sysex Decoder

This filter looks for an incoming sys-ex message that matches the supplied pattern and updates the variables from the sys-ex data. Once a matching sys-ex message is found a MIDI message is generated using the supplied settings.

Generally for each variable you'll want one of two behaviours:

  1. Always use a specific value - in which case set the value in the MIDI filter and don't include the variable in the sys-ex pattern. Or...

  2. Use a value from the sys-ex data - in this case, leave the MIDI filter setting at zero and use the appropriate variable in the sys-ex pattern.

The example above is matching on a the standard MIDI sys-ex for master volume, extracting the 14-bit value from bytes 6 and 7, storing them in the $val variable and then sending the value as 14-bit MIDI CC 31.

Suppose instead of always sending on CC 31 you want to extract the CC number from the device number of the sys-ex message. Also, let's also suppose you only wanted the coarse 7-bit value:

Sysex Decoder 2

In this example we're:

  • Extracting the controller number from byte 3 ($(cc))
  • Ignoring the fine part of the value (??)
  • Set the Controller Number back to zero

Note that setting the controller number back to zero is important. Without that the value from the sys-ex data and the supplied value will be bit-wise ORed together.

The Suppress Sys-ex option causes the matched sys-ex message to be suppressed. When turned off, both the sys-ex and the generated controller message are sent.

Sys-ex Patcher MIDI Filter

The sys-ex patcher filter provides a way to generate a similiar sys-ex event from an incoming sys-ex event.

To use the sys-ex patcher MIDI filter you give it two sys-ex patterns. One which decodes the incoming sysex and if it matches, uses the second pattern to generate a new sysex message. Variables can be to pass arbitrary data from the decode pattern to the encode pattern. You can have have as many variables as you like (well up to 256) and you can name them what ever you like.

The following example, uses two variables $(a) and $(b) to capture two values from the incoming sys-ex message and generate a new sys-ex message with just one byte changed:

Sysex Patcher MIDI Filter

The above will work if the incoming sys-ex event always has the same length. There's no direct support for variable length sys-ex pattern matching. However if you have a very limited range of data lengths you could use a couple of filters. eg: say the data could be 2, 3 or 4 bytes in length you could do this:

Sysex Patcher MIDI Filter