.. _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:: convertTempoAtBeat(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.convertTempoAtBeat(60, 1, 2) # 60 bpm at quarter, going to half
    30.0 
    >>> tempo.convertTempoAtBeat(60, 1, .25) # 60 bpm at quarter, going to 16th
    240.0 
    >>> tempo.convertTempoAtBeat(60, 1.5, 1) # 60 at dotted quarter, get quarter
    90.0 
    >>> tempo.convertTempoAtBeat(60, 1.5, 2) # 60 at dotted quarter, get half
    45.0 
    >>> tempo.convertTempoAtBeat(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. As this object is a Music21Object, it also has a .duration property object. 

    >>> from music21 import *
    >>> a = tempo.MetronomeMark("slow", 40, note.HalfNote())
    >>> a.number
    40 
    >>> a.referent
    <music21.duration.Duration 2.0> 
    >>> a.referent.type
    'half' 
    >>> a.text
    'slow' 
    >>> mm = tempo.MetronomeMark('adagio')
    >>> mm.number
    52 
    >>> mm.numberImplicit
    True 
    >>> tm2 = music21.tempo.MetronomeMark(u"très vite")
    >>> tm2.text.endswith('vite')
    True 
    >>> tm2.number
    144 
    >>> tm2 = music21.tempo.MetronomeMark(number=200)
    >>> tm2.text
    'prestissimo' 
    >>> tm2.referent
    <music21.duration.Duration 1.0> 

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

    **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
            52 
            >>> 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
            52 
            >>> 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 music21 import *
            >>> mm = tempo.MetronomeMark(number=120)
            >>> mm.text == None
            True 
            >>> mm.text = 'medium fast'
            >>> 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.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`

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

    **MetronomeMark** **methods**

        .. 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
            168 
            >>> 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 "moderate"> 

        .. 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.base.Music21Object`: :meth:`~music21.base.Music21Object.searchParentByAttr`, :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.hasSpannerSite`, :meth:`~music21.base.Music21Object.isClassOrSubclass`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.removeNonContainedLocations`, :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")
    >>> tm.text
    'adagio' 

    
    Common marks such as "adagio," "moderato," "molto allegro," etc. 
    get sensible default values.  If not found, uses a default of 90: 

    

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

    **TempoText** **properties**

        .. attribute:: text

            Get or set the text as a string. 

            >>> import music21
            >>> tm = music21.tempo.TempoText("adagio")
            >>> 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.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`

        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
            52 

        .. method:: getTextExpression(numberImplicit=False)

            Return a TextExpression object for this text. 

        .. method:: isValidText(value)

            Return True or False if the supplied text could be used for this TempoText. 

        .. method:: setTextExpression(vale)

            Given a TextExpression, set it in this object. 

        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchParentByAttr`, :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.hasSpannerSite`, :meth:`~music21.base.Music21Object.isClassOrSubclass`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.removeNonContainedLocations`, :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(value=None)

    A class for representing the relationship between two MetronomeMarks. Generally this relationship is one of equality. 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. 

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

    **MetricModulation** **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.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`

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

    **MetricModulation** **methods**

        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.searchParentByAttr`, :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.hasSpannerSite`, :meth:`~music21.base.Music21Object.isClassOrSubclass`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.removeNonContainedLocations`, :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. 


