MIDI File Mapper

A Tool for Moving MIDI Files Between Instruments

Wally Venable



MIDI File Mapper is a free, compact, program which facilitates transposing, substituting, and modifying notes in MIDI files. It can process an entire directory in a single operation. The changes are specified in a "map" which is prepared as a text file. The article includes sample maps for use with MIDI files for mechanical music instruments such as band organs.

What is MIDI Mapping?

MIDI stands for Musical Instrument Digital Interface. MIDI files do not contain music, they contain instructions, and MIDI operations allow one digital device to send instructions to another. The digital device may be a musical instrument which actually plays notes, a computational device such as a computer or cell phone, or a controller for almost any electro-mechanical device. Many MIDI devices allow for almost simultaneous two way communications.

The MIDI protocol provides for 16 channels, each of which contains 128 "notes." In essence it provides control over a total of 2048 switches. It is typically portrayed in MIDI editors as having 16 "piano" keyboards, each of which has 128 keys. In comparison with most digital communications, MIDI provides very slow serial communication - on the order of 1000 instructions per second, but compared with a human playing a musical instrument, it is blazingly fast.

Few users of MIDI really need to know the technical details of devices or the software because of the availability of good software. Most MIDI devices and software work with basic rules established in 1985.

MIDI mapping allows the user to replace any "note" with any other, and to modify note properties such as length and attack in the process.

Mapping is particularly useful when dealing with mechanical musical instruments since many instrument builders, and installers of MIDI systems in existing instruments, have constructed interfaces which are unique to a single instrument. Files for one organ will often not be playable on another, even when the instruments play exactly the same musical scale.

There is also the issue of the "scales" used in mechanical instruments. Many standard scales are not chromatic, and have gaps where no notes are provided. In older instruments, the "keyframes" and "tracker bars" are often arranged in an order which facilitates tubing or mechanical connections, rather than note order, and in some cases the order is mixed up in order to prevent books or rolls from being played on more than a single instruments.

MIDI Mapping allows an organ owner or arranger to move any set of signals from what appears to be a random order to one which can be edited "as music," or to move signals to the order required by another instrument. This has become particularly useful now that much music in the public domain is now available as computer scans of books or rolls.

Program History & Description

MIDI File Mapper* (MFM) is a utility that allows you to remap the notes in MIDI files. I have found it to be a tremendously powerful tool for adapting arrangements for band organs, including "organ grinder" crank organs from one instrument to another.

Mark Heath, the developer, focused on creating a program for converting drum patterns between specific drum samplers or converting between loops for two different samplers. In the process he included features which allow a user to create a custom map which will move any note from one position in a file to another, and thus becomes a very useful tool for moving MIDI files to and from formats used to play music on any musical instrument.

On the downside, by 2010 Heath had a program which met his own needs and moved on to other projects. He has shared his code as Open Source Software - source code may be downloaded freely, but it seems that no other programmer has stepped in to continue development. Several features described in the documentation do not work. The most prominent of these is conversion between Type 0 and Type 1 files, but this is easily handled in most regular MIDI editors.

The complete download package is only a 152 k zip file, while the program itself, MidiFileMapper.exe, is only 66 kilobytes. The package includes several sample maps. Extended documentation can be found, and downloaded as .HTML pages. The program does not do a full Windows installation, but is easily run by double-clicking on the program file name in the directory in which you have placed it.

Procedures for running the program are covered in the on-line .HTML documentation. See the materials at http://midifilemapper.codeplex.com/  and related links.

MIDI File Mapper ships with some mappings for popular drum samplers, and allows you to import maps from Cakewalk SONAR or Steinberg Cubase.

As supplied and described on the website, there is little to attract the attention of arrangers for band organs and other mechanical music instruments. I plan to expand information on those uses, starting here, and eventually will be writing an article for COAA's Carousel Organ magazine.

Creating Maps

Maps are created as .XML (Extensible Markup Language) files. XML is a Microsoft markup language that defines a set of rules for encoding documents in a format which is both human-readable and machine-readable. That may seem confusing at first, but what it really amounts to is that you create a simple, but often lengthy, text document listing your rules and save it with the extension .XML. I use Windows Notepad to do that. If you double-click an .XML file, it typically opens in a web browser. The general rules for file preparation are covered in the program documentation.

If opened in a web browser, the appearance on the screen is a bit clearer than if opened in a text editor, but both will contain the same information.

As a sometime teacher of programming, I find comments in code are essential for later editing. An .XML comment takes the form
<!-- This is a sample comment -->
I have added comments to my maps to help others in studying them, as well as ones to assist myself in revision.

If a MIDI instruction in the original file does not appear in the map, the instruction will (probably) not appear in the output file. In processing complex MIDI files this may allow removal of such things as Pitch Bend and Peddle signals from the file. In the band organ world it allows removal of signals such as the Coin Drop or Tracker Bar Shut-off.

It is also possible to map more than one note in the input file to the same output note. For example, MIDI C3 in Channel 1, C4  in Channel 2, and C5 in Channel 3 might all be moved to C5 in Channel 1 when transferring music from a large large organ to a small one. This will create overlaps which may be edited out later. As far as I know, it is not possible to do the reverse, to move a combined Bass Drum-Cymbal signal to separate Bass Drum and Cymbal notes in the output.

Sample Maps for MFM

Here are three samples of my maps:

Map 1. - Transpose 12 Semitones.xml
This simply transposes the notes up an octave. It can be easily modified to any other number of semitones. Variations of this map will be useful in transposing MIDI files between the various implementations of the Carl Frei 20 note scale in use.

Map 2. -  W-125-Smythe_to_OSI
This short example shows some of the code to map notes in a Wurlitzer 125 scale MIDI file created from a roll scan to fit a small organ we have. Only one line for each section is shown. The Bass, Accompaniment, and Melody notes are transposed to appropriate notes in Channel 1 which plays pipes and the velocities are set to an appropriate level for later editing. The Counter-melody is transposed to appropriate notes in Channel 2, which plays bells, and notes have their Velocity and Duration adjusted. Percussion notes remain in Channel 10, but are reassigned and have their Velocity and Duration adjusted. In the full version there is a line of "code" for every note in the Wurlitzer 125 scale in the actual working map.

Map 3. AMI_to_PowerTracks
This map takes notes in an Ames format (AMI) two-channel file and separates them into individual tracks for editing with PowerTracks Pro, my primary MIDI music editor. Note that this is for a Wurlitzer 165 scale instrument, and might need to be modified substantially for other AMI scales. Lengths of snare drum notes are not modified because the W-165 has a reiterating snare drum.

More to follow.

Eventually I expect may move and expand this documentation at www.wallace-venable.name/mechanical-music/MIDI_File_Mapper

* MIDI File Mapper is NOT the Microsoft MIDI Mapper program which is used in some versions of Windows to select the Default MIDI Playback device.