partitura

Partitura is a lightweight Python package designed for Music Information Retrieval (MIR) researchers. It provides easy access to musical information contained in symbolic music formats (scores and MIDI performances).

Key features include:

• Note arrays: Lists of timed pitched events.
• Pianorolls: 2D time x pitch matrices.
• Rich musical elements: Support for time/key signatures, performance directives, repeat structures, pitch spellings, and voicing information.
• Alignment support: Loading score-to-performance alignments.

While music21 is better suited for computational musicology and complex score manipulation, partitura is optimized for machine learning and deep learning workflows, focusing on fast feature extraction from symbolic data.

Partitura treats MIDI files as either a score or a performance, rather than a single ambiguous entity. This distinction is important because scores contain structural information (key/time signatures, tempo) while performances contain expressive information (dynamics, expressive timing).

Use the following specific functions to ensure correct loading:

• For Scores: Use partitura.load_score_midi. This function offers simple quantization for unquantized MIDIs.
• For Performances: Use partitura.load_performance_midi.

Note: You should generally not expect a MIDI representation of a performance to be loaded correctly as a Part instance using score-loading functions.

Partitura provides a generic load_score function that automatically detects the file format (MusicXML, Kern, MIDI, or MEI) and returns a partitura.Score object. You can also use format-specific loaders if preferred.

To access musical data, you typically iterate through score.parts. Each part contains musical objects like notes, rests, and time signatures.

import partitura as pt

# Generic loader (recommended)
score = pt.load_score('path/to/file.musicxml')

# Format-specific loaders
score = pt.load_musicxml('path/to/file.musicxml')
score = pt.load_kern('path/to/file.krn')
score = pt.load_mei('path/to/file.mei')

You can use a hybrid workflow by combining music21 and partitura. This is useful if you need the advanced manipulation capabilities of music21 but want the fast feature extraction of partitura.

Workflow:

1. Load a score in music21.
2. Perform complex manipulations/modifications using music21 APIs.
3. Use the music21 to partitura converter to transform the score into a Partitura object.
4. Extract MIR features using partitura.

A TimePoint represents a specific temporal position within a Part. They are used to track the start and end of musical elements like notes or rests.

Key Attributes:

• t: The integer time associated with the point.
• quarter: The duration of a quarter note at this point.
• starting_objects: A dictionary grouping objects that start at this time by their class.
• ending_objects: A dictionary grouping objects that end at this time by their class.
• prev / next: Pointers to the preceding and succeeding TimePoint in the timeline.

Common Methods:

• iter_starting(cls, include_subclasses=False): Yields objects of type cls starting at this point.
• iter_ending(cls, include_subclasses=False): Yields objects of type cls ending at this point.
• iter_prev(...) / iter_next(...): Iterates backwards or forwards through the timeline starting from this point.

A TimedObject is the base class for any musical element that occupies a span of time. Every TimedObject has a start and an end attribute, both of which are TimePoint instances.

Key Properties:

• duration: Returns the duration of the object in divisions (end.t - start.t). Returns None if the object is not yet attached to a Part (i.e., start or end is None).

The GenericNote class provides the foundation for notes, rests, and unpitched notes. It manages attributes like voice, staff, id, and stem_direction.

Symbolic Duration: GenericNote supports a symbolic_duration property. This can be a dictionary specifying:

• type: e.g., 'quarter', 'half'.
• dots: integer number of dots.
• actual_notes / normal_notes: used for rhythmical tuplets.

If symbolic_duration is not manually set, the class attempts to estimate it dynamically based on the numeric duration and the quarter duration of the note's start timepoint.

The Part object is the central representation of a musical score in Partitura.

Key characteristics:

• It is a timeline object where time is measured in divs (integer units).
• Its elements are TimedObjects (e.g., notes, measures) which possess a start and end time.
• It provides methods to map between divs and musical units like beats or quarters.

Working with Notes

Each Part contains a notes list. Notes can be added or removed using part.add(note_object, start, end) and part.remove(note_object). Note timing must be specified in divs.

import partitura as pt

# Load a score
part = pt.load_musicxml("path/to/score.xml")[0]

# Create and add a new note
a_new_note = pt.score.Note(id='n04', step='A', octave=4, voice=1)
part.add(a_new_note, start=3, end=15)  # timing in divs

# Remove a note
part.remove(a_new_note)