musicscore.beat

class musicscore.beat.Beat(quarter_duration=1)[source]

Bases: MusicTree, QuarterDurationMixin, QuantizeMixin, FinalizeMixin

Parent type: Voice

Child type: Chord

Beat is the direct ancestor of chords. Each Chord is placed with an offset between 0 and beat’s quarter duration inside the beat as its child .

Quarter duration of a beat’s Chord child can exceed its own quarter duration. If a Chord is longer than the quarter duration of beat’s parent Voice, a leftover Chord will be added as leftover property to the Voice which will be added to next measure’s appropriate voice .

Beat manages splitting of each child Chord into appropriate tied Chord s if needed, for example if this chord has a non-writable quarter duration like 5/6.

The dots and tuplets are also added here to Chord or directly to their Note children.

Beaming and quantization are also further important tasks of a beat.

add_child(child: Chord) → List[Chord][source]

If child’s quarter duration is less than beat’s remaining quarter duration: child is added to the beat.

If child’s quarter duration is greater than beat’s remaining quarter duration: Chord’s _split_and_add_beatwise is method called. It is possible to add a chord with a quarter duration exceeding the beat’s quarter duration without splitting the chord. For example if the first beat in a 4/4 measure gets a chord with quarter duration 3, the chord will be added to this first beat as a child and the following two beats will be set to filled without having a child themselves and the parent Voice returns the fourth beat if its get_current_beat is called.

If child’s quarter duration exceeds the Voice’s remaining quarter duration a leftover Chord will be added to the voice and can be accessed when the next Measure is created.

Parameters:: child – Chord to be added as child
Returns:: list of split chords

fill_with_rests() → None[source]: If Beat is not filled, it will be filled with rest(s)

finalize()[source]

finalize can only be called once.

It calls finalize method of all Chord children.
Following updates are triggered: _update_note_tuplets, _update_chord_beams, quantize_quarter_durations (if get_quantized is True), _split_not_writable_chords

get_beats() → List[Beat]

MusicTree method

This method can be used for Score and Part, Measure, Staff and Voice.

Returns:: a flat list of all beats.
Return type:: List[Beat]

get_children() → List[Tree]

Tree method

Returns:: list of added children.
Return type:: List[Tree]

get_children_of_type(type) → List[Tree]

Tree method

Returns:: list of added children of type.
Return type:: List[Tree]

get_chord(*args, **kwargs) → Chord

MusicTree method

This method can be used for Score and Part, Measure, Staff, Voice and Beat

Parameters:

args – can be used instead of kwargs. A mixture of args and kwargs is not allowed.
kwargs – part_number, measure_number, staff_number, voice_number, beat_number, chord_number depending on musicscore’s class. A Staff for example needs voice_number, beat_number and chord_number while a Score needs all keyword arguments.

Return type:

Chord

get_chords() → List[Chord]

MusicTree method

This method can be used for Score and Part, Measure and Staff, Voice and Beat

Returns:: a flat list of all chords.
Return type:: List[Chord]

get_coordinates_in_tree() → str

Tree method

Returns:: 0 for root. 1, 2, … for layer 1. Other layers: x.y.z…. Example: 3.2.2 => third child of secod child of second child of the root.
Return type:: str

>>> class TestTree(Tree):
...   def _check_child_to_be_added(self, child):
...      return True
>>> root = TestTree()
>>> root.get_coordinates_in_tree()
'0'
>>> child1 = root.add_child(TestTree())
>>> child2 = root.add_child(TestTree())
>>> grandchild1 = child2.add_child(TestTree())
>>> grandchild2 = child2.add_child(TestTree())
>>> child1.get_coordinates_in_tree()
'1'
>>> child2.get_coordinates_in_tree()
'2'
>>> grandchild1.get_coordinates_in_tree()
'2.1'
>>> grandchild2.get_coordinates_in_tree()
'2.2'

get_indentation() → str

Tree method

Returns:: indentation according to level (layer number). As default it is used for creating tabs in tree_representation
Return type:: str

get_layer(level: int, key: Callable | None = None) → list

Tree method

Parameters:

level – layer number where 0 is the root.
key – An optional callable for each node in the layer.

Returns:

All nodes on this level. The leaves of branches which are shorter than the given level will be repeated on this and all following layers.

Return type:

list

get_leaves(key: Callable | None = None) → list

Tree method

Parameters:: key – An optional callable to be called on each leaf.
Returns:: nested list of leaves or values of key(leaf) for each leaf
Return type:: nested list of Tree

get_parent() → Tree

Tree method

Returns:: parent. None for root.
Return type:: Tree

get_possible_subdivisions(beat_quarter_duration: QuarterDuration | None = None) → List[int]

QuantizeMixin method

This method is used by Beat’s quantize_quarter_durations().

Possible subdivisions dictionary can be set with set_possible_subdivisions(). Keys in the subdivisions dictionary correspond to beat quarter durations (e.g. 1, 1/2 etc.) For example if get_possible_subdivisions()[1] == [3, 5, 8] a beat with a quarter duration of 1 can after quantization consists only of eighth triplets, quintuplets and 32ths. If this dictionary is not set or beat_quarter_duration as key does not exist, the parent’s possible subdivisions dictionary will be checked.

Score has a default POSSIBLE_SUBDIVISIONS dictionary which will be used if no other musicscore node on the path from self to root has its own possible subdivisions dictionary with beat_quarter_duration as a key. For setting possible subdivisions dictionary use always set_possible_subdivisions().

Parameters:: beat_quarter_duration – Used as key in possible subdivisions dictionary. If None and self is a Beat self.quarter_duration is used. If None and self is not a Beat it is set to 1.
Returns:: A list of possible subdivisions of a Beat. This is used by beat’s quantize_quarter_durations()
Return type:: List[int]

get_root() → Tree

Tree method

Returns:: root (upmost node of a tree which has no parent)
Return type:: Tree

get_subdivision()[source]

iterate_leaves() → Iterator[Tree]

Tree method

Returns:: A generator iterating over all leaves.

quantize_quarter_durations()[source]: When called the positioning of children will be quantized according to get_possible_subdivisions() This method is called by Measure

remove(child: Tree) → None

Tree method

Child’s parent will be set to None and child will be removed from list of children.

Parameters:: child –
Returns:: None

remove_children() → None

Tree method

Calls remove() on all children.

Returns:: None

replace_child(old, new, index: int = 0) → None

Tree method

Parameters:

old – child or function
new – child
index – index of old child in the list of its appearances

Returns:

None

reversed_path_to_root() → Iterator[Tree]

Tree method

Returns:: path from self upwards through all ancestors up to the root.

set_possible_subdivisions(subdivisions: list[int], beat_quarter_duration: QuarterDuration | None = None) → None

QuantizeMixin method

This method is used to set or change possible subdivisions dictionary of a beat or its ascendants. For example if get_possible_subdivisions()[1] == [3, 5, 8] a beat with a quarter duration of 1 can after quantization consists only of eighth triplets, quintuplets and 32ths.

Parameters:

subdivisions – list of possible subdivisions to be used in musicscore.beat.Beat.quantize_quarter_durations()
beat_quarter_duration – If None and self is a Beat self.quarter_duration is used. If None and self is not a Beat it is set to 1.

Returns:

None

set_subdivision(val)[source]

traverse() → Iterator[Tree]

Tree method

Traverse all tree nodes.

Returns:: generator

tree_representation(key: Callable | None = None, tab: Callable | None = None) → str

Tree method

Parameters:

key – An optional callable if None compact_repr property of each node is called.
tab – An optional callable if None get_indentation() method of each node is called.

Returns:

a representation of all nodes as string in tree form.

Return type:

str

property compact_repr: str

Tree property

Returns:: compact representation of a node. Default is the string representation. This property is used as default in the tree_representation method and can be customized in subclasses to get the most appropriate representation.
Return type:: str

default_show_accidental_signs = 'modern': Class attribute of MusicTree

property filled_quarter_duration

Returns:: How much of beat’s quarter duration is already filled.
Return type:: QuarterDuration

property get_quantized: bool

QuantizeMixin property

If get_quantized is set to None the first get_quantized of ancestors which is False or True will be returned.
If musicscore.score.Score.get_quantized is set to None it will be converted to False
musicscore.measure.Measure.finalize() loops over all beats. If musicscore.beat.Beat.get_quantized returns True musicscore.beat.Beat.quantize_quarter_durations() is called.

Type:: Optional[bool]
Return type:: bool

property is_filled: bool

Returns:: True if no children can be added anymore. If False there is still room for further child or children.
Return type:: bool

property is_leaf: bool

Tree property

Returns:: True if self has no children. False if self has one or more children.
Return type:: bool

property is_root: bool

Tree property

Returns:: True if self has no parent, else False.
Return type:: bool

property level: int

Tree property

Returns:: 0 for root, 1, 2 etc. for each layer of children
Return type:: nonnegative int

>>> class TestTree(Tree):
...   def _check_child_to_be_added(self, child):
...      return True
>>> root = TestTree()
>>> root.level
0
>>> ch = root.add_child(TestTree()).add_child(TestTree()).add_child(TestTree())
>>> ch.level
3

property next: Tree | None

Tree property

Returns:: next sibling. None if this is the last current child of the parent.
Return type:: Tree

property number: int

Returns:: Beat’s number inside its parent’s musicscore.voice.Voice
Return type:: int

property offset: QuarterDuration

Returns:: Offset in Beat’s parent musicscore.voice.Voice
Return type:: QuarterDuration

property previous: Tree | None

Tree property

Returns:: previous sibling. None if this is the first child of the parent.
Return type:: Tree

property quarter_duration: QuarterDuration

Set and get the duration measured in quarters.

Setting value can be of types int, float, quicktions.Fraction, QuarterDuration

property show_accidental_signs: str

MusicTree property

If show_accidental_signs is set to None the first get_quantized of ancestors which is False or True will be returned.
If show_accidental_signs is set to None it will be converted to default_show_accidental_signs
Possible show_accidental_signs are: None, ‘modern’, ‘traditional’

Type:: Optional[str]
Return type:: str

property up: Tree

Tree property

Returns:: get_parent()
Return type:: Tree

musicscore.beat.beam_chord_group(chord_group: List[Chord]) → None[source]: Function for setting beams of a list of chords (chord_group). This function is used to create or update beams inside a beat. Chord types must be set first.

musicscore.beat.get_chord_group_subdivision(chords)[source]