StateChunkAndRppMidiFormat
From CockosWiki
Contents |
State Chunk and RPP File MIDI Format
In RPP files, MIDI messages are encoded in lines of text. With the exception of System Exclusive MIDI messages, each midi message is encoded in a line containing 5 to 8 fields delimited by spaces, and is terminated by a return character. The same format is also used by the REAPER API functions RPR GetSetItemState and RPR GetSetTrackState when getting and setting MIDI items. This format is also referred to as "State Chunks" when used in the context of the API functions.
To give you a quick flavour - here's a short example which could (except for the // style comments) easily have come from an RPP file or been returned by a GetSet*State() function; there are other examples later.
HASDATA 1 960 QN // number of ticks (960) per Quarter Note E 3840 bc 07 5a // Offset of 3840, Control Change Ch0xC, Main Volume E 0 bc 0a 7f // Offset of 0, Control Change Ch0xC, Pan Position E 0 bc 5d 28 // Offset of 0, Control Change Ch0xC, Chorus Level e 59344 9c 45 64 // Offset of 59344, Note On Ch0xC, Note A4, Velocity 0x64 e 232 9c 45 00 // Offset of 232, Note On Ch0xC, Note A4, Velocity 0x0 -- Note off, in effect
Look at the last line in the example above, the data is in five fields. The first field contains an 'e', the second a decimal number, '232', and the third, fourth & fifth contain hexadecimal numbers: '9c', '45', & '00'.
Explanations for the data in these fields are given in the tables below; it's probably worth mentioning that the RPP format for MIDI data assumes you know which numbers are decimal and which are in hex. The three two-character hex fields correspond to the three bytes in a Midi Message according to the MIDI Specification.
Standard Midi Messages
The first character of field 1 (the "state field") indicates the format of the following fields to expect on the current line. For standard midi messages, the first character of the first field will be 'e' or 'E'. These standard messages will be in the format:
state tick_offset hex1 hex2 hex3 [prequantized_offset]
| Field | Function |
|---|---|
| state | The state field indicates if the midi message is selected and/or muted in the reaper midi editor.
|
| tick_offset | Number of MIDI Ticks between this midi message and the previous midi message in the current item. |
| hex1, hex2, hex3 | Each hex field is the two character hexcode for the a bytes of the midi message according to the Midi Spec. hex3 will be '00' for midi messages with only two bytes(verify). |
| [prequantized_offset] | Optional field only exists for midi events that have been quantized. It is the difference between the note's position and where its position was before it was quantized |
Extended Midi Messages
If tick_offset or prequantized_offset would be larger than 2^32 (about 4 billion ticks), then the extended midi message encoding is used instead of the standard encoding. The first character of the first field in all extended messages will be an 'x' or an 'X'. The extended midi message format is:
state tick_offset1 tick_offset2 hex1 hex1 hex3 [prequantized_offset1 prequantized_offset2]
| Field | Function |
|---|---|
| state |
|
| tick_offset1, tick_offset2 | When the first character of a line is an X or x, the number of midi ticks between this midi event and the previous midi event are encoded as the sum of tick_offset1 and tick_offset2 |
| hex1, hex2, hex3 | Same as for standard Midi messages. The three bytes of Midi Message |
| prequantized_offset1, prequantized_offset2 | When the first character of a line is an X or x, the difference between the note's position and where its position was before it was quantized is encoded as the sum of prequantized_offset1 and prequantized_offset2 |
Don't confuse messages beginning with 'X' with messages beginning with '<X'. '<X' is used for Sysex MIDI messages.
HASDATA Line
A HASDATA line will indicate the number of MIDI Ticks in one quarter note (most often 960 or 480). This line will occur in the midi section of the RPP state chunk before any lines including a tick_offset field.
Example of a HASDATA line specifying 960 ticks per quarter note:
HASDATA 1 960 QN
Sysex, Text, Other Meta-Messages
System Exclusive, text, and other meta-messages will have the format:
<X tick_offset1 tick_offset2 base64_string>
Examples
These are the MIDI message data portions of Item State Chunks retrieved using the script CopyItemStateToClipboard.pl
1/16th Note Scale of C
This example was generated by REAPER's internal MIDI editor. All messages have an upper case 'E', so no notes or events were left selected in the MIDI editor
HASDATA 1 960 QN // number of ticks (960) per Quarter Note E 0 90 18 60 // Offset of 0, Note on, Note C1 Ch0x0, Velocity 0x60 E 240 80 18 00 // Offset of 240 (1/4 note), Note off, Note C1 Ch0x0, Velocity 0x0 E 240 90 1a 60 E 240 80 1a 00 E 240 90 1c 60 E 240 80 1c 00 E 240 90 1e 60 E 240 80 1e 00 E 240 90 1f 60 E 240 80 1f 00 E 240 90 21 60 E 240 80 21 00 E 240 90 23 60 E 240 80 23 00 E 240 90 24 60 // Offset of 240 (1/4 note), Note on, Note C2 Ch0x0, Velocity 0x60 E 240 80 24 00 // Offset of 240 (1/4 note), Note off, Note C2 Ch0x0, Velocity 0x0 E 240 b0 7b 00 // Offset of 240 (1/4 note), Control Change Ch0x0, All notes off
Pitch Wheel And More
This example came from a MIDI file found online and imported into REAPER. Notice that it uses Note On messages with a Velocity of zero instead of Note Off messages.
The Pitch Bend messages towards the end of the fragment (which are for the Channel and not a note) are interesting as well, the first Pitch Wheel has a value of 0, so it doesn't change the note at all. A note is played and then another Pitch Wheel message with a value of 0x11 (Hex 11).
This is followed by a whole string of Pitch Wheel messages, all with an offset of 8 and all increasing the Pitch by various amounts.
The last figure in each Pitch Wheel Message I can't find a definition for yet but it seems to be a sequence number defining the message's place in an overall Pitch Wheel "event" which goes on a little, and would be a bit much to include in full.
The sequence number (if that's what it is) starts at 0x40 and is incremented until it reaches 0x5F, then a Note Off (E5) followed by a Pitch Wheel message of zero and a sequence of 0x40. This (obviously) looks like a reset.
HASDATA 1 960 QN // number of ticks (960) per Quarter Note
<X 0 0 // Exclusive Data, no manufacturer's id though
/wNHdWl0YXIy // so it's Universal Exclusive Data and not
> // System Exclusive Data
// These two UED messages are actually Track Name "Guitar2"
// and Instrument Name "MU100R-1"
<X 0 0
/wRNVTEwMFItMQ== // Universal Exclusive Data
>
E 3840 bc 07 5a // Offset of 3840, Control Change Ch0xC, Main Volume
E 0 bc 0a 7f // Offset of 0, Control Change Ch0xC, Pan Position
E 0 bc 5d 28 // Offset of 0, Control Change Ch0xC, Chorus Level
e 59344 9c 45 64 // Offset of 59344, Note On Ch0xC, Note A4, Velocity 0x64
e 232 9c 45 00 // Offset of 232, Note On Ch0xC, Note A4, Velocity 0x0 -- Note off, in effect
e 8 9c 47 56 // Offset of 8, Note On Ch0xC, Note B4, Velocity 0x56
e 232 9c 47 00 // Offset of 232, Note On Ch0xC, Note B4, Velocity 0x0 -- Note off, in effect
e 8 9c 48 58
e 1440 9c 48 00
e 240 9c 4a 4e
e 2400 9c 4a 00
e 0 9c 4c 5c // Offset of 0, Note On Ch0xC, Note E5, Velocity 0x5c
e 5280 9c 4c 00 // Offset of 5280, Note On Ch0xC, Note E5, Velocity 0x0 -- Note off, in effect
E 1856 ec 00 40 // Offset of 1856, Pitch Wheel +0x0
e 0 9c 4c 57 // Offset of 0, Note On Ch0xC, Note E5, Velocity 0x57
E 8 ec 11 40 // Offset of 8, Pitch Wheel +0x11
E 8 ec 22 40
E 8 ec 32 40
E 8 ec 43 40
E 8 ec 54 40
E 8 ec 64 40
E 8 ec 75 40
E 8 ec 06 41
E 8 ec 16 41
E 8 ec 27 41
E 8 ec 38 41
E 8 ec 48 41
E 8 ec 59 41
E 8 ec 6a 41
E 8 ec 7a 41
E 8 ec 0b 42
E 8 ec 1c 42
E 8 ec 2c 42
E 8 ec 3d 42
E 8 ec 4e 42
E 8 ec 5e 42
E 8 ec 6f 42
E 8 ec 00 43 // note that the "Sequence Number" is increasing every 7 or 8 Pitch Wheel messages
