This project has moved. For the latest updates, please go here.

Map File Format

If you are a user of Cakewalk SONAR or Steinberg Cubase, then you may not need to learn the MIDI File Mapper XML mapping format at all. You simply set up a drum map in your sequencer, test that it performs the mapping you require, and save it to a file, which can be later loaded into MIDI File Mapper. However, if you do not own these sequencers, or if you want even greater control over the precise nature of the mapping, then you will need to learn to use MIDI File Mapper's built in format.

The format is standard XML, and the top level node name must be MidiMappingRules.

1. The General Section

The General section includes the Name of the map and any Author and Version information. It is the first section in the mapping file. The values in this section are not strictly needed, but are useful.

<?xml encoding="utf-8" version="1.0" ?>
<MidiMappingRules>
   <General
      Name="GM to Latin Percussion EZX"
      Author="Mark Heath"
      Version="1.0"
   />
</MidiMappingRules>

2. NoteMap Rules

After the General section will typically come a number of NoteMap nodes. You will normally add one of these for each MIDI note you wish to map. You can also set one up to map a range of notes. By default, MIDI File Mapper will exclude all notes from the output file unless they are explicitly present here. A maximum of one NoteMap rule is applied to each input MIDI note.
  • The Name attribute gives it a user friendly name - useful for naming kit pieces in a drum map.
  • The InNote attribute specifies which MIDI note numbers (0-127) will be affected by this rule. You can specify a single number (e.g. "25"), a range (e.g. "30-40") or even a list of values (e.g. "50,62,74"). If omitted value will be set to "*", which indicates that all notes will be affected.
  • The InChannel attribute specifies which MIDI channels (1-16) will be affected by this rule. By default this is "*" - all channels, but you can limit it to just one channel or a list of channels if you wish.
  • The InVelocity attribute specifies the MIDI velocity range (0-127) for events that will be affected by this rule. By default this is "*" - all velocity values, but you can limit it a range of velocities if you wish (e.g. "0-64").
  • The OutNote attribute specifies the MIDI note number that note events matching the InNote, InChannel and InVelocity will be mapped to. For drum maps this will typically be a set number (e.g. "62"), but you can also transpose (e.g. "+12" or "-1"). By default the InNote will remain unchanged.
  • The OutChannel attribute specifies the MIDI channel (1-16) that events atching this rule will be mapped to. This will normally be a set number (e.g. "1") or can be left out so its channel will be unchanged.
  • The OutVelocity attribute allows the note velocity of matching events to be modified. They can be set to a set value (e.g. "100"), adjusted by a fixed amount (e.g. "+20" or "-4"), scaled (e.g. "50%", or "200%") or left unchanged (the default "*").
  • The OutDuration attribute allows the duration of matching note events to be modified. They can be set to a set number of ticks (e.g. "15"), adjusted by a fixed amount (e.g. "+20" or "-4"), scaled (e.g. "50%", or "200%") or left unchanged (the default "*").

The following example shows a note on any channel with note number 36 being passed
through unchanged to the output file.

<NoteMap Name="Bass Drum" InNote="36" OutNote="36" />


The following example shows a note on any channel with note number 36 being passed
through to the output file with its channel being set to channel 1.

<NoteMap Name="Bass Drum" InNote="36" OutNote="36" OutChannel="1" />


The following example shows all notes being transposed up two semitones, except
for those on channel 10, which are drums. Note that if the second NoteMap rule wasn't present, the drums would have been filtered out.

<?xml version="1.0" encoding="utf-8" ?>
<MidiMappingRules>
  <General
    Name="Transpose 2 Semitones"
    Author="Mark Heath"
    Description="Test file"
    />

  <NoteMap Name="Transpose All Notes" InChannel="1-9,11-16" InNote="*" OutNote="+2" />
  <NoteMap Name="Don't Transpose Drums" InChannel="10" InNote="*" OutNote="*" />
</MidiMappingRules>


The following example will reduce the velocities of all hi-hats and increase the velocity of all snare hits in a General MIDI drum pattern file. All other notes are passed through unchanged by the third NoteMap.

<?xml version="1.0" encoding="utf-8" ?>
<MidiMappingRules>
  <General Name="Quiet Hats, Loud Snare" />
  <NoteMap Name="Hats" InNote="42,44,46" OutVelocity="75%" />
  <NoteMap Name="Snare" InNote="38-40" OutVelocity="125%" />
  <NoteMap Name="Pass-through" InNote="*" OutNote="*" />
</MidiMappingRules>

3. ControllerMap Rules

Often you simply want to remap notes, but if your MIDI files contain controllers, you may wish to move them to a different channel, or modify them in some other way. The ControllerMap node allows you to do this, in a similar way to NoteMap.
  • The Name attribute gives it a user friendly name - for example, what this controller is for. This simply makes the XML mapping file easier to read
  • The InController attribute specifies which MIDI controllers (0-127) will be affected by this rule. You can specify a single number (e.g. "25"), a range (e.g. "30-40") or even a list of values (e.g. "50,62,74"). If omitted value will be set to "*", which indicates that all controllers will be affected.
  • The InChannel attribute specifies which MIDI channels (1-16) will be affected by this rule. By default this is "*" - all channels, but you can limit it to just one channel or a list of channels if you wish.
  • The InValue attribute specifies the controller value range (0-127) for events that will be affected by this rule. By default this is "*" - all controller values, but you can limit it a range of controller values if you wish (e.g. "0-64").
  • The OutController attribute specifies the MIDI controller number that controller events matching the InController, InChannel and InValue will be mapped to. This will typically be a set number (e.g. "62") if you want to change from one controller value to another. By default the controller number will remain unchanged.
  • The OutChannel attribute specifies the MIDI channel (1-16) that events matching this rule will be mapped to. This will normally be a set number (e.g. "1") or can be left out so its channel will be unchanged.
  • The OutValue attribute allows the controller value of matching events to be modified. They can be set to a set value (e.g. "100"), adjusted by a fixed amount (e.g. "+20" or "-4"), scaled (e.g. "50%", or "200%") or left unchanged (the default "*").

4. Exclude Rules

There may be some types of MIDI event that you would like to exclude from the resulting output file, such as controllers or MIDI meta-events. The Exclude node allows you to choose which events will be excluded from the output file.
  • The EventType attribute specifies what type of events to exclude and is set to one of the following values:
    • Controller
    • PitchWheel
    • PatchChange
    • ChannelAfterTouch
    • KeyAfterTouch
    • Copyright
    • Text
    • Marker
    • Sysex
    • NonStandard (MIDI meta events not found in the MIDI spec)
    • SequencerSpecific
    • SmpteOffset
    • CuePoint
    • Lyric
    • DeviceName
    • ProgramName
    • TrackInstrumentName
    • TrackName
    • TrackSequenceNumber
    • ContinueSequence
    • StopSequence
    • StartSequence
    • TimingClock
    • All (all the above)
  • The Channel attribute specifies which channels will be excluded for the event type specified (note this only applies to MIDI events that have channels). By default this will be all channels (i.e. "*").

4. TextMap Rules

TextMap rules allow you to replace the text in a text event (such as Copyright, SequenceTrackName etc). Currently only basic modification is supported.

The EventType attribute specifies what type of event will be modified. The allowed values are Copyright, Text, Marker and TrackName.
The OutValue attribute specifies the new text to be inserted. Use the string {FILENAME} if you wish the filename of the input file (without .MID) extension to be used.
The InValue attribute specifies the text to be searched for. If this is empty, with the default Regular Expression matching rule, then all rules will match.
The following example will replace the text in any TrackName events with the filename of the MIDI file being processed:

<TextMap EventType="TrackName" OutValue="{FILENAME}" />

5. Insert Rules

TODO

6. AfterTouch Rules

TODO

7. PitchWheelChange Rules

TODO

Last edited Oct 13, 2009 at 1:21 PM by markheath, version 3

Comments

No comments yet.