partitura

The top level of the package contains functions to load and save data, display rendered scores, and functions to estimate pitch spelling, voice assignment, and key signature.

partitura.load_score(filename: str | bytes | PathLike, force_note_ids='keep') Score[source]

Load a score format supported by partitura. Currently the accepted formats are MusicXML, MIDI, Kern and MEI, plus all formats for which MuseScore has support import-support (requires MuseScore 4 or 3).

Parameters:
  • filename (str or file-like object) – Filename of the score to parse, or a file-like object

  • force_note_ids ((None, bool or "keep")) – When True each Note in the returned Part(s) will have a newly assigned unique id attribute. Existing note id attributes in the input file will be discarded. If ‘keep’, only notes without a note id will be assigned one. If None or False, the notes in the resulting Part(s) will have an id only if the input file has ids for the notes.

Returns:

scr – A score instance.

Return type:

partitura.score.Score

partitura.load_score_as_part(filename: str | bytes | PathLike) Part[source]

load part helper function: Load a score format supported by partitura and merge the result in a single part

Parameters:

filename (str or file-like object) – Filename of the score to parse, or a file-like object

Returns:

part – A part instance.

Return type:

partitura.score.Part

partitura.load_performance(filename: str | bytes | PathLike, default_bpm: float | int = 120, merge_tracks: bool = False, first_note_at_zero: bool = False, pedal_threshold: int = 64) Performance[source]

Load a performance format supported by partitura. Currently the accepted formats are MIDI and matchfiles.

Parameters:
  • filename (str or file-like object) – Filename of the score to parse, or a file-like object

  • default_bpm (number, optional) – Tempo to use wherever the MIDI does not specify a tempo. Defaults to 120.

  • merge_tracks (bool, optional) – For MIDI files, merges all tracks into a single track.

  • first_note_at_zero (bool, optional) – Remove silence at the beginning, so that the first note (or first MIDI message, e.g., pedal) starts at time 0.

  • pedal_threshold (int) – Threshold for the sustain pedal.

Returns:

performance – A Performance instance.

Return type:

partitura.performance.Performance

partitura.load_musicxml(filename: str | bytes | PathLike, validate: bool = False, force_note_ids: bool | str | None = None) Score[source]

Parse a MusicXML file and build a composite score ontology structure from it (see also scoreontology.py).

Parameters:
  • xml (str or file-like object) – Path to the MusicXML file to be parsed, or a file-like object

  • validate (bool, optional) – When True the validity of the MusicXML is checked against the MusicXML 3.1 specification before loading the file. An exception will be raised when the MusicXML is invalid. Defaults to False.

  • force_note_ids ((bool, 'keep') optional.) – When True each Note in the returned Part(s) will have a newly assigned unique id attribute. Existing note id attributes in the MusicXML will be discarded. If ‘keep’, only notes without a note id will be assigned one.

Returns:

scr – A Score instance.

Return type:

Score

partitura.save_musicxml(score_data: List[Part | PartGroup] | Part | PartGroup | Score, out: str | bytes | PathLike | None = None) str | None[source]

Save a one or more Part or PartGroup instances in MusicXML format.

Parameters:
Returns:

If no output file is specified using out the function returns the MusicXML data as a string. Otherwise the function returns None.

Return type:

None or str

partitura.load_mei(filename: str | bytes | PathLike) Score[source]

Loads a Mei score from path and returns a partitura Score object.

Parameters:

filename (PathLike) – The path to an MEI score.

Returns:

scr – A Score object

Return type:

partitura.score.Score

partitura.load_kern(filename: str | bytes | PathLike, force_note_ids: bool | str | None = None, parallel: bool = False) Score[source]

Parse a Kern file and build a composite score ontology structure from it (see also scoreontology.py).

Parameters:
  • filename (PathLike) – Path to the Kern file to be parsed

  • force_note_ids ((bool, 'keep') optional.) – When True each Note in the returned Part(s) will have a newly assigned unique id attribute. Existing note id attributes in the Kern will be discarded. If ‘keep’, only notes without a note id will be assigned one.

Returns:

scr – A Score object

Return type:

partitura.score.Score

partitura.musicxml_to_notearray(filename, flatten_parts=True, include_pitch_spelling=False, include_key_signature=False, include_time_signature=False)[source]

Return pitch, onset, and duration information for notes from a MusicXML file as a structured array.

By default a single array is returned by combining the note information of all parts in the MusicXML file.

Parameters:
  • fn (str) – Path to a MusicXML file

  • flatten_parts (bool) – If True, returns a single array containing all notes. Otherwise, returns a list of arrays for each part.

  • 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

Returns:

note_arrays – Structured array or list of structured arrays containing score information.

Return type:

structured array or list of structured arrays

partitura.load_score_midi(filename: str | bytes | PathLike | MidiFile, part_voice_assign_mode: int | None = 0, quantization_unit: int | None = None, estimate_voice_info: bool = True, estimate_key: bool = False, assign_note_ids: bool = True) Score[source]

Load a musical score from a MIDI file and return it as a Part instance.

This function interprets MIDI information as describing a score. Pitch names are estimated using Meredith’s PS13 algorithm [1]. Assignment of notes to voices can either be done using Chew and Wu’s voice separation algorithm [2], or by choosing one of the part/voice assignment modes that assign voices based on track/channel information. Furthermore, the key signature can be estimated based on Krumhansl’s 1990 key profiles [3].

This function expects times to be metrical/quantized. Optionally a quantization unit may be specified. If you wish to access the non- quantized time of MIDI events you may wish to used the load_performance_midi function instead.

Parameters:
  • filename (PathLike or mido.MidiFile) – Path to MIDI file or mido.MidiFile object.

  • part_voice_assign_mode ({0, 1, 2, 3, 4, 5}, optional) –

    This keyword controls how part and voice information is associated to track and channel information in the MIDI file. The semantics of the modes is as follows:

    0

    Return one Part per track, with voices assigned by channel

    1

    Return one PartGroup per track, with Parts assigned by channel (no voices)

    2

    Return single Part with voices assigned by track (tracks are combined, channel info is ignored)

    3

    Return one Part per track, without voices (channel info is ignored)

    4

    Return single Part without voices (channel and track info is ignored)

    5

    Return one Part per <track, channel> combination, without voices Defaults to 0.

  • quantization_unit (integer or None, optional) – Quantize MIDI times to multiples of this unit. If None, the quantization unit is chosen automatically as the smallest division of the parts per quarter (MIDI “ticks”) that can be represented as a symbolic duration. Defaults to None.

  • estimate_key (bool, optional) – When True use Krumhansl’s 1990 key profiles [3] to determine the most likely global key, discarding any key information in the MIDI file.

  • estimate_voice_info (bool, optional) – When True use Chew and Wu’s voice separation algorithm [2] to estimate voice information. This option is ignored for part/voice assignment modes that infer voice information from the track/channel info (i.e. part_voice_assign_mode equals 1, 3, 4, or 5). Defaults to True.

Returns:

One or more part or partgroup objects

Return type:

partitura.score.Part, partitura.score.PartGroup, or a list of these

References

partitura.save_score_midi(score_data: List[Part | PartGroup] | Part | PartGroup | Score, out: str | bytes | PathLike | None, part_voice_assign_mode: int = 0, velocity: int = 64, anacrusis_behavior: str = 'shift', minimum_ppq: int = 0) MidiFile | None[source]

Write data from Part objects to a MIDI file

Parameters:
  • score_data (Score, list, Part, or PartGroup) – The musical score to be saved. A partitura.score.Score object, a partitura.score.Part, a partitura.score.PartGroup or a list of these.

  • out (str or file-like object) – Either a filename or a file-like object to write the MIDI data to.

  • part_voice_assign_mode ({0, 1, 2, 3, 4, 5}, optional) –

    This keyword controls how part and voice information is associated to track and channel information in the MIDI file. The semantics of the modes is as follows:

    0

    Write one track for each Part, with channels assigned by voices

    1

    Write one track for each PartGroup, with channels assigned by Parts (voice info is lost) (There can be multiple levels of partgroups, I suggest using the highest level of partgroup/part) [note: this will e.g. lead to all strings into the same track] Each part not in a PartGroup will be assigned its own track

    2

    Write a single track with channels assigned by Part (voice info is lost)

    3

    Write one track per Part, and a single channel for all voices (voice info is lost)

    4

    Write a single track with a single channel (Part and voice info is lost)

    5

    Return one track per <Part, voice> combination, each track having a single channel.

    The default mode is 0.

  • velocity (int, optional) – Default velocity for all MIDI notes. Defaults to 64.

  • anacrusis_behavior ({"shift", "pad_bar", "time_sig_change"}, optional) – Strategy to deal with anacrusis. If “shift”, all time points are shifted by the anacrusis (i.e., the first note starts at 0). If “pad_bar”, the “incomplete” bar of the anacrusis is padded with silence. Defaults to ‘shift’. If “time_sig_change”, the time signature is changed to match the duration of the measure. This also ensure the beat and downbeats position are coherent in case of incomplete measures later in the score.

  • minimum_ppq (int, optional) – Minimum ppq to use for the MIDI file. If the ppq of the score is less, it will be doubled until it is above the threshold. This is useful because some libraries like miditok require a certain minimum ppq to work properly.

Returns:

If no output is specified using out, the function returns a MidiFile object. Otherwise, the function returns None.

Return type:

None or MidiFile

partitura.load_via_musescore(filename: str | bytes | PathLike, validate: bool = False, force_note_ids: bool | str | None = True) Score[source]

Load a score through through the MuseScore program.

This function attempts to load the file in MuseScore, export it as MusicXML, and then load the MusicXML. This should enable loading of all file formats that for which MuseScore has import-support (e.g. MIDI, and ABC, but currently not MEI).

Parameters:
  • filename (str) – Filename of the score to load

  • validate (bool, optional) – When True the validity of the MusicXML generated by MuseScore is checked against the MusicXML 3.1 specification before loading the file. An exception will be raised when the MusicXML is invalid. Defaults to False.

  • force_note_ids (bool, optional.) – When True each Note in the returned Part(s) will have a newly assigned unique id attribute. Existing note id attributes in the MusicXML will be discarded.

Returns:

One or more part or partgroup objects

Return type:

partitura.score.Part, partitura.score.PartGroup, or a list of these

partitura.load_performance_midi(filename: str | bytes | PathLike | MidiFile, default_bpm: int | float = 120, merge_tracks: bool = False) Performance[source]

Load a musical performance from a MIDI file.

This function should be used for MIDI files that encode performances, such as those obtained from a capture of a MIDI instrument. This function loads note on/off events as well as control events, but ignores other data such as time and key signatures. Furthermore, the PerformedPart instance that the function returns does not retain the ticks_per_beat or tempo events. The timing of all events is represented in seconds. If you wish to retain this information consider using the load_score_midi function.

Parameters:
  • filename (str) – Path to MIDI file

  • default_bpm (number, optional) – Tempo to use wherever the MIDI does not specify a tempo. Defaults to 120.

  • merge_tracks (bool, optional) – For MIDI files, merges all tracks into a single track.

Returns:

A Performance instance.

Return type:

partitura.performance.Performance

partitura.save_performance_midi(performance_data: List[PerformedPart] | PerformedPart | Performance, out: str | bytes | PathLike | None, mpq: int = 500000, ppq: int = 480, default_velocity: int = 64, merge_tracks_save: bool | None = False) MidiFile | None[source]

Save a PerformedPart or a Performance as a MIDI file

Parameters:
  • performance_data (PerformanceLike) – The performance to be saved.

  • out (str or file-like object) – Either a filename or a file-like object to write the MIDI data to.

  • mpq (int, optional) – Microseconds per quarter note. This is known in MIDI parlance as the “tempo” value. Defaults to 500000 (i.e. 120 BPM).

  • ppq (int, optional) – Parts per quarter, also known as ticks per beat. Defaults to 480.

  • default_velocity (int, optional) – A default velocity value (between 0 and 127) to be used for notes without a specified velocity. Defaults to 64.

  • merge_tracks_save (bool, optional) – Determines whether midi tracks are merged when exporting to a midi file. Defaults to False.

Returns:

If no output is specified using out, the function returns a MidiFile object. Otherwise, the function returns None.

Return type:

None or MidiFile

partitura.load_match(filename: str | bytes | PathLike, create_score: bool = False, pedal_threshold: int = 64, first_note_at_zero: bool = False, offset_duration_whole: bool = True) Tuple[Performance | list | Score][source]

Load a matchfile.

Parameters:
  • filename (str) – The matchfile

  • create_score (bool, optional) – When True create a Part object from the snote information in the match file. Defaults to False.

  • pedal_threshold (int, optional) – Threshold for adjusting sound off of the performed notes using pedal information. Defaults to 64.

  • first_note_at_zero (bool, optional) – When True the note_on and note_off times in the performance are shifted to make the first note_on time equal zero.

Returns:

  • performance (:class:partitura.performance.Performance)

  • alignment (list) – The score–performance alignment, a list of dictionaries

  • scr (:class:partitura.score.Score) – The score. This item is only returned when create_score = True.

partitura.save_match(alignment: List[dict], performance_data: List[PerformedPart] | PerformedPart | Performance, score_data: List[Part | PartGroup] | Part | PartGroup | Score, out: str | bytes | PathLike = None, mpq: int = 500000, ppq: int = 480, performer: str | None = None, composer: str | None = None, piece: str | None = None, score_filename: str | bytes | PathLike | None = None, performance_filename: str | bytes | PathLike | None = None, assume_unfolded: bool = False) MatchFile | None[source]

Save an Alignment of a PerformedPart to a Part in a match file.

Parameters:
  • alignment (list) – A list of dictionaries containing alignment information. See partitura.io.importmatch.alignment_from_matchfile.

  • performance_data (`PerformanceLike) – The performance information as a Performance

  • score_data (ScoreLike) – The musical score. A partitura.score.Score object, a partitura.score.Part, a partitura.score.PartGroup or a list of these.

  • out (str) – Out to export the matchfile.

  • mpq (int) – Milliseconds per quarter note.

  • ppq (int) – Parts per quarter note.

  • performer (str or None) – Name(s) of the performer(s) of the PerformedPart.

  • composer (str or None) – Name(s) of the composer(s) of the piece represented by Part.

  • piece (str or None:) – Name of the piece represented by Part.

  • score_filename (PathLike) – Name of the file containing the score.

  • performance_filename (PathLike) – Name of the (MIDI) file containing the performance.

  • assume_part_unfolded (bool) – Whether to assume that the part has been unfolded according to the repetitions in the alignment. If False, the part will be automatically unfolded to have maximal coverage of the notes in the alignment. See partitura.score.unfold_part_alignment.

Returns:

matchfile – If no output is specified using out, the function returns a MatchFile object. Otherwise, the function returns None.

Return type:

MatchFile

partitura.load_nakamuramatch(filename: str | bytes | PathLike) Tuple[ndarray | list][source]

Load a match file as returned by Nakamura et al.’s MIDI to musicxml alignment

Fields of the file format as specified in [8]: ID (onset time) (offset time) (spelled pitch) (onset velocity)(offset velocity) channel (match status) (score time) (note ID)(error index) (skip index)

Parameters:

filename (str) – The nakamura match.txt-file

Returns:

  • align (structured array) – structured array of performed notes

  • ref (structured array) – structured array of score notes

  • alignment (list) – The score–performance alignment, a list of dictionaries

References

partitura.load_nakamuracorresp(filename: str | bytes | PathLike) Tuple[ndarray | list][source]

Load a corresp file as returned by Nakamura et al.’s MIDI to MIDI alignment.

Fields of the file format as specified in [8]: (ID) (onset time) (spelled pitch) (integer pitch) (onset velocity)

Parameters:

filename (str) – The nakamura match.txt-file

Returns:

  • align (structured array) – structured array of performed notes

  • ref (structured array) – structured array of score notes

  • alignment (list) – The score–performance alignment, a list of dictionaries

partitura.load_parangonada_csv(dirname: str | bytes | PathLike, create_score: bool = False) ndarray[source]

Load Parangonada Project alignment files

Parameters:
  • dirname (PathLike) – Directory with the CSV files in Parangonada

  • create_score (bool) – Create a score. For now it just creats a note array, but the argument name was chosen to be consistent with load_match.

Returns:

  • performance (partitura.performance.Performance) – The performance in the alignment

  • alignment (List of dict) – The main alignment

  • zalignment (List of dict) – The secondary alignment (for comparing the first one)

  • feature (np.ndarray) – A structured array with note-level feature information

  • score_note_array – A note array containing note information in the score. Will change to a score object in a future release!

partitura.save_parangonada_csv(alignment: List[dict], performance_data: List[PerformedPart] | PerformedPart | Performance | ndarray, score_data: List[Part | PartGroup] | Part | PartGroup | Score | ndarray, outdir: str | bytes | PathLike | None = None, zalign: List[dict] | None = None, feature: List[dict] | None = None) Tuple[ndarray] | None[source]

Save an alignment for visualization with parangonda.

Parameters:
  • alignment (list) – A list of note alignment dictionaries.

  • performance_data (Performance, PerformedPart, structured ndarray) – The performance information

  • score_data (ScoreLike) – The musical score. A partitura.score.Score object, a partitura.score.Part, a partitura.score.PartGroup or a list of these.

  • outdir (PathLike) – A directory to save the files into.

  • ppart (PerformedPart, structured ndarray) – A PerformedPart or its note_array.

  • zalign (list, optional) – A second list of note alignment dictionaries.

  • feature (list, optional) – A list of expressive feature dictionaries.

Returns:

  • perf_note_array (np.ndarray) – The performance note array. Only returned if outdir is None.

  • score_note_array (np.ndarray) – The note array from the score. Only returned if outdir is None.

  • alignarray (np.ndarray)

  • zalignarray (np.ndarray)

  • featurearray (np.ndarray)

partitura.render(score_data: List[Part | PartGroup] | Part | PartGroup | Score, fmt: str = 'png', dpi: int = 90, out: str | bytes | PathLike | None = None) None[source]

Create a rendering of one or more parts or partgroups.

The function can save the rendered image to a file (when out_fn is specified), or shown in the default image viewer application.

Rendering is first attempted through musecore, and if that fails through lilypond. If that also fails the function returns without raising an exception.

Parameters:
  • score_data (ScoreLike) – The score content to be displayed

  • fmt ({'png', 'pdf'}, optional) – The image format of the rendered material

  • out_fn (str or None, optional) – The path of the image output file. If None, the rendering will be displayed in a viewer.