User Manual
MIDI Syntax
OnSong uses a text-based syntax for expressing MIDI commands. While you can use the MIDI Events in the Metadata Editor, you can also express MIDI commands in text.
Delimited Values
First and foremost, multiple MIDI commands can be separated by various characters including: a tab character, comma, semi-colon, vertical pipe, or new line. The comma is the most common delimiter. For example:
1.2:0@0, PC1.2:3@0, N67@1, START, SS8
Channel
Each entry may contain an @ symbol. The numeric value after the symbol is the channel on which the command is to be sent. Since channels in MIDI start on zero, channel one would be a zero (0), channel two a one (1), etc.
If no @ symbol is used, the command is sent or received on all channels.
Prefixes
Each entry in the list contains a prefix. This prefix determines what type of MIDI command to send. These include:
- PC or No Prefix is a program change event.
- N is a note event
- CC is a control change event.
- NRPN is a non-register parameter number.
- SS is a song select event.
- START is a start command.
- STOP is a stop command.
- CONTINUE is a continue command.
- WAIT waits a specific amount of time before sending more events.
- F0 prefixes a SysEx message.
- @ prefixes a MIDI global tag.
Values
The value of the command appears just before the @ symbol or at the end of the entry if no @ is given. This is the value of the program change, control change, note, or song select based on the prefix. In the case of SysEx entries, the hexadecimal value of the SysEx is provided directly after the F0 prefix which is used as a header to all SysEx commands.
Subvalues
In some cases, additional information is conveyed in the MIDI command as subvalues. For instance, MSB and LSB, as well as velocity of control values can be sent this way. This is expressed through the addition of a colon in the value portion. The subvalue has different context depending on the type of MIDI command sent:
- Program Change has subvalues aligning with the MSB/LSB of the program change. These values are separated by a period with the MSB on the left and the LSB on the right.
- Control Change has the value of the control set using this. The number can be between 0 and 127. If omitted, the value of 127 is inferred. You can also separate multiple values with a hyphen to step through values. For instance, 127-0 will latch the value of 127 between on and off states.
- Note Event has a subvalue relating to the velocity at which the note should be played. This can be set to a numerical value between 0 and 127. You can step through multiple note velocities by separating them with a hyphen.
Examples
Let's start with a simple program change. In this scenario we use program change 8 that also sends an MSB of 4 and an LSB of 2 on channel 1. The example starts with the most complex variation of this and removes the bank select and channel to become more broad:
PC3.1:7@0, 3.1:7@0, 3:7@0, 3:7, 7@0, 7
Control changes are similar except that the left side of the syntax is the control change number and the right side is an optional value. If the value is not provided, 127 is sent instead. We will send Control Change 106 with a value of 64 on channel 3.
CC105:63@2, CC105:63. CC105@2, CC105
Now let's take a look at note events. We want to play C4 on channel 8 at 75% velocity, we would enter the following because OnSong starts counting MIDI C0 as 0 on the MIDI note scale:
N60:95@7, N60@7, N60:95, N60
Again, it is important to remember that as values are removed from the MIDI syntax, the MIDI statement becomes more broad and less specific. For instance, the last version of the note event will send C4 at 100% velocity on all channels.
We can also delay MIDI by added a WAIT command. The following will delay the MIDI for 2 second as well as 500 ms (half a second). You can specify seconds as 1-10 seconds or in milliseconds.
WAIT2, WAIT500
Last, we can reference MIDI globals which a preconfigured lists of MIDI events that can be referenced. If you have a MIDI global with "on" as the tag (with no quotes), then you can reference that global with the following:
@on
