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