Table Of Contents

Previous topic

music21.chord

Next topic

music21.dynamics

This Page

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

>>> convertQuarterLengthToType(2)
'half'
>>> convertQuarterLengthToType(0.125)
'32nd'
>>> convertQuarterLengthToType(0.33333)
Traceback (most recent call last):
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.

>>> convertTypeToNumber('quarter')
4
>>> convertTypeToNumber('half')
2
>>> convertTypeToNumber('1024th')
1024
>>> convertTypeToNumber('maxima')
0.125
music21.duration.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.

>>> convertTypeToQuarterLength('whole')
4.0
>>> convertTypeToQuarterLength('16th')
0.25
>>> convertTypeToQuarterLength('quarter', 2)
1.75
>>> tup = Tuplet(numberNotesActual = 5, numberNotesNormal = 4)
>>> convertTypeToQuarterLength('quarter', 0, [tup])
0.800000...
>>> tup = Tuplet(numberNotesActual = 3, numberNotesNormal = 4)
>>> 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).
>>> convertTypeToQuarterLength('half', 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.

>>> dottedMatch(3.0)
(1, 'half')
>>> dottedMatch(1.75)
(2, 'quarter')
This value is not equal to any dotted note length
>>> dottedMatch(1.6)
(False, False)
maxDots can be lowered for certain searches
>>> dottedMatch(1.875)
(3, 'quarter')
>>> dottedMatch(1.875, 2)
(False, False)
music21.duration.musicXMLTypeToType(value)

Convert a MusicXML type to an music21 type.

>>> musicXMLTypeToType('long')
'longa'
>>> musicXMLTypeToType('quarter')
'quarter'
>>> musicXMLTypeToType(None)
Traceback (most recent call last):
DurationException...
music21.duration.nextLargerType(durType)

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

>>> nextLargerType("16th")
'eighth'
>>> nextLargerType("whole")
'breve'
>>> nextLargerType("duplex-maxima")
'unexpressible'
music21.duration.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:
>>> def pql(qLen, qLenDiv):
...    partitionList = partitionQuarterLength(qLen, qLenDiv)
...    for dur in partitionList:
...        print(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)
>>> #Dividing 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)
>>> #Dividing 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)
>>> #Dividing 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')
>>> #Dividing 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)
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.

>>> quarterLengthToClosestType(.5)
('eighth', True)
>>> quarterLengthToClosestType(.75)
('eighth', False)
>>> quarterLengthToClosestType(1.8)
('quarter', False)
music21.duration.quarterLengthToDurations(qLen)

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: d = 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

>>> unitSpec(quarterLengthToDurations(2))
[(2.0, 'half', 0, None, None, None)]
Dots are supported
>>> unitSpec(quarterLengthToDurations(3))
[(3.0, 'half', 1, None, None, None)]
>>> unitSpec(quarterLengthToDurations(6.0))
[(6.0, 'whole', 1, None, None, None)]
Double and triple dotted half note.
>>> unitSpec(quarterLengthToDurations(3.5))
[(3.5, 'half', 2, None, None, None)]
>>> unitSpec(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.
>>> unitSpec(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 = unitSpec(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
>>> unitSpec(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
>>> unitSpec(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
>>> unitSpec(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
>>> unitSpec(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.
>>> unitSpec(quarterLengthToDurations(2.5))
[(2.0, 'half', 0, None, None, None), (0.5, 'eighth', 0, None, None, None)]
>>> unitSpec(quarterLengthToDurations(2.3333333))
[(2.0, 'half', 0, None, None, None), (0.333..., 'eighth', 0, 3, 2, 'eighth')]
>>> unitSpec(quarterLengthToDurations(1.0/6.0))
[(0.1666..., '16th', 0, 3, 2, '16th')]
music21.duration.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.

>>> 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.
>>> quarterLengthToTuplet(.3333333, 1)
[<music21.duration.Tuplet 3/2/eighth>]
>>> quarterLengthToTuplet(.20)
[<music21.duration.Tuplet 5/4/16th>, <music21.duration.Tuplet 5/2/eighth>, <music21.duration.Tuplet 5/1/quarter>]
>>> c = quarterLengthToTuplet(.3333333, 1)[0]
>>> c.tupletMultiplier()
0.6666...
music21.duration.roundDuration(qLen)
music21.duration.typeToMusicXMLType(value)

Convert a music21 type to a MusicXML type.

>>> typeToMusicXMLType('longa')
'long'
>>> typeToMusicXMLType('quarter')
'quarter'
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()
>>> aDur.quarterLength = 3
>>> unitSpec(aDur)
(3.0, 'half', 1, None, None, None)
>>> bDur = Duration()
>>> bDur.quarterLength = 1.125
>>> unitSpec(bDur)
(1.125, 'complex', None, None, None, None)
>>> cDur = Duration()
>>> cDur.quarterLength = 0.3333333
>>> unitSpec(cDur)
(0.33333..., 'eighth', 0, 3, 2, 'eighth')
>>> 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')]
music21.duration.updateTupletType(durationList)

Given a list of Durations or DurationUnits (not yet working properly), examine each Duration, and each component, and set Tuplet type to start or stop, as necessary.

>>> a = Duration(); a.quarterLength = .33333
>>> b = Duration(); b.quarterLength = .33333
>>> c = DurationUnit(); c.quarterLength = .33333
>>> d = Duration(); d.quarterLength = 2
>>> e = Duration(); e.quarterLength = .33333
>>> f = DurationUnit(); f.quarterLength = .33333
>>> g = Duration(); g.quarterLength = .33333
>>> a.tuplets[0].type == None
True
>>> 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: DurationCommon

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

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

Duration attributes

Attributes without Documentation: linkages

Duration properties

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

Property defining if this Duration has more than one DurationUnit object on the component list.

>>> aDur = Duration()
>>> aDur.quarterLength = 1.375
>>> aDur.isComplex
True
>>> len(aDur.components)
2
>>> aDur = Duration()
>>> aDur.quarterLength = 1.6666666
>>> aDur.isComplex
True
>>> len(aDur.components)
2
>>> aDur = Duration()
>>> aDur.quarterLength = .25
>>> aDur.isComplex
False
>>> len(aDur.components)
1
lily
Simple lily duration: does not include tuplets These are taken care of in the lily processing in stream.Stream since lilypond requires tuplets to be in groups
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.

>>> d = Duration()
>>> d.midi = 1024
>>> d.type
'quarter'
>>> d.type = '16th'
>>> d.midi
256
>>> d.quarterLength
0.25
musicxml
Return a complete MusicXML string with defaults.
mx

Returns a list of one or more musicxml.Note() objects with all rhythms and ties necessary. mxNote objects are incompletely specified, lacking full representation and information on pitch, etc.

>>> a = Duration()
>>> a.quarterLength = 3
>>> b = a.mx
>>> len(b) == 1
True
>>> isinstance(b[0], musicxmlMod.Note)
True
>>> a = Duration()
>>> a.quarterLength = .33333333
>>> b = a.mx
>>> len(b) == 1
True
>>> isinstance(b[0], musicxmlMod.Note)
True
quarterLength
Can be the same as the base class.
tuplets
When there are more than one component, each component may have its own tuplet.
type
Get the duration type.

Duration methods

addDurationUnit(dur)

Add a DurationUnit or a Duration’s components to this Duration.

>>> a = Duration('quarter')
>>> b = Duration('quarter')
>>> a.addDurationUnit(b)
>>> a.quarterLength
2.0
>>> a.type
'complex'
appendTuplet(newTuplet)
No documentation.
augmentOrDiminish(scalar, retainComponents=False, inPlace=True)

Given a scalar greater than zero, return a scaled version of this duration.

>>> aDur = Duration()
>>> aDur.quarterLength = 1.5 # dotted quarter
>>> aDur.augmentOrDiminish(2)
>>> aDur.quarterLength
3.0
>>> aDur.type
'half'
>>> aDur.dots
1
>>> bDur = 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>]
clear()

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

>>> a = Duration()
>>> a.quarterLength = 4
>>> a.type
'whole'
>>> a.clear()
>>> a.quarterLength
0.0
>>> a.type
'zero'
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 = []
TODO: remove "for x in [1,1,1]" notation; it's confusing (Perl-like)
better is just to copy and paste three times.  Very easy to see what
is happening.
>>> for x in [1,1,1]:
...   components.append(Duration('quarter'))
>>> a = 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
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 = []
>>> for x in [1,1,1]:
...    components.append(Duration('quarter'))
>>> a = Duration()
>>> a.components = components
>>> a.updateQuarterLength()
>>> a.quarterLength
3.0
>>> a.componentStartTime(0)
0.0
>>> a.componentStartTime(1)
1.0
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 coponents. This cannot be done for all Durations, as DurationUnits cannot express all durations

>>> a = 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'
expand(qLenDiv=4)
Make a duration notatable by partitioning it into smaller units (default qLenDiv = 4 (whole note)). uses partitionQuarterLength
fill(quarterLengthList=[, 'quarter', 'half', 'quarter'])
Utility method for testing; a quick way to fill components. This will remove any exisiting values.
show(format=musicxml)
Same as Music21Object.show()
sliceComponentAtPosition(quarterPosition)

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

>>> a = Duration()
>>> a.clear() # need to remove default
>>> components = []
>>> a.addDurationUnit(Duration('quarter'))
>>> a.addDurationUnit(Duration('quarter'))
>>> a.addDurationUnit(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'
updateQuarterLength()
Look to components and determine quarter length.
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 DurationCommon: aggregateTupletRatio()

Tuplet

class music21.duration.Tuplet(*arguments, **keywords)

A tuplet object is a representation of one or more ratios that modify duration values and are stored in Duration objects. Note that this is a duration modifier. We should also have a tupletGroup object that groups note objects into larger groups.

>>> myTup = Tuplet(numberNotesActual = 5, numberNotesNormal = 4)
>>> print(myTup.tupletMultiplier())
0.8
>>> myTup2 = Tuplet(8, 5)
>>> print(myTup2.tupletMultiplier())
0.625
>>> myTup2 = 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]
...
TupletException: A frozen tuplet (or one attached to a duration) is immutable
>>> myHalf = Duration("half")
>>> myHalf.appendTuplet(myTup2)
>>> myTup2.tupletActual = [5, 4]
...
TupletException: A frozen tuplet (or one attached to a duration) is immutable

Tuplet attributes

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 and ‘unexpressable’ type for anything that cannot be expressed as a single notation unit, and thus needs a full Duration object (such as 2.5 quarterLengths.)
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 and ‘unexpressable’ 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

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

>>> a = Tuplet()
>>> a.bracket = True
>>> b, c = a.mx
tupletActual
Get or set a two element list of number notes actual and duration actual.
tupletNormal
Get or set a two element list of number notes actual and duration normal.

Tuplet methods

augmentOrDiminish(scalar, inPlace=True)

Given a scalar greater than zero, return a scaled version of this Duration.

>>> a = 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...
setDurationType(type)

Set the Duration for both actual and normal.

>>> a = Tuplet()
>>> a.tupletMultiplier()
0.666...
>>> a.totalTupletLength()
1.0
>>> a.setDurationType('half')
>>> a.tupletMultiplier()
0.6666...
>>> a.totalTupletLength()
4.0
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 = Tuplet()
>>> a.tupletMultiplier()
0.666...
>>> a.setRatio(6,2)
>>> a.tupletMultiplier()
0.333...
One way of expressing 6/4-ish triplets without numbers:
>>> a = Tuplet()
>>> a.setRatio(3,1)
>>> a.durationActual = DurationUnit('quarter')
>>> a.durationNormal = DurationUnit('half')
>>> a.tupletMultiplier()
0.666...
>>> a.totalTupletLength()
2.0
totalTupletLength()

The total length in quarters 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 = 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
tupletMultiplier()

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

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

AppogiaturaStartDuration

Inherits from: Duration, DurationCommon

class music21.duration.AppogiaturaStartDuration(*arguments, **keywords)
First positional argument is assumed to be type string or a quarterLength.

AppogiaturaStopDuration

Inherits from: Duration, DurationCommon

class music21.duration.AppogiaturaStopDuration(*arguments, **keywords)
First positional argument is assumed to be type string or a quarterLength.

DurationCommon

class music21.duration.DurationCommon

A base class for both Duration and DurationUnit objects.

DurationCommon methods

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

>>> complexDur = Duration('eighth')
>>> complexDur.appendTuplet(Tuplet())
>>> complexDur.aggregateTupletRatio()
(3, 2)
>>> tup2 = Tuplet()
>>> tup2.setRatio(5, 4)
>>> complexDur.appendTuplet(tup2)
>>> complexDur.aggregateTupletRatio()
(15, 8)

DurationUnit

Inherits from: DurationCommon

class music21.duration.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 and ‘unexpressable’ 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 attributes

Attributes without Documentation: linkStatus

DurationUnit properties

dots
_dots is a list (so we can do weird things like Crumb half-dots) Normally we only want the first element. So that’s what _getDots returns...
lily
Simple lily duration: does not include tuplets; these appear in the Stream object, because of how lily represents triplets
ordinal

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

>>> a = DurationUnit('whole')
>>> a.ordinal
4
>>> b = DurationUnit('maxima')
>>> b.ordinal
1
>>> c = DurationUnit('1024th')
>>> c.ordinal
14
quarterLength

Property for getting or setting the quarterLength of a DurationUnit.

>>> a = DurationUnit()
>>> a.quarterLength = 3
>>> a.type
'half'
>>> a.dots
1
>>> a.quarterLength = .5
>>> a.type
'eighth'
>>> a.quarterLength = .75
>>> a.type
'eighth'
>>> a.dots
1
>>> b = DurationUnit()
>>> b.quarterLength = 16
>>> b.type
'longa'
tuplets
Return a tuple of Tuplet objects
type

Property for getting or setting the type of a DurationUnit.

>>> a = DurationUnit()
>>> a.quarterLength = 3
>>> a.type
'half'
>>> a.dots
1
>>> a.type = 'quarter'
>>> a.quarterLength
1.5
>>> a.type = '16th'
>>> a.quarterLength
0.375

DurationUnit methods

appendTuplet(newTuplet)
No documentation.
augmentOrDiminish(scalar, inPlace=True)

Given a scalar greater than one, return a scaled version of this duration.

>>> bDur = 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>)
No documentation.
setTypeFromNum(typeNum)
No documentation.
No documentation.
updateQuarterLength()

Updates the quarterLength if linkStatus is True. Called by self._getQuarterLength if _quarterLengthNeedsUpdating is set to True. To set quarterLength, use self.quarterLength.

>>> bDur = DurationUnit('16th')
>>> bDur.quarterLength
0.25
>>> bDur.unlink()
>>> bDur.quarterLength = 234
>>> bDur.quarterLength
234
>>> bDur.type
'16th'
>>> bDur.link() # if linking is restored, type is used to get qLen
>>> bDur.updateQuarterLength()
>>> bDur.quarterLength
0.25
updateType()
No documentation.

Methods inherited from DurationCommon: aggregateTupletRatio()

GraceDuration

Inherits from: Duration, DurationCommon

class music21.duration.GraceDuration

LongGraceDuration

Inherits from: Duration, DurationCommon

class music21.duration.LongGraceDuration

ZeroDuration

Inherits from: DurationUnit, DurationCommon

class music21.duration.ZeroDuration