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.
>>> from music21 import *
>>> 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
return the name of a generic ensemble with “number” players:
>>> from music21 import *
>>> instrument.ensembleNameBySize(4)
'quartet'
>>> instrument.ensembleNameBySize(1)
'solo'
>>> instrument.ensembleNameBySize(83)
'treoctogetet'
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>
return the instrument with “number” as its assigned midi program:
>>> from music21 import *
>>> 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
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.
takes a Stream that has Unpitched objects and moves their .storedInstrument attributes to a new Stream (unless inPlace = True)
>>> from music21 import *
>>> 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...>
Inherits from: Music21Object
Base class for all musical instruments. Designed for subclassing, though usually a more specific instrument class (such as StringInstrument) would be better to subclass.
Instrument attributes
- classSortOrder¶
Property which returns an number (int or otherwise) depending on the class of the Music21Object that represents a priority for an object based on its class alone – used as a tie for stream sorting in case two objects have the same offset and priority. Lower numbers are sorted to the left of higher numbers. For instance, Clef, KeySignature, TimeSignature all come (in that order) before Note.
All undefined classes have classSortOrder of 20 – same as note.Note
>>> from music21 import * >>> m21o = base.Music21Object() >>> m21o.classSortOrder 20 >>> tc = clef.TrebleClef() >>> tc.classSortOrder 0>>> ks = key.KeySignature(3) >>> ks.classSortOrder 1New classes can define their own default classSortOrder
>>> class ExampleClass(base.Music21Object): ... classSortOrderDefault = 5 ... >>> ec1 = ExampleClass() >>> ec1.classSortOrder 5Attributes without Documentation: instrumentName, midiChannel, lowestNote, inGMPercMap, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition
Attributes inherited from Music21Object: isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint
Instrument properties
Properties inherited from Music21Object: classes, fullyQualifiedClasses, activeSite, beat, beatDuration, beatStr, beatStrength, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds
Instrument methods
- 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.
>>> from music21 import * >>> used = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11] >>> i = instrument.Violin() >>> i.autoAssignMidiChannel(used) 12 >>> i.midiChannel 12
- bestName()¶
Find a viable name, looking first at instrument, then part, then abbreviations.
- instrumentIdRandomize()¶
Force a unique id by using an MD5
- partIdRandomize()¶
Force a unique id by using an MD5
Methods inherited from Music21Object: findAttributeInHierarchy(), getContextAttr(), setContextAttr(), addContext(), addLocation(), getAllContextsByClass(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unwrapWeakref(), wrapWeakref(), write()
Inherits from: Guitar, StringInstrument, Instrument, Music21Object
Inherits from: Guitar, StringInstrument, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object
Inherits from: WoodwindInstrument, Instrument, Music21Object
Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object
Inherits from: Clarinet, WoodwindInstrument, Instrument, Music21Object
>>> from music21 import *
>>> bcl = instrument.BassClarinet()
>>> bcl.instrumentName
'Bass clarinet'
>>> bcl.midiProgram
71
>>> 'WoodwindInstrument' in bcl.classes
True
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Trombone, BrassInstrument, Instrument, Music21Object
Inherits from: WoodwindInstrument, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: KeyboardInstrument, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: WoodwindInstrument, Instrument, Music21Object
Inherits from: KeyboardInstrument, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: StringInstrument, Instrument, Music21Object
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
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Cymbals, UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Guitar, StringInstrument, Instrument, Music21Object
Inherits from: Guitar, StringInstrument, Instrument, Music21Object
Inherits from: Organ, Instrument, Music21Object
Inherits from: WoodwindInstrument, Instrument, Music21Object
Inherits from: Cymbals, UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Guitar, StringInstrument, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: KeyboardInstrument, Instrument, Music21Object
Inherits from: Cymbals, UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: BrassInstrument, Instrument, Music21Object
>>> from music21 import *
>>> hn = instrument.Horn()
>>> hn.instrumentName
'Horn'
>>> hn.midiProgram
60
>>> 'BrassInstrument' in hn.classes
True
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Instrument, Music21Object
Inherits from: StringInstrument, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Soprano, Vocalist, Instrument, Music21Object
Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object
Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object
Inherits from: Instrument, Music21Object
Percussion attributes
Attributes without Documentation: percMapPitch
Attributes inherited from Instrument: classSortOrder, instrumentName, midiChannel, lowestNote, inGMPercMap, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition
Attributes inherited from Music21Object: isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint
Percussion properties
Properties inherited from Music21Object: classes, fullyQualifiedClasses, activeSite, beat, beatDuration, beatStr, beatStrength, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds
Percussion methods
Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()
Methods inherited from Music21Object: findAttributeInHierarchy(), getContextAttr(), setContextAttr(), addContext(), addLocation(), getAllContextsByClass(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unwrapWeakref(), wrapWeakref(), write()
Inherits from: KeyboardInstrument, Instrument, Music21Object
>>> from music21 import *
>>> p = instrument.Piano()
>>> p.instrumentName
'Piano'
>>> p.midiProgram
0
Piano attributes
Attributes without Documentation: names
Attributes inherited from Instrument: classSortOrder, instrumentName, midiChannel, lowestNote, inGMPercMap, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition
Attributes inherited from Music21Object: isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint
Piano properties
Properties inherited from Music21Object: classes, fullyQualifiedClasses, activeSite, beat, beatDuration, beatStr, beatStrength, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds
Piano methods
Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()
Methods inherited from Music21Object: findAttributeInHierarchy(), getContextAttr(), setContextAttr(), addContext(), addLocation(), getAllContextsByClass(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unwrapWeakref(), wrapWeakref(), write()
Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object
Inherits from: Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object
Inherits from: Cymbals, UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: WoodwindInstrument, Instrument, Music21Object
Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object
Inherits from: StringInstrument, Instrument, Music21Object
Inherits from: WoodwindInstrument, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Cymbals, UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object
Inherits from: Cymbals, UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Instrument, Music21Object
StringInstrument attributes
Attributes inherited from Instrument: classSortOrder, instrumentName, midiChannel, lowestNote, inGMPercMap, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition
Attributes inherited from Music21Object: isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint
StringInstrument properties
- 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.[*]
>>> from music21 import * >>> 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*)
Properties inherited from Music21Object: classes, fullyQualifiedClasses, activeSite, beat, beatDuration, beatStr, beatStrength, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds
StringInstrument methods
Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()
Methods inherited from Music21Object: findAttributeInHierarchy(), getContextAttr(), setContextAttr(), addContext(), addLocation(), getAllContextsByClass(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unwrapWeakref(), wrapWeakref(), write()
Inherits from: Cymbals, UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: BrassInstrument, Instrument, Music21Object
Inherits from: BrassInstrument, Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: StringInstrument, Instrument, Music21Object
Inherits from: Percussion, Instrument, Music21Object
UnpitchedPercussion attributes
Attributes inherited from Percussion: percMapPitch
Attributes inherited from Instrument: classSortOrder, instrumentName, midiChannel, lowestNote, inGMPercMap, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition
Attributes inherited from Music21Object: isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint
UnpitchedPercussion properties
- 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
>>> from music21 import * >>> bd = instrument.BongoDrums() >>> bd.modifier 'high' >>> bd.percMapPitch 60 >>> bd.modifier = 'low' >>> bd.percMapPitch 61Variations 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'Properties inherited from Music21Object: classes, fullyQualifiedClasses, activeSite, beat, beatDuration, beatStr, beatStrength, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds
UnpitchedPercussion methods
Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()
Methods inherited from Music21Object: findAttributeInHierarchy(), getContextAttr(), setContextAttr(), addContext(), addLocation(), getAllContextsByClass(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unwrapWeakref(), wrapWeakref(), write()
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Vibraslap attributes
Attributes without Documentation: instrumenAbbreviation
Attributes inherited from Percussion: percMapPitch
Attributes inherited from Instrument: classSortOrder, instrumentName, midiChannel, lowestNote, inGMPercMap, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition
Attributes inherited from Music21Object: isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint
Vibraslap properties
Properties inherited from UnpitchedPercussion: modifier
Properties inherited from Music21Object: classes, fullyQualifiedClasses, activeSite, beat, beatDuration, beatStr, beatStrength, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds
Vibraslap methods
Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()
Methods inherited from Music21Object: findAttributeInHierarchy(), getContextAttr(), setContextAttr(), addContext(), addLocation(), getAllContextsByClass(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unwrapWeakref(), wrapWeakref(), write()
Inherits from: StringInstrument, Instrument, Music21Object
Inherits from: Instrument, Music21Object
n.b. called Vocalist to not be confused with stream.Voice
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object
Whistle attributes
Attributes without Documentation: percMapPitch
Attributes inherited from Instrument: classSortOrder, instrumentName, midiChannel, lowestNote, inGMPercMap, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition
Attributes inherited from Music21Object: isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint
Whistle properties
Properties inherited from Music21Object: classes, fullyQualifiedClasses, activeSite, beat, beatDuration, beatStr, beatStrength, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds
Whistle methods
Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()
Methods inherited from Music21Object: findAttributeInHierarchy(), getContextAttr(), setContextAttr(), addContext(), addLocation(), getAllContextsByClass(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unwrapWeakref(), wrapWeakref(), write()
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: UnpitchedPercussion, Percussion, Instrument, Music21Object
Inherits from: Instrument, Music21Object
Inherits from: PitchedPercussion, Percussion, Instrument, Music21Object