musicscore.beat

class musicscore.beat.Beat(quarter_duration=1, *args, **kwargs)[source]

Bases: MusicTree, SimplifiedSextuplets, 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

classmethod create_tree_from_list(tree_list_representation: list[list[Any]], represented_attribute_names: list[str]) → T

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

filter_nodes(key: Callable[[T], Any], return_value: Any) → list[T]

Tree method

>>> root.filter_nodes(lambda node: node.get_level(), 2)
[grandchild1, grandchild2, grandchild3]

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[T]

Tree method

Returns:: list of added children.

get_children_of_type(type_: type) → list[T]

Tree method

Returns:: list of added children of type.d
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_distance(reference: T | None = None) → int

>>> root.get_distance()
0
>>> greatgrandchild1.get_distance()
3
>>> greatgrandchild1.get_distance(child2)
2

get_farthest_leaf() → T

>>> root.get_farthest_leaf()
greatgrandchild1

get_layer(level: int, key: Callable[[T], Any] | None = None) → Any

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[[T], Any] | None = None) → list[Union[Any, list[Any]]]

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

>>> root.get_leaves()
[child1, [[greatgrandchild1, greatgrandchild2], grandchild2], child3, [grandchild3]]

get_level() → int

Tree

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

>>> root.get_level()
0
>>> child1.get_level()
1
>>> grandchild1.get_level()
2
>>> greatgrandchild1.get_level()
3

get_list_representation(key: Callable[[Tree[T]], Any]) → list[list[Any]]

get_number_of_layers() → int

>>> root.get_number_of_layers()
3

get_parent() → T | None

Tree method

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

get_position_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

>>> print(root.get_tree_representation(key=lambda node: node.get_position_in_tree()))
└── 0
    ├── 1
    ├── 2
    │   ├── 2.1
    │   │   ├── 2.1.1
    │   │   └── 2.1.2
    │   └── 2.2
    ├── 3
    └── 4
        └── 4.1

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_reversed_path_to_root() → list[T]

Tree method

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

>>> greatgrandchild1.get_reversed_path_to_root()
[greatgrandchild1, grandchild1, child2, root]

get_root() → T

Tree method

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

>>> greatgrandchild1.get_root() == root
True
>>> child4.get_root() == root
True
>>> root.get_root() == root
True

get_self_with_key(key: Callable[[T], Any] | None = None) → Any

get_subdivision()[source]

get_tree_representation(key: Callable[[T], Any] | None = None, space: int = 3) → str

Tree method

Parameters:: key – An optional callable if None string(node) is called.
Returns:: a representation of all nodes as string in tree form.

>>> print(root.get_tree_representation())
└── root
    ├── child1
    ├── child2
    │   ├── grandchild1
    │   │   ├── greatgrandchild1
    │   │   └── greatgrandchild2
    │   └── grandchild2
    ├── child3
    └── child4
        └── grandchild3

iterate_leaves() → Iterator[T]

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: T) → 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: T, new: T, 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

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[T]

Tree method

Traverse all tree nodes.

Returns:: generator

property content: Any

default_show_accidental_signs = 'modern'

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_first_child: bool

property is_last_child: bool

>>> t = TestTree('root')
>>> for node in t.traverse():
...    if node.name in ['root', 'child4', 'grandchild2', 'grandchild3', 'greatgrandchild1']:
...        assert node.is_last_child
...    else:
...        assert not node.is_last_child

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 next: T | 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: T | 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, fractions.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 simplified_sextuplets: bool

property up: T | None

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