pymusicxml.score_components.Duration

class pymusicxml.score_components.Duration(note_type: str, num_dots: int = 0, tuplet_ratio: Optional[tuple] = None)

Bases: DurationalObject

Represents a length that can be written as a single note or rest.

Parameters:

• note_type – written musicXML duration type, e.g. “quarter”

• num_dots – number of duration dots

• tuplet_ratio – One of (a) None, indicating not part of a tuplet (b) a tuple of either (# actual notes, # normal notes) (c) a tuple of (# actual, # normal, note type), e.g. (4, 3, 0.5) for 4 in the space of 3 eighths.

Variables:

• note_type – written musicXML duration type, e.g. quarter

• num_dots – number of duration dots

• tuplet_ratio – see param definition.

Methods

from_divisor(divisor[, num_dots, tuplet_ratio])	Constructs a Duration from a divisor
from_string(duration_string)	Parses various string representations into a Duration
from_written_length(written_length[, ...])	Constructs a Duration from a written length
get_note_type_and_number_of_dots(length[, ...])	Given a length in quarter notes, get the note type and number of dots.
min_denominator()	Minimum divisor of a quarter note that would be needed to represent the duration of this note accurately.
num_beams()	The number of beams needed to for a note of this duration.
render()	Renders this component to a tuple of ElementTree.Element.
render_to_beat_unit_tags()	Renders the beat unit tags needed in metronome directions.
wrap_as_score()	Wraps this component in a Score so that it can be exported and viewed

Inherited Methods

export_to_file(file_path[, pretty_print])	Exports this musical object (wrapped as a score) to the given file path.
to_xml([pretty_print])	Renders this component to MusicXML, adding a version tag, but not wrapping it up as a full score.
view_in_software(command)	Uses the given terminal command to create a score out of this musical object, and open it in music notation software.

Attributes

divisions	In MusicXML, "divisions" is a measure attribute that specifies a smallest metric subdivision for the measure in terms of how many would fit in a quarter note.
length_in_divisions	Length in terms of subdivisions.
true_length	True length in terms of the number of quarter notes, taking into tuplet time modification.
written_length	Written length in terms of the number of quarter notes.

property divisions: int

In MusicXML, “divisions” is a measure attribute that specifies a smallest metric subdivision for the measure in terms of how many would fit in a quarter note. So if divisions is 8, then a dotted quarter would have duration 12. When we create a duration, divisions is automatically set to the the smallest number with which we could accurately specify this duration. So a dotted quarter note would get set to 2 (since it’s three 8th notes), and a triplet quarter would get set to 3 (since it’s 2/3rds of a quarter note). Later, when we go to render a whole measure, the least common multiple of all of these minimum divisions for all the objects in the measure gets calculated, and the divisions attribute for all the objects gets reset to that.

property written_length: float

Written length in terms of the number of quarter notes.

property true_length: float

True length in terms of the number of quarter notes, taking into tuplet time modification. Returns 0 in the case of grace notes.

min_denominator() → int

Minimum divisor of a quarter note that would be needed to represent the duration of this note accurately. For instance, a triplet quarter note would have min_denominator 3, since it is 2/3 of a quarter.

property length_in_divisions: int

Length in terms of subdivisions. (See description of “divisions” attribute in Duration)

num_beams() → int

The number of beams needed to for a note of this duration.

classmethod from_written_length(written_length: float, tuplet_ratio=None, max_dots_allowed=4)

Constructs a Duration from a written length

Parameters:

• written_length – written length in quarter notes

• tuplet_ratio – see description in Duration constructor

• max_dots_allowed – The maximum number of dots to allow

Raise:

ValueError if the given note length is impossible with max_dots_allowed dots or fewer

classmethod from_divisor(divisor: int, num_dots=0, tuplet_ratio=None)

Constructs a Duration from a divisor

Parameters:

• divisor – the number of this duration that fit in a whole note. 4 = quarter note, 8 = 8th note, etc.

• num_dots – see description in Duration constructor

• tuplet_ratio – see description in Duration constructor

classmethod from_string(duration_string: str)

Parses various string representations into a Duration

Parameters:

duration_string – Can take a variety of forms, e.g. “dotted eighth”, “16.”

static get_note_type_and_number_of_dots(length: float, max_dots_allowed: int = 4) → tuple[str, int]

Given a length in quarter notes, get the note type and number of dots.

Parameters:

• length – length in quarter notes

• max_dots_allowed – maximum number of dots to allow

Raise:

ValueError if the given note length is impossible with max_dots_allowed dots or fewer

Returns:

tuple of (note type string, number of dots)

render() → Sequence[Element]

Renders this component to a tuple of ElementTree.Element. (The reason for making it a tuple is that musical objects like chords are represented by several notes side by side, with all but the first containing a </chord> tag.)

render_to_beat_unit_tags() → Sequence[Element]

Renders the beat unit tags needed in metronome directions.

wrap_as_score() → Score

Wraps this component in a Score so that it can be exported and viewed

export_to_file(file_path: str, pretty_print: bool = True) → None

Exports this musical object (wrapped as a score) to the given file path.

Parameters:

• file_path – The path of the file we want to write to.

• pretty_print – If True, breaks the MusicXML onto multiple lines, with indentation

to_xml(pretty_print: bool = False) → str

Renders this component to MusicXML, adding a version tag, but not wrapping it up as a full score.

Parameters:

pretty_print – If True, breaks the MusicXML onto multiple lines, with indentation

view_in_software(command: str) → None

Uses the given terminal command to create a score out of this musical object, and open it in music notation software.

Parameters:

command – The terminal command corresponding to the software with which we want to open the score.