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: Union[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 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.load_score_as_part(filename: Union[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.load_performance(filename: Union[str, bytes, PathLike], default_bpm: Union[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.load_musicxml(filename: Union[str, bytes, PathLike], validate: bool = False, force_note_ids: Optional[Union[bool, str]] = 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
- partitura.save_musicxml(score_data: Union[List[Union[Part, PartGroup]], Part, PartGroup, Score], out: Optional[Union[str, bytes, PathLike]] = None) Optional[str] [source]¶
Save a one or more Part or PartGroup instances in MusicXML format.
- Parameters
score_data (Score, list, Part, or PartGroup) – The musical score to be saved. A
partitura.score.Score
object, apartitura.score.Part
, apartitura.score.PartGroup
or a list of these.out (str, file-like object, or None, optional) – Output file
- 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: Union[str, bytes, PathLike]) Score [source]¶
Loads a Mei score from path and returns a list of Partitura.Part
- Parameters
filename (PathLike) – The path to an MEI score.
- Returns
scr – A Score object
- Return type
- partitura.load_kern(filename: Union[str, bytes, PathLike], force_note_ids: Optional[Union[bool, str]] = 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.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: Union[str, bytes, PathLike, MidiFile], part_voice_assign_mode: Optional[int] = 0, quantization_unit: Optional[int] = 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
- 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(score_data: Union[List[Union[Part, PartGroup]], Part, PartGroup, Score], out: Optional[Union[str, bytes, PathLike]], part_voice_assign_mode: int = 0, velocity: int = 64, anacrusis_behavior: str = 'shift') Optional[MidiFile] [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, apartitura.score.Part
, apartitura.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"}, 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’.
- 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: Union[str, bytes, PathLike], validate: bool = False, force_note_ids: Optional[Union[bool, str]] = 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: Union[str, bytes, PathLike, MidiFile], default_bpm: Union[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.save_performance_midi(performance_data: Union[List[PerformedPart], PerformedPart, Performance], out: Optional[Union[str, bytes, PathLike]], mpq: int = 500000, ppq: int = 480, default_velocity: int = 64) Optional[MidiFile] [source]¶
Save a
PerformedPart
or aPerformance
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.
- 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: Union[str, bytes, PathLike], create_score: bool = False, pedal_threshold: int = 64, first_note_at_zero: bool = False, offset_duration_whole: bool = True) Tuple[Union[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: Union[List[PerformedPart], PerformedPart, Performance], score_data: Union[List[Union[Part, PartGroup]], Part, PartGroup, Score], out: Union[str, bytes, PathLike] = None, mpq: int = 500000, ppq: int = 480, performer: Optional[str] = None, composer: Optional[str] = None, piece: Optional[str] = None) Optional[MatchFile] [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, apartitura.score.Part
, apartitura.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.
- 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: Union[str, bytes, PathLike]) Tuple[Union[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: Union[str, bytes, PathLike]) Tuple[Union[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: Union[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: Union[List[PerformedPart], PerformedPart, Performance, ndarray], score_data: Union[List[Union[Part, PartGroup]], Part, PartGroup, Score, ndarray], outdir: Optional[Union[str, bytes, PathLike]] = None, zalign: Optional[List[dict]] = None, feature: Optional[List[dict]] = None) Optional[Tuple[ndarray]] [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, apartitura.score.Part
, apartitura.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(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
orpartitura.score.PartGroup
) – or a list of these The score content to be displayedfmt ({'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.