.. _moduleDuration:

music21.duration
================

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

.. module:: music21.duration

The duration module contains
:class:`~music21.duration.Duration` objects (among other objects and
functions).  Duration objects are a fundamental component of
:class:`~music21.note.Note` and all Music21Objects, such as
:class:`~music21.meter.TimeSignature` objects.


Containers such as :class:`~music21.stream.Stream` and :class:`~music21.stream.Score`
also have durations which are equal to the position of the ending of the
last object in the Stream.


Music21 Durations are almost always measured in QuarterNotes, so an
eighth note has a duration of 0.5.  Different Duration-like objects
support objects such as grace notes which take no duration on the
page, have a short (but real) duration when played, and have a
duration-type representation when performed.

Example usage:



>>> from music21 import *
>>> d = duration.Duration()
>>> d.quarterLength = 0.5
>>> d.type
'eighth'
>>> d.type = 'whole'
>>> d.quarterLength
4.0
>>> d.quarterLength = 0.166666666
>>> d.type
'16th'
>>> d.tuplets[0].numberNotesActual
3
>>> d.tuplets[0].numberNotesNormal
2





.. function:: convertQuarterLengthToType(qLen)

    Return a type if there exists a type that is exactly equal to the duration of the provided quarterLength. Similar to quarterLengthToClosestType() but this function only returns exact matches.



    >>> from music21 import *
    >>> duration.convertQuarterLengthToType(2)
    'half'
    >>> duration.convertQuarterLengthToType(0.125)
    '32nd'
    >>> duration.convertQuarterLengthToType(0.33333)
    Traceback (most recent call last):
    DurationException: cannot convert quarterLength 0.33333 exactly to type



.. function:: convertTypeToNumber(dType)

    Convert a duration type string (`dType`) to a numerical scalar representation that shows
    how many of that duration type fits within a whole note.



    >>> from music21 import *
    >>> duration.convertTypeToNumber('quarter')
    4
    >>> duration.convertTypeToNumber('half')
    2
    >>> duration.convertTypeToNumber('1024th')
    1024
    >>> duration.convertTypeToNumber('maxima')
    0.125



.. function:: convertTypeToQuarterLength(dType, dots=0, tuplets=[], dotGroups=[])


    Given a rhythm type (`dType`), number of dots (`dots`), an optional list of
    Tuplet objects (`tuplets`), and a (very) optional list of
    Medieval dot groups (`dotGroups`), return the equivalent quarter length.



    >>> from music21 import *
    >>> duration.convertTypeToQuarterLength('whole')
    4.0
    >>> duration.convertTypeToQuarterLength('16th')
    0.25
    >>> duration.convertTypeToQuarterLength('quarter', 2)
    1.75




    >>> tup = duration.Tuplet(numberNotesActual = 5, numberNotesNormal = 4)
    >>> duration.convertTypeToQuarterLength('quarter', 0, [tup])
    0.8...




    >>> tup = duration.Tuplet(numberNotesActual = 3, numberNotesNormal = 4)
    >>> duration.convertTypeToQuarterLength('quarter', 0, [tup])
    1.333333...


    Also can handle those rare medieval dot groups
    (such as dotted-dotted half notes that take a full measure of 9/8.
    Conceptually, these are dotted-(dotted-half) notes.  See
    trecento.trecentoCadence for more information
    ).


    >>> duration.convertTypeToQuarterLength('half', dots = 1, dotGroups = [1,1])
    4.5



.. function:: dottedMatch(qLen, maxDots=4)

    Given a quarterLength, determine if there is a dotted
    (or non-dotted) type that exactly matches. Returns a pair of
    (numDots, type) or (False, False) if no exact matches are found.

    Returns a maximum of four dots by default.



    >>> from music21 import *
    >>> duration.dottedMatch(3.0)
    (1, 'half')
    >>> duration.dottedMatch(1.75)
    (2, 'quarter')

    This value is not equal to any dotted note length



    >>> duration.dottedMatch(1.6)
    (False, False)

    maxDots can be lowered for certain searches



    >>> duration.dottedMatch(1.875)
    (3, 'quarter')
    >>> duration.dottedMatch(1.875, 2)
    (False, False)
    ⁠ 
    >>> duration.dottedMatch(0.00001, 2)
    (False, False)




.. function:: musicXMLTypeToType(value)

    Convert a MusicXML type to an music21 type.



    >>> from music21 import *
    >>> duration.musicXMLTypeToType('long')
    'longa'
    >>> duration.musicXMLTypeToType('quarter')
    'quarter'
    >>> duration.musicXMLTypeToType(None)
    Traceback (most recent call last):
    DurationException...



.. function:: nextLargerType(durType)


    Given a type (such as 16th or quarter), return the next larger type.



    >>> from music21 import *
    >>> duration.nextLargerType("16th")
    'eighth'
    >>> duration.nextLargerType("whole")
    'breve'
    >>> duration.nextLargerType("duplex-maxima")
    'unexpressible'



.. function:: nextSmallerType(durType)


    Given a type (such as 16th or quarter), return the next smaller type.



    >>> from music21 import *
    >>> duration.nextSmallerType("16th")
    '32nd'
    >>> duration.nextSmallerType("whole")
    'half'
    >>> duration.nextSmallerType("1024th")
    'unexpressible'



.. function:: partitionQuarterLength(qLen, qLenDiv=4)


    Given a `qLen` (quarterLength) and a `qLenDiv`, that is, a base quarterLength to divide the `qLen` into
    (default = 4; i.e., into whole notes), returns a list of Durations that
    partition the given quarterLength so that there is no leftovers.

    This is a useful tool for partitioning a duration by Measures (i.e., take a long Duration and
    make it fit within several measures) or by beat groups.

    Here is a Little demonstration function that will show how we can use partitionQuarterLength:


    >>> from music21 import *
    >>> def pql(qLen, qLenDiv):
    ...    partitionList = duration.partitionQuarterLength(qLen, qLenDiv)
    ...    for dur in partitionList:
    ...        print(duration.unitSpec(dur))


    Divide 2.5 quarters worth of time into eighth notes.


    >>> pql(2.5,.5)
    (0.5, 'eighth', 0, None, None, None)
    (0.5, 'eighth', 0, None, None, None)
    (0.5, 'eighth', 0, None, None, None)
    (0.5, 'eighth', 0, None, None, None)
    (0.5, 'eighth', 0, None, None, None)


    Divide 5 qLen into 2.5 qLen bundles (i.e., 5/8 time)


    >>> pql(5, 2.5)
    (2.0, 'half', 0, None, None, None)
    (0.5, 'eighth', 0, None, None, None)
    (2.0, 'half', 0, None, None, None)
    (0.5, 'eighth', 0, None, None, None)


    Divide 5.25 qLen into dotted halves


    >>> pql(5.25,3)
    (3.0, 'half', 1, None, None, None)
    (2.0, 'half', 0, None, None, None)
    (0.25, '16th', 0, None, None, None)


    Divide 1.33333 qLen into triplet eighths:


    >>> pql(4.0/3.0, 1.0/3.0)
    (0.333..., 'eighth', 0, 3, 2, 'eighth')
    (0.333..., 'eighth', 0, 3, 2, 'eighth')
    (0.333..., 'eighth', 0, 3, 2, 'eighth')
    (0.333..., 'eighth', 0, 3, 2, 'eighth')

    Divide 1.5 into triplet eighths
    >>> pql(1.5,.33333333333333)
    (0.333..., 'eighth', 0, 3, 2, 'eighth')
    (0.333..., 'eighth', 0, 3, 2, 'eighth')
    (0.333..., 'eighth', 0, 3, 2, 'eighth')
    (0.333..., 'eighth', 0, 3, 2, 'eighth')
    (0.1666..., '16th', 0, 3, 2, '16th')

    There is no problem if the division unit is larger then the source duration, it
    just will not be totally filled.


    >>> pql(1.5, 4)
    (1.5, 'quarter', 1, None, None, None)



.. function:: quarterLengthToClosestType(qLen)


    Returns a two-unit tuple consisting of

    1. The type string ("quarter") that is smaller than or equal to the quarterLength of provided.

    2. Boolean, True or False, whether the conversion was exact.



    >>> from music21 import *
    >>> duration.quarterLengthToClosestType(.5)
    ('eighth', True)
    >>> duration.quarterLengthToClosestType(.75)
    ('eighth', False)
    >>> duration.quarterLengthToClosestType(1.8)
    ('quarter', False)



.. function:: quarterLengthToDurations(qLen, link=True)


    Returns a List of new Duration Units given a quarter length.

    For many simple quarterLengths, the list will have only a
    single element.  However, for more complex durations, the list
    could contain several durations (presumably to be tied to each other).

    (All quarterLengths can, technically, be notated as a single unit
    given a complex enough tuplet, but we don't like doing that).

    This is mainly a utility function. Much faster for many purposes
    is something like::

       d = duration.Duration()
       d.quarterLength = 251.231312

    and then let Duration automatically create Duration Components as necessary.

    These examples use unitSpec() to get a concise summary of the contents



    >>> from music21 import *
    >>> duration.unitSpec(duration.quarterLengthToDurations(2))
    [(2.0, 'half', 0, None, None, None)]

    Dots are supported



    >>> duration.unitSpec(duration.quarterLengthToDurations(3))
    [(3.0, 'half', 1, None, None, None)]
    >>> duration.unitSpec(duration.quarterLengthToDurations(6.0))
    [(6.0, 'whole', 1, None, None, None)]

    Double and triple dotted half note.



    >>> duration.unitSpec(duration.quarterLengthToDurations(3.5))
    [(3.5, 'half', 2, None, None, None)]
    >>> duration.unitSpec(duration.quarterLengthToDurations(3.75))
    [(3.75, 'half', 3, None, None, None)]

    A triplet quarter note, lasting .6666 qLen
    Or, a quarter that is 1/3 of a half.
    Or, a quarter that is 2/3 of a quarter.



    >>> duration.unitSpec(duration.quarterLengthToDurations(2.0/3.0))
    [(0.666..., 'quarter', 0, 3, 2, 'quarter')]

    A triplet eighth note, where 3 eights are in the place of 2.
    Or, an eighth that is 1/3 of a quarter
    Or, an eighth that is 2/3 of eighth



    >>> post = duration.unitSpec(duration.quarterLengthToDurations(.3333333))
    >>> common.almostEquals(post[0][0], .3333333)
    True
    >>> post[0][1:]
    ('eighth', 0, 3, 2, 'eighth')

    A half that is 1/3 of a whole, or a triplet half note.
    Or, a half that is 2/3 of a half



    >>> duration.unitSpec(duration.quarterLengthToDurations(4.0/3.0))
    [(1.33..., 'half', 0, 3, 2, 'half')]

    A sixteenth that is 1/5 of a quarter
    Or, a sixteenth that is 4/5ths of a 16th



    >>> duration.unitSpec(duration.quarterLengthToDurations(1.0/5.0))
    [(0.2..., '16th', 0, 5, 4, '16th')]

    A 16th that is  1/7th of a quarter
    Or, a 16th that is 4/7 of a 16th



    >>> duration.unitSpec(duration.quarterLengthToDurations(1.0/7.0))
    [(0.142857..., '16th', 0, 7, 4, '16th')]

    A 4/7ths of a whole note, or
    A quarter that is 4/7th of of a quarter



    >>> duration.unitSpec(duration.quarterLengthToDurations(4.0/7.0))
    [(0.571428..., 'quarter', 0, 7, 4, 'quarter')]

    If a duration is not containable in a single unit, this method
    will break off the largest type that fits within this type
    and recurse, adding as my units as necessary.



    >>> duration.unitSpec(duration.quarterLengthToDurations(2.5))
    [(2.0, 'half', 0, None, None, None), (0.5, 'eighth', 0, None, None, None)]
    ⁠ 
    >>> duration.unitSpec(duration.quarterLengthToDurations(2.3333333))
    [(2.0, 'half', 0, None, None, None), (0.333..., 'eighth', 0, 3, 2, 'eighth')]



    >>> duration.unitSpec(duration.quarterLengthToDurations(1.0/6.0))
    [(0.1666..., '16th', 0, 3, 2, '16th')]
    ⁠ 
    >>> duration.quarterLengthToDurations(.18333333333333)
    [<music21.duration.DurationUnit 0.125>, <music21.duration.DurationUnit 0.03125>, <music21.duration.DurationUnit 0.015625>, <music21.duration.DurationUnit 0.0078125>]



    >>> duration.quarterLengthToDurations(0.0)
    [<music21.duration.ZeroDuration>]




.. function:: quarterLengthToTuplet(qLen, maxToReturn=4)


    Returns a list of possible Tuplet objects for a
    given `qLen` (quarterLength). As there may be more than one
    possible solution, the `maxToReturn` integer specifies the
    maximum number of values returned.

    Searches for numerators specified in duration.defaultTupletNumerators
    (3, 5, 7, 11, 13). Does not return dotted tuplets, nor nested tuplets.

    Note that 4:3 tuplets won't be found, but will be found as dotted notes
    by dottedMatch.



    >>> from music21 import *
    >>> duration.quarterLengthToTuplet(.33333333)
    [<music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/1/quarter>]

    By specifying only 1 `maxToReturn`, the a single-length list containing the Tuplet with the smallest type will be returned.



    >>> duration.quarterLengthToTuplet(.3333333, 1)
    [<music21.duration.Tuplet 3/2/eighth>]
    ⁠ 
    >>> duration.quarterLengthToTuplet(.20)
    [<music21.duration.Tuplet 5/4/16th>, <music21.duration.Tuplet 5/2/eighth>, <music21.duration.Tuplet 5/1/quarter>]



    >>> c = duration.quarterLengthToTuplet(.3333333, 1)[0]
    >>> c.tupletMultiplier()
    0.6666...



.. function:: typeToMusicXMLType(value)

    Convert a music21 type to a MusicXML type.



    >>> from music21 import *
    >>> duration.typeToMusicXMLType('longa')
    'long'
    >>> duration.typeToMusicXMLType('quarter')
    'quarter'



.. function:: unitSpec(durationObjectOrObjects)


    A simple data representation of most Duration objects. Processes a single Duration or a List of Durations, returning a single or list of unitSpecs.

    A unitSpec is a tuple of qLen, durType, dots, tupleNumerator, tupletDenominator, and tupletType (assuming top and bottom tuplets are the same).

    This function does not deal with nested tuplets, etc.



    >>> from music21 import *
    >>> aDur = duration.Duration()
    >>> aDur.quarterLength = 3
    >>> duration.unitSpec(aDur)
    (3.0, 'half', 1, None, None, None)
    ⁠ 
    >>> bDur = duration.Duration()
    >>> bDur.quarterLength = 1.125
    >>> duration.unitSpec(bDur)
    (1.125, 'complex', None, None, None, None)



    >>> cDur = duration.Duration()
    >>> cDur.quarterLength = 0.3333333
    >>> duration.unitSpec(cDur)
    (0.33333..., 'eighth', 0, 3, 2, 'eighth')
    ⁠ 
    >>> duration.unitSpec([aDur, bDur, cDur])
    [(3.0, 'half', 1, None, None, None), (1.125, 'complex', None, None, None, None), (0.333333..., 'eighth', 0, 3, 2, 'eighth')]



.. function:: updateTupletType(durationList)

    Given a list of Durations or DurationUnits,
    examine each Duration, and each component, and set Tuplet type to
    start or stop, as necessary.



    >>> from music21 import *
    >>> a = duration.Duration(); a.quarterLength = .33333
    >>> b = duration.Duration(); b.quarterLength = .33333
    >>> c = duration.DurationUnit(); c.quarterLength = .33333
    >>> d = duration.Duration(); d.quarterLength = 2
    >>> e = duration.Duration(); e.quarterLength = .33333
    >>> f = duration.DurationUnit(); f.quarterLength = .33333
    >>> g = duration.Duration(); g.quarterLength = .33333
    ⁠ 
    >>> a.tuplets[0].type == None
    True
    >>> duration.updateTupletType([a, b, c, d, e, f, g])
    >>> a.tuplets[0].type == 'start'
    True
    >>> b.tuplets[0].type == None
    True
    >>> c.tuplets[0].type == 'stop'
    True
    >>> e.tuplets[0].type == 'start'
    True
    >>> g.tuplets[0].type == 'stop'
    True



Duration
--------

Inherits from: :class:`~music21.duration.DurationCommon`, :class:`~music21.base.JSONSerializer`

.. class:: Duration(*arguments, **keywords)


    Durations are one of the most important objects in music21. A Duration
    represents a span of musical time measurable in terms of quarter notes
    (or in advanced usage other units). For instance, "57 quarter notes"
    or "dotted half tied to quintuplet sixteenth note" or simply "quarter note."


    A Duration object is made of one or more DurationUnit objects
    stored on the `components` list.


    Multiple DurationUnits in a single Duration may be used
    to express tied notes, or may be used to split duration
    across barlines or beam groups. Some Duration objects are
    not expressible as a single notation unit.


    Duration objects are not Music21Objects. Duration objects share
    many properties and attributes with DurationUnit objects,
    but Duration is not a subclass of DurationUnit.


    If a single argument is passed to Duration() and it is
    a string, then it is assumed to be a type, such as
    'half', 'eighth', or '16th', etc.  If that single argument
    is a number then it is assumed to be a quarterLength (2 for
    half notes, .5 for eighth notes, .75 for dotted eighth notes,
    .333333333 for a triplet eighth, etc.).  If one or more
    named arguments are passed then the Duration() is configured
    according to those arguments.  Supported arguments are
    'type', 'dots', or 'components' (a list of :class:`music21.duration.DurationUnit` objects),


    Example 1: a triplet eighth configured by quarterLength:




    >>> from music21 import *
    >>> d = duration.Duration(.333333333)
    >>> d.type
    'eighth'
    >>> d.tuplets
    (<music21.duration.Tuplet 3/2/eighth>,)


    Example 2: A Duration made up of multiple :class:`music21.duration.DurationUnit`
    objects
    automatically configured by the specified quarterLength.




    >>> d2 = duration.Duration(.625)
    >>> d2.type
    'complex'
    >>> d2.components
    [<music21.duration.DurationUnit 0.5>, <music21.duration.DurationUnit 0.125>]



    Example 3: A Duration configured by keywords.




    >>> d3 = duration.Duration(type = 'half', dots = 2)
    >>> d3.quarterLength
    3.5





    First positional argument is assumed to be type string or a quarterLength.



    **Duration** **attributes**

        Attributes without Documentation: `isGrace`, `linkage`

    **Duration** **properties**

        .. attribute:: components

            No documentation.


        .. attribute:: dotGroups


            See the explanation under :class:`~music21.duration.DurationUnit` about
            what dotGroups (medieval dotted-dotted notes are).  In a complex
            duration, only the dotGroups of the first component matter




            >>> from music21 import duration
            >>> a = duration.Duration()
            >>> a.type = 'half'
            >>> a.dotGroups = [1,1]
            >>> a.quarterLength
            4.5




        .. attribute:: dots


            Returns the number of dots in the Duration
            if it is a simple Duration.  Otherwise raises error.



        .. attribute:: fullName

            Return the most complete representation of this Duration, providing dots, type, tuplet, and quarter length representation.



            >>> from music21 import *
            >>> d = duration.Duration(quarterLength=1.5)
            >>> d.fullName
            'Dotted Quarter'
            ⁠ 
            >>> d = duration.Duration(type='half')
            >>> d.fullName
            'Half'



            >>> d = duration.Duration(quarterLength=1.25)
            >>> d.fullName
            'Quarter tied to 16th (1.25 total QL)'
            >>> d.addDurationUnit(duration.DurationUnit(.3333333))
            >>> d.fullName
            'Quarter tied to 16th tied to Eighth Triplet (0.33QL) (1.58 total QL)'




            >>> d = duration.Duration(quarterLength=0.333333)
            >>> d.fullName
            'Eighth Triplet (0.33QL)'
            ⁠ 
            >>> d = duration.Duration(quarterLength=0.666666)
            >>> d.fullName
            'Quarter Triplet (0.67QL)'



            >>> d = duration.Duration(quarterLength=0.571428)
            >>> d.fullName
            'Quarter Tuplet of 7/4ths (0.57QL)'
            ⁠ 
            >>> d = duration.Duration(quarterLength=0)
            >>> d.fullName
            'Zero Duration (0 total QL)'



        .. attribute:: isComplex


            Returns True if this Duration has more than one DurationUnit object on the `component` list.
            That is to say if it's a single Duration that need multiple tied noteheads to represent.




            >>> from music21 import *
            >>> aDur = duration.Duration()
            >>> aDur.quarterLength = 1.375
            >>> aDur.isComplex
            True
            >>> len(aDur.components)
            2
            >>> aDur.components
            [<music21.duration.DurationUnit 1.0>, <music21.duration.DurationUnit 0.375>]




            >>> bDur = duration.Duration()
            >>> bDur.quarterLength = 1.6666666
            >>> bDur.isComplex
            True
            >>> len(bDur.components)
            2
            >>> bDur.components
            [<music21.duration.DurationUnit 1.0>, <music21.duration.DurationUnit 0.6666...>]





            >>> cDur = duration.Duration()
            >>> cDur.quarterLength = .25
            >>> cDur.isComplex
            False
            >>> len(cDur.components)
            1



        .. attribute:: isLinked


            Return a boolean describing this duration is linked or not.
            The `isLinked` of the first component in a complex duration
            determines the link status for the entire Duration




            >>> from music21 import *
            >>> d = duration.Duration(2.0)
            >>> d.type
            'half'
            >>> d.quarterLength
            2.0
            >>> d.isLinked
            True
            >>> d.unlink()
            >>> d.quarterLength = 4.0
            >>> d.type
            'half'
            >>> d.isLinked
            False



        .. attribute:: midi


            Get or set a duration value in MIDI ticks.
            MIDI duration values are measured in ticks per quarter.
            The music21 default ticks per quarter setting is set in
            defaults.py (1024 by default).




            >>> from music21 import *
            >>> d = duration.Duration()
            >>> d.midi = 1024
            >>> d.type
            'quarter'
            >>> d.type = '16th'
            >>> d.quarterLength
            0.25
            >>> d.midi
            256


            More complex rhythms can also be set automatically:




            >>> d2 = duration.Duration()
            >>> d2.midi = 1200
            >>> d2.type
            'complex'
            >>> d2.quarterLength
            1.171875
            >>> d2.components
            [<music21.duration.DurationUnit 1.0>, <music21.duration.DurationUnit 0.125>, <music21.duration.DurationUnit 0.046875>]
            >>> d2.components[2].type
            '128th'
            >>> d2.components[2].dots
            1



        .. attribute:: musicxml

            Return a complete MusicXML string with defaults.



        .. attribute:: ordinal

            Get the ordinal value of the Duration.



            >>> from music21 import *
            >>> d = duration.Duration()
            >>> d.quarterLength = 2.0
            >>> d.ordinal
            5




        .. attribute:: quarterLength


            Returns the quarter note length or Sets the quarter note length to the specified value.


            Currently (if the value is different from what is already stored)
            this wipes out any existing components, not preserving
            their type.  So if you've set up Duration(1.5) as 3-eighth notes,
            setting Duration to 1.75 will NOT dot the last eighth note, but
            instead give you a single double-dotted half note.




            >>> from music21 import *
            >>> a = duration.Duration()
            >>> a.quarterLength = 3.5
            >>> a.quarterLength
            3.5
            >>> for thisUnit in a.components:
            ...    print(unitSpec(thisUnit))
            (3.5, 'half', 2, None, None, None)
            ⁠ 
            >>> a.quarterLength = 2.5
            >>> a.quarterLength
            2.5
            >>> for thisUnit in a.components:
            ...    print(unitSpec(thisUnit))
            (2.0, 'half', 0, None, None, None)
            (0.5, 'eighth', 0, None, None, None)


            Note that integer values of quarter lengths get silently converted to floats:



            >>> b = duration.Duration()
            >>> b.quarterLength = 5
            >>> b.quarterLength
            5.0
            >>> b.type  # complex because 5qL cannot be expressed as a single note.
            'complex'





        .. attribute:: tuplets


            When there are more than one component, each component may have its
            own tuplet.



        .. attribute:: type


            Get or set the type of the Duration.



        Properties inherited from :class:`~music21.duration.DurationCommon`: :attr:`~music21.duration.DurationCommon.classes`

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

    **Duration** **methods**

        .. method:: addDurationUnit(dur, link=True)


            Add a DurationUnit or a Duration's components to this Duration.
            Does not simplify the Duration.  For instance, adding two
            quarter notes results in two tied quarter notes, not one half note.
            See `consolidate` below for more info on how to do that.




            >>> from music21 import *
            >>> a = duration.Duration('quarter')
            >>> b = duration.Duration('quarter')
            >>> a.addDurationUnit(b)
            >>> a.quarterLength
            2.0
            >>> a.type
            'complex'



        .. method:: appendTuplet(newTuplet)

            No documentation.


        .. method:: augmentOrDiminish(amountToScale, retainComponents=False, inPlace=True)


            Given a number greater than zero,
            multiplies the current quarterLength of the
            duration by the number and resets the components
            for the duration (by default).  Or if inPlace is
            set to False, returns a new duration that has
            the new length.


            Note that the default for inPlace is the opposite
            of what it is for augmentOrDiminish on a Stream.
            This is done purposely to reflect the most common
            usage.




            >>> from music21 import *
            >>> aDur = duration.Duration()
            >>> aDur.quarterLength = 1.5 # dotted quarter
            >>> aDur.augmentOrDiminish(2)
            >>> aDur.quarterLength
            3.0
            >>> aDur.type
            'half'
            >>> aDur.dots
            1


            A complex duration that cannot be expressed as a single notehead (component)




            >>> bDur = duration.Duration()
            >>> bDur.quarterLength = 2.125 # requires components
            >>> len(bDur.components)
            2
            >>> cDur = bDur.augmentOrDiminish(2, retainComponents=True, inPlace=False)
            >>> cDur.quarterLength
            4.25
            >>> cDur.components
            [<music21.duration.DurationUnit 4.0>, <music21.duration.DurationUnit 0.25>]
            ⁠ 
            >>> dDur = bDur.augmentOrDiminish(2, retainComponents=False, inPlace=False)
            >>> dDur.components
            [<music21.duration.DurationUnit 4.0>, <music21.duration.DurationUnit 0.25>]





        .. method:: clear()


            Permit all components to be removed.
            (It is not clear yet if this is needed)



            >>> from music21 import *
            >>> a = duration.Duration()
            >>> a.quarterLength = 4
            >>> a.type
            'whole'
            >>> a.clear()
            >>> a.quarterLength
            0.0
            >>> a.type
            'zero'



        .. method:: componentIndexAtQtrPosition(quarterPosition)

            returns the index number of the duration component sounding at
            the given quarter position.

            Note that for 0 and the last value, the object is returned.



            >>> from music21 import *
            >>> components = []
            >>> components.append(duration.Duration('quarter'))
            >>> components.append(duration.Duration('quarter'))
            >>> components.append(duration.Duration('quarter'))
            ⁠ 
            >>> a = duration.Duration()
            >>> a.components = components
            >>> a.updateQuarterLength()
            >>> a.quarterLength
            3.0
            >>> a.componentIndexAtQtrPosition(.5)
            0
            >>> a.componentIndexAtQtrPosition(1.5)
            1
            >>> a.componentIndexAtQtrPosition(2.5)
            2


            this is odd behavior:

            e.g. given d1, d2, d3 as 3 quarter notes and
            self.components = [d1, d2, d3]

            then

            self.componentIndexAtQtrPosition(1.5) == d2
            self.componentIndexAtQtrPosition(2.0) == d3
            self.componentIndexAtQtrPosition(2.5) == d3



        .. method:: componentStartTime(componentIndex)


            For a valid component index value, this returns the quarter note offset
            at which that component would start.


            This does not handle fractional arguments.




            >>> from music21 import *
            >>> components = []
            >>> components.append(duration.Duration('quarter'))
            >>> components.append(duration.Duration('quarter'))
            >>> components.append(duration.Duration('quarter'))
            ⁠ 
            >>> a = duration.Duration()
            >>> a.components = components
            >>> a.updateQuarterLength()
            >>> a.quarterLength
            3.0
            >>> a.componentStartTime(0)
            0.0
            >>> a.componentStartTime(1)
            1.0



        .. method:: consolidate()


            Given a Duration with multiple components, consolidate into a single
            Duration. This can only be based on quarterLength; this is
            destructive: information is lost from components.


            This cannot be done for all Durations, as DurationUnits cannot express all durations




            >>> from music21 import *
            >>> a = duration.Duration()
            >>> a.fill(['quarter', 'half', 'quarter'])
            >>> a.quarterLength
            4.0
            >>> len(a.components)
            3
            >>> a.consolidate()
            >>> a.quarterLength
            4.0
            >>> len(a.components)
            1


            But it gains a type!




            >>> a.type
            'whole'



        .. method:: expand(qLenDiv=4)


            Make a duration notatable by partitioning it into smaller
            units (default qLenDiv = 4 (whole note)).  uses partitionQuarterLength



        .. method:: fill(quarterLengthList=['quarter', 'half', 'quarter'])

            Utility method for testing; a quick way to fill components. This will
            remove any exisiting values.



        .. method:: getGraceDuration(appogiatura=False)

            Return a deep copy of this Duration as a GraceDuration instance with the same types.



            >>> from music21 import *
            >>> d = duration.Duration(1.25)
            >>> gd = d.getGraceDuration()
            >>> gd.quarterLength
            0.0
            >>> [(x.quarterLength, x.type) for x in gd.components]
            [(0.0, 'quarter'), (0.0, '16th')]
            >>> d.quarterLength
            1.25



        .. method:: link()

            Set all components to be linked



        .. method:: setQuarterLengthUnlinked(value)

            Set the quarter note length to the specified value.



        .. method:: setTypeUnlinked(value)

            Make this Duration unlinked, and set the type. Quarter note length will not be adjusted.



        .. method:: show(format='musicxml')


            Same as Music21Object.show().



        .. method:: sliceComponentAtPosition(quarterPosition)

            Given a quarter position within a component, divide that
            component into two components.




            >>> from music21 import *
            >>> a = duration.Duration()
            >>> a.clear() # need to remove default
            >>> components = []
            ⁠ 
            >>> a.addDurationUnit(duration.Duration('quarter'))
            >>> a.addDurationUnit(duration.Duration('quarter'))
            >>> a.addDurationUnit(duration.Duration('quarter'))



            >>> a.quarterLength
            3.0
            >>> a.sliceComponentAtPosition(.5)
            >>> a.quarterLength
            3.0
            >>> len(a.components)
            4
            >>> a.components[0].type
            'eighth'
            >>> a.components[1].type
            'eighth'
            >>> a.components[2].type
            'quarter'



        .. method:: splitDotGroups()


            splits a dotGroup-duration (of 1 component) into a new duration of two
            components.  Returns a new duration


            Probably does not handle properly tuplets of dot-groups.  Never seen one, so probably okay.




            >>> from music21 import *
            >>> d1 = duration.Duration(type = 'half')
            >>> d1.dotGroups = [1,1]
            >>> d1.quarterLength
            4.5
            >>> d2 = d1.splitDotGroups()
            >>> d2.components
            [<music21.duration.DurationUnit 3.0>, <music21.duration.DurationUnit 1.5>]
            >>> d2.quarterLength
            4.5



            Here's how a system that does not support dotGroups can still display
            the notes accurately.  N.B. MusicXML does this automatically, so
            no need.




            >>> n1 = note.Note()
            >>> n1.duration = d1
            >>> n1.duration = n1.duration.splitDotGroups()
            >>> n1.duration.components
            [<music21.duration.DurationUnit 3.0>, <music21.duration.DurationUnit 1.5>]
            >>> s1 = stream.Stream()
            >>> s1.append(meter.TimeSignature('9/8'))
            >>> s1.append(n1)
            >>> s1.show('lily.png')



            .. image:: images/duration_splitDotGroups.*




            >>> n2 = note.Note()
            >>> n2.duration.type = 'quarter'
            >>> n2.duration.dotGroups = [1,1]
            >>> n2.quarterLength
            2.25
            >>> n2.show() # generates a dotted-quarter tied to dotted-eighth




        .. method:: unlink()


            Unlink all components allowing the type, dots, etc., to not be the same as the
            normal representation in quarterLength units.



        .. method:: updateQuarterLength()

            Look to components and determine quarter length.



        .. method:: write(fmt='musicxml', fp=None)


            As in Music21Object.write: Writes a file in the given format (musicxml by default)

            A None file path will result in temporary file.



        Methods inherited from :class:`~music21.duration.DurationCommon`: :meth:`~music21.duration.DurationCommon.aggregateTupletRatio`

        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`


Tuplet
------



.. class:: Tuplet(*arguments, **keywords)


    A tuplet object is a representation of a musical tuplet (like a
    triplet).  It expresses a ratio that
    modifies duration values and are stored in Duration objects in
    a "tuple" (immutable list; since there can be nested tuplets) in
    the duration's .tuplets property.


    The primary representation uses two pairs of note numbers and durations.


    The first pair of note numbers and durations describes the representation
    within the tuplet, or the value presented by the context. This is
    called "actual." In a standard 8th note triplet this would be 3, eighth.
    Attributes are `numberNotesActual`, `durationActual`.


    The second pair of note numbers and durations describes the space that would
    have been occupied in a normal context. This is called "normal." In a
    standard 8th note triplet this would be 2, eighth. Attributes
    are `numberNotesNormal`, `durationNormal`.


    If duration values are not provided, the `durationActual` and `durationNormal`
    are assumed to be eighths.


    If only one duration, either `durationActual` or `durationNormal`, is
    provided, both are set to the same value.


    Note that this is a duration modifier, or a generator of ratios to scale
    quarterLength values in Duration objects.





    >>> from music21 import *
    >>> myTup = duration.Tuplet(numberNotesActual = 5, numberNotesNormal = 4)
    >>> print(myTup.tupletMultiplier())
    0.8
    >>> myTup2 = duration.Tuplet(8, 5)
    >>> print(myTup2.tupletMultiplier())
    0.625
    >>> myTup2 = duration.Tuplet(6, 4, "16th")
    >>> print(myTup2.durationActual.type)
    16th
    >>> print(myTup2.tupletMultiplier())
    0.666...


    Tuplets may be frozen, in which case they become immutable. Tuplets
    which are attached to Durations are automatically frozen




    >>> myTup.frozen = True
    >>> myTup.tupletActual = [3, 2]
    Traceback (most recent call last):
    ...
    TupletException: A frozen tuplet (or one attached to a duration) is immutable
    ⁠ 
    >>> myHalf = duration.Duration("half")
    >>> myHalf.appendTuplet(myTup2)
    >>> myTup2.tupletActual = [5, 4]
    Traceback (most recent call last):
    ...
    TupletException: A frozen tuplet (or one attached to a duration) is immutable




    **Tuplet** **attributes**

        .. attribute:: durationActual

            A DurationUnit is a duration notation that (generally) can be notated with a a single notation unit, such as one note head, without a tie.

            DurationUnits are not usually instantiated by users of music21,
            but are used within Duration objects to model the containment of numerous summed components.

            Like Durations, DurationUnits have the option of unlinking the quarterLength
            and its representation on the page. For instance, in 12/16, Brahms sometimes
            used a dotted half note to indicate the length of 11/16th of a note. (see Don
            Byrd's Extreme Notation webpage for more information). Since this duration can
            be expressed by a single graphical unit in Brahms's shorthand, it can be modeled
            by a single DurationUnit of unliked graphical/temporal representation.

            Additional types are needed beyond those in Duration::

                * 'zero' type for zero-length durations
                * 'unexpressible' type for anything that cannot
                  be expressed as a single notation unit, and thus
                  needs a full Duration object (such as 2.5 quarterLengths.)



        .. attribute:: durationNormal

            A DurationUnit is a duration notation that (generally) can be notated with a a single notation unit, such as one note head, without a tie.

            DurationUnits are not usually instantiated by users of music21,
            but are used within Duration objects to model the containment of numerous summed components.

            Like Durations, DurationUnits have the option of unlinking the quarterLength
            and its representation on the page. For instance, in 12/16, Brahms sometimes
            used a dotted half note to indicate the length of 11/16th of a note. (see Don
            Byrd's Extreme Notation webpage for more information). Since this duration can
            be expressed by a single graphical unit in Brahms's shorthand, it can be modeled
            by a single DurationUnit of unliked graphical/temporal representation.

            Additional types are needed beyond those in Duration::

                * 'zero' type for zero-length durations
                * 'unexpressible' type for anything that cannot
                  be expressed as a single notation unit, and thus
                  needs a full Duration object (such as 2.5 quarterLengths.)



        Attributes without Documentation: `frozen`, `tupletActualShow`, `placement`, `numberNotesActual`, `tupletId`, `nestedLevel`, `bracket`, `tupletNormalShow`, `type`, `numberNotesNormal`

    **Tuplet** **properties**

        .. attribute:: fullName

            Return the most complete representation of this tuplet in a readable form.



            >>> from music21 import *
            >>> t = duration.Tuplet(numberNotesActual = 5, numberNotesNormal = 4)
            >>> t.fullName
            'Tuplet of 5/4ths'
            ⁠ 
            >>> t = duration.Tuplet(numberNotesActual = 3, numberNotesNormal = 2)
            >>> t.fullName
            'Triplet'




        .. attribute:: mx

            From this object return both an mxTimeModification object and an mxTuplet object configured for this Triplet.
            mxTuplet needs to be on the Notes mxNotations field



            >>> from music21 import *
            >>> a = duration.Tuplet()
            >>> a.bracket = True
            >>> b, c = a.mx



        .. attribute:: tupletActual

            Get or set a two element list of number notes actual and duration actual.



        .. attribute:: tupletNormal

            Get or set a two element list of number notes actual and duration normal.



    **Tuplet** **methods**

        .. method:: augmentOrDiminish(amountToScale, inPlace=True)


            Given a number greater than zero,
            multiplies the current quarterLength of the
            duration by the number and resets the components
            for the duration (by default).  Or if inPlace is
            set to False, returns a new duration that has
            the new length.


            Note that the default for inPlace is the opposite
            of what it is for augmentOrDiminish on a Stream.
            This is done purposely to reflect the most common
            usage.




            >>> from music21 import *
            >>> a = duration.Tuplet()
            >>> a.setRatio(6,2)
            >>> a.tupletMultiplier()
            0.333...
            >>> a.durationActual
            <music21.duration.DurationUnit 0.5>
            >>> a.augmentOrDiminish(.5)
            >>> a.durationActual
            <music21.duration.DurationUnit 0.25>
            >>> a.tupletMultiplier()
            0.333...



        .. method:: setDurationType(durType)

            Set the Duration for both actual and normal.

            A type string or quarter length can be given.



            >>> from music21 import *
            >>> a = duration.Tuplet()
            >>> a.tupletMultiplier()
            0.666...
            >>> a.totalTupletLength()
            1.0
            >>> a.setDurationType('half')
            >>> a.tupletMultiplier()
            0.6666...
            >>> a.totalTupletLength()
            4.0
            ⁠ 
            >>> a.setDurationType(2)
            >>> a.totalTupletLength()
            4.0
            >>> a.setDurationType(4)
            >>> a.totalTupletLength()
            8.0





        .. method:: setRatio(actual, normal)

            Set the ratio of actual divisions to represented in normal divisions.
            A triplet is 3 actual in the time of 2 normal.



            >>> from music21 import *
            >>> a = duration.Tuplet()
            >>> a.tupletMultiplier()
            0.666...
            >>> a.setRatio(6,2)
            >>> a.tupletMultiplier()
            0.333...

            One way of expressing 6/4-ish triplets without numbers:
            >>> a = duration.Tuplet()
            >>> a.setRatio(3,1)
            >>> a.durationActual = duration.DurationUnit('quarter')
            >>> a.durationNormal = duration.DurationUnit('half')
            >>> a.tupletMultiplier()
            0.666...
            >>> a.totalTupletLength()
            2.0



        .. method:: totalTupletLength()


            The total duration in quarter length of the tuplet as defined, assuming that
            enough notes existed to fill all entire tuplet as defined.

            For instance, 3 quarters in the place of 2 quarters = 2.0
            5 half notes in the place of a 2 dotted half notes = 6.0
            (In the end it's only the denominator that matters)



            >>> from music21 import *
            >>> a = duration.Tuplet()
            >>> a.totalTupletLength()
            1.0
            >>> a.numberNotesActual = 3
            >>> a.durationActual = Duration('half')
            >>> a.numberNotesNormal = 2
            >>> a.durationNormal = Duration('half')
            >>> a.totalTupletLength()
            4.0
            >>> a.setRatio(5,4)
            >>> a.totalTupletLength()
            8.0
            >>> a.setRatio(5,2)
            >>> a.totalTupletLength()
            4.0



        .. method:: tupletMultiplier()

            Get a floating point value by which to scale the duration that
            this Tuplet is associated with.



            >>> from music21 import *
            >>> myTuplet = duration.Tuplet()
            >>> print(round(myTuplet.tupletMultiplier(), 3))
            0.667
            >>> myTuplet.tupletActual = [5, Duration('eighth')]
            >>> myTuplet.numberNotesActual
            5
            >>> myTuplet.durationActual.type
            'eighth'
            >>> print(myTuplet.tupletMultiplier())
            0.4




AppogiaturaDuration
-------------------

Inherits from: :class:`~music21.duration.GraceDuration`, :class:`~music21.duration.Duration`, :class:`~music21.duration.DurationCommon`, :class:`~music21.base.JSONSerializer`

.. class:: AppogiaturaDuration(*arguments, **keywords)



DurationCommon
--------------

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

.. class:: DurationCommon()

    A base class for both Duration and DurationUnit objects.



    **DurationCommon** **properties**

        .. attribute:: classes

            Returns a list containing the names (strings, not objects) of classes that this
            object belongs to -- starting with the object's class name and going up the mro()
            for the object.  Very similar to Perl's @ISA array.  See music21.Music21Object.classes for more details.


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

    **DurationCommon** **methods**

        .. method:: aggregateTupletRatio()

            Return the aggregate tuplet ratio. Say you have 3:2 under a 5:4.  This will give the equivalent
            in non-nested tuplets. Returns a tuple representing the tuplet(!).  In the case of 3:2 under 5:4,
            it will return (15, 8).

            This tuple is needed for MusicXML time-modification among other places



            >>> from music21 import *
            >>> complexDur = duration.Duration('eighth')
            >>> complexDur.appendTuplet(duration.Tuplet())
            >>> complexDur.aggregateTupletRatio()
            (3, 2)


            Nested tuplets are possible...




            >>> tup2 = duration.Tuplet()
            >>> tup2.setRatio(5, 4)
            >>> complexDur.appendTuplet(tup2)
            >>> complexDur.aggregateTupletRatio()
            (15, 8)



        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`


DurationUnit
------------

Inherits from: :class:`~music21.duration.DurationCommon`, :class:`~music21.base.JSONSerializer`

.. class:: DurationUnit(prototype='quarter')

    A DurationUnit is a duration notation that (generally) can be notated with a a single notation unit, such as one note head, without a tie.

    DurationUnits are not usually instantiated by users of music21,
    but are used within Duration objects to model the containment of numerous summed components.

    Like Durations, DurationUnits have the option of unlinking the quarterLength
    and its representation on the page. For instance, in 12/16, Brahms sometimes
    used a dotted half note to indicate the length of 11/16th of a note. (see Don
    Byrd's Extreme Notation webpage for more information). Since this duration can
    be expressed by a single graphical unit in Brahms's shorthand, it can be modeled
    by a single DurationUnit of unliked graphical/temporal representation.

    Additional types are needed beyond those in Duration::

        * 'zero' type for zero-length durations
        * 'unexpressible' type for anything that cannot
          be expressed as a single notation unit, and thus
          needs a full Duration object (such as 2.5 quarterLengths.)



    **DurationUnit** **properties**

        .. attribute:: dotGroups


            _dots is a list (so we can do weird things like dot groups)
            _getDotGroups lets you do the entire list (as a tuple)



            >>> from music21 import *
            >>> d1 = duration.DurationUnit()
            >>> d1.type = 'half'
            >>> d1.dotGroups = [1, 1]  # dotted dotted half
            >>> d1.dots
            1
            >>> d1.dotGroups
            (1, 1)
            >>> d1.quarterLength
            4.5



        .. attribute:: dots


            _dots is a list (so we can do weird things like dot groups)
            Normally we only want the first element.
            So that's what _getDots returns...



        .. attribute:: fullName

            Return the most complete representation of this Duration, providing dots, type, tuplet, and quarter length representation.



            >>> from music21 import *
            >>> d = duration.DurationUnit()
            >>> d.quarterLength = 1.5
            >>> d.fullName
            'Dotted Quarter'
            ⁠ 
            >>> from music21 import *
            >>> d = duration.DurationUnit()
            >>> d.quarterLength = 1.75
            >>> d.fullName
            'Double Dotted Quarter'



            >>> d = duration.DurationUnit()
            >>> d.type = 'half'
            >>> d.fullName
            'Half'




            >>> d = duration.DurationUnit()
            >>> d.type = 'longa'
            >>> d.fullName
            'Imperfect Longa'
            ⁠ 
            >>> d.dots = 1
            >>> d.fullName
            'Perfect Longa'



        .. attribute:: isLinked


            Return a boolean describing this duration is linked or not.s



            >>> from music21 import *
            >>> d = duration.DurationUnit()
            >>> d.isLinked
            True
            >>> d.unlink()
            >>> d.isLinked
            False



        .. attribute:: ordinal


            Converts type to an ordinal number where maxima = 1 and 1024th = 14;  whole = 4 and quarter = 6.
            Based on duration.ordinalTypeFromNum



            >>> from music21 import *
            >>> a = duration.DurationUnit('whole')
            >>> a.ordinal
            4
            >>> b = duration.DurationUnit('maxima')
            >>> b.ordinal
            1
            >>> c = duration.DurationUnit('1024th')
            >>> c.ordinal
            14



        .. attribute:: quarterLength

            Property for getting or setting the quarterLength of a DurationUnit.



            >>> from music21 import *
            >>> a = duration.DurationUnit()
            >>> a.quarterLength = 3
            >>> a.quarterLength
            3.0
            >>> a.type
            'half'
            >>> a.dots
            1
            >>> a.quarterLength = .5
            >>> a.type
            'eighth'
            >>> a.quarterLength = .75
            >>> a.type
            'eighth'
            >>> a.dots
            1
            >>> b = duration.DurationUnit()
            >>> b.quarterLength = 16
            >>> b.type
            'longa'




        .. attribute:: tuplets

            Return a tuple of Tuplet objects


        .. attribute:: type

            Property for getting or setting the type of a DurationUnit.



            >>> from music21 import *
            >>> a = duration.DurationUnit()
            >>> a.quarterLength = 3
            >>> a.type
            'half'
            >>> a.dots
            1
            >>> a.type = 'quarter'
            >>> a.quarterLength
            1.5
            >>> a.type = '16th'
            >>> a.quarterLength
            0.375



        Properties inherited from :class:`~music21.duration.DurationCommon`: :attr:`~music21.duration.DurationCommon.classes`

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

    **DurationUnit** **methods**

        .. method:: appendTuplet(newTuplet)

            No documentation.


        .. method:: augmentOrDiminish(amountToScale, inPlace=True)


            Given a number greater than zero,
            multiplies the current quarterLength of the
            duration by the number and resets the components
            for the duration (by default).  Or if inPlace is
            set to False, returns a new duration that has
            the new length.


            Note that the default for inPlace is the opposite
            of what it is for augmentOrDiminish on a Stream.
            This is done purposely to reflect the most common
            usage.



            >>> from music21 import *
            >>> bDur = duration.DurationUnit('16th')
            >>> bDur.augmentOrDiminish(2)
            >>> bDur.quarterLength
            0.5
            >>> bDur.type
            'eighth'
            >>> bDur.augmentOrDiminish(4)
            >>> bDur.type
            'half'
            >>> bDur.augmentOrDiminish(.125)
            >>> bDur.type
            '16th'
            ⁠ 
            >>> cDur = bDur.augmentOrDiminish(16, inPlace=False)
            >>> cDur, bDur
            (<music21.duration.DurationUnit 4.0>, <music21.duration.DurationUnit 0.25>)



        .. method:: link()

            No documentation.


        .. method:: setTypeFromNum(typeNum)

            No documentation.


        .. method:: unlink()

            No documentation.


        .. method:: updateQuarterLength()


            Updates the quarterLength if _link is True. Called by self._getQuarterLength if _quarterLengthNeedsUpdating is set
            to True.

            To set quarterLength, use self.quarterLength.



            >>> from music21 import *
            >>> bDur = duration.DurationUnit('16th')
            >>> bDur.quarterLength
            0.25
            >>> bDur.unlink()
            >>> bDur.quarterLength = 234
            >>> bDur.quarterLength
            234.0
            >>> bDur.type
            '16th'
            >>> bDur.link() # if linking is restored, type is used to get qLen
            >>> bDur.updateQuarterLength()
            >>> bDur.quarterLength
            0.25



        .. method:: updateType()

            No documentation.


        Methods inherited from :class:`~music21.duration.DurationCommon`: :meth:`~music21.duration.DurationCommon.aggregateTupletRatio`

        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`


GraceDuration
-------------

Inherits from: :class:`~music21.duration.Duration`, :class:`~music21.duration.DurationCommon`, :class:`~music21.base.JSONSerializer`

.. class:: GraceDuration(*arguments, **keywords)

    A Duration that, no matter how it is created, always has a quarter length of zero.

    GraceDuration can be created with an implied quarter length and type; these values are used to configure the duration, but then may not be relevant after instantiation.



    >>> from music21 import *
    >>> gd = duration.GraceDuration(type='half')
    >>> gd.quarterLength
    0.0
    >>> gd.type
    'half'
    ⁠ 
    >>> gd = duration.GraceDuration(.25)
    >>> gd.type
    '16th'
    >>> gd.quarterLength
    0.0
    >>> gd.isLinked
    False



    >>> gd = duration.GraceDuration(1.25)
    >>> gd.type
    'complex'
    >>> gd.quarterLength
    0.0
    >>> [(x.quarterLength, x.type) for x in gd.components]
    [(0.0, 'quarter'), (0.0, '16th')]



    **GraceDuration** **attributes**

        Attributes without Documentation: `isGrace`, `stealTimePrevious`, `stealTimeFollowing`, `makeTime`, `slash`

        Attributes inherited from :class:`~music21.duration.Duration`: :attr:`~music21.duration.Duration.linkage`

    **GraceDuration** **properties**

        Properties inherited from :class:`~music21.duration.Duration`: :attr:`~music21.duration.Duration.components`, :attr:`~music21.duration.Duration.dotGroups`, :attr:`~music21.duration.Duration.dots`, :attr:`~music21.duration.Duration.fullName`, :attr:`~music21.duration.Duration.isComplex`, :attr:`~music21.duration.Duration.isLinked`, :attr:`~music21.duration.Duration.midi`, :attr:`~music21.duration.Duration.musicxml`, :attr:`~music21.duration.Duration.ordinal`, :attr:`~music21.duration.Duration.quarterLength`, :attr:`~music21.duration.Duration.tuplets`, :attr:`~music21.duration.Duration.type`

        Properties inherited from :class:`~music21.duration.DurationCommon`: :attr:`~music21.duration.DurationCommon.classes`

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

    **GraceDuration** **methods**

        Methods inherited from :class:`~music21.duration.Duration`: :meth:`~music21.duration.Duration.addDurationUnit`, :meth:`~music21.duration.Duration.appendTuplet`, :meth:`~music21.duration.Duration.augmentOrDiminish`, :meth:`~music21.duration.Duration.clear`, :meth:`~music21.duration.Duration.componentIndexAtQtrPosition`, :meth:`~music21.duration.Duration.componentStartTime`, :meth:`~music21.duration.Duration.consolidate`, :meth:`~music21.duration.Duration.expand`, :meth:`~music21.duration.Duration.fill`, :meth:`~music21.duration.Duration.getGraceDuration`, :meth:`~music21.duration.Duration.link`, :meth:`~music21.duration.Duration.setQuarterLengthUnlinked`, :meth:`~music21.duration.Duration.setTypeUnlinked`, :meth:`~music21.duration.Duration.show`, :meth:`~music21.duration.Duration.sliceComponentAtPosition`, :meth:`~music21.duration.Duration.splitDotGroups`, :meth:`~music21.duration.Duration.unlink`, :meth:`~music21.duration.Duration.updateQuarterLength`, :meth:`~music21.duration.Duration.write`

        Methods inherited from :class:`~music21.duration.DurationCommon`: :meth:`~music21.duration.DurationCommon.aggregateTupletRatio`

        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`


ZeroDuration
------------

Inherits from: :class:`~music21.duration.DurationUnit`, :class:`~music21.duration.DurationCommon`, :class:`~music21.base.JSONSerializer`

.. class:: ZeroDuration()


    Represents any Music21 element that does not last any length of time.



    **ZeroDuration** **attributes**

        Attributes without Documentation: `isGrace`

    **ZeroDuration** **properties**

        Properties inherited from :class:`~music21.duration.DurationUnit`: :attr:`~music21.duration.DurationUnit.dotGroups`, :attr:`~music21.duration.DurationUnit.dots`, :attr:`~music21.duration.DurationUnit.fullName`, :attr:`~music21.duration.DurationUnit.isLinked`, :attr:`~music21.duration.DurationUnit.ordinal`, :attr:`~music21.duration.DurationUnit.quarterLength`, :attr:`~music21.duration.DurationUnit.tuplets`, :attr:`~music21.duration.DurationUnit.type`

        Properties inherited from :class:`~music21.duration.DurationCommon`: :attr:`~music21.duration.DurationCommon.classes`

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

    **ZeroDuration** **methods**

        Methods inherited from :class:`~music21.duration.DurationUnit`: :meth:`~music21.duration.DurationUnit.appendTuplet`, :meth:`~music21.duration.DurationUnit.augmentOrDiminish`, :meth:`~music21.duration.DurationUnit.link`, :meth:`~music21.duration.DurationUnit.setTypeFromNum`, :meth:`~music21.duration.DurationUnit.unlink`, :meth:`~music21.duration.DurationUnit.updateQuarterLength`, :meth:`~music21.duration.DurationUnit.updateType`

        Methods inherited from :class:`~music21.duration.DurationCommon`: :meth:`~music21.duration.DurationCommon.aggregateTupletRatio`

        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`


