.. _moduleTempo:

music21.tempo
=============

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.tempo

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




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




.. function:: convertTempoByNumber(numberSrc, quarterLengthBeatSrc, numberDst)

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



.. function:: 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: :class:`~music21.tempo.TempoIndication`, :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: 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 :class:`~music21.tempo.TempoIndication`: :attr:`~music21.tempo.TempoIndication.classSortOrder`

        Attributes inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.isSpanner`, :attr:`~music21.base.Music21Object.isStream`, :attr:`~music21.base.Music21Object.isVariant`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.groups`, :attr:`~music21.base.Music21Object.id`

    **MetronomeMark** **properties**

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



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



        .. attribute:: referent

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



        .. attribute:: text

            Get or set a text string for this MetronomeMark. Internally implemented as a :class:`~music21.tempo.TempoText` object, which stores the text in a :class:`~music21.expression.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 :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.duration`, :attr:`~music21.base.Music21Object.isGrace`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`, :attr:`~music21.base.Music21Object.seconds`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **MetronomeMark** **methods**

        .. method:: durationToSeconds(durationOrQuarterLength)

            Given a duration specified as a :class:`~music21.duration.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



        .. method:: getEquivalentByNumber(number)

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




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



        .. method:: getMaintainedNumberWithReferent(referent)

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



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



        .. method:: 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">



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



        .. method:: secondsToDuration(seconds)

            Given a duration in seconds, return a :class:`~music21.duration.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>



        .. method:: 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 :class:`~music21.tempo.TempoIndication`: :meth:`~music21.tempo.TempoIndication.getPreviousMetronomeMark`, :meth:`~music21.tempo.TempoIndication.getSoundingMetronomeMark`

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

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


TempoText
---------

Inherits from: :class:`~music21.tempo.TempoIndication`, :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: TempoText(text=None)




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



    **TempoText** **attributes**

        Attributes inherited from :class:`~music21.tempo.TempoIndication`: :attr:`~music21.tempo.TempoIndication.classSortOrder`

        Attributes inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.isSpanner`, :attr:`~music21.base.Music21Object.isStream`, :attr:`~music21.base.Music21Object.isVariant`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.groups`, :attr:`~music21.base.Music21Object.id`

    **TempoText** **properties**

        .. attribute:: 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 :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.duration`, :attr:`~music21.base.Music21Object.isGrace`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`, :attr:`~music21.base.Music21Object.seconds`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **TempoText** **methods**

        .. method:: applyTextFormatting(te=None, numberImplicit=False)

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



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



        .. method:: getTextExpression(numberImplicit=False)

            Return a TextExpression object for this text.



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



        .. method:: setTextExpression(vale)

            Given a TextExpression, set it in this object.



        Methods inherited from :class:`~music21.tempo.TempoIndication`: :meth:`~music21.tempo.TempoIndication.getPreviousMetronomeMark`, :meth:`~music21.tempo.TempoIndication.getSoundingMetronomeMark`

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

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


MetricModulation
----------------

Inherits from: :class:`~music21.tempo.TempoIndication`, :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: 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 :class:`~music21.tempo.TempoIndication`: :attr:`~music21.tempo.TempoIndication.classSortOrder`

        Attributes inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.isSpanner`, :attr:`~music21.base.Music21Object.isStream`, :attr:`~music21.base.Music21Object.isVariant`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.groups`, :attr:`~music21.base.Music21Object.id`

    **MetricModulation** **properties**

        .. attribute:: newMetronome

            Get or set the the right :class:`~music21.tempo.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




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




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



        .. attribute:: oldMetronome

            Get or set the the left :class:`~music21.tempo.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




        .. attribute:: 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 :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.duration`, :attr:`~music21.base.Music21Object.isGrace`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`, :attr:`~music21.base.Music21Object.seconds`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **MetricModulation** **methods**

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




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



        .. method:: 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 :class:`~music21.tempo.TempoIndication`: :meth:`~music21.tempo.TempoIndication.getPreviousMetronomeMark`, :meth:`~music21.tempo.TempoIndication.getSoundingMetronomeMark`

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

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


TempoIndication
---------------

Inherits from: :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

.. class:: TempoIndication()

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



    **TempoIndication** **attributes**

        .. attribute:: 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 :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.isSpanner`, :attr:`~music21.base.Music21Object.isStream`, :attr:`~music21.base.Music21Object.isVariant`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.groups`, :attr:`~music21.base.Music21Object.id`

    **TempoIndication** **properties**

        Properties inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.duration`, :attr:`~music21.base.Music21Object.isGrace`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`, :attr:`~music21.base.Music21Object.seconds`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **TempoIndication** **methods**

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



        .. method:: getSoundingMetronomeMark(found=None)

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



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

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


