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)[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
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
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
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
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
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
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
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
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
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

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, 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) – The class to search for
  • 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:

cls – Instances of type cls

last_point

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

Returns:
Return type:TimePoint
first_point

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

Returns:
Return type:TimePoint
note_array

A structured array containing pitch, onset, duration, voice and id for each note

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

Bases: partitura.utils.generic.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: partitura.utils.generic.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
class partitura.score.GenericNote(id=None, voice=None, staff=None, symbolic_duration=None, articulations=None)[source]

Bases: partitura.score.TimedObject

Represents the common aspects of notes and rests (and in the future unpitched notes)

Parameters:
  • voice (integer, optional (default: None)) –
  • id (integer, optional (default: None)) –
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
duration

The duration of the note in divisions

Returns:
Return type:int
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
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
duration_from_symbolic

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

Returns:
Return type:int or None
tie_prev_notes

TODO

Returns:Description of return value
Return type:type
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, *args, **kwargs)[source]

Bases: partitura.score.GenericNote

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
alter_sign

The alteration of the note

Returns:
Return type:str
class partitura.score.Rest(*args, **kwargs)[source]

Bases: partitura.score.GenericNote

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

Bases: partitura.score.Note

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: partitura.score.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: partitura.score.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(number, sign, line, octave_change)[source]

Bases: partitura.score.TimedObject

A clef.

Clefs associate the lines of a staff to musical pitches.

Parameters:
  • number (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)
nr

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: partitura.score.TimedObject

A slur.

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: partitura.score.TimedObject

A tuplet.

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: partitura.score.TimedObject

A repeat.

This class represents a repeated section in the score, designated by its start and end times.

class partitura.score.DaCapo[source]

Bases: partitura.score.TimedObject

A Da Capo sign.

class partitura.score.Fine[source]

Bases: partitura.score.TimedObject

A Fine sign.

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

Bases: partitura.score.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: partitura.score.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.Measure(number=None)[source]

Bases: partitura.score.TimedObject

A measure.

Parameters:number (int or None, optional) – The number of the measure. Defaults to None
number

See parameters

Type:int
page

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

Returns:
Return type:int or None
system

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

Returns:
Return type:int or None
class partitura.score.TimeSignature(beats, beat_type)[source]

Bases: partitura.score.TimedObject

A time signature.

Parameters:
  • beats (int) – The number of beats in a measure
  • beat_type (int) – The note type that defines the beat unit. (4 for quarter notes, 2 for half notes, etc.)
beats

See parameters

Type:int
beat_type

See parameters

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

Bases: partitura.score.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
microseconds_per_quarter

The number of microseconds per quarter under this tempo.

This is useful for MIDI representations.

Returns:
Return type:int
class partitura.score.KeySignature(fifths, mode)[source]

Bases: partitura.score.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
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: partitura.score.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) –
  • 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: partitura.score.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.Direction(text, raw_text=None, staff=None)[source]

Bases: partitura.score.TimedObject

Base class for performance directions in the score.

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

Bases: partitura.score.Direction

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

Bases: partitura.score.Direction

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

Bases: partitura.score.Direction

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

Bases: partitura.score.Direction

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

Bases: partitura.score.Direction

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

Bases: partitura.score.Direction

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

Bases: partitura.score.ConstantDirection, partitura.score.LoudnessDirection

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

Bases: partitura.score.ConstantDirection, partitura.score.TempoDirection

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

Bases: partitura.score.ConstantDirection, partitura.score.ArticulationDirection

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

Bases: partitura.score.DynamicDirection, partitura.score.LoudnessDirection

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

Bases: partitura.score.DynamicDirection, partitura.score.TempoDirection

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

Bases: partitura.score.DynamicLoudnessDirection

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

Bases: partitura.score.DynamicLoudnessDirection

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

Bases: partitura.score.DynamicTempoDirection

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

Bases: partitura.score.DynamicTempoDirection

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

Bases: partitura.score.ImpulsiveDirection, partitura.score.LoudnessDirection

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

Bases: partitura.score.ConstantTempoDirection

class partitura.score.PartGroup(group_symbol=None, group_name=None, number=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
partitura.score.iter_unfolded_parts(part)[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
partitura.score.unfold_part_maximal(part)[source]

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

Returns: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

Notes

This function does not currently support nested repeats, such as in case 45d of the MusicXML Test Suite.

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 (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

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.

Parameters:part (Part) – Part instance
class partitura.score.InvalidTimePointException[source]

Bases: object

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