# MIDI Monitor
Documentation

# Basics

MIDI Monitor is an app to display MIDI signals going in and out of your Mac. 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.

MIDI Monitor requires a Mac with OS X 10.7 or later.

Please check http://www.snoize.com/MIDIMonitor/ for news and updates.

# How to use it

When you launch MIDI Monitor, it will automatically open a new document. The window shows you the MIDI messages 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 displayed MIDI events.

### Events

The main part of the window shows the events that MIDI Monitor has received, in order from oldest to newest.

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

To clear the list of events, press the Clear button, use the menu command Events > Clear Events, or press `⌘K`. To change the number of events that the list will remember, just change the number in the text field and press return.

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

### Sources

This section lets you choose the sources of MIDI events that this window listens to.

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.
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, including normal MIDI output ports, and applications which act as destinations. Selecting a destination lets you "spy" on the data that other apps send to that destination. This happens outside of the system's normal MIDI processing, so the application sending 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.

### Display

#### Time format

Controls how events' timestamps are displayed.

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. Most people won't find this very useful, but programmers might.
  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

Controls how MIDI Monitor displays the musical note in 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 of all events. Intended for experts only.

Data formatting
  Data is displayed as raw hexadecimal bytes, without any interpretation.
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. 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

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

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.

  This preference depends on "Ask to keep changes when closing documents" in the General section of System Preferences. If that is OFF (which it is, by default) then documents are automatically saved for you, and the MIDI Monitor preference only affects untitled documents. If the system preference is ON, then the MIDI Monitor preference affects all documents.

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

# Advanced Features

### Detailed Event Data

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

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

### Rescan MIDI

You can use the menu command Special > Rescan MIDI 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.)

# Contact

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

### Acknowledgements

MIDI Monitor is copyright © 2001-2014 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.