Cinmidi

cinmidi is a command-line program that displays MIDI messages as text on the computer screen as they enter in real-time from an external MIDI controller. The binary MIDI input bytes are converted to their ASCII numeric equivalents when displaying on the screen (selectable as base-2, base-10 or base-16 numbers). Cinmidi stands for "Console INput MIDI".

Options

Here is a list of cinmidi command-line options:

Here are some example function calls to the cinmidi program:

cinmidi -2

cinmidi -n

cinmidi -fe

cinmidi -f 89abcdf

cinmidi -n -f 8abcdef

Timing information

Each text-line output by cinmidi displays a single MIDI message that contains three primary components. The first number on a line is the timestamp of the message. This is followed by one or more MIDI message byte and optionally followed by a comment starting with ';', which describes the meaning of the message.

The timestamp was added by the cinmidi program and was not transmitted via MIDI, but rather provided by the operating system when the MIDI message arrived. Each MIDI byte takes about 300 microseconds to transmit, and typical MIDI messages are three bytes long. That means each MIDI message takes about 1 millisecond (or 0.001 seconds) to enter the computer. Therefore, the timestamp has a resolution of one millisecond. Higher 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 sufficient playback of the data. The default timestamp style is delta milliseconds. The default can be modified with these two options:

;;
;; Style:          default
;; Timing:         delta milliseconds
;; Message format: delta-time, MIDI command-byte, MIDI parameter-byte(s)
;; Format:         asciimidi 1.0
;; Command-line:   C:\Users\ccarh\Downloads\cinmidi.exe
;; Input Port:     0: Q49
;;

0       0x90  48  89            ; NOTE chan:1 key:C3 vel:89
125     0x80  48  64            ; NOTEOFF chan: 1 key:C3 vel: 64
47      0x90  50 100            ; NOTE chan:1 key:D3 vel:100
93      0x80  50  64            ; NOTEOFF chan: 1 key:D3 vel: 64
47      0x90  52 100            ; NOTE chan:1 key:E3 vel:100
110     0x80  52  64            ; NOTEOFF chan: 1 key:E3 vel: 64
62      0x90  53 102            ; NOTE chan:1 key:F3 vel:102
94      0x80  53  64            ; NOTEOFF chan: 1 key:F3 vel: 64
109     0x90  55 110            ; NOTE chan:1 key:G3 vel:110
172     0x80  55  64            ; NOTEOFF chan: 1 key:G3 vel: 64

;;
;; Style:          default
;; Timing:         absolute milliseconds
;; Message format: received-time, command-byte, parameter-byte(s)
;; Format:         asciimidi 1.0
;; Command-line:   C:\Users\ccarh\Downloads\cinmidi.exe -a
;; Input Port:     0: Q49
;;

922     0x90  48  97            ; NOTE chan:1 key:C3 vel:97
1047    0x80  48  64            ; NOTEOFF chan: 1 key:C3 vel: 64
1125    0x90  50 107            ; NOTE chan:1 key:D3 vel:107
1219    0x80  50  64            ; NOTEOFF chan: 1 key:D3 vel: 64
1297    0x90  52 106            ; NOTE chan:1 key:E3 vel:106
1375    0x80  52  64            ; NOTEOFF chan: 1 key:E3 vel: 64
1469    0x90  53 104            ; NOTE chan:1 key:F3 vel:104
1547    0x80  53  64            ; NOTEOFF chan: 1 key:F3 vel: 64
1703    0x90  55 110            ; NOTE chan:1 key:G3 vel:110
1844    0x80  55  64            ; NOTEOFF chan: 1 key:G3 vel: 64

;;
;; Style:          default
;; Timing:         delta seconds
;; Message format: delta-time, MIDI command-byte, MIDI parameter-byte(s)
;; Format:         asciimidi 1.0
;; Command-line:   C:\Users\ccarh\Downloads\cinmidi.exe -s
;; Input Port:     0: Q49
;;

0       0x90  48  92            ; NOTE chan:1 key:C3 vel:92
0.157   0x80  48  64            ; NOTEOFF chan: 1 key:C3 vel: 64
0.203   0x90  50 102            ; NOTE chan:1 key:D3 vel:102
0.109   0x80  50  64            ; NOTEOFF chan: 1 key:D3 vel: 64
0.203   0x90  52 100            ; NOTE chan:1 key:E3 vel:100
0.094   0x80  52  64            ; NOTEOFF chan: 1 key:E3 vel: 64
0.25    0x90  53 104            ; NOTE chan:1 key:F3 vel:104
0.109   0x80  53  64            ; NOTEOFF chan: 1 key:F3 vel: 64
0.282   0x90  55 108            ; NOTE chan:1 key:G3 vel:108
0.109   0x80  55  64            ; NOTEOFF chan: 1 key:G3 vel: 64

;;
;; Style:          default
;; Timing:         absolute seconds
;; Message format: received-time, command-byte, parameter-byte(s)
;; Format:         asciimidi 1.0
;; Command-line:   C:\Users\ccarh\Downloads\cinmidi.exe -as
;; Input Port:     0: Q49
;;

0.906   0x90  48  99            ; NOTE chan:1 key:C3 vel:99
1.047   0x80  48  64            ; NOTEOFF chan: 1 key:C3 vel: 64
1.156   0x90  50 108            ; NOTE chan:1 key:D3 vel:108
1.234   0x80  50  64            ; NOTEOFF chan: 1 key:D3 vel: 64
1.39    0x90  52 104            ; NOTE chan:1 key:E3 vel:104
1.469   0x80  52  64            ; NOTEOFF chan: 1 key:E3 vel: 64
1.609   0x90  53 104            ; NOTE chan:1 key:F3 vel:104
1.703   0x80  53  64            ; NOTEOFF chan: 1 key:F3 vel: 64
1.875   0x90  55 108            ; NOTE chan:1 key:G3 vel:108
2.031   0x80  55  64            ; NOTEOFF chan: 1 key:G3 vel: 64

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 easily grouped by the most significant nibble in the command byte. Below is a table giving the primary MIDI commands (not expanding command in the 0xF0 group). The notation "0x80" is the C-programing language's notation for hexadecimal numbers. 0x80 is the hexadecimal number "80" which is equivalent to the decimal number 128. MIDI commands are grouped into sets of 16, so the most significant hex digit (nibble) is equated to a MIDI command.

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 (channel 1), and the last channel is F (channel 16).

Again, "0x" is a C-programming convention for indicating a hexadecimal number. You can also signify a hexadecimal number with by an "h" following the number or a subscript 16 following the number. All of these number representations 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, so this is the default style for cinmidi. 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 no calculation involved when displayed as a hex number, but decimal-notated MIDI command bytes are much more difficult to interpret in your head.

By default, the cinmidi 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. 'cinmidi -2' displays MIDI bytes as binary numbers, and 'cinmidi -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 (a number in the range 0x90-0x9F) is followed always followed by exactly two MIDI data bytes. The first byte tells you which key is being turned on, and the second byte tells you how hard the key was pressed on the keyboard controller (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:

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 orphaned data parameters. The cinmidi 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 cinmidi.

Filtering out unwanted MIDI commands

By default, the cinmidi 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:

So, for example, the program call 'cinmidi -f ab' would prevent the display of aftertouch or continuous controller messages. Note that 'cinmidi -fab' and 'cinmidi -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:

So, for example, the program call 'cinmidi -c 9F' would prevent the display of messages from MIDI channels 10 and 16. Note that cinmidi -c9F and cinmidi -c "9F" are equivalent comamnd-line syntaxes to the previous 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 often 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: 'cinmidi -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 'cinmidi -i' option.

Miscellaneous command-line options

'cinmidi -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.

'cinmidi -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.

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

'cinmidi -k' by default you can type text into the screen or file display as the cinmidi 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.

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

Output file format

The output file format can be played with the playascii found in the download section below. The cinmidi program generates data which can be played back by this program. Here are the specifications for the ASCII representation of MIDI data:

• 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".

Here is example asciimidi file output from cinmidi.

The output file created with the -o option can be played back if the -2 option was not used. To playback the file, save the file to the hard-coded filename "file" and run the playascii program (executable given below).

Download

Computer geek method of compiling binasc/playascii for Linux and OS X:

1. git clone https://github.com/craigsapp/improv
2. cd improv
3. make
4. bin/cinmidi