Previous topic

music21.stream

Next topic

music21.test.test

Table Of Contents

Table Of Contents

music21.tempo

This module defines objects for describing tempo and changes in tempo.

music21.tempo.interpolateElements(element1, element2, sourceStream, destinationStream, autoAdd=True)

Assume that element1 and element2 are two elements in sourceStream and destinationStream with other elements (say eA, eB, eC) between them. For instance, element1 could be the downbeat at offset 10 in sourceStream (a Stream representing a score) and offset 20.5 in destinationStream (which might be a Stream representing the timing of notes in particular recording at approximately but not exactly qtr = 30). Element2 could be the following downbeat in 4/4, at offset 14 in source but offset 25.0 in the recording:

>>> from music21 import *
>>> sourceStream = stream.Stream()
>>> destinationStream = stream.Stream()
>>> element1 = note.QuarterNote("C4")
>>> element2 = note.QuarterNote("G4")
>>> sourceStream.insert(10, element1)
>>> destinationStream.insert(20.5, element1)
>>> sourceStream.insert(14, element2)
>>> destinationStream.insert(25.0, element2)

Suppose eA, eB, and eC are three quarter notes that lie between element1 and element2 in sourceStream and destinationStream, as in:

>>> eA = note.QuarterNote("D4")
>>> eB = note.QuarterNote("E4")
>>> eC = note.QuarterNote("F4")
>>> sourceStream.insert(11, eA)
>>> sourceStream.insert(12, eB)
>>> sourceStream.insert(13, eC)
>>> destinationStream.append([eA, eB, eC])  # not needed if autoAdd were true

then running this function will cause eA, eB, and eC to have offsets 21.625, 22.75, and 23.875 respectively in destinationStream:

>>> tempo.interpolateElements(element1, element2, sourceStream, destinationStream, autoAdd = False)
>>> for el in [eA, eB, eC]:
...    print el.getOffsetBySite(destinationStream)
21.625
22.75
23.875

if the elements between element1 and element2 do not yet appear in destinationStream, they are automatically added unless autoAdd is False.

(with the default autoAdd, elements are automatically added to new streams):

>>> destStream2 = stream.Stream()
>>> destStream2.insert(10.1, element1)
>>> destStream2.insert(50.5, element2)
>>> tempo.interpolateElements(element1, element2, sourceStream, destStream2)
>>> for el in [eA, eB, eC]:
...    print el.getOffsetBySite(destStream2)
20.2
30.3
40.4

(unless autoAdd is set to false, in which case a Tempo Exception arises...)

>>> destStream3 = stream.Stream()
>>> destStream3.insert(100, element1)
>>> destStream3.insert(500, element2)
>>> tempo.interpolateElements(element1, element2, sourceStream, destStream3, autoAdd = False)
Traceback (most recent call last):
...
TempoException: Could not find element <music21.note.Note D> with id ...
music21.tempo.convertTempoByNumber(numberSrc, quarterLengthBeatSrc, numberDst)

Convert between equivalent tempi, where the speed stays the same but the beat referent and number change.

music21.tempo.convertTempoByReferent(numberSrc, quarterLengthBeatSrc, quarterLengthBeatDst=1.0)

Convert between equivalent tempi, where the speed stays the same but the beat referent and number chnage.

>>> from music21 import *
>>> tempo.convertTempoByReferent(60, 1, 2) # 60 bpm at quarter, going to half
30.0
>>> tempo.convertTempoByReferent(60, 1, .25) # 60 bpm at quarter, going to 16th
240.0
>>> tempo.convertTempoByReferent(60, 1.5, 1) # 60 at dotted quarter, get quarter
90.0
>>> tempo.convertTempoByReferent(60, 1.5, 2) # 60 at dotted quarter, get half
45.0
>>> tempo.convertTempoByReferent(60, 1.5, 1/3.) # 60 at dotted quarter, get trip
270.0

MetronomeMark

Inherits from: TempoIndication, Music21Object, JSONSerializer

class music21.tempo.MetronomeMark(text=None, number=None, referent=None, parentheses=False)

A way of specifying a particular tempo with a text string, a referent (a duration) and a number.

The referent attribute is a Duration object, or a string duration type or a floating-point quarter-length value used to create a Duration.

MetronomeMarks, as Music21Object subclasses, also have .duration object property independent of the referent.

The text attribute will usually return a unicode string. If you use “from __future__ import unicode_literals” this will not be a problem at all.

>>> from music21 import *
>>> a = tempo.MetronomeMark("slow", 40, note.HalfNote())
>>> a.number
40
>>> a.referent
<music21.duration.Duration 2.0>
>>> a.referent.type
'half'
>>> print a.text
slow

Some text marks will automatically suggest a number.

>>> mm = tempo.MetronomeMark('adagio')
>>> mm.number
56
>>> mm.numberImplicit
True

For certain numbers, a text value can be set implicitly

>>> tm2 = tempo.MetronomeMark(number=208)
>>> print tm2.text
prestissimo
>>> tm2.referent
<music21.duration.Duration 1.0>

Unicode values sometimes are hard to work with. Here’s an example that works...

>>> marking = "très vite"
>>> print marking
très vite
>>> print tempo.defaultTempoValues[marking]
144
>>> tm2 = tempo.MetronomeMark(marking)
>>> tm2.text.endswith('vite')
True
>>> tm2.number
144

MetronomeMark attributes

Attributes without Documentation: numberImplicit, parentheses, textImplicit

Attributes inherited from TempoIndication: classSortOrder

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

MetronomeMark properties

number

Get and set the number, or the numerical value of the Metronome.

>>> from music21 import *
>>> mm = tempo.MetronomeMark('slow')
>>> mm.number
56
>>> mm.numberImplicit
True
>>> mm.number = 52.5
>>> mm.number
52.5
>>> mm.numberImplicit
False
numberSounding

Get and set the numberSounding, or the numerical value of the Metronome that is used for playback independent of display. If numberSounding is None, number is assumed to be numberSounding.

>>> from music21 import *
>>> mm = tempo.MetronomeMark('slow')
>>> mm.number
56
>>> mm.numberImplicit
True
>>> mm.numberSounding == None
True
>>> mm.numberSounding = 120
>>> mm.numberSounding
120
referent

Get or set the referent, or the Duration object that is the reference for the tempo value in BPM.

text

Get or set a text string for this MetronomeMark. Internally implemented as a TempoText object, which stores the text in a TextExpression object.

>>> from __future__ import unicode_literals
>>> from music21 import *
>>> mm = tempo.MetronomeMark(number=123)
>>> mm.text == None
True
>>> mm.text = 'medium fast'
>>> print mm.text
medium fast

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds

Properties inherited from JSONSerializer: json

MetronomeMark methods

durationToSeconds(durationOrQuarterLength)

Given a duration specified as a Duration object or a quarter length, return the resultant time in seconds at the tempo specified by this MetronomeMark.

>>> from music21 import tempo
>>> mm1 = tempo.MetronomeMark(referent=1.0, number=60.0)
>>> mm1.durationToSeconds(60)
60.0
>>> mm1.durationToSeconds(duration.Duration('16th'))
0.25
getEquivalentByNumber(number)

Return a new MetronomeMark object that has an equivalent speed but different number and referent values based on a supplied tempo number.

getEquivalentByReferent(referent)

Return a new MetronomeMark object that has an equivalent speed but different number and referent values based on a supplied referent (given as a Duration type, quarterLength, or Duration object).

>>> from music21 import *
>>> mm1 = music21.tempo.MetronomeMark(number=60, referent=1.0)
>>> mm1.getEquivalentByReferent(.5)
<music21.tempo.MetronomeMark larghetto Eighth=120.0>
>>> mm1.getEquivalentByReferent(duration.Duration('half'))
<music21.tempo.MetronomeMark larghetto Half=30.0>
getMaintainedNumberWithReferent(referent)

Return a new MetronomeMark object that has an equivalent number but a new referent.

getQuarterBPM(useNumberSounding=True)

Get a BPM value where the beat is a quarter; must convert from the defined beat to a quarter beat. Will return None if no beat number is defined.

This mostly used for generating MusicXML <sound> tags when necessary.

>>> from music21 import *
>>> mm = MetronomeMark(number=60, referent='half')
>>> mm.getQuarterBPM()
120.0
>>> mm.referent = 'quarter'
>>> mm.getQuarterBPM()
60.0
getTextExpression(returnImplicit=False)

If there is a TextExpression available that is not implicit, return it; otherwise, return None.

>>> from music21 import *
>>> mm = MetronomeMark('presto')
>>> mm.number
184
>>> mm.numberImplicit
True
>>> mm.getTextExpression()
<music21.expressions.TextExpression "presto">
>>> mm.textImplicit
False

>>> mm = MetronomeMark(number=90)
>>> mm.numberImplicit
False
>>> mm.textImplicit
True
>>> mm.getTextExpression() == None
True
>>> mm.getTextExpression(returnImplicit=True)
<music21.expressions.TextExpression "maestoso">
secondsPerQuarter()

Return the duration in seconds for each quarter length (not necessarily the referent) of this MetronomeMark.

>>> from music21 import tempo
>>> mm1 = tempo.MetronomeMark(referent=1.0, number=60.0)
>>> mm1.secondsPerQuarter()
1.0
>>> mm1 = tempo.MetronomeMark(referent=2.0, number=60.0)
>>> mm1.secondsPerQuarter()
0.5
>>> mm1 = tempo.MetronomeMark(referent=2.0, number=30.0)
>>> mm1.secondsPerQuarter()
1.0
secondsToDuration(seconds)

Given a duration in seconds, return a Duration object equal to that time.

>>> from music21 import tempo
>>> mm1 = tempo.MetronomeMark(referent=1.0, number=60.0)
>>> mm1.secondsToDuration(0.25)
<music21.duration.Duration 0.25>
>>> mm1.secondsToDuration(0.5).type
'eighth'
>>> mm1.secondsToDuration(1)
<music21.duration.Duration 1.0>
setQuarterBPM(value, setNumber=True)

Given a value in BPM, use it to set the value of this MetroneMark. BPM values are assumed to be refer only to quarter notes; different beat values, if definded here, will be scaled

>>> from music21 import *
>>> mm = MetronomeMark(number=60, referent='half')
>>> mm.setQuarterBPM(240) # set to 240 for a quarter
>>> mm.number  # a half is half as fast
120.0

Methods inherited from TempoIndication: getPreviousMetronomeMark(), getSoundingMetronomeMark()

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()

TempoText

Inherits from: TempoIndication, Music21Object, JSONSerializer

class music21.tempo.TempoText(text=None)
>>> import music21
>>> tm = music21.tempo.TempoText("adagio")
>>> print tm.text
adagio

TempoText attributes

Attributes inherited from TempoIndication: classSortOrder

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

TempoText properties

text

Get or set the text as a string.

Depending on whether “from __future__ import unicode_literals” is turned on, this might give a unicode literal (u’adagio’)

>>> import music21
>>> tm = music21.tempo.TempoText("adagio")
>>> print tm.text
adagio
>>> tm.getTextExpression()
<music21.expressions.TextExpression "adagio">

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds

Properties inherited from JSONSerializer: json

TempoText methods

applyTextFormatting(te=None, numberImplicit=False)

Apply the default text formatting to the text expression version of of this repeat

getMetronomeMark()

Return a MetronomeMark object that is configured from this objects Text.

>>> from music21 import *
>>> tt = tempo.TempoText("slow")
>>> mm = tt.getMetronomeMark()
>>> mm.number
56
getTextExpression(numberImplicit=False)

Return a TextExpression object for this text.

isCommonTempoText(value=None)

Return True or False if the supplied text seems like a plausible Tempo indications be used for this TempoText.

>>> from music21 import *
>>> tt = tempo.TempoText("adagio")
>>> tt.isCommonTempoText()
True

>>> tt = tempo.TempoText("Largo e piano")
>>> tt.isCommonTempoText()
True
>>> tt = tempo.TempoText("undulating")
>>> tt.isCommonTempoText()
False
setTextExpression(vale)

Given a TextExpression, set it in this object.

Methods inherited from TempoIndication: getPreviousMetronomeMark(), getSoundingMetronomeMark()

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()

MetricModulation

Inherits from: TempoIndication, Music21Object, JSONSerializer

class music21.tempo.MetricModulation

A class for representing the relationship between two MetronomeMarks. Generally this relationship is one of equality, where the number is maintained but the referent that number is applied to changes.

The basic definition of a MetricModulation is given by supplying two MetronomeMarks, one for the oldMetronome, the other for the newMetronome. High level properties, oldReferent and newReferent, and convenience methods permit only setting the referent.

The classicalStyle attribute determines of the first MetronomeMark describes the new tempo, not the old (the reverse of expected usage).

The maintainBeat attribute determines if, after an equality statement, the beat is maintained. This is relevant for moving from 3/4 to 6/8, for example.

>>> from music21 import *
>>> s = stream.Stream()
>>> mm1 = tempo.MetronomeMark(number=60)
>>> s.append(mm1)
>>> s.repeatAppend(note.Note(quarterLength=1), 2)
>>> s.repeatAppend(note.Note(quarterLength=.5), 4)

>>> mmod1 = tempo.MetricModulation()
>>> mmod1.oldReferent = .5 # can use Duration objects
>>> mmod1.newReferent = 'quarter' # can use Duration objects
>>> s.append(mmod1)
>>> mmod1.updateByContext() # get number from last MetronomeMark on Stream
>>> mmod1.newMetronome
<music21.tempo.MetronomeMark animato Quarter=120.0>
>>> s.append(note.Note())
>>> s.repeatAppend(note.Note(quarterLength=1.5), 2)

>>> mmod2 = tempo.MetricModulation()
>>> s.append(mmod2) # if the obj is added to Stream, can set referents
>>> mmod2.oldReferent = 1.5 # will get number from previous MetronomeMark
>>> mmod2.newReferent = 'quarter'
>>> mmod2.newMetronome
<music21.tempo.MetronomeMark animato Quarter=80.0>
>>> s.repeatAppend(note.Note(), 4)

MetricModulation attributes

Attributes without Documentation: parentheses, maintainBeat, transitionSymbol, classicalStyle, arrowDirection

Attributes inherited from TempoIndication: classSortOrder

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

MetricModulation properties

newMetronome

Get or set the the right MetronomeMark object for the new, or following value.

>>> from music21 import *
>>> mm1 = tempo.MetronomeMark(number=60, referent=1)
>>> mm1
<music21.tempo.MetronomeMark larghetto Quarter=60>
>>> mmod1 = tempo.MetricModulation()
>>> mmod1.newMetronome = mm1
>>> mmod1.newMetronome = 'junk'
Traceback (most recent call last):
MetricModulationException: newMetronome property must be set with a MetronomeMark instance
newReferent

Get or set the referent of the new MetronomeMark.

>>> from music21 import *
>>> mm1 = tempo.MetronomeMark(number=60, referent=1)
>>> mmod1 = tempo.MetricModulation()
>>> mmod1.newMetronome = mm1
>>> mmod1.newMetronome
<music21.tempo.MetronomeMark larghetto Quarter=60>
>>> mmod1.newReferent = .25
>>> mmod1.newMetronome
<music21.tempo.MetronomeMark larghetto 16th=240.0>
number

Get and the number of the MetricModulation, or the number assigned to the new MetronomeMark.

>>> from music21 import *
>>> s = stream.Stream()
>>> mm1 = tempo.MetronomeMark(number=60)
>>> s.append(mm1)
>>> s.repeatAppend(note.Note(quarterLength=1), 2)
>>> s.repeatAppend(note.Note(quarterLength=.5), 4)

>>> mmod1 = tempo.MetricModulation()
>>> mmod1.oldReferent = .5 # can use Duration objects
>>> mmod1.newReferent = 'quarter'
>>> s.append(mmod1)
>>> mmod1.updateByContext()
>>> mmod1.newMetronome
<music21.tempo.MetronomeMark animato Quarter=120.0>
>>> mmod1.number
120.0
oldMetronome

Get or set the the left MetronomeMark object for the old, or previous value.

>>> from music21 import *
>>> mm1 = tempo.MetronomeMark(number=60, referent=1)
>>> mm1
<music21.tempo.MetronomeMark larghetto Quarter=60>
>>> mmod1 = tempo.MetricModulation()
>>> mmod1.oldMetronome = mm1

Note that we do need to have a proper MetronomeMark instance to figure this out:

>>> mmod1.oldMetronome = 'junk'
Traceback (most recent call last):
MetricModulationException: oldMetronome property must be set with a MetronomeMark instance
oldReferent

Get or set the referent of the old MetronomeMark.

>>> from music21 import *
>>> mm1 = tempo.MetronomeMark(number=60, referent=1)
>>> mmod1 = tempo.MetricModulation()
>>> mmod1.oldMetronome = mm1
>>> mmod1.oldMetronome
<music21.tempo.MetronomeMark larghetto Quarter=60>
>>> mmod1.oldReferent = .25
>>> mmod1.oldMetronome
<music21.tempo.MetronomeMark larghetto 16th=240.0>

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, duration, isGrace, measureNumber, offset, priority, seconds

Properties inherited from JSONSerializer: json

MetricModulation methods

setEqualityByReferent(side=None, referent=1.0)

Set the other side of the metric modulation to an equality; side can be specified, or if one side is None, that side will be set.

>>> from music21 import *
>>> mm1 = tempo.MetronomeMark(number=60, referent=1)
>>> mmod1 = tempo.MetricModulation()
>>> mmod1.newMetronome = mm1
>>> mmod1.setEqualityByReferent(None, 2)
>>> mmod1
<music21.tempo.MetricModulation <music21.tempo.MetronomeMark larghetto Half=30.0>=<music21.tempo.MetronomeMark larghetto Quarter=60>>
setOtherByReferent(side=None, referent=1.0)

Set the other side of the metric modulation not based on equality, but on a direct translation of the tempo value.

updateByContext()

Update this metric modulation based on the context, or the surrounding MetronomeMarks or MetricModulations. The object needs to reside in a Stream for this to be effective.

Methods inherited from TempoIndication: getPreviousMetronomeMark(), getSoundingMetronomeMark()

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()

TempoIndication

Inherits from: Music21Object, JSONSerializer

class music21.tempo.TempoIndication

A generic base class for all tempo indications to inherit. Can be used to filter out all types of tempo indications.

TempoIndication 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 inherited from Music21Object: isSpanner, isStream, isVariant, hideObjectOnPrint, groups, id

TempoIndication properties

TempoIndication methods

getPreviousMetronomeMark()

Do activeSite and context searches to try to find the last relevant MetronomeMark or MetricModulation object. If a MetricModulation mark is found, return the new MetronomeMark, or the last relevant.

>>> from music21 import *
>>> s = stream.Stream()
>>> s.insert(0, tempo.MetronomeMark(number=120))
>>> mm1 = MetronomeMark(number=90)
>>> s.insert(20, mm1)
>>> mm1.getPreviousMetronomeMark()
<music21.tempo.MetronomeMark animato Quarter=120>
getSoundingMetronomeMark(found=None)

Get the appropriate MetronomeMark from anu sort of TempoIndication, regardless of class.

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()