partitura.score

This module defines an ontology of musical elements to represent musical scores, such as measures, notes, slurs, words, tempo and loudness directions. A score is defined at the highest level by a Part object (or a hierarchy of Part objects, in a PartGroup object). This object serves as a timeline at which musical elements are registered in terms of their start and end times.

class partitura.score.Part(id, part_name=None, part_abbreviation=None, quarter_duration=1)[source]

Bases: object

Represents a score part, e.g. all notes of one single instrument (or multiple instruments written in the same staff). Note that there may be more than one staff per score part.

Parameters:
  • id (str) – The identifier of the part. In order to be compatible with MusicXML the identifier should not start with a number.

  • part_name (str or None, optional) – Name for the part. Defaults to None

  • part_abbreviation (str or None, optional) – Abbreviated name for part

  • quarter_duration (int, optional) – The default quarter duration. See set_quarter_duration() for details.

id

See parameters

Type:

str

part_name

See parameters

Type:

str

part_abbreviation

See parameters

Type:

str

pretty()[source]

Return a pretty representation of this object.

Returns:

A pretty representation

Return type:

str

property time_signature_map

A function mapping timeline times to the beats and beat_type of the time signature at that time. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property key_signature_map

A function mappting timeline times to the key and mode of the key signature at that time. The function can take scalar values or lists/arrays of values

Returns:

The mapping function

Return type:

function

property measure_map

A function mapping timeline times to the start and end of the measure they are contained in. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property measure_number_map

A function mapping timeline times to the measure number of the measure they are contained in. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property metrical_position_map

A function mapping timeline times to their relative position in the measure they are contained in. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property beat_map

A function mapping timeline times to beat times. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property inv_beat_map

A function mapping beat times to timeline times. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property quarter_map

A function mapping timeline times to quarter times. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property inv_quarter_map

A function mapping quarter times to timeline times. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

property notes

Return a list of all Note objects in the part. This list includes GraceNote objects but not Rest objects.

Returns:

list of Note objects

Return type:

list

property notes_tied

Return a list of all Note objects in the part that are either not tied, or the first note of a group of tied notes. This list includes GraceNote objects but not Rest objects.

Returns:

List of Note objects

Return type:

list

property measures

Return a list of all Measure objects in the part

Returns:

List of Measure objects

Return type:

list

property rests

Return a list of all rest objects in the part

Returns:

List of Rest objects

Return type:

list

property repeats

Return a list of all Repeat objects in the part

Returns:

List of Repeat objects

Return type:

list

property key_sigs

Return a list of all Key Signature objects in the part

Returns:

List of Key Signature objects

Return type:

list

property time_sigs

Return a list of all Time Signature objects in the part

Returns:

List of Time Signature objects

Return type:

list

property dynamics

Return a list of all Dynamics markings in the part

Returns:

List of Dynamics objects

Return type:

list

property tempo_directions

Return a list of all tempo direction in the part

Returns:

List of TempoDirection objects

Return type:

list

property articulations

Return a list of all Articulation markings in the part

Returns:

List of Articulation objects

Return type:

list

property segments

Return a list of all segments in the part

Returns:

List of Segment objects

Return type:

list

quarter_durations(start=None, end=None)[source]

Return an Nx2 array with quarter duration (second column) and their respective times (first column).

When a start and or end time is specified, the returned array will contain only the entries within those bounds.

Parameters:
  • start (number, optional) – Start of range

  • end (number, optional) – End of range

Returns:

An array with quarter durations and times

Return type:

ndarray

property quarter_duration_map

A function mapping timeline times to quarter durations in effect at those times. The function can take scalar values or lists/arrays of values.

Returns:

The mapping function

Return type:

function

set_quarter_duration(t, quarter)[source]

Set the duration of a quarter note from timepoint t onwards.

Setting the quarter note duration defines how intervals between timepoints are related to musical durations. For example when two timepoints t1 and t2 have associated times 10 and 20 respecively, then the interval between t1 and t2 corresponds to a half note when the quarter duration equals 5 during that interval.

The quarter duration can vary throughout the part. When setting a quarter duration at time t, then that value takes effect until the time of the next quarter duration. If a different quarter duration was already set at time t, it wil be replaced.

Note setting the quarter duration does not change the timepoints, only the relation to musical time. For illustration: in the example above, when changing the current quarter duration from 5 to 10, a note that starts at t1 and ends at t2 will change from being a half note to being a quarter note.

Parameters:
  • t (int) – Time at which to set the quarter duration

  • quarter (int) – The quarter duration

get_point(t)[source]

Return the TimePoint object with time t, or None if there is no such object.

get_or_add_point(t)[source]

Return the TimePoint object with time t; if there is no such object, create it, add it to the time line, and return it.

Parameters:

t (int) – Time value t

Returns:

a TimePoint object with time t

Return type:

TimePoint

add(o, start=None, end=None)[source]

Add an object to the timeline.

An object can be added by start time, end time, or both, depending on which of the start and end keywords are provided. If neither is provided this method does nothing.

start and end should be non-negative integers.

Parameters:
  • o (TimedObject) – Object to be removed

  • start (int, optional) – The start time of the object

  • end (int, optional) – The end time of the object

remove(o, which='both')[source]

Remove an object from the timeline.

An object can be removed by start time, end time, or both.

Parameters:
  • o (TimedObject) – Object to be removed

  • which ({'start', 'end', 'both'}, optional) – Whether to remove o as a starting object, an ending object, or both. Defaults to ‘both’.

iter_all(cls=None, start=None, end=None, include_subclasses=False, mode='starting')[source]

Iterate (in direction of increasing time) over all instances of cls that either start or end (depending on mode) in the interval start to end. When start and end are omitted, the whole timeline is searched.

Parameters:
  • cls (class, optional) – The class of objects to iterate over. If omitted, iterate over all objects in the part.

  • start (TimePoint, optional) – The start of the interval to search. If omitted or None, the search starts at the start of the timeline. Defaults to None.

  • end (TimePoint, optional) – The end of the interval to search. If omitted or None, the search ends at the end of the timeline. Defaults to None.

  • include_subclasses (bool, optional) – If True also return instances that are subclasses of cls. Defaults to False.

  • mode ({'starting', 'ending'}, optional) – Flag indicating whether to search for starting or ending objects. Defaults to ‘starting’.

Yields:

object – Instances of the specified type.

apply()[source]

Apply all changes to the timeline for objects like octave Shift.

property last_point

The last TimePoint on the timeline, or None if the timeline is empty.

Return type:

TimePoint

property first_point

The first TimePoint on the timeline, or None if the timeline is empty.

Return type:

TimePoint

note_array(**kwargs)[source]

Create a structured array with note information from a Part object.

Parameters:
  • include_pitch_spelling (bool (optional)) – If True, includes pitch spelling information for each note. Default is False

  • include_key_signature (bool (optional)) – If True, includes key signature information, i.e., the key signature at the onset time of each note (all notes starting at the same time have the same key signature). Default is False

  • include_time_signature (bool (optional)) – If True, includes time signature information, i.e., the time signature at the onset time of each note (all notes starting at the same time have the same time signature). Default is False

  • include_metrical_position (bool (optional)) – If True, includes metrical position information, i.e., the position of the onset time of each note with respect to its measure (all notes starting at the same time have the same metrical position). Default is False

  • include_grace_notes (bool (optional)) – If True, includes grace note information, i.e. if a note is a grace note and the grace type “” for non grace notes). Default is False

  • include_divs_per_quarter (bool (optional)) – If True, includes the number of divs per quarter note. Default is False

  • Returns

  • note_array (structured array) –

rest_array(include_pitch_spelling=False, include_key_signature=False, include_time_signature=False, include_metrical_position=False, include_grace_notes=False, include_staff=False, collapse=False)[source]

Create a structured array with rest information from a Part object.

Parameters:
  • include_pitch_spelling (bool (optional)) – If True, includes pitch spelling information for each rest, i.e. all information is 0. Default is False

  • include_key_signature (bool (optional)) – If True, includes key signature information, i.e., the key signature at the onset time of each rest (all notes starting at the same time have the same key signature). Default is False

  • include_time_signature (bool (optional)) – If True, includes time signature information, i.e., the time signature at the onset time of each note (all notes starting at the same time have the same time signature). Default is False

  • include_metrical_position (bool (optional)) – If True, includes metrical position information, i.e., the position of the onset time of each rest with respect to its measure (all notes starting at the same time have the same metrical position). Default is False

  • include_grace_notes (bool (optional)) – If True, includes returns empty strings as type and false.

  • feature_functions (list or str) – A list of feature functions. Elements of the list can be either the functions themselves or the names of a feature function as strings (or a mix). The feature functions specified by name are looked up in the featuremixer.featurefunctions module.

  • Returns

  • rest_array (structured array) –

set_musical_beat_per_ts(mbeats_per_ts={})[source]

Set the number of musical beats for each time signature. If no musical beat is specified for a certain time signature, the default one is used, i.e. 2 for 6/X, 3 for 9/X, 4 for 12/X, and the number of beats for the others ts. Each musical beat has equal duration.

Parameters:

mbeats_per_ts (dict, optional) – A dict where the keys are time signature strings (e.g. “3/4”) and the values are the number of musical beats. If a certain time signature is not specified, the defaults values are used. Defaults to an empty dict.

use_musical_beat(mbeats_per_ts={})[source]

Consider the musical beat as the reference for all elements that concern the number and position of beats. An optional parameter can set the number of musical beats for specific time signatures, otherwise the default values are used.

Parameters:

mbeats_per_ts (dict, optional) – A dict where the keys are time signature strings (e.g. “3/4”) and the values are the number of musical beats. If a certain time signature is not specified, the defaults values are used. Defaults to an empty dict.

use_notated_beat()[source]

Consider the notated beat (numerator of time signature) as the reference for all elements that concern the number and position of beats. It also reset the number of musical beats for each time signature to default values.

class partitura.score.TimePoint(t, quarter=None)[source]

Bases: ComparableMixin

A TimePoint represents a temporal position within a Part.

TimePoints are used to keep track of the starting and ending of musical elements in the part. They are created automatically when adding musical elements to a part using its add() method, so there should be normally no reason to instantiate TimePoints manually.

Parameters:
  • t (int) – The time associated to this TimePoint. Should be a non- negative integer.

  • quarter (int) – The duration of a quarter note at this TimePoint

t

See parameters

Type:

int

quarter

See parameters

Type:

int

starting_objects

A dictionary where the musical objects starting at this time are grouped by class.

Type:

dictionary

ending_objects

A dictionary where the musical objects ending at this time are grouped by class.

Type:

dictionary

prev

The preceding TimePoint (or None if there is none)

Type:

TimePoint

next

The succeding TimePoint (or None if there is none)

Type:

TimePoint

add_starting_object(obj)[source]

Add object obj to the list of starting objects.

remove_starting_object(obj)[source]

Remove object obj from the list of starting objects.

remove_ending_object(obj)[source]

Remove object obj from the list of ending objects.

add_ending_object(obj)[source]

Add object obj to the list of ending objects.

iter_starting(cls, include_subclasses=False)[source]

Iterate over all objects of type cls that start at this time point.

Parameters:
  • cls (class) – The type of objects to iterate over

  • include_subclasses (bool, optional) – When True, include all objects of all subclasses of cls in the iteration. Defaults to False.

Yields:

cls – Instance of type cls

iter_ending(cls, include_subclasses=False)[source]

Iterate over all objects of type cls that end at this time point.

Parameters:
  • cls (class) – The type of objects to iterate over

  • include_subclasses (bool, optional) – When True, include all objects of all subclasses of cls in the iteration. Defaults to False.

Yields:

cls – Instance of type cls

iter_prev(cls, eq=False, include_subclasses=False)[source]

Iterate backwards in time from the current timepoint over starting object(s) of type cls.

Parameters:
  • cls (class) – Class of objects to iterate over

  • eq (bool, optional) – If True start iterating at the current timepoint, rather than its predecessor. Defaults to False.

  • include_subclasses (bool, optional) – If True include subclasses of cls in the iteration. Defaults to False.

Yields:

cls – Instances of cls

iter_next(cls, eq=False, include_subclasses=False)[source]

Iterate forwards in time from the current timepoint over starting object(s) of type cls.

Parameters:
  • cls (class) – Class of objects to iterate over

  • eq (bool, optional) – If True start iterating at the current timepoint, rather than its successor. Defaults to False.

  • include_subclasses (bool, optional) – If True include subclasses of cls in the iteration. Defaults to False.

Yields:

cls – Instances of cls

class partitura.score.TimedObject[source]

Bases: ReplaceRefMixin

This is the base class of all classes that have a start and end point. The start and end attributes initialized to None, and are set/unset when the object is added to/removed from a Part, using its add() and remove() methods, respectively.

start

Start time of the object

Type:

TimePoint

end

End time of the object

Type:

TimePoint

property duration

The duration of the timed object in divisions. When either the start or the end property of the object are None, the duration is None.

Return type:

int or None

class partitura.score.GenericNote(id=None, voice=None, staff=None, symbolic_duration=None, articulations=None, ornaments=None, doc_order=None)[source]

Bases: TimedObject

Represents the common aspects of notes, rests, and unpitched notes.

Parameters:
  • id (str, optional (default: None)) – A string identifying the note. To be compatible with the MusicXML format, the id must be unique within a part and must not start with a number.

  • voice (int, optional) – An integer representing the voice to which the note belongs. Defaults to None.

  • staff (str, optional) – An integer representing the staff to which the note belongs. Defaults to None.

  • doc_order (int, optional) – The document order index (zero-based), expressing the order of appearance of this note (with respect to other notes) in the document in case the Note belongs to a part that was imported from MusicXML. Defaults to None.

property symbolic_duration

The symbolic duration of the note.

This property returns a dictionary specifying the symbolic duration of the note. The dictionary may have the following keys:

  • type : the note type as a string, e.g. ‘quarter’, ‘half’

  • dots : an integer specifying the number of dots. When this key is missing it means there are no dots.

  • actual_notes : Specifies the number of actual notes in a rhythmical tuplet. Used in conjunction with normal_notes.

  • normal_notes : Specifies the normal number of notes in a rhythmical tuplet. For example a triplet of eights in the time of two eights would correspond to actual_notes=3, normal_notes=2.

The symbolic duration dictionary of a note can either be set manually (for example by specifying the symbolic_duration constructor keyword argument), or left unspecified (i.e. None). In the latter case the symbolic duration is estimated dynamically based on the note start and end times. Note that this latter case is generally preferrable because it ensures that the symbolic duration is consistent with the numeric duration.

If the symbolic duration cannot be estimated from the numeric duration None is returned.

Returns:

A dictionary specifying the symbolic duration of the note, or None if the symbolic duration could not be estimated from the numeric duration.

Return type:

dict or None

property end_tied

The Timepoint corresponding to the end of the note, or— when this note belongs to a group of tied notes—the end of the last note in the group.

Returns:

End of note

Return type:

TimePoint

property duration_tied

Time difference of the start of the note to the end of the note, or—when this note belongs to a group of tied notes— the end of the last note in the group.

Returns:

Duration of note

Return type:

int

property duration_from_symbolic

Return the numeric duration given the symbolic duration of the note and the quarter_duration in effect.

Return type:

int or None

property tie_prev_notes

TODO

Returns:

Description of return value

Return type:

type

property tie_next_notes

TODO

Returns:

Description of return value

Return type:

type

iter_chord(same_duration=True, same_voice=True)[source]

Iterate over notes with coinciding start times.

Parameters:
  • same_duration (bool, optional) – When True limit the iteration to notes that have the same duration as the current note. Defaults to True.

  • same_voice (bool, optional) – When True limit the iteration to notes that have the same voice as the current note. Defaults to True.

Yields:

GenericNote

class partitura.score.Note(step, octave, alter=None, beam=None, **kwargs)[source]

Bases: GenericNote

Subclass of GenericNote representing pitched notes.

Parameters:
  • step ({'C', 'D', 'E', 'F', 'G', 'A', 'B'}) – The note name of the pitch (in upper case). If a lower case note name is given, it will be converted to upper case.

  • octave (int) – An integer representing the octave of the pitch

  • alter (int, optional) –

    An integer (or None) representing the alteration of the pitch as follows:

    -2

    double flat

    -1

    flat

    0 or None

    unaltered

    1

    sharp

    2

    double sharp

    Defaults to None.

property midi_pitch

The midi pitch value of the note (MIDI note number). C4 (middle C, in german: c’) is note number 60.

Returns:

The note’s pitch as MIDI note number.

Return type:

integer

property alter_sign

The alteration of the note

Return type:

str

class partitura.score.UnpitchedNote(step, octave, beam=None, notehead=None, noteheadstyle=True, **kwargs)[source]

Bases: GenericNote

Subclass of GenericNote representing unpitched notes.

Parameters:

Parameters

note name is given, it will be converted to upper case.

octaveint

An integer representing the octave of the pitch

noteheadstring

A string representing the notehead. Defaults to None

noteheadstylebool

A boolean indicating whether the notehead is filled. Defaults to true

property midi_pitch

The midi pitch value of the note (MIDI note number).

Returns:

The note’s position as MIDI note number.

Return type:

integer

class partitura.score.Rest(hidden=False, *args, **kwargs)[source]

Bases: GenericNote

A subclass of GenericNote representing a rest.

class partitura.score.Beam(id=None)[source]

Bases: TimedObject

Represent beams (for MEI)

class partitura.score.GraceNote(grace_type, *args, steal_proportion=None, **kwargs)[source]

Bases: Note

A subclass of Note representing a grace note.

Parameters:
  • grace_type ({'grace', 'acciaccatura', 'appoggiatura'}) – The type of grace note. Use ‘grace’ for a unspecified grace note type.

  • steal_proportion (float, optional) – The proportion of the previous (acciaccatura) or next (appoggiatura) note duration that is occupied by the grace note. Defaults to None.

main_note

The (non-grace) note to which this grace note belongs.

Type:

Note

grace_seq_len

The length of the sequence of grace notes to which this grace note belongs.

Type:

list

iter_grace_seq(backwards=False)[source]

Iterate over this and all subsequent/preceding grace notes, excluding the main note.

Parameters:

backwards (bool, optional) – When True, iterate over preceding grace notes. Otherwise iterate over subsequent grace notes. Defaults to False.

Yields:

GraceNote

class partitura.score.Page(number=0)[source]

Bases: TimedObject

A page in a musical score. Its start and end times describe the range of musical time that is spanned by the page.

Parameters:

number (int, optional) – The number of the system. Defaults to 0.

number

See parameters

Type:

int

class partitura.score.System(number=0)[source]

Bases: TimedObject

A system in a musical score. Its start and end times describe the range of musical time that is spanned by the system.

Parameters:

number (int, optional) – The number of the system. Defaults to 0.

number

See parameters

Type:

int

class partitura.score.Clef(staff, sign, line, octave_change)[source]

Bases: TimedObject

Clefs associate the lines of a staff to musical pitches.

Parameters:
  • staff (int, optional) – The number of the staff to which this clef belongs.

  • sign ({'G', 'F', 'C', 'percussion', 'TAB', 'jianpu', 'none'}) – The sign of the clef

  • line (int) – The staff line at which the sign is positioned

  • octave_change (int) – The number of octaves to shift the pitches up (postive) or down (negative)

staff

See parameters

Type:

int

sign

See parameters

Type:

{‘G’, ‘F’, ‘C’, ‘percussion’, ‘TAB’, ‘jianpu’, ‘none’}

line

See parameters

Type:

int

octave_change

See parameters

Type:

int

class partitura.score.Slur(start_note=None, end_note=None)[source]

Bases: TimedObject

Slurs indicate musical grouping across notes.

Parameters:
  • start_note (Note, optional) – The note at which this slur starts. Defaults to None.

  • end_note (Note, optional) – The note at which this slur ends. Defaults to None.

start_note

See parameters

Type:

Note or None

end_note

See parameters

Type:

Note or None

class partitura.score.Tuplet(start_note=None, end_note=None)[source]

Bases: TimedObject

Tuplets indicate musical grouping across notes.

Parameters:
  • start_note (Note, optional) – The note at which this tuplet starts. Defaults to None.

  • end_note (Note, optional) – The note at which this tuplet ends. Defaults to None.

start_note

See parameters

Type:

Note or None

end_note

See parameters

Type:

Note or None

class partitura.score.Repeat[source]

Bases: TimedObject

Repeats represent a repeated section in the score, designated by its start and end times.

class partitura.score.DaCapo[source]

Bases: TimedObject

A Da Capo sign.

class partitura.score.Fine[source]

Bases: TimedObject

A Fine sign.

class partitura.score.DalSegno[source]

Bases: TimedObject

A Dal Segno sign.

class partitura.score.Segno[source]

Bases: TimedObject

A Segno sign.

class partitura.score.ToCoda[source]

Bases: TimedObject

A To Coda sign.

class partitura.score.Coda[source]

Bases: TimedObject

A Coda sign.

class partitura.score.Fermata(ref=None)[source]

Bases: TimedObject

A Fermata sign.

Parameters:

ref (TimedObject or None, optional) – An object to which this fermata applies. In practice this is a Note or a Barline. Defaults to None.

ref

See parameters

Type:

TimedObject or None

class partitura.score.Ending(number)[source]

Bases: TimedObject

Class that represents one part of a 1—2— type ending of a musical passage (a.k.a Volta brackets).

Parameters:

number (int) – The number associated to this ending

number

See parameters

Type:

int

class partitura.score.Barline(style)[source]

Bases: TimedObject

Class that represents the style of a barline

class partitura.score.Measure(number=None, name=None)[source]

Bases: TimedObject

A measure

Parameters:
  • number (int) – The running count independent of measure regularity/ volta endings, continuously counting up all measures in a musicxml score file and always starting from one.

  • name (string, optional) – The ID of the measure in a given musicxml score file. Can be a non-number in case of volta endings, irregular measures (i.e., pickup measures in the middle of the piece). Defaults to None

number

See parameters

Type:

int

name

See parameters

Type:

str

property page

The page number on which this measure appears, or None if there is no associated page.

Return type:

int or None

property system

The system number in which this measure appears, or None if there is no associated system.

Return type:

int or None

class partitura.score.TimeSignature(beats, beat_type)[source]

Bases: TimedObject

A time signature.

Parameters:
  • beats (int) – The number of beats in a measure (the numerator).

  • beat_type (int) – The note type that defines the beat unit (the denominator). (4 for quarter notes, 2 for half notes, etc.)

  • musical_beats (int) – The number of beats according to musicologial standards (2 if beats is 2 or 6; 3 if beats is 3 or 9; 4 if beats is 4 or 12; else beats)

beats

See parameters

Type:

int

beat_type

See parameters

Type:

int

musical_beat

See parameters

Type:

int

class partitura.score.Tempo(bpm, unit=None)[source]

Bases: TimedObject

A tempo indication.

Parameters:
  • bpm (number) – The tempo indicated in rate per minute

  • unit (str or None, optional) – The unit to which the specified rate correspnds. This is a string that expreses a duration category, such as “q” for quarter “h.” for dotted half, and so on. When None, the unit is assumed to be quarters. Defaults to None.

bpm

See parameters

Type:

number

unit

See parameters

Type:

str or None

property microseconds_per_quarter

The number of microseconds per quarter under this tempo.

This is useful for MIDI representations.

Return type:

int

class partitura.score.Staff(number, lines=5)[source]

Bases: TimedObject

A staff.

Parameters:
  • number (int) – The staff number

  • lines (int, optional (default: 5)) –

number

See parameters

Type:

int

class partitura.score.KeySignature(fifths, mode)[source]

Bases: TimedObject

Key signature.

Parameters:
  • fifths (number) – Number of sharps (positive) or flats (negative)

  • mode (str) – Mode of the key, either ‘major’ or ‘minor’

fifths

See parameters

Type:

number

mode

See parameters

Type:

str

property name

The key signature name, where the root is uppercase, and an trailing ‘m’ indicates minor modes (e.g. ‘Am’, ‘G#’).

Returns:

The key signature name

Return type:

str

class partitura.score.Transposition(diatonic, chromatic)[source]

Bases: TimedObject

Represents a <transpose> tag that tells how to change all (following) pitches of that part to put it to concert pitch (i.e. sounding pitch).

Parameters:
  • diatonic (int) – TODO

  • chromatic (int) – The number of semi-tone steps to add or subtract to the pitch to get to the (sounding) concert pitch.

diatonic

See parameters

Type:

int

chromatic

See parameters

Type:

int

class partitura.score.Words(text, staff=None)[source]

Bases: TimedObject

A textual element in the score.

Parameters:
  • text (str) – The text

  • staff (int or None, optional) – The staff to which the text is associated. Defaults to None

text

See parameters

Type:

str

staff

See parameters

Type:

int or None, optional

class partitura.score.OctaveShiftDirection(shift_type, shift_size=8, staff=None)[source]

Bases: TimedObject

An octave shift direction.

class partitura.score.Harmony(text)[source]

Bases: TimedObject

A harmony element in the score not currently used.

Parameters:

text (str) – The harmony text

text

See parameters

Type:

str

class partitura.score.RomanNumeral(text)[source]

Bases: TimedObject

A harmony element in the score usually for Roman Numerals.

Parameters:

text (str) – The harmony text

text

See parameters

Type:

str

class partitura.score.ChordSymbol(root, kind, bass=None)[source]

Bases: TimedObject

A harmony element in the score usually for Chord Symbols.

class partitura.score.Interval(number, quality, direction='up')[source]

Bases: object

An interval element usually used for transpositions

Parameters:
  • number (int) – The interval number (e.g. 1, 2, 3, 4, 5, 6, 7, …)

  • quality (str) – The interval quality (e.g. M, m, P, A, d, dd, AA)

  • direction (str) – The interval direction (e.g. up, down)

class partitura.score.Direction(text=None, raw_text=None, staff=None)[source]

Bases: TimedObject

Base class for performance directions in the score.

class partitura.score.LoudnessDirection(text=None, raw_text=None, staff=None)[source]

Bases: Direction

class partitura.score.TempoDirection(text=None, raw_text=None, staff=None)[source]

Bases: Direction

class partitura.score.ArticulationDirection(text=None, raw_text=None, staff=None)[source]

Bases: Direction

class partitura.score.PedalDirection(text=None, raw_text=None, staff=None)[source]

Bases: Direction

class partitura.score.ConstantDirection(text=None, raw_text=None, staff=None)[source]

Bases: Direction

class partitura.score.DynamicDirection(text=None, raw_text=None, staff=None)[source]

Bases: Direction

class partitura.score.ImpulsiveDirection(text=None, raw_text=None, staff=None)[source]

Bases: Direction

class partitura.score.ConstantLoudnessDirection(text=None, raw_text=None, staff=None)[source]

Bases: ConstantDirection, LoudnessDirection

class partitura.score.ConstantTempoDirection(text=None, raw_text=None, staff=None)[source]

Bases: ConstantDirection, TempoDirection

class partitura.score.ConstantArticulationDirection(text=None, raw_text=None, staff=None)[source]

Bases: ConstantDirection, ArticulationDirection

class partitura.score.DynamicLoudnessDirection(*args, wedge=False, **kwargs)[source]

Bases: DynamicDirection, LoudnessDirection

class partitura.score.DynamicTempoDirection(text=None, raw_text=None, staff=None)[source]

Bases: DynamicDirection, TempoDirection

class partitura.score.IncreasingLoudnessDirection(*args, wedge=False, **kwargs)[source]

Bases: DynamicLoudnessDirection

class partitura.score.DecreasingLoudnessDirection(*args, wedge=False, **kwargs)[source]

Bases: DynamicLoudnessDirection

class partitura.score.IncreasingTempoDirection(text=None, raw_text=None, staff=None)[source]

Bases: DynamicTempoDirection

class partitura.score.DecreasingTempoDirection(text=None, raw_text=None, staff=None)[source]

Bases: DynamicTempoDirection

class partitura.score.ImpulsiveLoudnessDirection(text=None, raw_text=None, staff=None)[source]

Bases: ImpulsiveDirection, LoudnessDirection

class partitura.score.SustainPedalDirection(line=False, *args, **kwargs)[source]

Bases: PedalDirection

Represents a Sustain Pedal Direction

class partitura.score.ResetTempoDirection(text=None, raw_text=None, staff=None)[source]

Bases: ConstantTempoDirection

class partitura.score.PartGroup(group_symbol=None, group_name=None, number=None, id=None)[source]

Bases: object

Represents a grouping of several instruments, usually named, and expressed in the score with a group symbol such as a brace or a bracket. In symphonic scores, bracketed part groups usually group families of instruments, such as woodwinds or brass, whereas braces are often used to group multiple instances of the same instrument. See the MusicXML documentation for further information.

Parameters:

group_symbol (str or None, optional) – The symbol used for grouping instruments.

group_symbol
Type:

str or None

name
Type:

str or None

number
Type:

int

parent
Type:

PartGroup or None

children
Type:

list of Part or PartGroup objects

pretty()[source]

Return a pretty representation of this object.

Returns:

A pretty representation

Return type:

str

note_array(*args, **kwargs)[source]

A structured array containing pitch, onset, duration, voice and id for each note in each part of the PartGroup. The note ids in this array include the number of the part to which they belong.

See Part.note_array()

rest_array(*args, **kwargs)[source]

A structured array containing pitch, onset, duration, voice and id for each note in each part of the PartGroup. The note ids in this array include the number of the part to which they belong.

See Part.note_array()

class partitura.score.Score(partlist: Part | PartGroup | Iterable[Part | PartGroup], id: str | None = None, work_title: str | None = None, work_number: str | None = None, movement_title: str | None = None, movement_number: str | None = None, title: str | None = None, subtitle: str | None = None, composer: str | None = None, lyricist: str | None = None, copyright: str | None = None)[source]

Bases: object

Main object for representing a score.

The Score object is basically an iterable that provides access to all Part objects in a musical score.

Parameters:
  • id (str) – The identifier of the score. In order to be compatible with MusicXML the identifier should not start with a number.

  • partlist (Part, PartGroup or list of Part or PartGroup instances.) – List of Part or PartGroup objects.

  • work_title (str, optional) – Work title of the score, if applicable.

  • work_number (str, optional) – Work number of the score, if applicable.

  • movement_title (str, optional) – Movement title of the score, if applicable.

  • movement_number (str, optional) – Movement number of the score, if applicable.

  • title (str, optional) – Title of the score, from <credit-words> tag

  • subtitle (str, optional) – Subtitle of the score.

  • composer (str, optional) – Composer of the score.

  • lyricist (str, optional) – Lyricist of the score.

  • copyright (str, optional.) – Copyright notice of the score.

id

See parameters.

Type:

str

parts

All Part objects.

Type:

list of Part objects

part_structure

List of all Part or PartGroup objects that specify the structure of the score.

Type:

list of Part or PartGrop

work_title

See parameters.

Type:

str

work_number

See parameters.

Type:

str

movement_title

See parameters.

Type:

str

movement_number

See parameters.

Type:

str

subtitle

See parameters.

Type:

str

composer

See parameters.

Type:

str

lyricist

See parameters.

Type:

str

copyright

See parameters.

Type:

str.

note_array(unique_id_per_part=True, include_pitch_spelling=False, include_key_signature=False, include_time_signature=False, include_metrical_position=False, include_grace_notes=False, include_staff=False, include_divs_per_quarter=False, **kwargs) ndarray[source]

Get a note array that concatenates the note arrays of all Part/PartGroup objects in the score.

partitura.score.add_measures(part)[source]

Add measures to a part.

This function adds Measure objects to the part according to any time signatures present in the part. Any existing measures will be untouched, and added measures will be delimited by the existing measures.

The Part object will be modified in place.

Parameters:

part (Part) – Part instance

partitura.score.remove_grace_notes(part)[source]

Remove all grace notes from a timeline.

The specified timeline object will be modified in place.

Parameters:

timeline (Timeline) – The timeline from which to remove the grace notes

partitura.score.expand_grace_notes(part)[source]

Expand grace note durations in a part.

The specified part object will be modified in place.

Parameters:

part (Part) – The part on which to expand the grace notes

partitura.score.iter_parts(partlist)[source]

Iterate over all Part instances in partlist, which is a list of either Part or PartGroup instances. PartGroup instances contain one or more parts or further partgroups, and are traversed in a depth-first fashion.

This function is designed to take the result of partitura.load_score_midi() and partitura.load_musicxml() as input.

Parameters:

partlist (Score, list, Part, or PartGroup) – A partitura.score.Part object, partitura.score.PartGroup or a list of these

Yields:

Part instances in partlist

partitura.score.repeats_to_start_end(repeats, first, last)[source]

Return pairs of (start, end) TimePoints corresponding to the start and end times of each Repeat object. If any of the start or end attributes are None, replace it with the end/start of the preceding/succeeding Repeat, respectively, or first or last.

Parameters:
  • repeats (list) – list of Repeat instances, possibly with None-valued start/end attributes

  • first (TimePoint) – The first TimePoint in the timeline

  • last (TimePoint) – The last TimePoint in the timeline

Returns:

list of (start, end) TimePoints corresponding to each Repeat in repeats

Return type:

list

partitura.score.tie_notes(part)[source]

Find notes that span measure boundaries and notes with composite durations, and split them adding ties.

Parameters:

part (Part) – Description of part

partitura.score.set_end_times(parts)[source]

Set missing end times of musical elements in a part to equal the start times of the subsequent element of the same class. This is useful for some classes

This function modifies the parts in place.

Parameters:

part (Part or PartGroup, or list of these) – Parts to be processed

partitura.score.find_tuplets(part)[source]

Identify tuplets in part and set their symbolic durations explicitly.

This function adds actual_notes and normal_notes keys to the symbolic duration of tuplet notes.

This function modifies the part in place.

Parameters:

part (Part) – Part instance

partitura.score.sanitize_part(part, tie_tolerance=0)[source]

Find and remove incomplete structures in a part such as Tuplets and Slurs without start or end and grace notes without a main note.

This function modifies the part in place.

Parameters:
  • part (Part) – Part instance

  • tie_tolerange (int, optional) – The maximum number of divs that separates notes that are tied together. Ideally, it is 0, but not so nice scores happen.

partitura.score.assign_note_ids(parts, keep=False)[source]

Assigns new note IDs mainly used for loaders.

partslist or score.PartGroup or score.Part

Some Partitura parts

keepbool

Keep or given note IDs or assign new ones.

class partitura.score.Segment(id, to, await_to, force_seq=False, type='default', info='')[source]

Bases: TimedObject

Class that represents any segment between two navigation markers such as repetitions, Volta brackets, or capo/fine/coda/segno directions.

Parameters:
  • id (string) – unique, ordererd identifier string

  • to (list) – list of ids of possible destinations

  • await_to – list of ids of possible destinations after a jump

  • type (string, optional) – String for the type of the segment (either “default” or “leap_start” and “leap_end”). A “leap” tuple has the effect of forcing the fastest (shortest) repetition unfolding after this segment, as is commonly expected after capo/fine/coda/segno directions.

  • info (string, optional) – String to describe the segment, used only for printing (pretty_segments)

partitura.score.add_segments(part)[source]

Add segment objects to a part based on repetition and capo/fine/coda/segno directions.

Parameters:

part (part) – A score part

partitura.score.get_segments(part)[source]

Get dictionary of segment objects of a part.

Parameters:

part (part) – A score part

Returns:

segments – A dictionary of Segment objects indexed by segment IDs.

Return type:

dict

partitura.score.pretty_segments(part)[source]

Get a pretty string of all the segments in a part.

class partitura.score.Path(path_list, segments, used_segment_jumps=None, no_repeats=False, all_repeats=False, jumped=False)[source]

Bases: object

Path that represents a sequence of segments.

Parameters:
  • path (list) – The string of segment IDs

  • segments (dict) – A dictionary of available segments by segment ID

  • used_segment_jumps (defaultdict(list), optional) – dictionary of used jumps per segment in this path

  • no_repeats (bool, optional) – Flag to generate no repeating jump destinations with list_of_destinations_from_last_segment

  • all_repeats (bool, optional) – Flag to generate all repeating jump destinations with list_of_destinations_from_last_segment (lower prority than no_repeats)

  • jumped (bool) – indicates the presence of a da capo, dal segno, or al coda jump in this path

pretty(part=None)[source]

create a pretty string describing this path instance. If a corresponding part is given, the string will give segment times in beats, else in divs.

copy()[source]

create a copy of this path instance.

make_copy_with_jump_to(destination, ignore_leap_info=True)[source]

create a copy of this path instance with an added jump. If the jump is a leap (dal segno, da capo, al coda) and leap information is not ignored, set the new Path to subsequently follow the the shortest version.

partitura.score.unfold_paths(path, paths, ignore_leap_info=True)[source]

Given a starting Path (at least one segment) recursively unfold into all possible Paths with its segments. Ended Paths are stored in a list.

Parameters:
  • path (Path) – a starting Path with at least one segment to be unfolded

  • paths (list) – empty list to accumulate paths that are fully unfolded until an “end” keyword was found

partitura.score.get_paths(part, no_repeats=False, all_repeats=False, ignore_leap_info=True)[source]

Get a list of paths and and a dictionary of segment objects of a part.

Common settings to get specific paths: - default: all possible paths

(no_repeats = False, all_repeats = False, ignore_leap_info = True)

  • default: all possible paths but without repetitions after leap

    (no_repeats = False, all_repeats = False, ignore_leap_info = False)

  • The longest possible path

    (no_repeats = False, all_repeats = True, ignore_leap_info = True)

  • The longest possible path but without repetitions after leap

    (no_repeats = False, all_repeats = True, ignore_leap_info = False)

  • The shortest possible path.

    (no_repeats = True) Note this might not be musically valid, e.g. a passing a “fine” even a first time will stop this unfolding.

Parameters:
  • part (part) – A score part

  • no_repeats (bool, optional) – Flag to choose no repeating segments, i.e. the shortest path.

  • all_repeats (bool, optional) – Flag to choose all repeating segments, i.e. the longest path. (lower priority than the previous flag)

  • ignore_leap_info (bool, optional) – If not ignored, Path changes to no_repeats = True if a leap is encountered. (A leap is a used dal segno, da capo, or al coda marking)

Returns:

paths – A list of path objects

Return type:

list

partitura.score.new_part_from_path(path, part, update_ids=True)[source]

create a new Part from a Path and an underlying Part

Parameters:
  • path (Path) – A Path object

  • part (part) – A score part

  • update_ids (bool (optional)) – Update note ids to reflect the repetitions. Note IDs will have a ‘-<repetition number>’, e.g., ‘n132-1’ and ‘n132-2’ represent the first and second repetition of ‘n132’ in the input part. Defaults to False.

Returns:

new_part – A score part corresponding to the Path

Return type:

part

partitura.score.new_scorevariant_from_path(path, part)[source]

create a new Part from a Path and an underlying Part

Parameters:
  • path (Path) – A Path object

  • part (part) – A score part

Returns:

scorevariant – A ScoreVariant object with segments corresponding to the part

Return type:

ScoreVariant

partitura.score.iter_unfolded_parts(part, update_ids=True)[source]

Iterate over unfolded clones of part.

For each repeat construct in part the iterator produces two clones, one with the repeat included and another without the repeat. That means the number of items returned is two to the power of the number of repeat constructs in the part.

The first item returned by the iterator is the version of the part without any repeated sections, the last item is the version of the part with all repeat constructs expanded.

Parameters:
  • part (Part) – Part to unfold

  • update_ids (bool (optional)) – Update note ids to reflect the repetitions. Note IDs will have a ‘-<repetition number>’, e.g., ‘n132-1’ and ‘n132-2’ represent the first and second repetition of ‘n132’ in the input part. Defaults to False.

partitura.score.unfold_part_maximal(score: List[Part | PartGroup] | Part | PartGroup | Score, update_ids=True, ignore_leaps=True)[source]

Return the “maximally” unfolded part/score, that is, a copy of the part where all segments marked with repeat signs are included twice.

Parameters:
  • score (ScoreLike) – The Part/Score to unfold.

  • update_ids (bool (optional)) – Update note ids to reflect the repetitions. Note IDs will have a ‘-<repetition number>’, e.g., ‘n132-1’ and ‘n132-2’ represent the first and second repetition of ‘n132’ in the input part. Defaults to False.

  • ignore_leaps (bool (optional)) – If ignored, repetitions after a leap are unfolded fully. A leap is a used dal segno, da capo, or al coda marking. Defaults to True.

Returns:

unfolded_part – The unfolded Part/Score

Return type:

ScoreLike

partitura.score.unfold_part_minimal(score: List[Part | PartGroup] | Part | PartGroup | Score)[source]

Return the “minimally” unfolded score/part, that is, a copy of the part where all segments marked with repeat are included only once. For voltas only the last volta segment is included. Note this might not be musically valid, e.g. a passing a “fine” even a first time will stop this unfolding. Warning: The unfolding of repeats is computed part-wise, inconsistent repeat markings of parts of a single result in inconsistent unfoldings.

Parameters:

score (ScoreLike) – The score/part to unfold.

Returns:

unfolded_score – The unfolded Part

Return type:

ScoreLike

partitura.score.unfold_part_alignment(part, alignment)[source]

Return the unfolded part given an alignment, that is, a copy of the part where the segments are repeated according to the repetitions in a performance.

Parameters:
  • part (Part) – The Part to unfold.

  • alignment (list of dictionaries) – List of dictionaries containing an alignment (like the ones obtained from a MatchFile (see alignment_from_matchfile).

Returns:

unfolded_part – The unfolded Part

Return type:

Part

partitura.score.make_score_variants(part)[source]

Create a list of ScoreVariant objects, each representing a distinct way to unfold the score, based on the repeat structure.

Parameters:

part (Part) – A part for which to make the score variants

Returns:

List of ScoreVariant objects

Return type:

list

partitura.score.merge_parts(parts, reassign='voice')[source]
Merge list of parts or PartGroup into a single part.

All parts are expected to have the same time signature

and quarter division.

All elements are merged, except elements with class:Barline, Page, System, Clef, Measure, TimeSignature, KeySignature that are only taken from the first part.

WARNING: this modifies the elements in the input, so the original input should not be used anymore.

Parameters:
  • parts (PartGroup, list of parts and partGroups) – The parts to merge

  • reassign (string (optional)) – If “staff” the new part have as many staves as the sum of the staves in parts, and the staff numbers get reassigned. If “voice”, the new part have only one staff, and as manually voices as the sum of the voices in parts; the voice number get reassigned.

Returns:

A new part that contains the elements of the old parts

Return type:

Part

partitura.score.is_a_within_b(a, b, wholly=False)[source]

Returns a boolean indicating whether a is (wholly) within b.

Parameters:
exception partitura.score.InvalidTimePointException(message=None)[source]

Bases: Exception

Raised when a time point is instantiated with an invalid number.