Previous topic

music21.demos.theoryAnalysis.theoryAnalyzer

Next topic

music21.dynamics

Table Of Contents

Table Of Contents

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.

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

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

>>> from music21 import *
>>> duration.convertTypeToQuarterLength('whole')
4.0
>>> duration.convertTypeToQuarterLength('16th')
0.25
>>> duration.convertTypeToQuarterLength('quarter', 2)
1.75
>>> tup = duration.Tuplet(numberNotesActual = 5, numberNotesNormal = 4)
>>> duration.convertTypeToQuarterLength('quarter', 0, [tup])
0.8...
>>> tup = duration.Tuplet(numberNotesActual = 3, numberNotesNormal = 4)
>>> duration.convertTypeToQuarterLength('quarter', 0, [tup])
1.333333...

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

>>> duration.convertTypeToQuarterLength('half', dots = 1, dotGroups = [1,1])
4.5
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.

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

This value is not equal to any dotted note length

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

maxDots can be lowered for certain searches

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

>>> duration.dottedMatch(0.00001, 2)
(False, False)
music21.duration.musicXMLTypeToType(value)

Convert a MusicXML type to an music21 type.

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

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

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

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

>>> from music21 import *
>>> duration.nextSmallerType("16th")
'32nd'
>>> duration.nextSmallerType("whole")
'half'
>>> duration.nextSmallerType("1024th")
'unexpressible'
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:

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

Divide 2.5 quarters worth of time into eighth notes.

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

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

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

Divide 5.25 qLen into dotted halves

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

Divide 1.33333 qLen into triplet eighths:

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

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

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

>>> pql(1.5, 4)
(1.5, 'quarter', 1, None, None, None)
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.
>>> from music21 import *
>>> duration.quarterLengthToClosestType(.5)
('eighth', True)
>>> duration.quarterLengthToClosestType(.75)
('eighth', False)
>>> duration.quarterLengthToClosestType(1.8)
('quarter', False)
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

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

Dots are supported

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

Double and triple dotted half note.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

>>> duration.unitSpec(duration.quarterLengthToDurations(2.5))
[(2.0, 'half', 0, None, None, None), (0.5, 'eighth', 0, None, None, None)]

>>> duration.unitSpec(duration.quarterLengthToDurations(2.3333333))
[(2.0, 'half', 0, None, None, None), (0.333..., 'eighth', 0, 3, 2, 'eighth')]
>>> duration.unitSpec(duration.quarterLengthToDurations(1.0/6.0))
[(0.1666..., '16th', 0, 3, 2, '16th')]

>>> duration.quarterLengthToDurations(.18333333333333)
[<music21.duration.DurationUnit 0.125>, <music21.duration.DurationUnit 0.03125>, <music21.duration.DurationUnit 0.015625>, <music21.duration.DurationUnit 0.0078125>]
>>> duration.quarterLengthToDurations(0.0)
[<music21.duration.ZeroDuration>]
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.

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

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

>>> duration.quarterLengthToTuplet(.3333333, 1)
[<music21.duration.Tuplet 3/2/eighth>]

>>> duration.quarterLengthToTuplet(.20)
[<music21.duration.Tuplet 5/4/16th>, <music21.duration.Tuplet 5/2/eighth>, <music21.duration.Tuplet 5/1/quarter>]
>>> c = duration.quarterLengthToTuplet(.3333333, 1)[0]
>>> c.tupletMultiplier()
0.6666...
music21.duration.typeToMusicXMLType(value)

Convert a music21 type to a MusicXML type.

>>> from music21 import *
>>> duration.typeToMusicXMLType('longa')
'long'
>>> duration.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.

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

>>> bDur = duration.Duration()
>>> bDur.quarterLength = 1.125
>>> duration.unitSpec(bDur)
(1.125, 'complex', None, None, None, None)
>>> cDur = duration.Duration()
>>> cDur.quarterLength = 0.3333333
>>> duration.unitSpec(cDur)
(0.33333..., 'eighth', 0, 3, 2, 'eighth')

>>> duration.unitSpec([aDur, bDur, cDur])
[(3.0, 'half', 1, None, None, None), (1.125, 'complex', None, None, None, None), (0.333333..., 'eighth', 0, 3, 2, 'eighth')]
music21.duration.updateTupletType(durationList)

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

>>> from music21 import *
>>> a = duration.Duration(); a.quarterLength = .33333
>>> b = duration.Duration(); b.quarterLength = .33333
>>> c = duration.DurationUnit(); c.quarterLength = .33333
>>> d = duration.Duration(); d.quarterLength = 2
>>> e = duration.Duration(); e.quarterLength = .33333
>>> f = duration.DurationUnit(); f.quarterLength = .33333
>>> g = duration.Duration(); g.quarterLength = .33333

>>> a.tuplets[0].type == None
True
>>> duration.updateTupletType([a, b, c, d, e, f, g])
>>> a.tuplets[0].type == 'start'
True
>>> b.tuplets[0].type == None
True
>>> c.tuplets[0].type == 'stop'
True
>>> e.tuplets[0].type == 'start'
True
>>> g.tuplets[0].type == 'stop'
True

Duration

Inherits from: DurationCommon, JSONSerializer

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:

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

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

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

Example 3: A Duration configured by keywords.

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

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

Duration attributes

Attributes without Documentation: isGrace, linkage

Duration properties

components

No documentation.

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
dots

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

fullName

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

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

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

>>> d = duration.Duration(quarterLength=0.666666)
>>> d.fullName
'Quarter Triplet (0.67QL)'
>>> d = duration.Duration(quarterLength=0.571428)
>>> d.fullName
'Quarter Tuplet of 7/4ths (0.57QL)'

>>> d = duration.Duration(quarterLength=0)
>>> d.fullName
'Zero Duration (0 total QL)'
isComplex

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

>>> from music21 import *
>>> aDur = duration.Duration()
>>> aDur.quarterLength = 1.375
>>> aDur.isComplex
True
>>> len(aDur.components)
2
>>> aDur.components
[<music21.duration.DurationUnit 1.0>, <music21.duration.DurationUnit 0.375>]
>>> bDur = duration.Duration()
>>> bDur.quarterLength = 1.6666666
>>> bDur.isComplex
True
>>> len(bDur.components)
2
>>> bDur.components
[<music21.duration.DurationUnit 1.0>, <music21.duration.DurationUnit 0.6666...>]
>>> cDur = duration.Duration()
>>> cDur.quarterLength = .25
>>> cDur.isComplex
False
>>> len(cDur.components)
1
isLinked

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

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

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

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

More complex rhythms can also be set automatically:

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

Return a complete MusicXML string with defaults.

ordinal

Get the ordinal value of the Duration.

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

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

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

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

>>> a.quarterLength = 2.5
>>> a.quarterLength
2.5
>>> for thisUnit in a.components:
...    print(unitSpec(thisUnit))
(2.0, 'half', 0, None, None, None)
(0.5, 'eighth', 0, None, None, None)

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

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

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

type

Get or set the type of the Duration.

Properties inherited from DurationCommon: classes

Properties inherited from JSONSerializer: json

Duration methods

addDurationUnit(dur, link=True)

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

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

No documentation.

augmentOrDiminish(amountToScale, retainComponents=False, inPlace=True)

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

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

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

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

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

>>> dDur = bDur.augmentOrDiminish(2, retainComponents=False, inPlace=False)
>>> dDur.components
[<music21.duration.DurationUnit 4.0>, <music21.duration.DurationUnit 0.25>]
clear()

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

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

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

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

>>> from music21 import *
>>> components = []
>>> components.append(duration.Duration('quarter'))
>>> components.append(duration.Duration('quarter'))
>>> components.append(duration.Duration('quarter'))

>>> a = duration.Duration()
>>> a.components = components
>>> a.updateQuarterLength()
>>> a.quarterLength
3.0
>>> a.componentIndexAtQtrPosition(.5)
0
>>> a.componentIndexAtQtrPosition(1.5)
1
>>> a.componentIndexAtQtrPosition(2.5)
2

this is odd behavior:

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

then

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

componentStartTime(componentIndex)

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

This does not handle fractional arguments.

>>> from music21 import *
>>> components = []
>>> components.append(duration.Duration('quarter'))
>>> components.append(duration.Duration('quarter'))
>>> components.append(duration.Duration('quarter'))

>>> a = duration.Duration()
>>> a.components = components
>>> a.updateQuarterLength()
>>> a.quarterLength
3.0
>>> a.componentStartTime(0)
0.0
>>> a.componentStartTime(1)
1.0
consolidate()

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

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

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

But it gains a type!

>>> a.type
'whole'
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.

getGraceDuration(appogiatura=False)

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

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

Set all components to be linked

setQuarterLengthUnlinked(value)

Set the quarter note length to the specified value.

setTypeUnlinked(value)

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

show(format='musicxml')

Same as Music21Object.show().

sliceComponentAtPosition(quarterPosition)

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

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

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

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

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

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

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

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

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

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

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.

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

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

>>> myTup.frozen = True
>>> myTup.tupletActual = [3, 2]
Traceback (most recent call last):
...
TupletException: A frozen tuplet (or one attached to a duration) is immutable

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

Tuplet attributes

durationActual

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

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

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

Additional types are needed beyond those in Duration:

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

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

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

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

Additional types are needed beyond those in Duration:

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

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

Tuplet properties

fullName

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

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

>>> t = duration.Tuplet(numberNotesActual = 3, numberNotesNormal = 2)
>>> t.fullName
'Triplet'
mx

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

>>> from music21 import *
>>> a = duration.Tuplet()
>>> a.bracket = True
>>> b, c = a.mx
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(amountToScale, inPlace=True)

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

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

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

Set the Duration for both actual and normal.

A type string or quarter length can be given.

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

>>> a.setDurationType(2)
>>> a.totalTupletLength()
4.0
>>> a.setDurationType(4)
>>> a.totalTupletLength()
8.0
setRatio(actual, normal)

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

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

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

totalTupletLength()

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

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

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

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

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

AppogiaturaDuration

Inherits from: GraceDuration, Duration, DurationCommon, JSONSerializer

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

DurationCommon

Inherits from: JSONSerializer

class music21.duration.DurationCommon

A base class for both Duration and DurationUnit objects.

DurationCommon properties

classes

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

Properties inherited from JSONSerializer: json

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

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

Nested tuplets are possible...

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

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

DurationUnit

Inherits from: DurationCommon, JSONSerializer

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

DurationUnit properties

dotGroups

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

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

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

fullName

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

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

>>> from music21 import *
>>> d = duration.DurationUnit()
>>> d.quarterLength = 1.75
>>> d.fullName
'Double Dotted Quarter'
>>> d = duration.DurationUnit()
>>> d.type = 'half'
>>> d.fullName
'Half'
>>> d = duration.DurationUnit()
>>> d.type = 'longa'
>>> d.fullName
'Imperfect Longa'

>>> d.dots = 1
>>> d.fullName
'Perfect Longa'
isLinked

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

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

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

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

Property for getting or setting the quarterLength of a DurationUnit.

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

Return a tuple of Tuplet objects

type

Property for getting or setting the type of a DurationUnit.

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

Properties inherited from DurationCommon: classes

Properties inherited from JSONSerializer: json

DurationUnit methods

appendTuplet(newTuplet)

No documentation.

augmentOrDiminish(amountToScale, inPlace=True)

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

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

>>> from music21 import *
>>> bDur = duration.DurationUnit('16th')
>>> bDur.augmentOrDiminish(2)
>>> bDur.quarterLength
0.5
>>> bDur.type
'eighth'
>>> bDur.augmentOrDiminish(4)
>>> bDur.type
'half'
>>> bDur.augmentOrDiminish(.125)
>>> bDur.type
'16th'

>>> cDur = bDur.augmentOrDiminish(16, inPlace=False)
>>> cDur, bDur
(<music21.duration.DurationUnit 4.0>, <music21.duration.DurationUnit 0.25>)

No documentation.

setTypeFromNum(typeNum)

No documentation.

No documentation.

updateQuarterLength()

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

To set quarterLength, use self.quarterLength.

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

No documentation.

Methods inherited from DurationCommon: aggregateTupletRatio()

Methods inherited from JSONSerializer: jsonAttributes(), jsonComponentFactory(), jsonPrint(), jsonRead(), jsonWrite()

GraceDuration

Inherits from: Duration, DurationCommon, JSONSerializer

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.

>>> from music21 import *
>>> gd = duration.GraceDuration(type='half')
>>> gd.quarterLength
0.0
>>> gd.type
'half'

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

GraceDuration attributes

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

Attributes inherited from Duration: linkage

GraceDuration properties

Properties inherited from Duration: components, dotGroups, dots, fullName, isComplex, isLinked, midi, musicxml, ordinal, quarterLength, tuplets, type

Properties inherited from DurationCommon: classes

Properties inherited from JSONSerializer: json

GraceDuration methods

ZeroDuration

Inherits from: DurationUnit, DurationCommon, JSONSerializer

class music21.duration.ZeroDuration

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

ZeroDuration attributes

Attributes without Documentation: isGrace

ZeroDuration properties

Properties inherited from DurationUnit: dotGroups, dots, fullName, isLinked, ordinal, quarterLength, tuplets, type

Properties inherited from DurationCommon: classes

Properties inherited from JSONSerializer: json

ZeroDuration methods