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):
music21.exceptions21.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>
        {0.0} <music21.note.Rest rest>
        {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>

TODO: parts should be in Score Order. Coincidence that this almost works. TODO: note redundant Alto Saxophone... instrument –

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: