MIDI File Mapper
A Tool for Moving MIDI Files Between Instruments
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
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
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
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
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.
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
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
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. -
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
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.