music21.duration

The duration module contains Duration objects (among other objects and functions). Duration objects are a fundamental component of Note and all Music21Objects, such as TimeSignature objects.

Containers such as Stream and 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 Quarter Notes, 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:

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

Functions

music21.duration.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.

>>> duration.convertQuarterLengthToType(2)
'half'
>>> duration.convertQuarterLengthToType(0.125)
'32nd'
>>> duration.convertQuarterLengthToType(0.33333)
Traceback (most recent call last):
music21.duration.DurationException: cannot convert quarterLength 0.33333 exactly to type
music21.duration.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.

>>> duration.convertTypeToNumber('quarter')
4.0
>>> duration.convertTypeToNumber('half')
2.0
>>> duration.convertTypeToNumber('1024th')
1024.0
>>> duration.convertTypeToNumber('maxima')
0.125
music21.duration.convertTypeToQuarterLength(dType, dots=0, tuplets=None, dotGroups=None)

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.

>>> 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])
Fraction(4, 5)
>>> tup = duration.Tuplet(numberNotesActual = 3, numberNotesNormal = 4)
>>> duration.convertTypeToQuarterLength('quarter', 0, [tup])
Fraction(4, 3)

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

music21.duration.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.

>>> 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)
music21.duration.durationTupleFromQuarterLength(ql=1.0)

Returns a DurationTuple for a given quarter length if the ql can be expressed as a type and number of dots (no tuplets, no complex duration, etc.). If it can’t be expressed, returns an “inexpressible” DurationTuple.

music21.duration.durationTupleFromTypeDots(durType='quarter', dots=0)

Returns a DurationTuple (which knows its quarterLength) for a given type and dots (no tuplets)

>>> dt = duration.durationTupleFromTypeDots('quarter', 0)
>>> dt
DurationTuple(type='quarter', dots=0, quarterLength=1.0)
>>> dt2 = duration.durationTupleFromTypeDots('quarter', 0)
>>> dt is dt2
True
>>> dt = duration.durationTupleFromTypeDots('zero', 0)
>>> dt
DurationTuple(type='zero', dots=0, quarterLength=0.0)
music21.duration.nextLargerType(durType)

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

>>> duration.nextLargerType("16th")
'eighth'
>>> duration.nextLargerType("whole")
'breve'
>>> duration.nextLargerType("duplex-maxima")
Traceback (most recent call last):
music21.duration.DurationException: cannot get the next larger of duplex-maxima
music21.duration.nextSmallerType(durType)

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

>>> duration.nextSmallerType("16th")
'32nd'
>>> duration.nextSmallerType("whole")
'half'
>>> duration.nextSmallerType("1024th")
'2048th'
>>> duration.nextSmallerType("2048th")
Traceback (most recent call last):
music21.duration.DurationException: cannot get the next smaller of 2048th
music21.duration.partitionQuarterLength(qLen, qLenDiv=4)

UNUSED now that .expand() is gone. REMOVE.

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 DurationsUnits that partition the given quarterLength so that there is no leftovers along with a tupletList that applies to each of them.

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:

>>> def pql(qLen, qLenDiv):
...    partitionList, tuplet = duration.partitionQuarterLength(qLen, qLenDiv)
...    for dur in partitionList:
...        print(dur)
...    print(tuplet)

Divide 2.5 quarters worth of time into eighth notes.

>>> duration.partitionQuarterLength(2.5, 0.5)
([DurationTuple(type='eighth', dots=0, quarterLength=0.5), 
  DurationTuple(type='eighth', dots=0, quarterLength=0.5), 
  DurationTuple(type='eighth', dots=0, quarterLength=0.5), 
  DurationTuple(type='eighth', dots=0, quarterLength=0.5), 
  DurationTuple(type='eighth', dots=0, quarterLength=0.5)],
  [None, None, None, None, None])
>>> pql(2.5, 0.5)
DurationTuple(type='eighth', dots=0, quarterLength=0.5)
DurationTuple(type='eighth', dots=0, quarterLength=0.5)
DurationTuple(type='eighth', dots=0, quarterLength=0.5)
DurationTuple(type='eighth', dots=0, quarterLength=0.5)
DurationTuple(type='eighth', dots=0, quarterLength=0.5)
[None, None, None, None, None]

Divide 5 qLen into 2.5 qLen bundles (i.e., 5/8 time) >>> pql(5.0, 2.5) DurationTuple(type=’half’, dots=0, quarterLength=2.0) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=’half’, dots=0, quarterLength=2.0) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) [None, None, None, None]

Divide 5.25 qLen into dotted halves >>> pql(5.25, 3) DurationTuple(type=’half’, dots=1, quarterLength=3.0) DurationTuple(type=’half’, dots=0, quarterLength=2.0) DurationTuple(type=‘16th’, dots=0, quarterLength=0.25) [None, None, None]

Divide 1.33333 qLen into triplet eighths: >>> pql(4.0/3.0, 1.0/3.0) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) [<music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/2/eighth>]

Divide 1.5 into triplet eighths, with a triplet 16th leftover. >>> pql(1.5, 1.0/3) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=’eighth’, dots=0, quarterLength=0.5) DurationTuple(type=‘16th’, dots=0, quarterLength=0.25) [<music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 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) DurationTuple(type=’quarter’, dots=1, quarterLength=1.5) [None]

music21.duration.quarterConversion(qLen)

Returns a 2-element namedtuple of (components, tuplet)

Components is a tuple of DurationTuples (normally one) that add up to the qLen when multiplied by...

Tuplet is a single Tuplet that adjusts all of the components.

(All quarterLengths can, technically, be notated as a single unit given a complex enough tuplet, as a last resort will look up to 199 as a tuplet type).

>>> duration.quarterConversion(2)
QuarterLengthConversion(components=(DurationTuple(type='half', dots=0, quarterLength=2.0),), 
    tuplet=None)
>>> duration.quarterConversion(0.5)
QuarterLengthConversion(components=(DurationTuple(type='eighth', dots=0, quarterLength=0.5),), 
    tuplet=None)

Dots are supported

>>> duration.quarterConversion(3)
QuarterLengthConversion(components=(DurationTuple(type='half', dots=1, quarterLength=3.0),), 
    tuplet=None)
>>> duration.quarterConversion(6.0)
QuarterLengthConversion(components=(DurationTuple(type='whole', dots=1, quarterLength=6.0),), 
    tuplet=None)

Double and triple dotted half note.

>>> duration.quarterConversion(3.5)
QuarterLengthConversion(components=(DurationTuple(type='half', dots=2, quarterLength=3.5),), 
    tuplet=None)
>>> duration.quarterConversion(3.75)
QuarterLengthConversion(components=(DurationTuple(type='half', dots=3, quarterLength=3.75),), 
    tuplet=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.quarterConversion(2.0/3.0)
QuarterLengthConversion(components=(DurationTuple(type='quarter', dots=0, quarterLength=1.0),), 
    tuplet=<music21.duration.Tuplet 3/2/quarter>)
>>> t = duration.quarterConversion(2.0/3.0).tuplet
>>> t
<music21.duration.Tuplet 3/2/quarter>
>>> t.durationActual
DurationTuple(type='quarter', dots=0, quarterLength=1.0)    

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

>>> duration.quarterConversion(1.0/3)
QuarterLengthConversion(components=(DurationTuple(type='eighth', dots=0, quarterLength=0.5),), 
    tuplet=<music21.duration.Tuplet 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.quarterConversion(4.0/3.0)
QuarterLengthConversion(components=(DurationTuple(type='half', dots=0, quarterLength=2.0),), 
    tuplet=<music21.duration.Tuplet 3/2/half>)
>>> duration.quarterConversion(1.0/6.0)
QuarterLengthConversion(components=(DurationTuple(type='16th', dots=0, quarterLength=0.25),), 
    tuplet=<music21.duration.Tuplet 3/2/16th>)

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

>>> duration.quarterConversion(1.0/5.0)
QuarterLengthConversion(components=(DurationTuple(type='16th', dots=0, quarterLength=0.25),), 
    tuplet=<music21.duration.Tuplet 5/4/16th>)

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

>>> duration.quarterConversion(1.0/7.0)
QuarterLengthConversion(components=(DurationTuple(type='16th', dots=0, quarterLength=0.25),), 
    tuplet=<music21.duration.Tuplet 7/4/16th>)

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

>>> duration.quarterConversion(4.0/7.0)
QuarterLengthConversion(components=(DurationTuple(type='quarter', dots=0, quarterLength=1.0),), 
                        tuplet=<music21.duration.Tuplet 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.quarterConversion(2.5)
QuarterLengthConversion(components=(DurationTuple(type='half', dots=0, quarterLength=2.0), 
                                    DurationTuple(type='eighth', dots=0, quarterLength=0.5)), 
                        tuplet=None)

Since tuplets now apply to the entire Duration, expect some odder tuplets for unusual values that should probably be split generally...

>>> duration.quarterConversion(7.0/3)
QuarterLengthConversion(components=(DurationTuple(type='whole', dots=0, quarterLength=4.0),), 
    tuplet=<music21.duration.Tuplet 12/7/16th>)

This is a very close approximation:

>>> duration.quarterConversion(.18333333333333)
QuarterLengthConversion(components=(DurationTuple(type='16th', dots=0, quarterLength=0.25),), 
    tuplet=<music21.duration.Tuplet 15/11/256th>)
>>> duration.quarterConversion(0.0)
QuarterLengthConversion(components=(DurationTuple(type='zero', dots=0, quarterLength=0.0),), 
    tuplet=None)
music21.duration.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.
>>> duration.quarterLengthToClosestType(.5)
('eighth', True)
>>> duration.quarterLengthToClosestType(.75)
('eighth', False)
>>> duration.quarterLengthToClosestType(1.8)
('quarter', False)

Some very very close types will return True for exact conversion...

>>> duration.quarterLengthToClosestType(2.0000000000000001)
('half', True)

Very big durations... are fine:

>>> duration.quarterLengthToClosestType(129.99)
('duplex-maxima', False)

Durations smaller than 2048th note raise a DurationException

>>> qL = duration.typeToDuration['2048th']
>>> qL
0.001953125
>>> qL = qL * .75
>>> duration.quarterLengthToClosestType(qL)
Traceback (most recent call last):
music21.duration.DurationException: Cannot return types smaller than 2048th; 
    qLen was: 0.00146484375
music21.duration.quarterLengthToNonPowerOf2Tuplet(qLen)

Slow, last chance function that returns a tuple of a single tuplet, probably with a non power of 2 denominator (such as 7:6) that represents the quarterLength and the DurationTuple that should be used to express the note.

This could be a double dotted note, but also a tuplet...

>>> duration.quarterLengthToNonPowerOf2Tuplet(7)
(<music21.duration.Tuplet 8/7/quarter>, DurationTuple(type='breve', dots=0, quarterLength=8.0))
>>> duration.quarterLengthToNonPowerOf2Tuplet(7.0/16)
(<music21.duration.Tuplet 8/7/64th>, DurationTuple(type='eighth', dots=0, quarterLength=0.5))
>>> duration.quarterLengthToNonPowerOf2Tuplet(7.0/3)
(<music21.duration.Tuplet 12/7/16th>, DurationTuple(type='whole', dots=0, quarterLength=4.0))

And of course...

>>> duration.quarterLengthToNonPowerOf2Tuplet(1)
(<music21.duration.Tuplet 1/1/quarter>, 
 DurationTuple(type='quarter', dots=0, quarterLength=1.0))
music21.duration.quarterLengthToTuplet(qLen, maxToReturn=4, tupletNumerators=(3, 5, 7, 11, 13))

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.

>>> duration.quarterLengthToTuplet(.33333333)
[<music21.duration.Tuplet 3/2/eighth>, <music21.duration.Tuplet 3/1/quarter>]
>>> duration.quarterLengthToTuplet(.20)
[<music21.duration.Tuplet 5/4/16th>, 
 <music21.duration.Tuplet 5/2/eighth>, 
 <music21.duration.Tuplet 5/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>]
>>> tup = duration.quarterLengthToTuplet(.3333333, 1)[0]
>>> tup.tupletMultiplier()
Fraction(2, 3)
music21.duration.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.

>>> 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', 0, None, None, None)
>>> cDur = duration.Duration()
>>> cDur.quarterLength = 0.3333333
>>> duration.unitSpec(cDur)
(Fraction(1, 3), 'eighth', 0, 3, 2, 'eighth')
>>> duration.unitSpec([aDur, bDur, cDur])
[(3.0, 'half', 1, None, None, None), 
 (1.125, 'complex', 0, None, None, None), 
 (Fraction(1, 3), 'eighth', 0, 3, 2, 'eighth')]

Duration

class music21.duration.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 immutable DurationTuple objects stored on the components list.

Multiple DurationTuples 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.

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’, ‘quarterLength’, or ‘components’.

Example 1: a triplet eighth configured by quarterLength:

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

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

>>> d2 = duration.Duration(.625)
>>> d2.type
'complex'
>>> d2.components
(DurationTuple(type='eighth', dots=0, quarterLength=0.5), 
 DurationTuple(type='32nd', dots=0, quarterLength=0.125))

Example 3: A Duration configured by keywords.

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

Duration bases

Duration read-only properties

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

Duration.fullName

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

>>> 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 1/4 total QL)'
>>> d = duration.Duration(quarterLength=0.333333)
>>> d.fullName
'Eighth Triplet (1/3 QL)'
>>> d = duration.Duration(quarterLength=0.666666)
>>> d.fullName
'Quarter Triplet (2/3 QL)'
>>> d = duration.Duration(quarterLength=0.571428)
>>> d.fullName
'Quarter Tuplet of 7/4ths (4/7 QL)'
>>> d = duration.Duration(quarterLength=0)
>>> d.fullName
'Zero Duration (0 total QL)'
Duration.isComplex

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

>>> aDur = duration.Duration()
>>> aDur.quarterLength = 1.375
>>> aDur.isComplex
True
>>> len(aDur.components)
2
>>> aDur.components
(DurationTuple(type='quarter', dots=0, quarterLength=1.0), 
 DurationTuple(type='16th', dots=1, quarterLength=0.375))
>>> cDur = duration.Duration()
>>> cDur.quarterLength = .25
>>> cDur.isComplex
False
>>> len(cDur.components)
1
Duration.ordinal

Get the ordinal value of the Duration.

>>> d = duration.Duration()
>>> d.quarterLength = 2.0
>>> d.ordinal
5
Duration.quarterLengthNoTuplets

Returns the quarter length of the duration without taking into account triplets.

Does not cache...

Duration read/write properties

Duration.client

A duration’s “client” is the object that holds this duration as a property. It is informed whenever the duration changes.

Duration.components
Duration.dotGroups

Dot groups are medieval dotted-dotted notes (written one above another). For instance a half note with dotGroups = (1,1) represents a dotted half note that is itself dotted. Worth 9 eighth notes (dotted-half tied to dotted-quarter). It is not the same as a double-dotted half note, which is only worth 7 eighth notes.

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

Returns the number of dots in the Duration if it is a simple Duration. Otherwise returns the number of dots on the first component

Previously it could return None if it was not a simple duration which led to some terribly difficult to find errors.

Duration.linked

Gets or sets the Linked property – if linked (default) then type, dots, tuplets are always coherent with quarterLength. If not, then they are separate.

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

>>> a = duration.Duration()
>>> a.quarterLength = 3.5
>>> a.quarterLength
3.5
>>> for thisUnit in a.components:
...    print(duration.unitSpec(thisUnit))
(3.5, 'half', 2, None, None, None)
>>> a.quarterLength = 2.5
>>> a.quarterLength
2.5
>>> for thisUnit in a.components:
...    print(duration.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 (internally opFracs):

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

Float values will be converted to fractions if they are inexpressible exactly as floats:

>>> b = duration.Duration()
>>> b.quarterLength = 1.0/3
>>> b.quarterLength
Fraction(1, 3)
Duration.tuplets

return a tuple of Tuplet objects

Duration.type

Get or set the type of the Duration.

>>> a = duration.Duration()
>>> a.type = 'half'
>>> a.quarterLength
2.0
>>> a.type= '16th'
>>> a.quarterLength
0.25

Duration methods

Duration.addDurationTuple(dur)

Add a DurationTuple 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.

>>> a = duration.Duration('quarter')
>>> b = duration.durationTupleFromTypeDots('quarter', 0)
>>> a.addDurationTuple(b)
>>> a.quarterLength
2.0
>>> a.type
'complex'
Duration.aggregateTupletMultiplier()

Returns the multiple of all the tuplet multipliers as an opFrac.

This method is needed for MusicXML time-modification among other places.

No tuplets...

>>> complexDur = duration.Duration('eighth')
>>> complexDur.aggregateTupletMultiplier()
1.0

With tuplets:

>>> complexDur.appendTuplet(duration.Tuplet())
>>> complexDur.aggregateTupletMultiplier()
Fraction(2, 3)

Nested tuplets are possible...

>>> tup2 = duration.Tuplet()
>>> tup2.setRatio(5, 4)
>>> complexDur.appendTuplet(tup2)
>>> complexDur.aggregateTupletMultiplier()
Fraction(8, 15)
Duration.appendTuplet(newTuplet)
Duration.augmentOrDiminish(amountToScale, retainComponents=False)

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.

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

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

>>> bDur = duration.Duration()
>>> bDur.quarterLength = 2.125 # requires components
>>> bDur.quarterLength
2.125
>>> len(bDur.components)
2
>>> bDur.components
(DurationTuple(type='half', dots=0, quarterLength=2.0), 
 DurationTuple(type='32nd', dots=0, quarterLength=0.125))
>>> cDur = bDur.augmentOrDiminish(2, retainComponents=True)
>>> cDur.quarterLength
4.25
>>> cDur.tuplets
()
>>> cDur.components
(DurationTuple(type='whole', dots=0, quarterLength=4.0), 
 DurationTuple(type='16th', dots=0, quarterLength=0.25))
>>> dDur = bDur.augmentOrDiminish(2, retainComponents=False)
>>> dDur.components
(DurationTuple(type='whole', dots=0, quarterLength=4.0), 
 DurationTuple(type='16th', dots=0, quarterLength=0.25))
Duration.clear()

Permit all components to be removed. (It is not clear yet if this is needed: YES! for zero duration!)

>>> a = duration.Duration()
>>> a.quarterLength = 4
>>> a.type
'whole'
>>> a.components
(DurationTuple(type='whole', dots=0, quarterLength=4.0),)
>>> a.clear()
>>> a.components
()
>>> a.type
'zero'
>>> a.quarterLength
0.0
Duration.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.

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

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

>>> components = []
>>> qdt = duration.DurationTuple('quarter', 0, 1.0)
>>> components.append(qdt)
>>> components.append(qdt)
>>> components.append(qdt)
>>> a = duration.Duration()
>>> a.components = components
>>> a.quarterLength
3.0
>>> a.componentStartTime(0)
0.0
>>> a.componentStartTime(1)
1.0
Duration.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 DurationTuples cannot express all durations

>>> a = duration.Duration()
>>> a.fill(['quarter', 'half', 'quarter'])
>>> a.quarterLength
4.0
>>> len(a.components)
3
>>> a.type
'complex'

After consolidate:

>>> a.consolidate()
>>> a.quarterLength
4.0
>>> len(a.components)
1

It gains a type!

>>> a.type
'whole'

If the type cannot be expressed then the type is inexpressible

>>> a = duration.Duration()
>>> a.fill(['quarter', 'half', 'half'])
>>> a.quarterLength
5.0
>>> len(a.components)
3
>>> a.type
'complex'

After consolidate:

>>> a.consolidate()
>>> a.quarterLength
5.0
>>> len(a.components)
1

It gains a type!

>>> a.type
'inexpressible'
Duration.currentComponents()

Advanced Method:

returns the current components WITHOUT running the component updater.

Needed by some internal methods.

>>> d = duration.Duration()
>>> d.currentComponents()
[]
Duration.fill(quarterLengthList=('quarter', 'half', 'quarter'))

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

Duration.getGraceDuration(appogiatura=False)

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

>>> d = duration.Duration(1.25)
>>> d
<music21.duration.Duration 1.25>
>>> d.components
(DurationTuple(type='quarter', dots=0, quarterLength=1.0), 
 DurationTuple(type='16th', dots=0, quarterLength=0.25))
>>> gd = d.getGraceDuration()
>>> gd
<music21.duration.GraceDuration unlinked type:zero quarterLength:0.0>
>>> gd.quarterLength
0.0
>>> gd.components
(DurationTuple(type='quarter', dots=0, quarterLength=0.0), 
 DurationTuple(type='16th', dots=0, quarterLength=0.0))

D is unchanged.

>>> d.quarterLength
1.25
Duration.informClient()

call informSites({‘changedAttribute’: ‘duration’, ‘quarterLength’: quarterLength}) on any call that changes the quarterLength

returns False if there was no need to inform or if client was not set. Otherwise returns True

Duration.sliceComponentAtPosition(quarterPosition)

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

>>> a = duration.Duration()
>>> a.clear() # need to remove default
>>> components = []
>>> a.addDurationTuple(duration.Duration('quarter'))
>>> a.addDurationTuple(duration.Duration('quarter'))
>>> a.addDurationTuple(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'
Duration.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.

>>> d1 = duration.Duration(type = 'half')
>>> d1.dotGroups = (1,1)
>>> d1.quarterLength
4.5
>>> d2 = d1.splitDotGroups()
>>> d2.components
(DurationTuple(type='half', dots=1, quarterLength=3.0), 
 DurationTuple(type='quarter', dots=1, quarterLength=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
(DurationTuple(type='half', dots=1, quarterLength=3.0), 
 DurationTuple(type='quarter', dots=1, quarterLength=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

Does NOT handle tuplets etc.

Duration.updateQuarterLength()

Look to components and determine quarter length.

Tuplet

class music21.duration.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.

>>> myTup = duration.Tuplet(numberNotesActual = 5, numberNotesNormal = 4)
>>> print(myTup.tupletMultiplier())
4/5

In this case, the tupletMultiplier is a float because it can be expressed as a binary number:

>>> myTup2 = duration.Tuplet(8, 5)
>>> tm = myTup2.tupletMultiplier()
>>> tm
0.625
>>> myTup2 = duration.Tuplet(6, 4, "16th")
>>> print(myTup2.durationActual.type)
16th
>>> print(myTup2.tupletMultiplier())
2/3

Tuplets may be frozen, in which case they become immutable. Tuplets which are attached to Durations are automatically frozen. Otherwise a tuplet could change without the attached duration knowing about it, which would be a real problem.

>>> myTup.frozen = True
>>> myTup.tupletActual = [3, 2]
Traceback (most recent call last):
music21.duration.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):
music21.duration.TupletException: A frozen tuplet (or one attached to a duration) is immutable

Note that if you want to create a note with a simple Tuplet attached to it, you can just change the quarterLength of the note:

>>> myNote = note.Note("C#4")
>>> myNote.duration.quarterLength = 0.8
>>> myNote.duration.quarterLength
Fraction(4, 5)
>>> myNote.duration.fullName
'Quarter Quintuplet (4/5 QL)'
>>> myNote.duration.tuplets
(<music21.duration.Tuplet 5/4/quarter>,)

Tuplet read-only properties

Tuplet.fullName

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

>>> t = duration.Tuplet(numberNotesActual = 5, numberNotesNormal = 2)
>>> t.fullName
'Quintuplet'
>>> t = duration.Tuplet(numberNotesActual = 3, numberNotesNormal = 2)
>>> t.fullName
'Triplet'
>>> t = duration.Tuplet(numberNotesActual = 17, numberNotesNormal = 14)
>>> t.fullName
'Tuplet of 17/14ths'

Tuplet read/write properties

Tuplet.tupletActual

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

Tuplet.tupletNormal

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

Tuplet methods

Tuplet.augmentOrDiminish(amountToScale)

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.

>>> a = duration.Tuplet()
>>> a.setRatio(6,2)
>>> a.tupletMultiplier()
Fraction(1, 3)
>>> a.durationActual
DurationTuple(type='eighth', dots=0, quarterLength=0.5)
>>> c = a.augmentOrDiminish(.5)
>>> c.durationActual
DurationTuple(type='16th', dots=0, quarterLength=0.25)
>>> c.tupletMultiplier()
Fraction(1, 3)
Tuplet.setDurationType(durType)

Set the Duration for both actual and normal.

A type string or quarter length can be given.

>>> a = duration.Tuplet()
>>> a.tupletMultiplier()
Fraction(2, 3)
>>> a.totalTupletLength()
1.0
>>> a.setDurationType('half')
>>> a.tupletMultiplier()
Fraction(2, 3)
>>> a.totalTupletLength()
4.0
>>> a.setDurationType(2)
>>> a.totalTupletLength()
4.0
>>> a.setDurationType(4)
>>> a.totalTupletLength()
8.0
Tuplet.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.

>>> a = duration.Tuplet()
>>> a.tupletMultiplier()
Fraction(2, 3)
>>> a.setRatio(6,2)
>>> a.tupletMultiplier()
Fraction(1, 3)

One way of expressing 6/4-ish triplets without numbers: >>> a = duration.Tuplet() >>> a.setRatio(3,1) >>> a.durationActual = duration.durationTupleFromTypeDots(‘quarter’, 0) >>> a.durationNormal = duration.durationTupleFromTypeDots(‘half’, 0) >>> a.tupletMultiplier() Fraction(2, 3) >>> a.totalTupletLength() 2.0

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

>>> a = duration.Tuplet()
>>> a.totalTupletLength()
1.0
>>> a.numberNotesActual = 3
>>> a.durationActual = duration.durationTupleFromTypeDots('half', 0)
>>> a.numberNotesNormal = 2
>>> a.durationNormal = duration.durationTupleFromTypeDots('half', 0)
>>> a.totalTupletLength()
4.0
>>> a.setRatio(5,4)
>>> a.totalTupletLength()
8.0
>>> a.setRatio(5,2)
>>> a.totalTupletLength()
4.0
Tuplet.tupletMultiplier()

Get a Fraction() by which to scale the duration that this Tuplet is associated with.

>>> myTuplet = duration.Tuplet()
>>> myTuplet.tupletMultiplier()
Fraction(2, 3)
>>> myTuplet.tupletActual = [5, duration.Duration('eighth')]
>>> myTuplet.numberNotesActual
5
>>> myTuplet.durationActual.type
'eighth'
>>> print(myTuplet.tupletMultiplier())
2/5
>>> myTuplet.numberNotesNormal = 4
>>> print(myTuplet.tupletMultiplier())
4/5

TupletFixer

class music21.duration.TupletFixer(streamIn=None)

The TupletFixer object takes in a flat stream and tries to fix the brackets and time modification values of the tuplet so that they reflect proper beaming, etc. It does not alter the quarterLength of any notes.

TupletFixer methods

TupletFixer.findTupletGroups(incorporateGroupings=False)

Finds all tuplets in the stream and puts them into groups.

If incorporateGroupings is True, then a tuplet.type=”stop” ends a tuplet group even if the next note is a tuplet.

This demonstration has three groups of tuplets, two sets of 8th note tuplets and one of 16ths:

>>> c = converter.parse(
...    'tinynotation: 4/4 trip{c8 d e} f4 trip{c#8 d# e#} g8 trip{c-16 d- e-}', 
...    makeNotation=False)
>>> tf = duration.TupletFixer(c) # no need to flatten this stream
>>> tupletGroups = tf.findTupletGroups()
>>> tupletGroups
[[<music21.note.Note C>, <music21.note.Note D>, <music21.note.Note E>],
 [<music21.note.Note C#>, <music21.note.Note D#>, <music21.note.Note E#>],
 [<music21.note.Note C->, <music21.note.Note D->, <music21.note.Note E->]]

These groups are stored in TupletFixer.allTupletGroups:

>>> tupletGroups is tf.allTupletGroups
True

Demonstration with incorporateGroupings:

>>> s = stream.Stream()
>>> for i in range(9):
...    n = note.Note()
...    n.ps = 60 + i
...    n.duration.quarterLength = 1.0/3
...    if i % 3 == 2:
...        n.duration.tuplets[0].type = 'stop'
...    s.append(n)
>>> tf = duration.TupletFixer(s)
>>> tupletGroups = tf.findTupletGroups(incorporateGroupings = True)
>>> tupletGroups
[[<music21.note.Note C>, <music21.note.Note C#>, <music21.note.Note D>],
 [<music21.note.Note E->, <music21.note.Note E>, <music21.note.Note F>],
 [<music21.note.Note F#>, <music21.note.Note G>, <music21.note.Note G#>]]

Without incorporateGroupings we just get one big set of tuplets

>>> tupletGroups = tf.findTupletGroups()
>>> len(tupletGroups)
1
>>> len(tupletGroups[0])
9
TupletFixer.fixBrokenTupletDuration(tupletGroup)

tries to fix cases like triplet quarter followed by triplet eighth to be a coherent tuplet.

requires a tuplet group from findTupletGroups() or TupletFixer.allTupletGroups

>>> s = stream.Stream()
>>> n1 = note.Note('C')
>>> n1.duration.quarterLength = 2.0/3
>>> n1.duration.quarterLength
Fraction(2, 3)
>>> s.append(n1)
>>> n2 = note.Note('D')
>>> n2.duration.quarterLength = 1.0/3
>>> n2.duration.quarterLength
Fraction(1, 3)
>>> s.append(n2)
>>> n1.duration.tuplets[0]
<music21.duration.Tuplet 3/2/quarter>
>>> n2.duration.tuplets[0]
<music21.duration.Tuplet 3/2/eighth>
>>> tf = duration.TupletFixer(s) # no need to flatten this stream
>>> tupletGroups = tf.findTupletGroups()
>>> tupletGroups
[[<music21.note.Note C>, <music21.note.Note D>]]
>>> tf.fixBrokenTupletDuration(tupletGroups[0])
>>> n1.duration.tuplets[0]
<music21.duration.Tuplet 3/2/eighth>
>>> n1.duration.quarterLength
Fraction(2, 3)
>>> n2.duration.tuplets[0]
<music21.duration.Tuplet 3/2/eighth>

More complex example, from a piece by Josquin:

>>> humdr = "**kern *M3/1 3.c 6d 3e 3f 3d 3%2g 3e 3f#"
>>> humdrLines = '\n'.join(humdr.split())
>>> humdrum.spineParser.flavors['JRP'] = True
>>> s = converter.parse(humdrLines, format='humdrum')
>>> m1 = s.parts[0].measure(1)
>>> tf = duration.TupletFixer(m1)
>>> tupletGroups = tf.findTupletGroups(incorporateGroupings=True)
>>> tf.fixBrokenTupletDuration(tupletGroups[-1])
>>> m1[-1].duration.tuplets[0]
<music21.duration.Tuplet 3/2/whole>
>>> m1[-1].duration.quarterLength
Fraction(4, 3)
TupletFixer.setStream(streamIn)

Define a stream to work on and reset all temporary variables.

DurationTuple

class music21.duration.DurationTuple(type, dots, quarterLength)

DurationTuple read-only properties

DurationTuple.dots

Alias for field number 1

DurationTuple.ordinal

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

>>> a = duration.DurationTuple('whole', 0, 4.0)
>>> a.ordinal
4
>>> b = duration.DurationTuple('maxima', 0, 32.0)
>>> b.ordinal
1
>>> c = duration.DurationTuple('1024th', 0, 1.0/256)
>>> c.ordinal
14
DurationTuple.quarterLength

Alias for field number 2

DurationTuple.type

Alias for field number 0

DurationTuple methods

DurationTuple.augmentOrDiminish(amountToScale)

GraceDuration

class music21.duration.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.

>>> gd = duration.GraceDuration(type='half')
>>> gd.quarterLength
0.0
>>> gd.type
'half'
>>> gd = duration.GraceDuration(.25)
>>> gd.type
'16th'
>>> gd.quarterLength
0.0
>>> gd.linked
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 bases

GraceDuration read-only properties

Read-only properties inherited from Duration:

GraceDuration read/write properties

GraceDuration.makeTime

True, False, or None (=unknown) whether the grace note should occupy time in performance. Default False. Currently not used in generated playback.

TODO: allow a duration object or number for duration.

GraceDuration.slash

True, False, or None (=unknown) whether the grace note should have a slash through it. Default True.

Read/write properties inherited from Duration:

GraceDuration methods

Methods inherited from Duration:

GraceDuration instance variables

GraceDuration.stealTimeFollowing

Number from 0 to 1 or None (default) for the amount of time to steal from the following note.

GraceDuration.stealTimePrevious

Number from 0 to 1 or None (default) for the amount of time to steal from the previous note.

QuarterLengthConversion

class music21.duration.QuarterLengthConversion(components, tuplet)

QuarterLengthConversion read-only properties

QuarterLengthConversion.components

Alias for field number 0

QuarterLengthConversion.tuplet

Alias for field number 1