Previous topic

music21.documentation.upload

Next topic

music21.dynamics

Table Of Contents

Table Of Contents

This Page

music21.duration

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):
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
>>> duration.convertTypeToNumber('half')
2
>>> duration.convertTypeToNumber('1024th')
1024
>>> 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])
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

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.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")
'unexpressible'
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")
'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 = 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)

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)
>>> duration.quarterLengthToClosestType(2.0000000000000001)
('half', True)
music21.duration.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

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

>>> 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...
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', 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')]
music21.duration.updateTupletType(durationList)

N.B. – DEPRECATED – call stream.makeNotation.makeTupletBrackets

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

>>> 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 is None
True
>>> duration.updateTupletType([a, b, c, d, e, f, g])
>>> a.tuplets[0].type == 'start'
True
>>> b.tuplets[0].type is None
True
>>> c.tuplets[0].type == 'stop'
True
>>> d.tuplets
()
>>> e.tuplets[0].type == 'start'
True
>>> f.tuplets[0].type is None
True
>>> g.tuplets[0].type == 'stop'
True

A single duration with tuplet (automatically forces into a List):

>>> dur = duration.Duration(1.0/3)
>>> duration.updateTupletType([dur] )
>>> dur.tuplets[0].type
'startStop'     

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 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 music21.duration.DurationUnit objects),

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

Duration bases

Duration read-only properties

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

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

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

Get the ordinal value of the Duration.

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

Read-only properties inherited from DurationCommon:

Duration read/write properties

Duration.components
Duration.dotGroups

See the explanation under 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
Duration.dots

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

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:

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

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

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

>>> a = duration.Duration('quarter')
>>> b = duration.Duration('quarter')
>>> a.addDurationUnit(b)
>>> a.quarterLength
2.0
>>> a.type
'complex'
Duration.appendTuplet(newTuplet)
Duration.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.

>>> 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>]
Duration.clear()

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

>>> a = duration.Duration()
>>> a.quarterLength = 4
>>> a.type
'whole'
>>> a.clear()
>>> a.quarterLength
0.0
>>> a.type
'zero'
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 = []
>>> 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
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 DurationUnits cannot express all durations

>>> 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'
Duration.expand(qLenDiv=4)

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

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 deep copy of this Duration as a GraceDuration instance with the same types.

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

Set all components to be linked

Duration.setQuarterLengthUnlinked(value)

Set the quarter note length to the specified value.

Duration.setTypeUnlinked(value)

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

Duration.show(format='musicxml')

Same as Music21Object.show().

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

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

Duration.updateQuarterLength()

Look to components and determine quarter length.

Duration.write(format='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:

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())
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. 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):
...
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

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.quarterLength = 0.8
>>> myNote.duration.fullName
'Quarter Quintuplet (0.8QL)'
>>> 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, 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.

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

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.Duration('half')
>>> a.numberNotesNormal = 2
>>> a.durationNormal = duration.Duration('half')
>>> a.totalTupletLength()
4.0
>>> a.setRatio(5,4)
>>> a.totalTupletLength()
8.0
>>> a.setRatio(5,2)
>>> a.totalTupletLength()
4.0
Tuplet.tupletMultiplier()

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

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

DurationUnit

class music21.duration.DurationUnit(prototype='quarter')

A DurationUnit is a duration notation that (generally) can be notated with 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 bases

DurationUnit read-only properties

DurationUnit.fullName

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

>>> d = duration.DurationUnit()
>>> d.quarterLength = 1.5
>>> d.fullName
'Dotted Quarter'
>>> 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'
DurationUnit.isLinked

Return a boolean describing this duration is linked or not.

>>> d = duration.DurationUnit()
>>> d.isLinked
True
::
>>> d.unlink()
>>> d.isLinked
False
DurationUnit.ordinal

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

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

Read-only properties inherited from DurationCommon:

DurationUnit read/write properties

DurationUnit.dotGroups

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

>>> d1 = duration.DurationUnit()
>>> d1.type = 'half'
>>> d1.dotGroups = [1, 1]  # dotted dotted half
>>> d1.dots
1
>>> d1.dotGroups
(1, 1)
>>> d1.quarterLength
4.5
DurationUnit.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 dots returns...

>>> a = duration.DurationUnit()
>>> a.dots # dots is zero before assignment
0
>>> a.type = 'quarter'
>>> a.dots = 1
>>> a.quarterLength
1.5
>>> a.dots = 2
>>> a.quarterLength
1.75
DurationUnit.quarterLength

Property for getting or setting the quarterLength of a DurationUnit.

>>> 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'
DurationUnit.tuplets

Return a tuple of Tuplet objects

DurationUnit.type

Property for getting or setting the type of a DurationUnit.

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

DurationUnit methods

DurationUnit.appendTuplet(newTuplet)
DurationUnit.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.

>>> 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>)
DurationUnit.setTypeFromNum(typeNum)
DurationUnit.updateQuarterLength()

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

To set quarterLength, use self.quarterLength.

>>> 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
DurationUnit.updateType()

Methods inherited from DurationCommon:

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-}')
>>> 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()
>>> n1.duration.quarterLength = 2.0/3
>>> s.append(n1)
>>> n2 = note.Note()
>>> n2.duration.quarterLength = 1.0/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()
>>> tf.fixBrokenTupletDuration(tupletGroups[0])
>>> n1.duration.tuplets[0]
<music21.duration.Tuplet 3/2/eighth>
>>> n1.duration.quarterLength
0.666...
>>> 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
1.333...
TupletFixer.setStream(streamIn)

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

DurationCommon

class music21.duration.DurationCommon

A base class for both Duration and DurationUnit objects.

DurationCommon bases

DurationCommon read-only properties

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

DurationCommon methods

DurationCommon.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 method is needed for MusicXML time-modification among other places.

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

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

GraceDuration read-only properties

Read-only properties inherited from Duration:

Read-only properties inherited from DurationCommon:

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.

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.

Read/write properties inherited from Duration:

GraceDuration methods

Methods inherited from Duration:

Methods inherited from DurationCommon:

ZeroDuration

class music21.duration.ZeroDuration

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

ZeroDuration bases

ZeroDuration read-only properties

Read-only properties inherited from DurationUnit:

Read-only properties inherited from DurationCommon:

ZeroDuration read/write properties

Read/write properties inherited from DurationUnit:

ZeroDuration methods

Methods inherited from DurationUnit:

Methods inherited from DurationCommon: