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. At the basic level it is somewhat analogous to a pair of panels and a set of patch cords.

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.

MFM provides basic mapping - allowing the user to replace any "note" with any other. It also allows the user to modify note properties such as length and attack in the process.

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.

This page expands information on its use for mechanical note, as opposed to electronic percussion, mapping.

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. The browser can not be used for editing purposes.

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 extensive comments to my maps. This to partly to help others in studying or modifying them, but primarily to assist myself in revision, and using cut-and-paste to generate new ones.

If a MIDI instruction (note on, etc.) 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 samples of my maps:

Map 1. - Transpose Up 2 Semitones
There are several implementations of the Carl Frei 20 note scale in use on MIDI controlled crank organs. All use the same intervals between notes, but some use an F as the lowest note (MIDI number 41 or 53) some use a G (MIDI number 43), and so on.

This map simply transposes the non-percussion Notes up two semitones. It can be easily modified to any other number of semitones. Any percussion notes or controls in the file are removed.

Map 2. Strip_MIDI
This map strips Control Signals from a MIDI File and Adjust Note Velocities to a Common Level. Instructions in an input MIDI file which are not included in a map are not passed to the output file. This map passes all of the notes from input to output.

On band organs, the organ magnets (solenoids) simply open and close, and pipes are either on or off. In this map the Note and Channel numbers are not changed, but all non-percussion Notes are set to a common Velocity of 75, and all percussion notes are set to 127. This allows the arranger to hear the MIDI file in an editor more-or-less as it would play on an organ with one stop open on each channel.

Such things as Control signals, Bend, etc. are not listed, and therefore are not passed to the output file.

Map 3. AMI_to_PowerTracks
The basic AMI (Ames Scale) format was created at a time when MIDI-to-Parallel circuit boards required that all notes, or other signals, be on the same channel. The AMI scales for large organs used two boards, with bass, melody, harmony and trumpet notes being mixed, and therefore not readily listented to or edited on a computer.

This map takes notes in an 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.

Map 4. -  W-125-Smythe_to_OSI
This example shows the code to map notes in a Wurlitzer 125 scale MIDI file created from a roll scan to fit a small organ we have. The small organ has a 20-note pipe section with an additional 9-note glockenspiel plus a tambourine, cymbal, and woodblock. 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 (Trumpet) 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. There is a line of "code" for every note in the Wurlitzer 125 scale.

In the process three notes are lost completely.

The 23 pipe notes are reduced to 20, with some overlapped.

The 13 trumpet notes are mapped to only 9 bell notes.

After transformation, the MIDI files are hand-edited to removed duplicate notes, improve articulation, and to change re-iterating snare signals to a series of strokes.

Map 5. -  W-150-Smythe_to_Frei_20er.xml
This example shows the code to map notes in a Wurlitzer 125 scale MIDI file created from a roll scan to fit a Carl Frei 20-note organ.

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 (Trumpet), Percussion and Control notes are removed. The Trombone notes duplicate the Bass and serve as a register, so they are also deleted.

There is no B or G# in 20-er scale and these three notes are lost completely.

After transformation, the MIDI files are hand-edited to removed duplicate notes, and improve articulation.

Caveat: Because of their relatively recent creation, all MIDI files are covered by a copyright held by someone, even if the original composition and arrangement are not. If you have not created the original MIDI file, you should understand your rights to use the work.