music21.instrument

This module represents instruments through objects that contain general information such as Metadata for instrument names, classifications, transpositions and default MIDI program numbers. It also contains information specific to each instrument or instrument family, such as string pitches, etc. Information about instrumental ensembles is also included here though it may later be separated out into its own ensemble.py module.

Functions

music21.instrument.bundleInstruments(streamIn, inPlace=False)
>>> up1 = note.Unpitched()
>>> up1.storedInstrument = instrument.BassDrum()
>>> upUnknownInstrument = note.Unpitched()

>>> up2 = note.Unpitched()
>>> up2.storedInstrument = instrument.Cowbell()
>>> s = stream.Stream()
>>> s.append(up1)
>>> s.append(upUnknownInstrument)
>>> s.append(up2)
>>> s2 = instrument.unbundleInstruments(s)
>>> s3 = instrument.bundleInstruments(s2)
>>> for test in s3:
...     print(test.storedInstrument)
Bass Drum
Bass Drum
Cowbell
music21.instrument.ensembleNameBySize(number)

return the name of a generic ensemble with “number” players:

>>> instrument.ensembleNameBySize(4)
'quartet'
>>> instrument.ensembleNameBySize(1)
'solo'
>>> instrument.ensembleNameBySize(83)
'treoctogetet'
music21.instrument.fromString(instrumentString)

Given a string with instrument content (from an orchestral score for example), attempts to return an appropriate Instrument.

>>> from music21 import instrument
>>> t1 = instrument.fromString("Clarinet 2 in A")
>>> t1
<music21.instrument.Instrument Clarinet>
>>> t1.transposition
<music21.interval.Interval m-3>

>>> t2 = instrument.fromString("Clarinetto 3")
>>> t2
<music21.instrument.Instrument Clarinet>

>>> t3 = instrument.fromString("Flauto 2")
>>> t3
<music21.instrument.Instrument Flute>

Excess information is ignored, and the useful information can be extracted correctly as long as it’s sequential.

>>> t4 = instrument.fromString("I <3 music saxofono tenor go beavers")
>>> t4
<music21.instrument.Instrument Tenor Saxophone>
music21.instrument.instrumentFromMidiProgram(number)

return the instrument with “number” as its assigned midi program:

>>> instrument.instrumentFromMidiProgram(0)
<music21.instrument.Instrument Piano>
>>> instrument.instrumentFromMidiProgram(21)
<music21.instrument.Instrument Accordion>
>>> instrument.instrumentFromMidiProgram(500)
Traceback (most recent call last):
    ...
InstrumentException: No instrument found with given midi program
music21.instrument.partitionByInstrument(streamObj)

Given a single Stream, or a Score or similar multi-part structure, partition into a Part for each unique Instrument, joining events possibly from different parts.

>>> p1 = converter.parse("tinynotation: 4/4 c4  d  e  f  g  a  b  c'  c1")
>>> p2 = converter.parse("tinynotation: 4/4 C#4 D# E# F# G# A# B# c#  C#1")

>>> p1.getElementsByClass('Measure')[0].insert(0.0, instrument.Piccolo())
>>> p1.getElementsByClass('Measure')[0].insert(2.0, instrument.AltoSaxophone())
>>> p1.getElementsByClass('Measure')[1].insert(3.0, instrument.Piccolo())

>>> p2.getElementsByClass('Measure')[0].insert(0.0, instrument.Trombone())
>>> p2.getElementsByClass('Measure')[0].insert(3.0, instrument.Piccolo()) # not likely...
>>> p2.getElementsByClass('Measure')[1].insert(1.0, instrument.Trombone())

>>> s = stream.Score()
>>> s.insert(0, p1)
>>> s.insert(0, p2)
>>> s.show('text')
{0.0} <music21.stream.Part ...>
    {0.0} <music21.stream.Measure 1 offset=0.0>
        {0.0} <music21.instrument.Instrument Piccolo>
        {0.0} <music21.clef.TrebleClef>
        {0.0} <music21.meter.TimeSignature 4/4>
        {0.0} <music21.note.Note C>
        {1.0} <music21.note.Note D>
        {2.0} <music21.instrument.Instrument Alto Saxophone>
        {2.0} <music21.note.Note E>
        {3.0} <music21.note.Note F>
    {4.0} <music21.stream.Measure 2 offset=4.0>
        {0.0} <music21.note.Note G>
        {1.0} <music21.note.Note A>
        {2.0} <music21.note.Note B>
        {3.0} <music21.instrument.Instrument Piccolo>
        {3.0} <music21.note.Note C>
    {8.0} <music21.stream.Measure 3 offset=8.0>
        {0.0} <music21.note.Note C>
        {4.0} <music21.bar.Barline style=final>
{0.0} <music21.stream.Part ...>
    {0.0} <music21.stream.Measure 1 offset=0.0>
        {0.0} <music21.instrument.Instrument Trombone>
        {0.0} <music21.clef.BassClef>
        {0.0} <music21.meter.TimeSignature 4/4>
        {0.0} <music21.note.Note C#>
        {1.0} <music21.note.Note D#>
        {2.0} <music21.note.Note E#>
        {3.0} <music21.instrument.Instrument Piccolo>
        {3.0} <music21.note.Note F#>
    {4.0} <music21.stream.Measure 2 offset=4.0>
        {0.0} <music21.note.Note G#>
        {1.0} <music21.instrument.Instrument Trombone>
        {1.0} <music21.note.Note A#>
        {2.0} <music21.note.Note B#>
        {3.0} <music21.note.Note C#>
    {8.0} <music21.stream.Measure 3 offset=8.0>
        {0.0} <music21.note.Note C#>
        {4.0} <music21.bar.Barline style=final>

>>> s2 = instrument.partitionByInstrument(s)
>>> len(s2.parts)
3

# TODO: this step might not be necessary...

>>> for p in s2.parts:
...     unused = p.makeRests(fillGaps=True, inPlace=True)

# TODO: this step SHOULD not be necessary (measureTemplate)...

>>> for p in s2.parts:
...     p.makeMeasures(inPlace = True)
...     p.makeTies(inPlace = True)

>>> s2.show('text')
{0.0} <music21.stream.Part Piccolo>
    {0.0} <music21.stream.Measure 1 offset=0.0>
        {0.0} <music21.instrument.Instrument Piccolo>
        {0.0} <music21.clef.TrebleClef>
        {0.0} <music21.meter.TimeSignature 4/4>
        {0.0} <music21.note.Note C>
        {1.0} <music21.note.Note D>
        {2.0} <music21.note.Rest rest>
        {3.0} <music21.note.Note F#>
    {4.0} <music21.stream.Measure 2 offset=4.0>
        {0.0} <music21.note.Note G#>
        {1.0} <music21.note.Rest rest>
        {3.0} <music21.note.Note C>
    {8.0} <music21.stream.Measure 3 offset=8.0>
        {0.0} <music21.note.Note C>
        {4.0} <music21.bar.Barline style=final>
{0.0} <music21.stream.Part Trombone>
    {0.0} <music21.stream.Measure 1 offset=0.0>
        {0.0} <music21.instrument.Instrument Trombone>
        {0.0} <music21.clef.BassClef>
        {0.0} <music21.meter.TimeSignature 4/4>
        {0.0} <music21.note.Note C#>
        {1.0} <music21.note.Note D#>
        {2.0} <music21.note.Note E#>
        {3.0} <music21.note.Rest rest>
    {4.0} <music21.stream.Measure 2 offset=4.0>
        {0.0} <music21.note.Rest rest>
        {1.0} <music21.note.Note A#>
        {2.0} <music21.note.Note B#>
        {3.0} <music21.note.Note C#>
    {8.0} <music21.stream.Measure 3 offset=8.0>
        {0.0} <music21.note.Note C#>
        {4.0} <music21.bar.Barline style=final>
{0.0} <music21.stream.Part Alto Saxophone>
    {0.0} <music21.stream.Measure 1 offset=0.0>
        {0.0} <music21.instrument.Instrument Alto Saxophone>
        {0.0} <music21.clef.TrebleClef>
        {0.0} <music21.meter.TimeSignature 4/4>
        {2.0} <music21.note.Note E>
        {3.0} <music21.note.Note F>
    {4.0} <music21.stream.Measure 2 offset=4.0>
        {0.0} <music21.instrument.Instrument Alto Saxophone>
        {0.0} <music21.note.Note G>
        {1.0} <music21.note.Note A>
        {2.0} <music21.note.Note B>
        {3.0} <music21.bar.Barline style=final>

Bug in makeRests – notice the missing rest at the beginning of the alto sax part...

TODO: parts should be in Score Order. Cooindicence that this works. TODO: note redundant Alto Saxophone...

music21.instrument.unbundleInstruments(streamIn, inPlace=False)

takes a Stream that has Unpitched objects and moves their .storedInstrument attributes to a new Stream (unless inPlace = True)

>>> up1 = note.Unpitched()
>>> up1.storedInstrument = instrument.BassDrum()
>>> up2 = note.Unpitched()
>>> up2.storedInstrument = instrument.Cowbell()
>>> s = stream.Stream()
>>> s.append(up1)
>>> s.append(up2)
>>> s2 = instrument.unbundleInstruments(s)
>>> s2.show('text')
{0.0} <music21.instrument.Instrument Bass Drum>
{0.0} <music21.note.Unpitched object at 0x...>
{1.0} <music21.instrument.Instrument Cowbell>
{1.0} <music21.note.Unpitched object at 0x...>

Instrument

class music21.instrument.Instrument

Base class for all musical instruments. Designed for subclassing, though usually a more specific instrument class (such as StringInstrument) would be better to subclass.

Some defined attributes for instruments include:

  • partId
  • partName
  • partAbbreviation
  • instrumentId
  • instrumentName
  • instrumentAbbreviation
  • midiProgram
  • midiChannel
  • lowestNote (a note object or a string)
  • highestNote (a note object or a string)
  • transposition (an interval object)
  • inGMPercMap (bool – if it uses the GM percussion map)
  • soundfontFn (filepath to a sound font, optional)

Instrument bases

Instrument read-only properties

Read-only properties inherited from Music21Object:

Instrument read/write properties

Read/write properties inherited from Music21Object:

Instrument methods

Instrument.autoAssignMidiChannel(usedChannels=[])

Assign an unused midi channel given a list of used channels.

assigns the number to self.midiChannel and returns it as an int.

Note that midi channel 10 is special, and thus is skipped.

Currently only 16 channels are used.

Note that the reused “usedChannels=[]” in the signature is NOT a mistake, but necessary for the case where there needs to be a global list.

>>> used = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11]
>>> i = instrument.Violin()
>>> i.autoAssignMidiChannel(used)
12
>>> i.midiChannel
12
Instrument.bestName()

Find a viable name, looking first at instrument, then part, then abbreviations.

Instrument.instrumentIdRandomize()

Force a unique id by using an MD5

Instrument.partIdRandomize()

Force a unique id by using an MD5

Methods inherited from Music21Object:

Instrument instance variables

Instance variables inherited from Music21Object:

Contrabass

class music21.instrument.Contrabass

For the Contrabass (or double bass), the stringPitches attribute refers to the sounding pitches of each string; whereas the lowestNote attribute refers to the lowest written note

Contrabass bases

Contrabass read-only properties

Read-only properties inherited from Music21Object:

Contrabass read/write properties

Read/write properties inherited from StringInstrument:

Read/write properties inherited from Music21Object:

Contrabass methods

Methods inherited from Instrument:

Methods inherited from Music21Object:

Contrabass instance variables

Instance variables inherited from Music21Object:

StringInstrument

class music21.instrument.StringInstrument

StringInstrument bases

StringInstrument read-only properties

Read-only properties inherited from Music21Object:

StringInstrument read/write properties

StringInstrument.stringPitches

stringPitches is a property that stores a list of Pitches (or pitch names, such as “C4”) that represent the pitch of the open strings from lowest to highest.[*]

>>> vln1 = instrument.Violin()
>>> [str(p) for p in vln1.stringPitches]
['G3', 'D4', 'A4', 'E5']

instrument.stringPitches are full pitch objects, not just names:

>>> [x.octave for x in vln1.stringPitches]
[3, 4, 4, 5]

Scordatura for Scelsi’s violin concerto Anahit. (N.B. that string to pitch conversion is happening automatically)

>>> vln1.stringPitches = ["G3","G4","B4","D4"]

([*]In some tuning methods such as reentrant tuning on the ukulele, lute, or five-string banjo the order might not strictly be from lowest to highest. The same would hold true for certain violin scordatura pieces, such as some of Biber’s *Mystery Sonatas*)

Read/write properties inherited from Music21Object:

StringInstrument methods

Methods inherited from Instrument:

Methods inherited from Music21Object:

StringInstrument instance variables

Instance variables inherited from Music21Object:

UnpitchedPercussion

class music21.instrument.UnpitchedPercussion

UnpitchedPercussion bases

UnpitchedPercussion read-only properties

Read-only properties inherited from Music21Object:

UnpitchedPercussion read/write properties

UnpitchedPercussion.modifier

Returns or sets the modifier for this instrument. A modifier could be something like “low-floor” for a TomTom or “rimshot” for a SnareDrum.

If the modifier is in the object’s ._modifierToPercMapPitch dictionary then changing the modifier also changes the .percMapPitch for the object

>>> bd = instrument.BongoDrums()
>>> bd.modifier
'high'

>>> bd.percMapPitch
60
>>> bd.modifier = 'low'
>>> bd.percMapPitch
61

Variations on modifiers can also be used and they get normalized:

>>> wb1 = instrument.Woodblock()
>>> wb1.percMapPitch
76
>>> wb1.modifier = 'LO'
>>> wb1.percMapPitch
77
>>> wb1.modifier  # n.b. -- not LO
'low'

Read/write properties inherited from Music21Object:

UnpitchedPercussion methods

Methods inherited from Instrument:

Methods inherited from Music21Object:

UnpitchedPercussion instance variables

Instance variables inherited from Music21Object: