Previous topic

music21.stream.timespans

Next topic

music21.test.dedent

Table Of Contents

Table Of Contents

This Page

music21.tempo

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

Functions

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:

>>> sourceStream = stream.Stream()
>>> destinationStream = stream.Stream()
>>> element1 = note.Note('C4', type='quarter')
>>> element2 = note.Note('G4', type='quarter')
>>> 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.Note('D4', type='quarter')
>>> eB = note.Note('E4', type='quarter')
>>> eC = note.Note('F4', type='quarter')
>>> 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("%.1f" % (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)
>>> eA.id = "blah"
>>> 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.

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

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.

>>> a = tempo.MetronomeMark("slow", 40, note.Note(type='half'))
>>> 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 = u'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 bases

MetronomeMark read-only properties

Read-only properties inherited from Music21Object:

MetronomeMark read/write properties

MetronomeMark.number

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

>>> mm = tempo.MetronomeMark('slow')
>>> mm.number
56
>>> mm.numberImplicit
True
>>> mm.number = 52.5
>>> mm.number       
52.5
>>> mm.numberImplicit
False
MetronomeMark.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.

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

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

MetronomeMark.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
>>> mm = tempo.MetronomeMark(number=123)
>>> mm.text == None 
True
>>> mm.text = 'medium fast'
>>> print(mm.text)
medium fast

Read/write properties inherited from Music21Object:

MetronomeMark methods

MetronomeMark.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
MetronomeMark.getEquivalentByNumber(number)

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

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

>>> mm1 = 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>
MetronomeMark.getMaintainedNumberWithReferent(referent)

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

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

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

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

>>> mm = tempo.MetronomeMark('presto')
>>> mm.number
184
>>> mm.numberImplicit
True
>>> mm.getTextExpression()
<music21.expressions.TextExpression "presto">
>>> mm.textImplicit
False
>>> mm = tempo.MetronomeMark(number=90)
>>> mm.numberImplicit
False
>>> mm.textImplicit     
True
>>> mm.getTextExpression() == None
True
>>> mm.getTextExpression(returnImplicit=True)
<music21.expressions.TextExpression "maestoso">
MetronomeMark.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
MetronomeMark.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>
MetronomeMark.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

>>> mm = tempo.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:

Methods inherited from Music21Object:

MetronomeMark instance variables

Instance variables inherited from TempoIndication:

  • isStream
  • hideObjectOnPrint
  • classSortOrder
  • groups
  • isVariant
  • id
  • isSpanner
  • xPosition

Instance variables inherited from Music21Object:

TempoText

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

TempoText bases

TempoText read-only properties

Read-only properties inherited from Music21Object:

TempoText read/write properties

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

Read/write properties inherited from Music21Object:

TempoText methods

TempoText.applyTextFormatting(te=None, numberImplicit=False)

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

TempoText.getMetronomeMark()

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

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

Return a TextExpression object for this text.

TempoText.isCommonTempoText(value=None)

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

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

Given a TextExpression, set it in this object.

Methods inherited from TempoIndication:

Methods inherited from Music21Object:

TempoText instance variables

Instance variables inherited from TempoIndication:

  • isStream
  • hideObjectOnPrint
  • classSortOrder
  • groups
  • isVariant
  • id
  • isSpanner
  • xPosition

Instance variables inherited from Music21Object:

MetricModulation

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.

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

MetricModulation read-only properties

MetricModulation.number

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

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

Read-only properties inherited from Music21Object:

MetricModulation read/write properties

MetricModulation.newMetronome

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

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

Get or set the referent of the new MetronomeMark.

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

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

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

Get or set the referent of the old MetronomeMark.

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

Read/write properties inherited from Music21Object:

MetricModulation methods

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

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

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

Methods inherited from Music21Object:

MetricModulation instance variables

Instance variables inherited from TempoIndication:

  • isStream
  • hideObjectOnPrint
  • classSortOrder
  • groups
  • isVariant
  • id
  • isSpanner
  • xPosition

Instance variables inherited from Music21Object:

TempoIndication

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 bases

TempoIndication read-only properties

Read-only properties inherited from Music21Object:

TempoIndication read/write properties

Read/write properties inherited from Music21Object:

TempoIndication methods

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

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

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

Methods inherited from Music21Object:

TempoIndication instance variables

Instance variables inherited from Music21Object: