The Maximum MIDI Programmer's ToolKit

The book includes over a dozen example programs that use the ToolKit as a real-world example of how MIDI applications can be implemented in Windows 95 and Windows NT. The ToolKit includes three DLLs that implement all of the low-level timing, MIDI input and output, and Standard MIDI File support needed for even the most demanding MIDI programs. In addition, seven C++ classes make adding support for MIDI even easier.

Three of the example programs, MidiSpy, SxLib, and MaxSeq, are useful programs as well as excellent starting places for more advanced applications. These three programs can be downloaded here (1.07Mb) so you can see how the ToolKit works.

Here is an overview of each of the programs, along with information about how some of the MIDI features are implemented using the ToolKit. These programs are explored in much greater detail in the book.

MidiSpy

MidiSpy is a MIDI viewer that will display received MIDI events, either in hexadecimal or as an interpreted trace. It can also echo events out to a select output device. As a working application, it is useful for testing MIDI instruments, viewing the output of other MIDI programs (especially when using a multiport MIDI interface), and as a general-purpose tool for examining MIDI data.

As an example program, MidiSpy implements basic MIDI functions, such as MIDI input, output, and device selection menus. These MIDI device menu lists are implemented using only a few function calls, and allow users to select desired MIDI ports. Opening and closing of MIDI devices is then handled automatically by the menuing code.

For example, to perform MIDI input and output, four TooKit classes are used: CMaxMidiIn and CMaxMidiOut for MIDI input and output, respectively, and CMidiInDeviceMenu and CMidiOutDeviceMenu to implement the input and output menus, like this:

// MaxMidi Input and Output Device Objects
CMaxMidiOut MidiOut;
CMaxMidiIn MidiIn;


// Input and Output Device Menus
CMidiInDeviceMenu InMenu;
CMidiOutDeviceMenu OutMenu;


// open the first input and output devices
MidiIn.Attach(GetSafeHwnd());
MidiOut.Attach(GetSafeHwnd());


// get the parent menu
CMenu* ParentMenu = GetParent()->GetMenu();


// create the device menus and select the first devices InMenu.Create(ParentMenu->GetSafeHmenu(),
ParentMenu->GetMenuItemCount()- 1, "&Input Device", IDM_INPUT);

InMenu.Attach(&MidiIn);

InMenu.SelectDevice(0);



OutMenu.Create(ParentMenu->GetSafeHmenu(),

ParentMenu->GetMenuItemCount() - 1, "&Output Device", IDM_OUTPUT);

OutMenu.Attach(&MidiOut);

OutMenu.SelectDevice(0);


This MFC code opens the first MIDI input and output ports that are available on the system and creates two new menus in the programs main menu. Input Device will show all of the available MIDI inputs, while Output Device displays the available MIDI outputs. Whenever a user selects a MIDI device from the menu, the corresponding menu object will close the current device and open the newly selected MIDI port.

Received MIDI events are retrieved from the ToolKit by calling the CMaxMidiIn::Get() function. Likewise, events are sent to a MIDI output using the CMaxMidiOut::Put() member function. For example, to echo received events to the selected MIDI output:

MidiEvent Event;

MidiIn.Get(&Event);

MidiOut.Put(&Event);

In a real ToolKit-based program, these events are processed in a virtual function that is overridden in a class derived from CMaxMidiIn. For example, in MidiSpy, this echo function is implemented in a class called MyMidiIn, like this:

BOOL MyMidiIn::ProcessMidiData(LPMIDIEVENT lpEvent)

{

if(DisplayMode == RAWMODE)

DisplayRawMidi(GetOwner(), lpEvent);

else

DisplayTrace(GetOwner(), lpEvent);

if(EchoOut && ThruEnabled)
EchoOut->Put(lpEvent);
return TRUE;
}

Here, the ProcessMidiData() function passes the received MIDI event (read from the ToolKit DLLs via a call to CMaxMidiIn::Get()), where it is displayed on the application's window and echoed to the MIDI output.

---

SxLib

SxLib is a System Exclusive librarian program that will receive and send sysex messages and store those messages in binary files. These files, normally saved with an syx extension, can then be read by many other popular MIDI programs. SxLib is an excellent starting place when writing a patch editor or more advanced librarian program. As an example application, it illustrates how sysex messages are handled in the ToolKit.

Using the ToolKit, each MIDI event is stored in an 8-byte structure, called a MidiEvent. The structure looks like this:


typedef struct {

DWORD time; // time in ticks since last event
BYTE status; // status byte of this midi message
BYTE data1; // first data byte of message
BYTE data2; // second data byte of message
BYTE data3; // third data byte, used for tempo changes
} MidiEvent;
For short messages, like Note Ons and Note Offs, there is a one-to-one correspondence between messages and MidiEvent structures. However, for long messages, such as sysexes, each byte of the sysex is stored in a single MidiEvent structure. For these messages, the status field is set to 0xF0, to indicate that this event is part of a sysex, and the message data, including the leading 0xF0 and trailing 0xF7 are stored in the data1 field. This allows the ToolKit to handle sysex messages like any other message, and makes using the ToolKit much easier.
But for some programs, such as System Exclusive librarians, this method of storage wastes space. Seven of the eight bytes are not needed when saving these messages to disk. In this case, it is best to compress the sysex data into a binary array and only move events into and out of MidiEvent structures when accessing ToolKit functions. This is how SxLib handles this type of data.

---

MaxSeq

MaxSeq is a multitrack sequencer that allows you to:
• Record and play an unlimited number of tracks
• Read and write Standard MIDI Files
• Adjust tempo between 10 and 250 bpm
• Record tempo changes for later playback
• Select timing resolutions between 24 and 960 tpb
• Synchronize to internal and MIDI sync
• Access all of the features of the ToolKit

This program uses all of the techniques that are explored in the book. Here are some examples from the program source code to illustrate how timing and Standard MIDI File support is implemented using the ToolKit.

// MaxMidi Sync Device
MySync SyncDev;
MySync* Sync;
The program uses a sync class that is derived from CMaxMidiSync. This class handles the beat counter display. MySync member functions also automatically stop sync when playback ends. A single instance of the MySync class, along with a pointer to the class, provide all of the sync functionality needed in the program.
The sync device is attached to the MIDI input and MIDI output classes when the application's view window is created:
// get a pointer to the sync device
CFrameWnd* pMainFrm = GetParentFrame();
Sync = &((CMainFrame*)pMainFrm)->SyncDev;


// open the first input and output devices MidiIn.Attach(GetSafeHwnd());
MidiOut.Attach(GetSafeHwnd());


// attach the sync device to the input and output devices MidiIn.Attach(Sync);
MidiOut.Attach(Sync);


// get the parent menu
CMenu* ParentMenu = GetParent()->GetMenu();


// create the device menus and select the first devices InMenu.Create(ParentMenu->GetSafeHmenu(),
ParentMenu->GetMenuItemCount() - 1, "&Input Device", IDM_INPUT); InMenu.Attach(&MidiIn);
InMenu.SelectDevice(0);


OutMenu.Create(ParentMenu->GetSafeHmenu(),
ParentMenu->GetMenuItemCount() - 1, "&Output Device", IDM_OUTPUT); OutMenu.Attach(&MidiOut);
OutMenu.SelectDevice(0);

The current tempo, timing resolution, and timer period can be set in response to menu selections made by the user. For example, to change the tempo the program call the sync device's Tempo() member function:

if(TempoDialog.DoModal() == IDOK)
{
// get the new value and set the tempo
dTempo = atof((LPCTSTR)TempoDialog.m_Tempo); SyncDev.Tempo(SyncDev.Convert(dTempo));
}

Here, Tempo() expects the tempo in microseconds per beat, while the TempoDialog dialog box allows the user to enter tempo in fractional beats per minute (e.g., 132.5 bpm). The ToolKit's Convert() function converts the floating point bpm tempo into an integer uS/beat representation.

The MaxSeq program stores MIDI data in tracks, using the CMaxMidiTrack ToolKit class. New tracks are created and attached to the MIDI input and output devices like this:

pNewTrack = new CMaxMidiTrack;
MidiOut.Attach(pNewTrack);
MidiIn.Attach(pNewTrack);
pRecTrack = pNewTrack;

Any number of tracks can be attached to a particular MIDI output device. During playback, all of the attached tracks are merged automatically by the ToolKit so that they play simultaneously. When recording a new track, the last track attached to the MIDI input device becomes the destination for newly received (and timestamped) events. Once one or more of the tracks contains events, playback is started like this:

// start synchronization
Sync->Start();


// start merging tracks into the output device
MidiOut.StartOut();

Starting record is almost as easy.

// reset the timestamp for the input device since
// input is always active (for echo while idle)
MidiIn.Reset();


// enable record for the selected track
pRecTrack->Flush();
pRecTrack->IsRecording(TRUE);


// start input
Sync->IsRecording(TRUE);
Sync->Start();


// start merging (non-record) tracks into the output device MidiOut.StartOut();

Once one or more tracks have been recorded, saving the data to a Standard MIDI File is simple. Here's how MaxSeq does it:

CMaxMidiSMF wSMF;
int i;


// open a smf for writing and output the recorded track if(pTrackList)
{
wSMF.Open(lpszPathName, WRITE);

for(i = 0; i < nTracks; i++)
wSMF.Attach(pTrackList[i]);

wSMF.Save();
wSMF.Close();
}

Here, pointers to each of the tracks in the sequence are kept in the pTrackList array. Writing the Standard MIDI File involves no more than creating an instance of CMaxMidiSMF, opening a file for write, attaching each of the track objects, and saving the file.

Reading a file is also simple.

// open the new SMF
SMF.Open(lpszPathName, READ);


// allocate the array of track pointers
nTracks = SMF.NumTracks();
pTrackList = (CMaxMidiTrack**)GlobalAlloc(GPTR,
sizeof(CMaxMidiTrack*) * nTracks);


for(i = 0; i < nTracks; i++)
{
pTrackList[i] = new CMaxMidiTrack;
SMF.Attach(pTrackList[i]);
pView->MidiOut.Attach(pTrackList[i]); pView->MidiIn.Attach(pTrackList[i]);
}


// load 'em up
SMF.Load();

All of the features of the ToolKit are explored more thoroughly in the book. Over a dozen example programs build in logical progression from the simplest MIDI tasks to full-featured, useful applications. The operation of each example is explained in detail, as is the internal working of the ToolKit itself. And all of this code is supplied for you to use, modify, and cannibalize.