class music21.midi.percussion.PercussionMapper

PercussionMapper provides tools to convert between MIDI notes and music21 instruments, based on the official General MIDI Level 1 Percussion Key Map. This mapping is conventionally applied to MIDI channel 10; see for more info.

Give me the instrument that corresponds to MIDI note 58!

>>> pm = midi.percussion.PercussionMapper()
>>> pm.reverseInstrumentMapping[58]
<class 'music21.instrument.Vibraslap'>

That’s right, vibraslap.

But you’re better off using the midiPitchToInstrument() method below!


Accepts 1-indexed MIDI programs, unlike music21’s 0-indexed .midiProgram and .midiChannel attributes on Instrument instances.

PercussionMapper methods


Takes an instrument.Instrument object and returns a pitch object with the corresponding 1-indexed MIDI note, according to the GM Percussion Map.

>>> pm = midi.percussion.PercussionMapper()
>>> myCow = instrument.Cowbell()
>>> cowPitch = pm.midiInstrumentToPitch(myCow)
>>> cowPitch.midi

Note that cowPitch is an actual pitch.Pitch object even though it’s meaningless!

>>> cowPitch
<music21.pitch.Pitch G#3>

If the instrument does not have an equivalent in the GM Percussion Map, return an Exception:

>>> myBagpipes = instrument.Bagpipes()
>>> pipePitch = pm.midiInstrumentToPitch(myBagpipes)
Traceback (most recent call last):
music21.midi.percussion.MIDIPercussionException: <music21.instrument.Bagpipes 'Bagpipes'>
    is not in the GM Percussion Map!

Takes a pitch.Pitch object or int and returns the corresponding instrument in the GM Percussion Map, using 1-indexed MIDI programs.

>>> pm = midi.percussion.PercussionMapper()
>>> cowPitch = pitch.Pitch(56)
>>> cowbell = pm.midiPitchToInstrument(cowPitch)
>>> cowbell
<music21.instrument.Cowbell 'Cowbell'>

Or it can just take an integer (representing MIDI note) for the pitch instead…

>>> moreCowbell = pm.midiPitchToInstrument(56)
>>> moreCowbell
<music21.instrument.Cowbell 'Cowbell'>

The standard GM Percussion list goes from 35 to 81; pitches outside this range raise an exception.

>>> bassDrum1Pitch = pitch.Pitch('B-1')
>>> pm.midiPitchToInstrument(bassDrum1Pitch)
Traceback (most recent call last):
music21.midi.percussion.MIDIPercussionException: 34 does not map to a valid instrument!

Also, certain GM instruments do not have corresponding music21 instruments, so at present they also raise an exception.

>>> cabasaPitch = 69
>>> pm.midiPitchToInstrument(cabasaPitch)
Traceback (most recent call last):
music21.midi.percussion.MIDIPercussionException: 69 does not map to a valid instrument!

Some music21 Instruments have more than one MidiPitch. In this case you’ll get the same Instrument object but with a different modifier

>>> acousticBassDrumPitch = pitch.Pitch(35)
>>> acousticBDInstrument = pm.midiPitchToInstrument(acousticBassDrumPitch)
>>> acousticBDInstrument
<music21.instrument.BassDrum 'Bass Drum'>
>>> acousticBDInstrument.modifier
>>> oneBassDrumPitch = pitch.Pitch(36)
>>> oneBDInstrument = pm.midiPitchToInstrument(oneBassDrumPitch)
>>> oneBDInstrument
<music21.instrument.BassDrum 'Bass Drum'>
>>> oneBDInstrument.modifier