Difference between revisions of "Cinmidi"

From CCARH Wiki
Jump to navigation Jump to search
Line 52: Line 52:
 
== Time information ==
 
== Time information ==
  
Each text line output by ''cinmidi'' displays a single MIDI message that contains several 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 '<tt>;</tt>'m, which describes the meaning of the message.
+
Each text line output by ''cinmidi'' displays a single MIDI message that contains several 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 '<tt>;</tt>', 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 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.

Revision as of 22:56, 14 January 2013

cinmidi 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. Cinmidi stands for "Console INput Midi".

Here is a synopsis of the ' cinmidi command:

Display/Record MIDI input data.

Usage: cinmidi [-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 cinmidi program (comments start with '#' character):

 # display MIDI input data in binary form:
 cinmidi -2
 
 # don't display note-off messages:
 cinmidi -n
 
 # don't display pitchbend data:
 cinmidi -fe
 
 # display only pitchbend data:
 cinmidi -f 89abcdf
 
 # display only note-on messages:
 cinmidi -n -f 8abcdef
 
 

Time information

Each text line output by cinmidi displays a single MIDI message that contains several 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:

Command Meaning
cinmidi Default behavior: display timestamps as delta times—the time (in milliseconds) since the previous message came in. Example output with delta times at the start of each line:
;;
;; 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
cinmidi -a Display timestamps in absolute time rather than delta time (all time values refer to the starting time of the recording). Here is example output from cinmidi when using the -a option. The first message was played 922 milliseconds after the program started.
;;
;; 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
cinmidi -s Display timestamps in seconds rather than milliseconds. The following example output from cinmidi displays the delta time stamps in seconds:
;;
;; 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
cinmidi -as The -a and -s options can also be used at the same time to display absolute time stamps in seconds:
;;
;; 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:

Command type Meaning Parameters
0x80 Note-off 2 (key, off velocity)
0x90 Note-on 2 (key, on velocity)
0xA0 Aftertouch 2 (key, key pressure)
0xB0 Continuous Controller 2 (controller #, value)
0xC0 Patch Change 1 (timbre #)
0xD0 Channel Pressure 1 (pressure)
0xE0 Pitch Wheel 2 (lsb, msb)
0xF0 System Messages variable

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 = 9016. 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 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)

0x90 - 0x9F0xF00xc00xd0

{|

| width="180" | 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 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:

{|

| width="150" | -f character | width="180" | 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 '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:

{|

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

|}

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 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: '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

There will be other programs which will be able to process the ASCII output of the cinmidi program. I'll call the output of the cinmidi 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 [cinmidi.ami here ] for example asciimidi file output from cinmidi.

Playing the output file created by 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).