amads.core.basics

amads.core.basics#

Quick overview: The basic hierarchy of a score is shown here. Each level of this hierarchy can contain 0 or more instances of the next level. Levels are optional, allowing for more note-list-like representations:

Score (one per musical work or movement)

Part (one per instrument)

Staff (usually 1, but e.g. 2 for grand staff)

Measure (one for each measure)

(Measure can contain multiple instances of the following) Note Rest Chord

Note (one for each note of the chord)

KeySignature TimeSignature

A “flattened” score looks like this:

Score (one per musical work or movement)

Part (one per instrument): Note (no other instances allowed, no ties)

Score, Part, Staff, Measure, and Chord are all EventGroups and their constructors can take a list of Events as their content.

The safe way to construct a score is to fully specify onsets for every Event. These onsets are absolute and will not be adjusted provided that the parent onset is also specified.

However, for convenience and to support simple constructs such as: Chord(Note(pitch=60), Note(pitch=64)),

onsets are optional and default to None. To make this simple example work: 1) Concurrences (Score, Part, and Chord) replace unspecified (None)

onsets in their immediate content with the parent’s onset (or 0 if it is None).

Sequences (Staff, Measure) replace unspecified (None) onsets in their immediate content starting with the parent’s onset (or 0 if None) for the first event and the offset of the previous Event for subsequent events.
To handle the construction of nested Events, when an unspecified (None) onset of an EventGroup is replaced, the entire subtree of its content is shifted by the same amount. E.g. if a Chord is constructed with Notes with unspecified onsets, the Notes onsets will initially be replaced with zeros. Then, if the Chord onset is unspecified (None) and the Chord is passed in the content of a Measure and the Chord onset is replaced with 1.0, then the Notes are shifted to 1.0. If the Measure is then passed in the content

of a Staff, the Measure and all its content might be shifted again.

class amads.core.basics.Chord(*args, parent=None, onset=None, duration=None)[source]#

A Chord is a collection of Notes, normally with onsets equal to that of the chord and the same durations but distinct key_nums, but none of this is enforced. The order of notes is arbitrary. Normally, a Chord is a member of a Measure. There is no requirement that simultaneous or overlapping notes be grouped into Chords, so the Chord class is merely an optional element of music structure representation.

See EventGroup documentation on construction styles.

Representation note: An alternative representation would be to subclass Note and allow a list of pitches, which has the advantage of enforcing the shared onsets and durations. However, there can be ties connected differently to each note within the Chord, thus we use a Concurrence with Note objects as elements. Each Note.tie can be None (no tie) or tie to a Note in another Chord or Measure.

Parameters:

*args (Event) – The Event objects to be added to the group. Content events with onsets of None are set to the offset of the chord, or zero if onset is None. (Defaults to None)
parent (Optional[EventGroup], optional) – The containing object or None. Must be passed as a keyword parameter due to *args. (Defaults to None)
onset (Optional[float], optional) – The onset (start) time. None means unknown, to be set when Sequence is added to a parent. Must be passed as a keyword parameter due to *args. (Defaults to None)
duration (Optional[float], optional) – The duration in quarters or seconds. (Defaults to None) (If duration is omitted or None, the duration is set so that self.offset ends at the max offset of args, or 0 if there is no content.) Must be passed as a keyword parameter due to *args. (Defaults to None)
content (Optional[list[Event]], optional) – A list of Event objects to be added to the group. Content events with onsets of None are set to the offset of the chord, or zero if onset is None. Must be passed as a keyword parameter due to *args. (Defaults to None)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time.

Type:: Optional[float]

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this collection.

Type:: list[Event]

is_measured()[source]#: Test if Chord conforms to strict hierarchy of Chord-Note

show(indent=0) → Chord[source]#

Display the Chord information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The Chord instance itself.
Return type:: Chord

class amads.core.basics.Concurrence(parent=None, onset=None, duration=None, content=None)[source]#

Concurrence represents a temporally simultaneous collection of music events (but if elements have a non-zero onset, a Concurrence can represent events organized over time). Thus, the main distinction between Concurrence and Sequence is that a Sequence can be constructed with pack=True to force sequential timing of the content. Note that a Sequence can have overlapping or entirely simultaneous Events as well.

Parameters:

parent (Optional[EventGroup], optional) – The containing object or None. (Defaults to None)
onset (Optional[float], optional) – The onset (start) time. None means unknown, to be set when Sequence is added to a parent. (Defaults to None)
duration (Optional[float], optional) – The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset in content, or 0 if there is no content.)
content (Optional[list[Event]], optional) – A list of Event objects to be added to the group. Content events with onsets of None are set to the offset of the concurrence, or zero if onset is None. (Defaults to None)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time. None represents “unknown” and to be determined when this object is added to a parent.

Type:: Optional[float]

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this collection.

Type:: list[Event]

pack(onset=0.0) → None[source]#

Adjust the content to onsets starting with the onset parameter (defaults to 0). The duration of self is set to the maximum offset of the content. This method essentially arranges the content to eliminate gaps. pack() works recursively on elements that are EventGroups.

Parameters:: onset (float, optional) – The onset (start) time for this object. (Defaults to 0)
Returns:: duration of self
Return type:: float

show(indent=0, label='Concurrence') → Concurrence[source]#

Display the Concurrence information.

Parameters:

indent (int, optional) – The indentation level for display. (Defaults to 0)
label (str, optional) – The label for the Concurrence. (Defaults to “Concurrence”)

Returns:

The Concurrence instance itself.

Return type:

Concurrence

class amads.core.basics.Event(parent, onset, duration)[source]#

A superclass for Note, Rest, EventGroup, and just about anything that takes place in time.

Parameters:

parent (Optional[EventGroup]) – The containing object or None.
onset (float) – The onset (start) time.
duration (float) – The duration of the event in quarters or seconds.

parent#

The containing object or None.

Type:: Optional[Event]

_onset#

The onset (start) time.

Type:: float

duration#

The duration of the event in quarters or seconds.

Type:: float

copy(parent=None) → Event[source]#

Return a deep copy of the Event instance except for the parent, which may be provided as an argument. See also copyempty to copy an EventGroup without the content.

Returns:: A deep copy (except for parent) of the Event instance.
Return type:: Event
Parameters:: parent (Optional[EventGroup])

get(property, default=None)[source]#

Get the value of a property from this Event.

Parameters:

property (str) – The name of the property to get.
default (Any, optional) – The default value to return if the property is not found. (Defaults to None)

Returns:

The value of the specified property.

Return type:

Any

has(property) → bool[source]#

Check if the Event has a specific property.

Parameters:: property (str) – The name of the property to check.
Returns:: True if the property exists, False otherwise.
Return type:: bool

property offset: float#

Retrieve the global offset (stop) time.

Returns:: The global offset (stop) time.
Return type:: float

property onset: float#

Retrieve the onset (start) time.

Returns:: The onset (start) time.
Return type:: float

property part: Part | None#

Retrieve the Part containing this event

Returns:: The Part containing this event or None if not found.
Return type:: Optional[Part]

property score: Score | None#

Retrieve the Score containing this event

Returns:: The Score containing this event or None if not found.
Return type:: Optional[Score]

set(property, value)[source]#

Set a property on this Event. Every event can be extended with additional properties.

Parameters:

property (str) – The name of the property to set.
value (Any) – The value to assign to the property.

property staff: Staff | None#

Retrieve the Staff containing this event

Returns:: The Staff containing this event or None if not found.
Return type:: Optional[Staff]

property units_are_quarters: bool#

Check if the times are in quarters.

Returns:: True if the event’s times in quarters and there is a parent.
Return type:: bool

property units_are_seconds: bool#

Check if the times are in seconds.

Returns:: True if the event’s times in seconds and there is a parent.
Return type:: bool

class amads.core.basics.EventGroup(parent, onset, duration, content, pack=False)[source]#

An EventGroup is a collection of Event objects. This is an abstract class. Use one of the subclasses: Score, Part, Staff, Measure or Chord.

Normally, you create any EventGroup (Chord, Measure, Staff, Part, Score) with no content, then add content, either in bulk by simply setting the content attribute to a list where list elements are Events whose parent attributes have been set to the group, or one event at a time, by calling the group’s insert method. (This will change the event parent from None to the group.) In this style, it is recommended to specify all onsets and durations explicitly, including the onset of the group itself.

Alternatively, you can provide content when the group is constructed. Chord, Measure, Staff, Part, and Score all have *args parameters so that you can write something like

Score(Part(Staff(Measure(Note(…), Note(…)),
Measure(Note(…), Note(…)))))

In this case, it is recommended that you leave the onsets of content and chord unknown (None, the default). Then, as each event or group becomes content for a parent, the onsets will be set automatically, organizing events sequentially (in Measures and Staves) or concurrently (in Chords, Parts, Scores).

The use of unknown (None) onsets is offered as a convenience for simple cases. The main risk is that onsets are considered to be relative to the group onset if the group onset is not known. E.g. if onsets are specified within the content of an EventGroup (Chord, Measure, Staff, Part, Score) but the group onset is unknown (None), and then you assign (or a parent assigns) an onset value to the group, the content onsets (even “known” ones) will all be shifted by the assigned onset. This happens only when changing an onset from None to a number. Subsequent changes to the group onset will not adjust the content onsets, which are considered absolute times once the group onset is known.

Parameters:

parent (Optional[EventGroup]) – The containing object or None.
onset (float) – The onset (start) time.
duration (float) – The duration in quarters or seconds.
content (Optional[list]) – A list of Event objects to be added to the group. The parent of each Event is set to this EventGroup, and it is an error if any Event already has a parent.
pack (bool)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time.

Type:: Optional[float]

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this collection.

Type:: list[Event]

Parameters:

pack (bool)
parent (EventGroup | None)
onset (float)
duration (float | None)
content (list[Event] | None)

emptycopy(parent=None) → EventGroup[source]#

Create a deep copy of the EventGroup except for the parent and content. The parent may be provided as an argument. This is useful for copying an EventGroup without copying its content. See also copy() to copy an EventGroup with its content.

Parameters:: parent (Optional[EventGroup]) – The new parent to insert the copied Event into.
Returns:: A deep copy of the EventGroup instance with the new parent (if any) and no content.
Return type:: EventGroup

expand_chords(parent=None) → EventGroup[source]#

Replace chords with the multiple notes they contain. Returns a deep copy with no parent unless parent is provided. Normally, you will call score.expand_chords() which returns a deep copy of Score with notes moved from each chord to the copy of the chord’s parent (a Measure or a Part). The parent parameter is primarily for internal use when expand_chords is called recursively on score content.

Parameters:: parent (EventGroup, optional) – The new parent to insert the copied EventGroup into. (Defaults to None)
Returns:: A deep copy of the EventGroup instance with all Chord instances expanded.
Return type:: EventGroup

find_all(elem_type) → Generator[Event, None, None][source]#

Find all instances of a specific type within the EventGroup. Assumes that objects of type elem_type are not nested within other objects of the same type.

Parameters:: elem_type (Type[Event]) – The type of event to search for.
Yields:: Event – Instances of the specified type found within the EventGroup.
Return type:: Generator[Event, None, None]

has_chords() → bool[source]#

Test if EventGroup (e.g. Score, Part, Staff, Measure) has any Chord objects.

Returns:: True iff the EventGroup contains any Chord objects.
Return type:: bool

has_instanceof(the_class) → bool[source]#

Test if EventGroup (e.g. Score, Part, Staff, Measure) contains any instances of the_class.

Parameters:: the_class (Type[Event]) – The class type to check for.
Returns:: True iff the EventGroup contains an instance of the_class.
Return type:: bool

has_measures() → bool[source]#

Test if EventGroup (e.g. Score, Part, Staff) has any measures.

Returns:: True iff the EventGroup contains any Measure objects.
Return type:: bool

has_rests() → bool[source]#

Test if EventGroup (e.g. Score, Part, Staff, Measure) has any Rest objects.

Returns:: True iff the EventGroup contains any Rest objects.
Return type:: bool

has_ties() → bool[source]#

Test if EventGroup (e.g. Score, Part, Staff, Measure) has any tied notes.

Returns:: True iff the EventGroup contains any tied notes.
Return type:: bool

inherit_duration() → EventGroup[source]#

Set the duration of this EventGroup according to the maximum offset (end) time of its children. If the EventGroup is empty, the duration is set to 0. This method modifies the EventGroup instance.

Returns:: The EventGroup instance (self) with updated duration.
Return type:: EventGroup

insert(event) → EventGroup[source]#

Insert an event without any changes to event.onset or self.duration. If the event is out of order, insert it just before the first element with a greater onset. The method modifies this object (self).

Parameters:: event (Event) – The event to be inserted.
Returns:: The EventGroup instance (self) with the event inserted.
Return type:: EventGroup

last() → Event | None[source]#

Retrieve the last event in the content list.

Returns:: The last event in the content list or None if the list is empty.
Return type:: Optional[Event]

list_all(elem_type) → list[Event][source]#

Find all instances of a specific type within the EventGroup. Assumes that objects of type elem_type are not nested within other objects of the same type.

Parameters:: elem_type (Type[Event]) – The type of event to search for.
Returns:: A list of all instances of the specified type found within the EventGroup.
Return type:: list[Event]

merge_tied_notes(parent=None, ignore=[]) → EventGroup[source]#

Create a new EventGroup with tied note sequences replaced by equivalent notes in each staff. Insert the new EventGroup into parent. Notes identified as being tied to are passed in ignore.

Parameters:

parent (Optional[EventGroup])
ignore (list[Note])

Return type:

EventGroup

property onset: float#

Retrieve the onset (start) time.

Returns:: The onset (start) time.
Return type:: float

remove(element) → EventGroup[source]#

Remove an element from the content list. The method modifies this object (self).

Parameters:: element (Event) – The event to be removed.
Returns:: The EventGroup instance (self) with the element removed. The returned value is not a copy.
Return type:: EventGroup

remove_rests(parent=None) → EventGroup[source]#

Remove all Rest objects. Returns a deep copy with no parent, unless parent is provided.

Parameters:: parent (EventGroup, optional) – The new parent to insert the copied Event into. (Defaults to None)
Returns:: A deep copy of the EventGroup instance with all Rest objects removed.
Return type:: EventGroup

show(indent=0, label='EventGroup') → EventGroup[source]#

Display the EventGroup information.

Parameters:

indent (int, optional) – The indentation level for display. (Defaults to 0)
label (str, optional) – The label for the EventGroup. (Defaults to “EventGroup”)

Returns:

The EventGroup instance itself.

Return type:

EventGroup

class amads.core.basics.KeySignature(parent=None, onset=0.0, keysig=0)[source]#

KeySignature is a zero-duration Event with keysig info.

Parameters:

parent (Optional[EventGroup], optional) – The containing object or None. (Defaults to None)
onset (float, optional) – The onset (start) time. An initial value of None might be assigned when the KeySignature is inserted into an EventGroup. (Defaults to None)
keysig (int, optional) – An integer representing the number of sharps (if positive) and flats (if negative), e.g. -3 for Eb major or C minor. (Defaults to 0)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time.

Type:: float

duration#

Always zero for this subclass.

Type:: float

keysig#

An integer representing the number of sharps and flats.

Type:: int

show(indent=0) → KeySignature[source]#

Display the KeySignature information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The KeySignature instance itself.
Return type:: KeySignature

class amads.core.basics.Measure(*args, parent=None, onset=None, duration=4, number=None, pack=False)[source]#

A Measure models a musical measure (bar) and can contain many object types including Note, Rest, Chord, KeySignature, Timesignature and (in theory) custom Events. Measures are elements of a Staff.

See EventGroup documentation on construction styles.

Parameters:

*args (Event) – A variable number of Event objects to be added to the group.
parent (Optional[EventGroup], optional) – The containing object or None. Must be passed as a keyword parameter due to *args. (Defaults to None)
onset (Optional[float], optional) – The onset (start) time. None means unknown, to be set when Sequence is added to a parent. Must be passed as a keyword parameter due to *args. (Defaults to None)
duration (Optional[float], optional) – The duration in quarters or seconds. Must be passed as a keyword parameter due to *args. (Defaults to 4)
number (Optional[str], optional) – A string representing the measure number. Must be passed as a keyword parameter due to *args. (Defaults to None)
pack (bool, optional) – If true, Events in *args are adjusted to form a sequence where the first event onset is the specified group onset (which defaults to 0) and the onset of other events is the offset of the previous event in the sequence. Must be passed as a keyword parameter due to *args. (Defaults to False).

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time. None represents “unknown” and to be determined when this object is added to a parent.

Type:: Optional[float]

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this Measure.

Type:: list[Event]

number#

A string representing the measure number if any.

Type:: Optional[str]

is_measured() → bool[source]#

Test if Measure conforms to strict hierarchy of: Measure-(Note or Rest or Chord) and Chord-Note

Returns:: True if the Measure conforms to normal hierarchy.
Return type:: bool

show(indent=0) → Measure[source]#

Display the Measure information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The Measure instance itself.
Return type:: Measure

class amads.core.basics.Note(parent=None, onset=None, duration=1, pitch=60, dynamic=None, lyric=None)[source]#

Note represents a musical note. It is normally an element of a Measure.

Parameters:

parent (Optional[EventGroup], optional) – The containing object or None.
onset (float, optional) – The onset (start) time. An initial value of None might be assigned when the Note is inserted into an EventGroup. (Defaults to None)
duration (float, optional) – The duration of the note in quarters or seconds. (Defaults to 1)
pitch (Union[Pitch, int], optional) – A Pitch object or an integer MIDI key number that will be converted to a Pitch object. (Defaults to C4)
dynamic (Optional[Union[int, str]], optional) – Dynamic level (MIDI velocity) or string. (Defaults to None)
lyric (Optional[str], optional) – Lyric text. (Defaults to None)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time. None represents an unspecified onset.

Type:: Optional[float]

duration#

The duration of the note in quarters or seconds. See the property tied_duration for the duration of an entire group if the note is the first of a tied group of notes.

Type:: float

pitch#

The pitch of the note.

Type:: Pitch

dynamic#

Dynamic level (MIDI velocity) or string.

Type:: Optional[Union[int, str]]

lyric#

Lyric text.

Type:: Optional[str]

tie#

The note that this note is tied to, if any.

Type:: Optional[Note]

enharmonic() → Pitch[source]#

Return a Pitch where alt is zero or has the opposite sign and where alt is minimized. E.g. enharmonic(C-double-flat) is A-sharp (not B-flat). If alt is zero, return a Pitch with alt of +1 or -1 if possible. Otherwise, return a Pitch with alt of -2.

Returns:: A Pitch object representing the enharmonic equivalent of the note.
Return type:: Pitch

property key_num: int#

Retrieve the MIDI key number of the note, e.g. C4 = 60.

Returns:: The MIDI key number of the note.
Return type:: int

lower_enharmonic() → Pitch[source]#

Return a valid Pitch with alt increased by 1 or 2, e.g. Db->C#, D->C##, D#->C###.

Returns:: A Pitch object representing the lower enharmonic equivalent of the note.
Return type:: Pitch

property name: str#: Retrieve the string representation of the pitch name, including accidentals, e.g. A# or Bb.

property name_with_octave: str#: Retrieve the string representation of the pitch name with octave, e.g. A4 or Bb3.

property octave: int#

Retrieve the octave number of the note, based on key_num. E.g. C4 is enharmonic to B#3 and represent the same (more or less) pitch, but BOTH have an octave of 4. On the other hand name() will return “C4” and “B#3”, respectively.

Returns:: The octave number of the note.
Return type:: int

property pitch_class: int#: Retrieve the pitch class of the note, e.g. 0, 1, 2, …, 11.

show(indent=0, tied=False) → Note[source]#

Show the note with its pitch name, onset, duration, and optional tie, dynamic, and lyric information.

Parameters:

indent (int, optional) – The indentation level for display. (Defaults to 0)
tied (bool)

Returns:

The Note instance itself.

Return type:

Note

simplest_enharmonic(sharp_or_flat='default') → Pitch[source]#

Return a valid Pitch with the simplest enharmonic representation. (see Pitch.simplest_enharmonic)

Parameters:: sharp_or_flat (str) – This is only relevant if the pitch needs an alteration, otherwise it is unused. The value can be “sharp” (use sharps), “flat” (use flats), and otherwise use the same enharmonic choice as the Pitch constructor.
Returns:: A Pitch object representing the enharmonic equivalent.
Return type:: Pitch

property step: str#: Retrieve the name of the pitch, e.g. A, B, C, D, E, F, G corresponding to letter names without accidentals.

property tied_duration: float#

Retrieve the duration of the note in quarters or seconds. If the note is the first note of a group of tied notes, return the duration of the entire group.

Returns:: The duration of the note in quarters or seconds.
Return type:: float

upper_enharmonic() → Pitch[source]#

Return a valid Pitch with alt decreased by 1 or 2, e.g. C#->Db, C##->D, C###->D#.

Returns:: A Pitch object representing the upper enharmonic equivalent of the note.
Return type:: Pitch

class amads.core.basics.Part(*args, parent=None, onset=0.0, duration=None, number=None, instrument=None)[source]#

A Part models a staff or staff group such as a grand staff. For that reason, a Part contains one or more Staff objects. It should not contain any other object types. Parts are normally elements of a Score. Note that in a flattened score, a Part is a collection of Notes, not Staffs, and it should be organized more sequentially than concurrently, so the default assignment of onset times may not be appropriate.

See EventGroup documentation on construction styles.

Parameters:

*args (Optional[Event], optional) – A variable number of Event objects to be added to the group.
parent (Optional[EventGroup], optional) – The containing object or None. Must be passed as a keyword parameter due to *args. (Defaults to None)
onset (Optional[float], optional) – The onset (start) time. If unknown (None), it will be set when this Part is added to a parent. Must be passed as a keyword parameter due to *args. (Defaults to None)
duration (Optional[float], optional) – The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset of args, or 0 if there is no content.) Must be passed as a keyword parameter due to *args. (Defaults to None)
number (Optional[str], optional) – A string representing the part number. (Defaults to None)
instrument (Optional[str], optional) – A string representing the instrument name. (Defaults to None)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time.

Type:: float

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this collection.

Type:: list[Event]

number#

A string representing the part number (if any). E.g. “22a”.

Type:: Union[str, None]

instrument#

A string representing the instrument name (if any).

Type:: Union[str, None]

flatten(in_place=False)[source]#

Build a flattened Part where content will consist of notes only.

Parameters:: in_place (bool, optional) – If in_place=True, assume Part already has no ties and can be modified. Otherwise, return a new Part where deep copies of tied notes are merged.

is_flat()[source]#: Test if Part is flat (contains only notes without ties).

is_measured()[source]#: Test if Part is measured. Conforms to strict hierarchy of: Part-Staff-Measure-(Note or Rest or Chord) and Chord-Note.

remove_measures(score, has_ties=True) → Part[source]#

Return a Part with all Measures removed, but preserving Staffs in the hierarchy. Notes are “lifted” from Measures to become direct content of their Staff. Uses merge_tied_notes() to copy this Part unless has_ties is False, in which case there must be no tied notes and this Part is modified.

Parameters:

score (Union[Score, None]) – The Score instance (if any) to which the new Part will be added.
has_ties (bool, optional) – If False, assume this is a copy we are free to modify, there are tied notes, and this Part is already contained by score. (Defaults to True: this Part will be copied into score.)

Returns:

A Part with all Measures removed.

Return type:

Part

show(indent=0) → Part[source]#

Display the Part information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The Part instance itself.
Return type:: Part

class amads.core.basics.Rest(parent=None, onset=None, duration=1)[source]#

Rest represents a musical rest. It is normally an element of a Measure.

Parameters:

parent (Optional[EventGroup], optional) – The containing object or None.
onset (float, optional) – The onset (start) time. An initial value of None might be assigned when the Note is inserted into an EventGroup. (Defaults to None)
duration (float, optional) – The duration of the rest in quarters or seconds. (Defaults to 1)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time. None represents an unspecified onset.

Type:: float, optional

duration#

The duration of the rest in quarters or seconds.

Type:: float

show(indent=0) → Rest[source]#

Display the Rest information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The Rest instance itself.
Return type:: Rest

class amads.core.basics.Score(*args, onset=0, duration=None, time_map=None)[source]#

A score is a top-level object representing a musical work. Normally, a Score contains Part objects, all with onsets zero.

See EventGroup documentation on construction styles.

Parameters:

*args (Event) – A variable number of Event objects to be added to the group.
onset (Optional[float], optional) – The onset (start) time. If unknown (None), onset will be set when the score is added to a parent, but normally, Scores do not have parents, so the default onset is 0. You can override this using keyword parameter (due to *args).
duration (Optional[float], optional) – The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset of args, or 0 if there is no content.) Must be passed as a keyword parameter due to *args. (Defaults to None)
time_map (TimeMap, optional) – A map from quarters to seconds (or seconds to quarters). Must be passed as a keyword parameter due to *args. (Defaults to None)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time.

Type:: float

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this collection.

Type:: list[Event]

time_map#

A map from quarters to seconds (or seconds to quarters).

Type:: TimeMap

_units_are_seconds#

True if the units are seconds, False if the units are quarters.

Type:: bool

Additional attributes may be assigned, e.g. ‘title’, ‘source_file’, ‘composer’, etc.

collapse_parts(part=None, staff=None, has_ties=True)[source]#

Merge the notes of selected Parts and Staffs into a flattened score with only one part, retaining only Notes. (Ties are merged.)

If you are using this method to extract notes by Staff, you can save some computation by performing a one-time

score = score.merge_tied_notes()

and providing the parameter has_ties=False. If has_ties is False, it is assumed without checking that part.has_ties() is False, allowing this method to skip calls to part.merge_tied_notes() for each selected part.

The flatten() method is similar. It can flatten each Part while retaining (not merging) the Parts, or it can flatten all notes into one Part. Normally, you use collapse_parts to select an individual Staff or Part and flatten it to a single note sequence.

Parameters:

part (Union[Number, str, list[int], None], optional) – If part is not None, only notes from the selected part are included. part may be an integer to match a part number, or part may be a string to match a part instrument, or part may be a list with an index, e.g. [3] will select the 4th part (because indexing is zero-based).
staff (Union[int, List[int], None], optional) – If staff is given, only the notes from selected staves are included. staff may be an integer to match a staff number, or staff may be a list with an index, e.g. [1] will select the 2nd staff. If staff is given without a part specification, an exception is raised. If staff is given and this is a flattened score (no staves), an exception is raised.
Note (The use of the form [1] for part and staff index notation)
ideal (is not)
numbers (but we need to distinguish between part)
Initially ((arbitrary labels) and part index.)
tuples (I used)

:param : :param but they are error prone. E.g. part=(0) means part=0: :param so you: :param have to write key_num_list(part=((0))). With [n]: :param you write: :param key_num_list(part=[0]) to indicate an index. This is: :param prettier and less prone to error.:

convert_to_quarters() → None[source]#

Convert the score to represent time in quarters.

Return type:: None

convert_to_seconds() → None[source]#

Convert the score to represent time in seconds.

Return type:: None

flatten(collapse=False)[source]#

Deep copy notes in a score to a flattened score consisting of only Parts containing Notes (Ties are merged.)

See collapse_parts() to select specific Parts or Staffs and flatten them.

Parameters:: collapse (bool, optional) – If collapse is True, multiple parts are collapsed into a single part, and notes are ordered according to onset times. The resulting score contains one or more Parts, each containing only Notes.

classmethod from_melody(pitches, durations=1.0, iois=None, onsets=None) → Score[source]#

Create a Score from a melody specified as a list of pitches and optional timing information.

Parameters:

pitches (list of int or list of Pitch) – MIDI note numbers or Pitch objects for each note.
durations (float or list of float) – Durations for each note. If a scalar value, it will be repeated for all notes. Defaults to 1.0 (quarter notes).
iois (float or list of float or None, optional Inter-onset) – intervals between successive notes. If a scalar value, it will be repeated for all notes. If not provided and onsets is None, takes values from the durations argument, assuming that notes are placed sequentially without overlap.
onsets (list of float or None, optional) – Start times. Cannot be used together with iois. If both are None, defaults to using durations as IOIs.

Returns:

A new Score object containing the melody in a single part. If pitches is empty, returns a score with an empty part.

Return type:

Score

Examples

Create a simple C major scale with default timing (sequential quarter notes):

>>> score = Score.from_melody([60, 62, 64, 65, 67, 69, 71, 72])  # all quarter notes
>>> notes = score.content[0].content
>>> len(notes)  # number of notes in first part
8
>>> notes[0].key_num
60
>>> score.duration  # last note ends at t=8
8.0

Create three notes with varying durations:

>>> score = Score.from_melody(
...     pitches=[60, 62, 64],  # C4, D4, E4
...     durations=[0.5, 1.0, 2.0],
... )
>>> score.duration  # last note ends at t=3.5
3.5

Create three notes with custom IOIs:

>>> score = Score.from_melody(
...     pitches=[60, 62, 64],  # C4, D4, E4
...     durations=1.0,  # quarter notes
...     iois=2.0,  # 2 beats between each note onset
... )
>>> score.duration  # last note ends at t=5
5.0

Create three notes with explicit onsets:

>>> score = Score.from_melody(
...     pitches=[60, 62, 64],  # C4, D4, E4
...     durations=1.0,  # quarter notes
...     onsets=[0.0, 2.0, 4.0],  # onset times 2 beats apart
... )
>>> score.duration  # last note ends at t=5
5.0

get_sorted_notes()[source]#: Return a list of sorted notes with merged ties

is_flat()[source]#: Test if Score is flat. Conforms to strict hierarchy of: Score-Part-Note with no tied notes.

is_flat_and_collapsed()[source]#: Determine if score has been flattened into one part

is_measured() → bool[source]#

Test if Score is measured. Conforms to strict hierarchy of: Score-Part-Staff-Measure-(Note or Rest or Chord) and Chord-Note.

Returns:: True if the Score is measured, False otherwise.
Return type:: bool

note_containers()[source]#: Returns a list of non-empty note containers. For Measured Scores, these are the Staff objects. For Flat Scores, these are the Part objects. This is mainly useful for extracting note sequences where each staff represents a separate sequence. In a Flat Score, staves are collapsed and each Part (instrument) represents a separate sequence. This implementation also handles a mix of Parts with and without Staffs, returning a list of whichever is the direct parent of a list of Notes.

part_count()[source]#: How many parts are in this score?

remove_measures() → Score[source]#

Create a new Score with all Measures removed, but preserving Staffs in the hierarchy. Notes are “lifted” from Measures to become direct content of their Staff. The result satisfies neither is_flat() nor is_measured(), but it could be useful in preserving a separation between staves. See also collapse_parts(), which can be used to extract individual staves from a score. The result will have ties merged. (If you want to preserve ties and access the notes in a Staff, consider using find_all(Staff), and then for each staff, find_all(Note), but note that ties can cross between staves.)

Returns:: A new Score instance with all Measures removed.
Return type:: Score

show(indent=0) → Score[source]#

Display the Score information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The Score instance itself.
Return type:: Score

property units_are_quarters: bool#: True if the units are in quarters, False if in seconds.

property units_are_seconds: bool#: True if the units are in seconds, False if in quarters.

class amads.core.basics.Sequence(parent, onset=None, duration=None, content=None, pack=False)[source]#

Sequence represents a temporal sequence of music events.

Parameters:

parent (Optional[EventGroup], optional) – The containing object or None. (Defaults to None)
onset (Optional[float], optional) – The onset (start) time. None means unknown, to be set when Sequence is added to a parent. (Defaults to None)
duration (Optional[float], optional) – The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset in content, or 0 if there is no content.) (Defaults to None)
content (Optional[list[Event]], optional) – A list of Event objects to be added to the group. Content events with onsets of None are set to the offset of the previous event in the sequence. The first event onset is the specified group onset, or zero if onset is None. (Defaults to None)
pack (bool) – If true, Events in content are adjusted to form a sequence where the first event onset is the specified group onset (where None means 0) and the onsets of other events are the offsets of the previous events in the sequence. A pack=True value changes the default behavior by overriding any existing onsets in the content and setting the onset of the Sequence to the minimum onset of content. (Defaults to False)

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time. None represents “unknown” and to be determined when this object is added to a parent.

Type:: Optional[float]

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this collection.

Type:: list[Event]

property last_offset#: return the offset (end) time of the last element, or the onset (start) time if the Sequence is empty

pack(onset=0.0) → float[source]#

Adjust the content to be sequential, begining with the parameter onset (defaults to 0), and each other object at an onset equal to the offset of the previous element. The duration of self is set to the offset of the last element. This method essentially arranges the content to eliminate gaps. pack() works recursively on elements that are EventGroups.

Parameters:: onset (float, optional) – The onset (start) time for this object. (Defaults to 0)
Returns:: duration of self
Return type:: float

show(indent=0, label='Sequence') → Sequence[source]#

Display the Sequence information.

Parameters:

indent (int, optional) – The indentation level for display. (Defaults to 0)
label (str, optional) – The label for the Sequence. (Defaults to “Sequence”)

Returns:

The Sequence instance itself.

Return type:

Sequence

class amads.core.basics.Staff(*args, parent=None, onset=0, duration=None, number=None, pack=False)[source]#

A Staff models a musical staff line extending through all systems. It can also model one channel of a standard MIDI file track. A Staff normally contains Measure objects and is an element of a Part.

See EventGroup documentation on construction styles.

Parameters:

*args (Optional[Event], optional) – A variable number of Event objects to be added to the group.
parent (Optional[EventGroup]) – The containing object or None. (Defaults to None)
onset (Optional[float], optional) – The onset (start) time. If unknown (None), it will be set when this Staff is added to a parent. Must be passed as a keyword parameter due to *args. (Defaults to None)
duration (Optional[float], optional) – The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset of args, or 0 if there is no content.) Must be passed as a keyword parameter due to *args. (Defaults to None)
number (Optional[int], optional) – The staff number. Normally, a Staff is given an integer number where 1 is the top staff of the part, 2 is the 2nd, etc. Must be passed as a keyword parameter due to *args. (Defaults to None)
pack (bool, optional) – If true, Events in *args are adjusted to form a sequence where the first event onset is the specified group onset (which defaults to 0) and the onset of other events is the offset of the previous event in the sequence. Must be passed as a keyword parameter due to *args. (Defaults to False).

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time.

Type:: float

duration#

The duration in quarters or seconds.

Type:: float

content#

Elements contained within this collection.

Type:: list[Event]

number#

The staff number. Normally a Staff is given an integer number where 1 is the top staff of the part, 2 is the 2nd, etc.

Type:: Optional[int]

is_measured()[source]#: Test if Staff is measured. Conforms to strict hierarchy of: Staff-Measure-(Note or Rest or Chord) and Chord-Note)

remove_measures() → Staff[source]#

Modify Staff by removing all Measures. Notes are “lifted” from Measures to become direct content of this Staff. There is no special handling for notes tied to or from another Staff, so normally this method should be used only on a Staff where ties have been merged (see merge_tied_notes()). This method is normally called from remove_measures() in Part, which insures that this Staff is not shared, so it is safe to modify it. If called directly, the caller, to avoid unintended side effects, must ensure that this Staff is not shared data. Only Note and KeySignature objects are copied from Measures to the Staff. All other objects are removed.

Returns:: A Staff with all Measures removed.
Return type:: Staff

show(indent=0) → Staff[source]#

Display the Staff information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The Staff instance itself.
Return type:: Staff

class amads.core.basics.TimeSignature(parent=None, onset=0.0, upper=4.0, lower=4)[source]#

TimeSignature is a zero-duration Event with timesig info.

Parameters:

parent (Optional[EventGroup], optional) – The containing object or None. (Defaults to None)
onset (float, optional) – The onset (start) time. An initial value of None might be assigned when the TimeSignature is inserted into an EventGroup. (Defaults to None)
upper (float, optional) – The “numerator” of the key signature: subdivisions units per measure, a number, which may be a fraction. (Defaults to 4)
lower (int, optional) – The “denominator” of the key signature: a whole number power of 2, e.g. 1, 2, 4, 8, 16, 32, 64. (Defaults to 4) representing the symbol for one subdivision, e.g. 4 implies quarter note.

parent#

The containing object or None.

Type:: Optional[EventGroup]

onset#

The onset (start) time.

Type:: float

duration#

Always zero for this subclass.

Type:: float

upper#

The “numerator” of the key signature: subdivisions per measure.

Type:: float

lower#

The “denominator” of the key signature: a whole number power of 2.

Type:: int

show(indent=0) → TimeSignature[source]#

Display the TimeSignature information.

Parameters:: indent (int, optional) – The indentation level for display. (Defaults to 0)
Returns:: The TimeSignature instance itself.
Return type:: TimeSignature

amads.core.basics

Contents

amads.core.basics#