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
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
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
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
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)
Convert a MusicXML type to an music21 type.
>>> musicXMLTypeToType('long')
'longa'
>>> musicXMLTypeToType('quarter')
'quarter'
>>> musicXMLTypeToType(None)
Traceback (most recent call last):
DurationException...
Given a type (such as 16th or quarter), return the next larger type.
>>> nextLargerType("16th")
'eighth'
>>> nextLargerType("whole")
'breve'
>>> nextLargerType("duplex-maxima")
'unexpressible'
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)
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)
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')]
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...
Convert a music21 type to a MusicXML type.
>>> typeToMusicXMLType('longa')
'long'
>>> typeToMusicXMLType('quarter')
'quarter'
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')]
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
Inherits from: DurationCommon
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
- ordinal¶
Get the ordinal value of the Duration.
>>> from music21 import * >>> d = duration.Duration() >>> d.quarterLength = 2.0 >>> d.ordinal 5
- 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()
A tuplet object is a representation of one or more ratios that modify duration values and are stored in Duration objects. 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 eighth. 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 duration
>>> 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]
...
TupletException: A frozen tuplet (or one attached to a duration) is immutable
>>> myHalf = duration.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
>>> from music21 import duration >>> 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(scalar, inPlace=True)¶
Given a scalar greater than zero, return a scaled version of this Duration.
>>> from music21 import duration >>> 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 duration >>> 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 duration >>> 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 duration >>> 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 duration >>> 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
Inherits from: Duration, DurationCommon
Inherits from: 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
>>> from music21 import duration >>> 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)
Inherits from: DurationCommon
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>)
- link()¶
- No documentation.
- setTypeFromNum(typeNum)¶
- No documentation.
- unlink()¶
- 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()
Inherits from: Duration, DurationCommon