Previous topic

music21.humdrum.spineParser

Next topic

music21.interval

Table Of Contents

Table Of Contents

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.

music21.instrument.ensembleNameBySize(number)

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'
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:

>>> 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
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.

Instrument

Inherits from: Music21Object, JSONSerializer

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.

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 *
>>> tc = clef.TrebleClef()
>>> tc.classSortOrder
0
>>> ks = key.KeySignature(3)
>>> ks.classSortOrder
1

New classes can define their own default classSortOrder

>>> class ExampleClass(base.Music21Object):
...     classSortOrderDefault = 5
...
>>> ec1 = ExampleClass()
>>> ec1.classSortOrder
5

Attributes without Documentation: instrumentName, midiChannel, lowestNote, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition

Attributes inherited from Music21Object: isSpanner, isStream, isVariant, id, groups, hideObjectOnPrint

Instrument properties

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: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), freezeIds(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unfreezeIds(), unwrapWeakref(), wrapWeakref(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Accordion

Inherits from: Organ, Instrument, Music21Object, JSONSerializer

class music21.instrument.Accordion

AcousticBass

Inherits from: Guitar, StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.AcousticBass

AcousticGuitar

Inherits from: Guitar, StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.AcousticGuitar

Agogo

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Agogo

Alto

Inherits from: Vocalist, Instrument, Music21Object, JSONSerializer

class music21.instrument.Alto

AltoSaxophone

Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.AltoSaxophone

Bagpipes

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Bagpipes

Banjo

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Banjo

Baritone

Inherits from: Vocalist, Instrument, Music21Object, JSONSerializer

class music21.instrument.Baritone

BaritoneSaxophone

Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.BaritoneSaxophone

Bass

Inherits from: Vocalist, Instrument, Music21Object, JSONSerializer

class music21.instrument.Bass

BassClarinet

Inherits from: Clarinet, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.BassClarinet
>>> from music21 import *
>>> bcl = instrument.BassClarinet()
>>> bcl.instrumentName
'Bass clarinet'
>>> bcl.midiProgram
71
>>> 'WoodwindInstrument' in bcl.classes
True

BassDrum

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.BassDrum

Bassoon

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Bassoon

BongoDrums

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.BongoDrums

BrassInstrument

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.BrassInstrument

Castanets

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Castanets

Celesta

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Celesta

Clarinet

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Clarinet

Clavichord

Inherits from: KeyboardInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Clavichord

CongaDrum

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.CongaDrum

Contrabass

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Contrabass

For the Contrabass, the stringPitches attribute refers to the sounding pitches of each string; whereas the lowestNote attribute refers to the lowest written note

Cowbells

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Cowbells

CrashCymbals

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.CrashCymbals

Dulcimer

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Dulcimer

ElectricBass

Inherits from: Guitar, StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.ElectricBass

ElectricGuitar

Inherits from: Guitar, StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.ElectricGuitar

ElectricOrgan

Inherits from: Organ, Instrument, Music21Object, JSONSerializer

class music21.instrument.ElectricOrgan

EnglishHorn

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.EnglishHorn

FingerCymbals

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.FingerCymbals

Flute

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Flute

FretlessBass

Inherits from: Guitar, StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.FretlessBass

Glockenspiel

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Glockenspiel

Gong

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Gong

Guitar

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Guitar

Handbells

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Handbells

Harmonica

Inherits from: Organ, Instrument, Music21Object, JSONSerializer

class music21.instrument.Harmonica

Harp

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Harp

Harpsichord

Inherits from: KeyboardInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Harpsichord

HiHatCymbal

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.HiHatCymbal

Horn

Inherits from: BrassInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Horn
>>> from music21 import *
>>> hn = instrument.Horn()
>>> hn.instrumentName
'Horn'
>>> hn.midiProgram
60
>>> 'BrassInstrument' in hn.classes
True

Kalimba

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Kalimba

KeyboardInstrument

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.KeyboardInstrument

Koto

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Koto

Mandolin

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Mandolin

Maracas

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Maracas

Marimba

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Marimba

MezzoSoprano

Inherits from: Soprano, Vocalist, Instrument, Music21Object, JSONSerializer

class music21.instrument.MezzoSoprano

Oboe

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Oboe

Ocarina

Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Ocarina

Organ

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.Organ

PanFlute

Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.PanFlute

Percussion

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.Percussion

Piano

Inherits from: KeyboardInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Piano
>>> 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, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition

Attributes inherited from Music21Object: isSpanner, isStream, isVariant, id, groups, hideObjectOnPrint

Piano properties

Piano methods

Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), freezeIds(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unfreezeIds(), unwrapWeakref(), wrapWeakref(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

Piccolo

Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Piccolo

PipeOrgan

Inherits from: Organ, Instrument, Music21Object, JSONSerializer

class music21.instrument.PipeOrgan

PitchedPercussion

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.PitchedPercussion

Ratchet

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Ratchet

Recorder

Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Recorder

ReedOrgan

Inherits from: Organ, Instrument, Music21Object, JSONSerializer

class music21.instrument.ReedOrgan

SandpaperBlocks

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.SandpaperBlocks

Saxophone

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Saxophone

Shakuhachi

Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Shakuhachi

Shamisen

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Shamisen

Shehnai

Inherits from: WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Shehnai

Siren

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Siren

Sitar

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Sitar

SizzleCymbal

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.SizzleCymbal

SleighBells

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.SleighBells

SnareDrum

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.SnareDrum

Soprano

Inherits from: Vocalist, Instrument, Music21Object, JSONSerializer

class music21.instrument.Soprano

SopranoSaxophone

Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.SopranoSaxophone

SteelDrum

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.SteelDrum

StringInstrument

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.StringInstrument

StringInstrument attributes

Attributes inherited from Instrument: classSortOrder, instrumentName, midiChannel, lowestNote, instrumentId, partId, instrumentAbbreviation, partAbbreviation, partName, highestNote, midiProgram, transposition

Attributes inherited from Music21Object: isSpanner, isStream, isVariant, id, 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()
>>> 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"]
>>> 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: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds

Properties inherited from JSONSerializer: json

StringInstrument methods

Methods inherited from Instrument: autoAssignMidiChannel(), bestName(), instrumentIdRandomize(), partIdRandomize()

Methods inherited from Music21Object: searchActiveSiteByAttr(), getContextAttr(), setContextAttr(), addContext(), addLocation(), addLocationAndActiveSite(), freezeIds(), getAllContextsByClass(), getCommonSiteIds(), getCommonSites(), getContextByClass(), getOffsetBySite(), getSiteIds(), getSites(), getSpannerSites(), hasContext(), hasSite(), hasSpannerSite(), hasVariantSite(), isClassOrSubclass(), mergeAttributes(), next(), previous(), purgeLocations(), purgeOrphans(), purgeUndeclaredIds(), removeLocationBySite(), removeLocationBySiteId(), setOffsetBySite(), show(), splitAtDurations(), splitAtQuarterLength(), splitByQuarterLengths(), unfreezeIds(), unwrapWeakref(), wrapWeakref(), write()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

SuspendedCymbal

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.SuspendedCymbal

Taiko

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Taiko

TamTam

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.TamTam

Tambourine

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Tambourine

TempleBlock

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.TempleBlock

Tenor

Inherits from: Vocalist, Instrument, Music21Object, JSONSerializer

class music21.instrument.Tenor

TenorDrum

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.TenorDrum

TenorSaxophone

Inherits from: Saxophone, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.TenorSaxophone

Timbales

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Timbales

Timpani

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Timpani

TomTom

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.TomTom

Triangle

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Triangle

Trombone

Inherits from: BrassInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Trombone

Trumpet

Inherits from: BrassInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Trumpet

Tuba

Inherits from: BrassInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Tuba

TubularBells

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.TubularBells

Ukulele

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Ukulele

Viola

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Viola

Violin

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Violin

Violoncello

Inherits from: StringInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Violoncello

Vocalist

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.Vocalist

n.b. called Vocalist to not be confused with stream.Voice

Whip

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Whip

Whistle

Inherits from: Flute, WoodwindInstrument, Instrument, Music21Object, JSONSerializer

class music21.instrument.Whistle

WindMachine

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.WindMachine

Woodblock

Inherits from: Percussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Woodblock

WoodwindInstrument

Inherits from: Instrument, Music21Object, JSONSerializer

class music21.instrument.WoodwindInstrument

Xylophone

Inherits from: PitchedPercussion, Instrument, Music21Object, JSONSerializer

class music21.instrument.Xylophone