improv Examples: midirec

---

Source code:

midirec.cpp

midirec is a command-line program that displays MIDI messages to the computer screen as they enter from an external MIDI instrument. The binary MIDI input bytes are converted to their ASCII numeric equivalents when displaying on the screen. midirec stands for "Console MIDI INput".

Here is a synopsis of the midirec command:

Display/Record MIDI input data.

Usage: midirec [-a][-i][-x|-d|-2] [-o output][-p port]

Options:
   -a = display MIDI timing in absolute time instead of delta time
   -i = don't display interpretation of MIDI message as comments
   -d = display MIDI bytes in decimal form
   -x = display MIDI bytes in hexadecimal form
   -2 = display MIDI bytes in binary form
   -n = do not display note-off messages
   -f string = filter out specified MIDI commands (e.g. "bc" will
        filter out control change and patch change messages)
   -c string = filter out specified MIDI channels, offset zero
        (e.g., "09AF", filters channels 1, 10, 11, and 16)
   -p port = use the specified MIDI input port
   -l = list MIDI input ports and then exit
   -o filename = send display to file as well as to screen
   -u string = specify a user name for the header information
   -s = display time values in seconds
   -k = disable keyboard input
   --options = list all options, default values, and aliases

Here are some example function calls to the midirec program (comments start with '#' character):

# display MIDI input data in binary form:
midirec -2

# don't display note-off messages:
midirec -n

# don't display pitchbend data:
midirec -fe

# display only pitchbend data:
midirec -f 89abcdf

# display only note-on messages:
midirec -n -f 8abcdef
                             

Time information

The display of a MIDI message contains several components. The first number on a line is the timestamp of the message. The timestamp was added by the midirec program and was not transmitted via MIDI. The timestamp is just used to tell you when the MIDI message arrived. Each MIDI byte takes about 300 microseconds to transmit, and typical MIDI messages are three bytes long. That means that each MIDI message takes about 1 millisecond (or 0.001 seconds) to enter the computer. Therefore, the timestamp was given the resolution of 1 millisecond. More resolution would not be of much use. Also, keep in mind that humans cannot hear the order of two events which are separated by less than 10 milliseconds (in the best case), so the timestamp is more than 10 times as accurate as it needs to be for good playback of the data.

The default timestamp style is delta milliseconds. The default can be modified with these two options:

• midirec -a = Display timestamps in absolute time rather than delta time (all time values refer to the start of the recording).
• midirec -s = Display timestamps in seconds rather than milliseconds.

MIDI command byte

MIDI command bytes are the second number on the line after the timestamp. A MIDI command is a number in the range from 128 to 255. In hexadecimal notation the MIDI commands can be easly grouped:

command type	meaning
0x80	Note-off
0x90	Note-on
0xA0	Aftertouch
0xB0	Continuous Controller
0xC0	Patch Change
0xD0	Channel Pressure
0xE0	Pitch Wheel
0xF0	System Messages

In hexadecimal notation, it is easy to see that the first character of the MIDI command byte is the command category as displayed in the table above. The channel that is affected by that command, is given in the second hexadecimal digit (always 0 in the table above). The first channel is 0, and the last channel is F.

"0x" is a C programming convention for indicating a hexadecimal number. You can also signify a hexadecimal number with a h following the number or a subscript 16 following the number. All of the following number are equivalent to the decimal number 144: 0x90 = 90h = 90₁₆. I like to see MIDI commands in hex form, and MIDI data in decimal form. You don't have to know the hex-dec equivalences, just keep in mind that hex digits are useful for interpreting what a MIDI command byte is supposed to mean -- there is not calculation involved with the hex number, but decimal notated MIDI command bytes are much more difficult to interpret in your head.

By default, the midirec program will display the MIDI command byte in C-style hex notation. You can change the display type to either binary or decimal as well. 'midirec -2' displays MIDI bytes as binary numbers, and 'midirec -d' displays MIDI bytes as decimal numbers.

MIDI data byte(s)

MIDI data bytes are in the range from 0 to 127. They are always associated with a MIDI command byte. The meaning of a MIDI data byte is determined by is position after a particular MIDI command byte. For example, a note-on command byte (0x90 - 0x9F) is followed by two MIDI data bytes. The first byte tells you which key is being turned on, and the next byte tells you how hard the key was pressed on the synthesizer keyboard (the attack velocity). Most MIDI messages with a command byte less than 0xF0 have two data byte parameters following them--except for 0xc0 (Patch Change) and 0xd0 (Channel Pressure) messages. The table below lists the number of data parameter bytes expected for each category of MIDI message:

command type	meaning	# of data parameters to follow
0x80	Note-off	2: key, velocity
0x90	Note-on	2: key, velocity
0xA0	Aftertouch	2: key, value
0xB0	Continuous Controller	2: controller #, value
0xC0	Patch Change	1: instrument #
0xD0	Channel Pressure	1: value
0xE0	Pitch Wheel	2: LSB MSB
0xF0	System Messages	more complicated

There is something called running status where data bytes are continuously sent without associated command byte. If this is the case the the last command byte that came in the MIDI stream is used as the command byte of the orphan data parameters. The midirec program inserts the MIDI command bytes into their appropriate places when displaying MIDI messages to the screen, so you can't see running status MIDI messages with midirec.

Filtering out unwanted MIDI commands

by default, the midirec will filter out two types of system message: 0xf8 (timing clocking messages) and 0xfe (active sensing messages). Those two messages, if they are present, occur too fast for a human to read on the screen.

If you want to filter out other command, such as all note-off commands, or filter out certain channels, the -f and -c options are useful.

To filter out generic categories of MIDI messages use the -f command which takes as an argument a string that contains a list of the types of MIDI messages to ignore. There are 8 categories of MIDI messages, each of which is represented by a single character in the -f option string:

-f character	command type	meaning
'8'	0x80	Note-off
'9'	0x90	Note-on
'A', or 'a'	0xA0	Aftertouch
'B', or 'b'	0xB0	Continuous Controller
'C', or 'c'	0xC0	Patch Change
'D', or 'd'	0xD0	Channel Pressure
'E', or 'e'	0xE0	Pitch Wheel
'F', or 'f'	0xF0	System Messages

So, for example, the program call 'midirec -f ab' would prevent the display of aftertouch or continuous controller messages. Note that 'midirec -fab' and 'midirec -f "ab"' are equivalent command-line syntaxes to the first example.



The -c command is used to filter out all MIDI messages related to a particular channel. The option takes as an argument a string which contains a list of the channels to ignore. Just to confuse you, there is exactly one character for each MIDI channel, and the numbering system starts at 0 rather than 1. Here are the channels and the string characters used in the -c option:

-c character	MIDI channel		-c character	MIDI channel
'0'	MIDI channel 1		'8'	MIDI channel 9
'1'	MIDI channel 2		'9'	MIDI channel 10
'2'	MIDI channel 3		'A', or 'a'	MIDI channel 11
'3'	MIDI channel 4		'B', or 'b'	MIDI channel 12
'4'	MIDI channel 5		'C', or 'c'	MIDI channel 13
'5'	MIDI channel 6		'D', or 'd'	MIDI channel 14
'6'	MIDI channel 7		'E', or 'e'	MIDI channel 15
'7'	MIDI channel 8		'F', or 'f'	MIDI channel 16

So, for example, the program call 'midirec -c 9F' would prevent the display of messages from MIDI channels 10 and 16. Note that 'midirec -c9F' and 'midirec -c "9F"' are equivalent comamnd-line syntaxes to the first example.

Note-offs are a special consideration, because the proper method to transmit them is rarely followed by using the 0x80 set of commands. Instead 0x90 commands are used with an attack velocity of 0 used to signify a note off. Therefore there is a separate option used to filter out all types of note-off commands: 'midirec -n'.

Interpretation comments

By default, every MIDI message will be accompanied with a comment on the right side of the screen that explains the current message in terms of standard General MIDI syntax. This option can be turned off by specifing the 'midirec -i' option.

Miscellaneous command-line options

'midirec -p 1' would specify that MIDI input port number one be used instead of the default 0. Use the -l option to determine how many ports are available.

'midirec -l' lists the ports that can be used for MIDI input. Each input port has an associated number (starting at 0) and a port name.

'midirec -o filename' enables you to copy the screen display to a file, you could also type 'midirec > filename which would save the output to a file, but then you couldn't see the input data on the screen.

'midirec -k' by default you can type text into the screen or file display as the midirec program is running. This option is useful to write extra comments into the file. Also, you can press the escape key to quit the program as well as control-c. With the -k option activated, the keyboard input is deactivated.

'midirec -u string' is useful to indicate who has recorded the MIDI data, for example, I might do: 'midirec -u "Craig Sapp" '

Output file format

There will be other programs which will be able to process the ASCII output of the midirec program. I'll call the output of the midirec program to be in the asciimidi format.

The basic format of a 1.0 asciimidi file is:

• Comments are started by a ';' character and last until the end of the line.
• The header starts at the first non-blank line and continues for each line which has a ';' in the first column (no leading spaces are allowed).
• a timestamp starts a line for a MIDI message. the timestamp can be delta or absolute according to the file header. The time can be either milliseconds or seconds according to the header.
• The MIDI command can be displayed with a "0x" by default or in binary, decimal or hexadecimal notation according to the header.
• The MIDI data bytes are display as decimal values by default, or also as binary or hexadecimal values.
• future additions may be as follows: MIDI-file information can be interleaved with the actual MIDI bytes. MIDI-file bytes are preceded by a ':' character which is in effect until the end of a line. MIDI header bytes would start a line with a ':' character (initial spaces allowed), while track information would start with a non-coloned absolute time/delta time associated with the given meta event.
• The preferred file extension will be '.ami' which stands for "ASCII MIDI".

Click here for example asciimidi file output from midirec.