Introduction and Overview

The CMU MIDI Toolkit (CMT) is a software package designed for experimental computer music education, composition, performance, and research. CMT includes a compiler for a simple, text-based music language, and software for recording, playing, and computing MIDI data in real time. CMT has three major attractions: the flexibility of an open-ended design, the availability of source code, and low system cost.

What does CMT do? The major components and their functions are:

Required Hardware and Software

CMT runs on:
  1. Any Commodore-Amiga computer with an added MIDI interface. You need the CAMD Midi Driver and library software from Commodore to use CMT. To use Moxc, you should have an Aztec or Lattice C compiler and preferably a hard disk. Note: The author still uses CMT on some old Amiga computers to run some legacy compositions, but CMT is no longer maintained or tested on Amigas.
  2. Any Macintosh (with Think C) and any MIDI interface. You need Apple's MIDI Manager from Apple's APDA to use CMT.
  3. IBM PC/XT/AT clones (with either Borland C, Turbo C, Microsoft C, or Quick C). PC versions will require a Roland or compatible MIDI interface.
  4. See Section ``Other Interface for PCs'' for information about other interface possibilities for the PC platform.
  5. At Carnegie Mellon University, there are two Unix implementations, one for AIX running on RS6000 machines, and one for Mach 3.0 running on i386 architecture machines. Unix requires special device drivers for MIDI; contact the author for details.
Note: a C compiler is required to use the Moxc programming environment. No compiler is needed (for any machine type) to use Adagio, Step, Cornucopia, or Conduct.

The entire CMU MIDI Toolkit occupies 5 to 10MB of disk space, although this could be trimmed considerably by not compiling all the examples.

Other Details

CMT is distributed by Roger B. Dannenberg, Computer Science Department, Carnegie Mellon University, Pittsburgh, PA, 15213-3890, USA. We hope that users will contribute new software to the system and enhance the existing software in various ways. We will encourage this by helping to integrate and document new software and by distributing software updates to CMT users.

Installing CMT

Software installation procedures are described in the file named README on the distribution disk.

With the computer powered off, install your (hardware) MIDI interface. Connect your keyboard MIDI OUT to the interface MIDI IN. Connect the interface MIDI OUT to your keyboard MIDI IN. Hardware procedures should be described in the documentation with your interface. This manual does not discuss hardware installation.

MIDI THRU is likely to cause some confusion at some point, so please read this and the next paragraph carefully. MIDI THRU means that MIDI IN data is copied to MIDI OUT. For example, an MPU-401 interface normally implements MIDI THRU when CMT is not running. Some synthesizers cannot handle having output data returned to their input, so you may have to disconnect one of the MIDI cables to avoid the adverse effects of MIDI THRU. On the other hand, if you connect your computer's MIDI OUT to a sound module, you may depend upon MIDI THRU to route MIDI from your keyboard to your sound module.

In the current releases (but check for documentation updates),

DOS IRQ and Base Address

The CMU MIDI Toolkit currently supports only Roland MPU-401 compatible interfaces on PC compatible computers. These interfaces are now available from several manufacturers. Usually, these interfaces are used on interrupt 2 at base address 33016, and this is where CMU MIDI Toolkit programs expect to find an interface. If the interface is not there, CMT will search interrupt levels and addresses for an MPU-401, but there is no absolutely safe way to do this. In the process of searching, CMT writes to various I/O locations, and if non-MPU-401 hardware responds to the write, a device may be reset and/or your machine may crash. To avoid the search when your interface is not at the default interrupt level and location, you can set two environment variables, MPUIRQ and MPUBASE. For example, to specify an IRQ level 6 and base address 36016, place the following in your autoexec.bat file:
set MPUIRQ=6
set MPUBASE=360
Be sure the values of these environment variables correspond to the actual hardware. Consult your MIDI interface hardware documentation to determine the proper values.

Other Interface for PCs

In addition to Roland MPU-401 interfaces, there are many options for MIDI on PCs. Some interfaces are MPU-401 compatible, and may require no changes (or at most putting the IRQ number and base address in the environment as described in the previous section). Other interfaces, including Rev. 4.xx Sound Blasters from Creative Labs, claim to be MPU-401 compatible but only support the MPU-401 UART mode. This can be handled easily as described in the next section (``SoundBlaster and MPU Compatible Interfaces''). Another possibility is that you have an earlier version of Sound Blaster, a Voyetra VP11, or a Keytronics MIDIator. These all require recompilation of CMT, and the full process is described in Appendix ``Non-MPU-401 MIDI Interfaces''.

SoundBlaster and MPU Compatible Interfaces

If you have an "MPU Compatible" MIDI interface, it may be compatible only with UART mode. If so, we have bad news and good news. The bad news is that CMT uses the ``intelligent'' mode to determine whether or not you actually have an MPU-401 installed in your system, and this will fail if your MIDI interface supports UART mode only. The good news is that you can set the MPUUART environment variable to disable the code that checks for an MPU-401. More good news is that CMT uses UART mode for everything else.

So, to use a SoundBlaster or other UART-mode MIDI interface, place the following in your autoexec.bat file:

and reboot. If you set MPUUART, then you must have the proper MPUIRQ and MPUBASE settings (see the previous section). CMT will not check these settings and will not operate if they are incorrect.

This procedure allows you to use the SoundBlaster MIDI interface only. You need an adapter cable to convert from the small sound card connector to MIDI connectors (see your sound card manual for details). Unfortunately, this procedure does not support the use of the synthesis capabilities of your sound card.

Files and Naming

Different operating systems use different naming conventions and terminology for files and directories or folders. This manual will use the slash character (``/'') to separate directory names and will use the term directory to mean a Macintosh folder. For Macintosh users,
means the step program in the folder util, which is within the folder app. All directory paths are assumed to start in the directory in which the toolkit is installed. For DOS users, substitute ``\'' for ``/'' in paths.

Within your main CMT directory you will find four main folders (with names greater than two letters) and a bunch of folders with one- and two-letter names.

The main folders are:

Sources and makefiles for application programs.

Executable programs for the applications.

Sources for code libraries that are shared by application programs and makefiles for the libraries.

Sample Adagio files, both compositions and tests.

The one- and two-letter directories are the details for individual platforms, i.e. a compiler and/or operating system; you can delete the ones you don't need. (Also, by the way, you can delete the makefiles for platforms you don't use from the individual library and applications directories.)

Within /app there are folders for specific applications and several general directories:

some complete, fairly complex compositions. /template
a program "outline", discussed in ch. 10. /test
some simple applications involving MIDI. /util
some useful programs not working with real-time MIDI.

Macintosh users may not be familiar with command lines. Since the toolkit developed from a command-line interface, parameters called options can be passed to programs by typing them on the command line. On the Macintosh, a dialog box appears when a program is started, prompting for a command line.

If you install and compile CMT, you will find that compiled programs are left in the same directory as the source (C) code. You may wish to copy these to a single directory such as bin. A set of compiled programs is included with the release.

Command Help

Typing "?" to any toolkit program will cause it to display the complete set of command line options. Any command line option may be abbreviated with a single letter if no other options start with the same letter.

Software Structure

For programmers intending to write new applications, the shear volume of code in CMT may be a bit overwhelming. This section gives a brief overview of the software, which is covered in greater detail in Chapters ``Programming in C'' through ``Advanced Moxc Features'', ``System Details'', and Appendix ``The MIDI Interface''.

Support Modules

In order to maintain portability, CMT is based on a number of support modules:


The programs Step, MM, Exget, Exput, and Tuning are built directly on this foundation, but most MIDI programs in CMT are based on a programming system called Moxc. Moxc depends upon the support modules listed above, and Moxc is in turn implemented in three modules:


Sequences are built on top of Moxc and account for a large fraction of the CMT code. The important modules are:


Some applications build upon both the seq_type structure and Moxc. These include Adagio, Cornucopia, and Conduct, described at the beginning of this chapter and more fully in chapters of their own. There are also a few small demonstration and test programs in app/test.

Previous Section | Next Section | Table of Contents | Index | Title Page