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_musicxml(xml, ensure_list=False, validate=False, force_note_ids=False)[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
  • ensure_list (bool, optional) – When True return a list independent of how many part or partgroup elements were created from the MIDI file. By default, when the return value of load_musicxml produces a
  • single (class:partitura.score.Part or) – partitura.score.PartGroup element, the element itself is returned instead of a list containing the element. Defaults to False.
  • 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, 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:

partlist – A list of either Part or PartGroup objects

Return type:

list

partitura.save_musicxml(parts, out=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.musicxml_to_notearray(fn, flatten_parts=True, sort_onsets=True, expand_grace_notes=True, validate=False, beat_times=True)[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.
  • expand_grace_notes (bool or 'delete') – When True, grace note onset and durations will be adjusted to have a non-zero duration.
  • beat_times (bool) – When True (default) return onset and duration in beats. Otherwise, return the onset and duration in divisions.
Returns:

score – Structured array containing the score. The fields are ‘pitch’, ‘onset’ and ‘duration’.

Return type:

structured array or list of structured arrays

partitura.load_score_midi(fn, part_voice_assign_mode=0, ensure_list=False, quantization_unit=None, estimate_voice_info=True, estimate_key=False, assign_note_ids=True)[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:
  • fn (str) – Path to MIDI file
  • 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.
  • ensure_list (bool, optional) – When True, return a list independent of how many part or partgroup elements were created from the MIDI file. By default, when the return value of load_score_midi produces a single partitura.score.Part or partitura.score.PartGroup element, the element itself is returned instead of a list containing the element. Defaults to False.
  • 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

[1]Meredith, D. (2006). “The ps13 Pitch Spelling Algorithm”. Journal of New Music Research, 35(2):121.
[2](1, 2) Chew, E. and Wu, Xiaodan (2004) “Separating Voices in Polyphonic Music: A Contig Mapping Approach”. In Uffe Kock, editor, Computer Music Modeling and Retrieval (CMMR), pp. 1–20, Springer Berlin Heidelberg.
[3](1, 2) Krumhansl, Carol L. (1990) “Cognitive foundations of musical pitch”, Oxford University Press, New York.
partitura.save_score_midi(parts, out, part_voice_assign_mode=0, velocity=64)[source]

Write data from Part objects to a MIDI file

Parameters:
  • parts (Part, PartGroup or list of these) – The musical score to be saved.
  • 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.
  • velocity (int, optional) – Default velocity for all MIDI notes.
partitura.load_via_musescore(fn)[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:fn (str) – Filename of the score to load
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(fn, default_bpm=120)[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:
  • fn (str) – Path to MIDI file
  • default_bpm (number, optional) – Tempo to use wherever the MIDI does not specify a tempo. Defaults to 120.
Returns:

A PerformedPart instance.

Return type:

partitura.performance.PerformedPart

partitura.save_performance_midi(performed_part, out, mpq=500000, ppq=480, default_velocity=64)[source]

Save a PerformedPart instance as a MIDI file.

Parameters:
  • performed_part (PerformedPart) – The performed part to save
  • 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.
partitura.render(part, fmt='png', dpi=90, out_fn=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:
  • part (partitura.score.Part or partitura.score.PartGroup or list of these) – 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.
partitura.EXAMPLE_MUSICXML = '/home/docs/.cache/Python-Eggs/partitura-0.3.5-py3.7.egg-tmp/partitura/assets/score_example.musicxml'

An example MusicXML file for didactic purposes