MIDI Monitor

Documentation



Basics

MIDI Monitor is a utility for Mac OS X which displays MIDI signals in a variety of formats. It can watch both incoming and outgoing MIDI streams, and can filter them by message type and channel.

Musicians will find it handy for tracking down confusing MIDI problems, and programmers can use it to test MIDI drivers and applications.

MIDI Monitor is FREE to download and use. The source code is available as Open Source (under the BSD license).

Please note that MIDI Monitor requires an Intel Mac with OS X 10.5 or later.

The MIDI Monitor web page can be found at this URL:
http://www.snoize.com/MIDIMonitor/
Please check there for news and updates.



How to use it

Parts of the window

When you launch MIDI Monitor, it will automatically open a new document. The window shows you the MIDI events that MIDI Monitor receives. There are also two sections, Sources and Filter, which start out hidden; click the gray arrows to expand them.

MIDI Monitor uses the standard Mac interface for dealing with documents; just open, close, and save as usual. A MIDI Monitor document saves its settings and the MIDI events which it is displaying.

Events

The main part of the window is a list of events that MIDI Monitor has received, in chronological order. The columns are as follows:

Time: When the event was received by the computer
Source: Where the event came from
Message: What kind of event happened (e.g. note on, note off, controller)
Chan: What channel the event was on. (Some types of messages do not have a channel.)
Data: The specific data in the event. The format depends on the type of message. (Some messages have no data.)

You can clear the list of events by pressing the Clear button, using the Events>Clear Events menu command, or typing Command-K. You can also change the number of events that the list will remember by changing the number in the text field.

Some kinds of events contain more data than can be shown in one line. These are System Exclusive (or SysEx) events and Invalid events. To show the full contents of the event, double-click it, or use the Events->Show Detailed Data menu command. (More on that later.)

Sources

This section lets you choose the sources of MIDI events that this window listens to. The sources come in three categories:

  • MIDI sources: These are ordinary MIDI sources, such as the input ports on your MIDI interface. Other applications on the computer may also appear in the list, if they are running and can act as MIDI sources.
    (If your MIDI devices don't appear in this list, see the Troubleshooting section.)

  • Act as destination for other programs: If you choose this, other applications will be able to send their output to this MIDI Monitor window, as though it was a MIDI output port.

  • Spy on output to destinations: Each MIDI destination on your computer is listed: this includes MIDI output ports and applications which act as destinations. Selecting a destination lets you "spy" on all of the data that is sent to that destination. This happens outside of the system's normal MIDI processing. so the application which sends the data does not know that it is being spied upon.

    (In order to do this, MIDI Monitor installs a MIDI driver in the Library/Audio/MIDI Drivers folder in your home folder. This driver does not have any effect on other applications, and does nothing when MIDI Monitor is not using it.)

Filter

MIDI Monitor also provides a filter, so you can see only the events you are interested in.

New windows start with all of the checkboxes checked, meaning that all messages are displayed. The large checkboxes control the filters for a whole category of messages; the small checkboxes each control the filter for one specific type of message. For "voice" messages, which include a channel number, you can also choose whether to listen to all channels or just one.



Preferences

The preferences window lets you change the way that MIDI Monitor displays values, as well as some other behavior. Changes in this window take effect immediately, and are automatically saved.


Display Preferences

Time format: The method of displaying the timestamps of events.

  • Clock time: Shows the timestamp in terms of normal human time, to the nearest 0.001 second. This is the most useful setting.

  • Host time: Shows the timestamp in terms of the computer's internal timebase. This is not very interesting for humans, but programmers may find it useful.
    • Integer: the time as returned by AudioGetCurrentHostTime() or UpTime(). This is an unsigned, 64-bit integer, which starts at 0 when the computer is started. This number will always increase at the same rate while the machine is running; however, one unit may represent different amounts of time on different machines, or different revisions of the operating system.
    • Seconds: The integer time divided by the number of ticks per second, as reported by AudioGetHostClockFrequency(). The value is shown to three decimal places.
    • Nanoseconds: The same as above, but with more digits displayed.

Note format: The method of displaying the musical note associated with note-on and note-off events.

  • Note (Middle C = C3): The name of the note in musical notation. Middle C (note 60) is displayed as C3, and the full range is from C-2 to G8. Yamaha uses this convention for naming notes, as do some (most?) other manufacturers.

  • Note (Middle C = C4): As above, but displayed an octave higher. Middle C (note 60) is displayed as C4, and the full range is from C-1 to G9. Roland uses this convention.

  • Decimal number: The note number in base 10, from 0 to 127.

  • Hexadecimal number: The note number in base 16, from $00 to $7F.

Controller format: The method of displaying the name or number of control events.

  • Standard name: The name of this controller as given in the MIDI standard. For example, controller 72 means "Release Time". Controllers without standard names are displayed as decimal numbers. Some controllers come in pairs; one controller conveys the "coarse" value (or high byte) and the other conveys the "fine" value (or low byte).

  • Decimal number: The controller number in base 10, from 0 to 127.

  • Hexadecimal number: The controller number in base 16, from $00 to $7F.

Data format: The method of displaying any other data in events.

  • Decimal number: The value in base 10. One byte values range from 0 to 127; signed two byte values range from -8192 to 8191.

  • Hexadecimal number: The value in base 16. One byte values range from $00 to $7F; two byte values range from $0000 to $3FFF, with $2000 as the "center" value.

Expert Mode: Changes the display slightly. Intended for experts only.

  • Note off events: According to the MIDI specification, a Note On event with velocity 0 is to be interpreted as the same as a Note Off event. Normally, MIDI Monitor shows "Note Off", to avoid confusion. ("Why does my keyboard send two note on events when I only pressed one key?") In expert mode, it will show "Note On".

  • Zero timestamp: When a program sends MIDI, it can provide a timestamp to schedule when the MIDI data should be sent, or zero which means "send it immediately". Normally, when MIDI Monitor sees a zero timestamp, it will substitute a timestamp of when it received the data, to avoid confusion. ("Why do the timestamps say 0? Is something broken?") In expert mode, it will show "0".


Sources Preferences

New windows will use these sources: When new windows are created, all of the sources in each of the checked categories will be selected.

Automatically open windows for new sources: If this checkbox is checked, when new sources become available, MIDI Monitor will open a new window which listens to the new sources.


Other Preferences

Save SysEx: This option lets you control how SysEx messages are saved to files. SysEx messages should always end with an EOX byte (hexadecimal F7). However, some devices do not follow this rule.

  • always with EOX byte ($F7): The file will end with an EOX byte, even if the message didn't have one when it was received. This is the default, and the most useful setting (especially if you want to use the SysEx file in another application).

  • as it was received: Saves the message exactly the same way as it was received, with or without the EOX byte.

Ask to save when a changed window is closed: When checked, MIDI Monitor will ask you to save a modified window when you close it, which is the standard Mac behavior. If you don't tend to save MIDI Monitor documents, this can get annoying, so uncheck this preference to turn off the warning.

Automatically check for updates: When checked, MIDI Monitor will periodically check if a newer version is available.



SysEx Event Data

To see the contents of a SysEx event, double-click it, or select it and use the Events->Show Detailed Data menu command.

The window shows information about the event, as well as a dump of the event's data in both hexadecimal and ASCII formats. Also, you may save the event data to a file using the "Save As" button.



Invalid Event Data

When MIDI Monitor receives data that does not conform to the MIDI specification, it shows the data in an Invalid event. To see the contents of the event, double-click it, or select it and use the Events->Show Detailed Data menu command.



Advanced Features

You can use the menu command "Rescan MIDI", in the "Special" menu, to reinitialize the entire MIDI system and look for available devices. Generally you shouldn't need to do this, but I've included it as a convenience. The Audio MIDI Setup application has a "Rescan MIDI" button that does exactly the same thing. (Developers: the menu command just calls CoreMIDI's MIDIRestart() function.)



Troubleshooting

If nothing is listed under MIDI Sources in the Sources section, then there are no MIDI devices available. You must have Mac OS X drivers for your devices; Mac OS 9 drivers will not work. Please check with the manufacturer of your device for drivers.



Contact

Please send questions or comments to: MIDIMonitor@snoize.com
If you find this program useful, I'd love to hear about it! And if you encounter bugs or have suggestions for improvement, please let me know.



Acknowledgements

MIDI Monitor is copyright © 2001-2012 by Kurt Revis. All rights reserved.

Thanks to the folks on the CoreAudio-API mailing list for all the help they have provided, and to everyone who has sent in bug reports and feature requests.