Partitura

https://partitura.readthedocs.io/en/latest/
Admin
Partitura is a lightweight Python package for handling symbolic music formats and extracting music...
Tokens:355,729
Snippets:2,078
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Partitura and Tutorial Content

Source: https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html

Installs the partitura package and clones the tutorial repository. It also configures the system path to access helper modules, which is necessary when running in environments like Google Colab.

```python
# Install partitura
! pip install partitura

# To be able to access helper modules in the repo for this tutorial
# (not necessary if the jupyter notebook is run locally instead of google colab)
!git clone https://github.com/CPJKU/partitura_tutorial.git
import warnings
warnings.filterwarnings('ignore')
import sys, os
sys.path.insert(0, os.path.join(os.getcwd(), "partitura_tutorial", "content"))
sys.path.insert(0,'/content/partitura_tutorial/content')
  
```

--------------------------------

### Install Partitura and Clone Tutorial Repository

Source: https://partitura.readthedocs.io/en/latest/_sources/Tutorial/notebook.ipynb.txt

Installs the partitura package using pip and clones the tutorial repository. It also sets up the Python path to access helper modules from the cloned repository, which is necessary when running in environments like Google Colab.

```python
# Install partitura
! pip install partitura
    
# To be able to access helper modules in the repo for this tutorial
# (not necessary if the jupyter notebook is run locally instead of google colab)
!git clone https://github.com/CPJKU/partitura_tutorial.git
import warnings
warnings.filterwarnings('ignore')
import sys, os
sys.path.insert(0, os.path.join(os.getcwd(), "partitura_tutorial", "content"))
sys.path.insert(0,'/content/partitura_tutorial/content')
```

--------------------------------

### Iterating Over Starting Objects

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Iterates over musical objects of specified classes that start at this TimePoint. Supports filtering by class and including subclasses.

```python
def iter_starting(
        self,
        cls: Type[TimedObject] | Iterable[Type[TimedObject]] | None = None,
        include_subclasses: bool = False,
    ) -> Generator[TimedObject, None, None]:
        """Iterate over all objects of type `cls` that start at this
        time point. When `cls` is a list/tuple of classes, include objects
        of any class in `cls`.

        Parameters
        ----------
        cls : class or list/tuple of classes
            Class(es) of objects to iterate over
        include_subclasses : bool, optional
            When True, include all objects of all subclasses of `cls`
            in the iteration. Defaults to False.

        Yields
        ------
        cls
            Instance of type `cls`

        """
        return self._iter_objects(cls, include_subclasses, mode="starting")

```

--------------------------------

### Adding Starting Objects to TimePoint

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Adds a musical object to the list of objects starting at this TimePoint. The object's 'start' attribute is set to this TimePoint.

```python
def add_starting_object(self, obj):
        """Add object `obj` to the list of starting objects."""
        obj.start = self
        self.starting_objects[type(obj)].add(obj)

```

--------------------------------

### Get Quarter Durations with Time Bounds

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Returns an Nx2 array of quarter durations and their respective times. Optionally filters by start and end times.

```python
qd = np.column_stack((self._quarter_times, self._quarter_durations))
        if start is not None:
            qd = qd[qd[:, 0] >= start, :]
        if end is not None:
            qd = qd[qd[:, 0] < end, :]
        return qd
```

--------------------------------

### Initialize and Set Up Dataset Directories

Source: https://partitura.readthedocs.io/en/latest/_sources/Tutorial/notebook.ipynb.txt

Initializes the dataset and defines directory paths for MusicXML, MIDI, and Match files. This setup is crucial for accessing the tutorial's data.

```python
# setup the dataset
from load_data import init_dataset
DATASET_DIR = init_dataset()
MUSICXML_DIR = os.path.join(DATASET_DIR, 'musicxml')
MIDI_DIR = os.path.join(DATASET_DIR, 'midi')
MATCH_DIR = os.path.join(DATASET_DIR, 'match')
```

--------------------------------

### Get Unique Sequence Information

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/musicanalysis/performance_codec.html

Calculates unique onsets, total duration, and optionally the difference between unique onsets from a sequence of note onsets and offsets. Useful for performance analysis where events are grouped by their start time.

```python
def get_unique_seq(onsets, offsets, unique_onset_idxs=None, return_diff=False):
    """
    Get unique onsets of a sequence of notes
    """

    first_time = np.min(onsets)

    # ensure last score time is later than last onset
    if np.max(onsets) == np.max(offsets):
        # last note without duration (grace note)
        last_time = np.max(onsets) + 1
    else:
        last_time = np.max(offsets)

    total_dur = last_time - first_time

    if unique_onset_idxs is None:
        # unique_onset_idxs = unique_onset_idx(score[:, 0])
        unique_onset_idxs = get_unique_onset_idxs(onsets)

    u_onset = np.array([np.mean(onsets[uix]) for uix in unique_onset_idxs])
    # add last offset, so we have as many IOIs as notes
    u_onset = np.r_[u_onset, last_time]

    output_dict = dict(
        u_onset=u_onset, total_dur=total_dur, unique_onset_idxs=unique_onset_idxs
    )

    if return_diff:
        output_dict["diff_u_onset"] = np.diff(u_onset)

    return output_dict
```

--------------------------------

### Initialize Dataset Directory

Source: https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html

Sets up the dataset for the tutorial by initializing the dataset directory and defining paths for MusicXML, MIDI, and Match files.

```python
# setup the dataset
from load_data import init_dataset
DATASET_DIR = init_dataset()
MUSICXML_DIR = os.path.join(DATASET_DIR, 'musicxml')
MIDI_DIR = os.path.join(DATASET_DIR, 'midi')
MATCH_DIR = os.path.join(DATASET_DIR, 'match')


```

--------------------------------

### Removing Starting Objects from TimePoint

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Removes a musical object from the list of objects starting at this TimePoint. The object's 'start' attribute is set to None. Handles cases where the object might not be present.

```python
def remove_starting_object(self, obj):
        """Remove object `obj` from the list of starting objects."""
        # TODO: check if object is stored under a superclass
        obj.start = None
        if type(obj) in self.starting_objects:
            try:
                self.starting_objects[type(obj)].remove(obj)
            except ValueError:
                # don't complain if the object isn't in starting_objects
                pass

```

--------------------------------

### Voice Setup Method

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/musicanalysis/voice_separation.html

Internal method to set up the Voice object after initialization or when streams are appended. It sorts streams by onset, collects all notes, establishes prev_stream and next_stream relationships between streams, and assigns the voice to all notes.

```python
def _setup_voice(self):
        # sort stream by onset
        self.streams.sort(key=lambda x: x.onset)

        # array notes in the stream
        self.notes = []
        for stream in self.streams:
            self.notes += list(stream.notes)

        self.notes = np.array(sort_by_onset(self.notes))

        self.streams[0].prev_stream = None
        self.streams[-1].next_stream = None
        for i, stream in enumerate(self.streams[1:]):
            stream.prev_stream = self.streams[i]
            self.streams[i].next_stream = stream

        self.voice = self._voice
```

--------------------------------

### Fill Rests Within Measure

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Fills in rests within a specific measure if a voice starts later than the measure's start time. It ensures that the duration from the measure start to the first note is accounted for.

```python
def _fill_rests_within_measure(measure: Measure, part: Part) -> None:
    start_time = measure.start.t
    end_time = measure.end.t
    notes = np.array(list(part.iter_all(GenericNote, start_time, end_time)))
    voc_staff = np.array([[n.voice, n.staff] for n in notes])
    un_voc_staff, inverse_map = np.unique(voc_staff, axis=0, return_inverse=True)
    for i in range(un_voc_staff):
        note_mask = inverse_map == i
        notes_per_vocstaff = notes[note_mask]
        # get note with min start.t
        min_start_note = notes_per_vocstaff[np.argmin(notes_per_vocstaff.start.t)]
        if min_start_note.start.t > start_time:
            sym_dur = estimate_symbolic_duration(
                min_start_note.start.t - start_time, part._quarter_durations[0]
            )
            rest = Rest(
                symbolic_duration=sym_dur,
                staff=min_start_note.staff,
                voice=min_start_note.voice,
            )
            part.add(rest, start_time, min_start_note.start.t)

        min_end_note = notes_per_vocstaff[
            np.argmin(np.vectorize(lambda x: x.end.t)(notes_per_vocstaff))
        ]
        if min_end_note.end.t < end_time:
            sym_dur = estimate_symbolic_duration(
                end_time - min_end_note.end.t, part._quarter_durations[0]
            )
            rest = Rest(
                symbolic_duration=sym_dur,
                staff=min_end_note.staff,
                voice=min_end_note.voice,
            )
            part.add(rest, min_end_note.end.t, end_time)

```

--------------------------------

### Load MusicXML with Options

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmusicxml.html

Demonstrates loading a MusicXML file with options for validation, forcing note IDs, and ignoring invisible objects. Includes a warning for the `ignore_invisible_objects` parameter.

```python
@deprecated_alias(xml="filename")
@deprecated_parameter("ensure_list")
def load_musicxml(
 filename: PathLike,
 validate: bool = False,
 force_note_ids: Optional[Union[bool, str]] = None,
 ignore_invisible_objects: bool = False,
) -> score.Score:
    """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.
    ignore_invisible_objects : bool, optional
        When True, objects that with the attribute `print-object="no"`
        will be ignored. Defaults to False.

    Returns
    -------
    scr: Score
        A `Score` instance.

    """
    # NOTE: raising warning for ignore_invisible_objects is not ideal and it should be changed in the future
    if ignore_invisible_objects:
        warnings.warn(
            "Be advised that the 'ignore_invisible_objects' option might sometimes lead "
            "to parsing errors for unusual musicxml files. \n"
            "Note that when ignore_invisible_objects is False (the default), the parsing works as expected as before."
        )

    xml = None
    if isinstance(filename, (str, Path)):
        if zipfile.is_zipfile(filename):
            with zipfile.ZipFile(filename) as zipped_xml:
                with zipped_xml.open("META-INF/container.xml") as container:
                    container_tree = etree.parse(container)
                    contained_xml_name = container_tree.find(".//rootfile").get(
                        "full-path"
                    )
                xml = zipped_xml.open(contained_xml_name)

    if xml is None:
        xml = filename

    if validate:
        validate_musicxml(xml, debug=True)
        # if xml is a file-like object we need to set the read pointer to the
        # start of the file for parsing
        if hasattr(xml, "seek"):
            xml.seek(0)

    parser = etree.XMLParser(
        resolve_entities=False,
        huge_tree=False,
        remove_comments=True,
        remove_blank_text=True,
    )
    document = etree.parse(xml, parser)

    if document.getroot().tag != "score-partwise":
        raise Exception("Currently only score-partwise structure is supported")

    partlist_el = document.find("part-list")

    if partlist_el is not None:
        # parse the (hierarchical) structure of score parts
        # (instruments) that are listed in the part-list element
        partlist, part_dict = _parse_partlist(partlist_el)
        # Go through each <part> to obtain the content of the parts.
        # The Part instances will be modified in place
        _parse_parts(
            document, part_dict, ignore_invisible_objects=ignore_invisible_objects
        )
    else:
        partlist = []

    if force_note_ids is True or force_note_ids == "keep":
        assign_note_ids(partlist, force_note_ids == "keep")

    composer = None
    scid = None
    work_title = None
    work_number = None
    movement_title = None
    movement_number = None
    title = None
    subtitle = None
    lyricist = None
    copyright = None

    # The work tag is preferred for the title of the score, otherwise
    # this method will search in the credit tags
    work_info_el = document.find("work")

    if work_info_el is not None:
        scid = get_value_from_tag(
            e=work_info_el,
            tag="work-title",
            as_type=str,
        )
        scidn = get_value_from_tag(
            e=work_info_el,
            tag="work-number",
            as_type=str,
        )

```

--------------------------------

### Load and Print MusicXML Part

Source: https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html

Loads a MusicXML file and prints its pretty representation. Ensure the path to the MusicXML file is correct.

```python
path_to_musicxml = pt.EXAMPLE_MUSICXML
part = pt.load_musicxml(path_to_musicxml)[0]
print(part.pretty())
```

--------------------------------

### TimedObject Initialization

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Initializes a TimedObject with start and end attributes set to None. This is the base class for objects with a defined start and end time.

```python
def __init__(self):
        super().__init__()
        self.start = None
        self.end = None
```

--------------------------------

### TimedObject String Representation

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Returns a string representation of the TimedObject, showing its start and end times and its type. Handles cases where start or end are None.

```python
def __str__(self):
        start = "" if self.start is None else f"{self.start.t}"
        end = "" if self.end is None else f"{self.end.t}"
        return start + "--" + end + " " + type(self).__name__
```

--------------------------------

### VSBaseScore Setup Score

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/musicanalysis/voice_separation.html

Sets up the score by processing notes, determining unique time points, and initializing sounding notes at each time point. Handles both list and numpy array inputs for notes.

```python
def _setup_score(self):
        if isinstance(self.notes, list):
            self.notes = np.array(list(set(self.notes)))
        elif isinstance(self.notes, np.ndarray):
            self.notes = np.array(list(set(self.notes)))

        # sort notes by onset
        self.notes = self.notes[np.argsort([n.onset for n in self.notes])]
        # Get onsets of the notes
        self.note_onsets = np.array([n.onset for n in self.notes])
        # Get offsets of the notes
        self.note_offsets = np.array([n.offset for n in self.notes])

        # Get unique onsets
        self.unique_onsets = np.unique(self.note_onsets)
        self.unique_onsets.sort()

        # Get duration of the notes
        self.note_durations = self.note_offsets - self.note_onsets

        # Get all timepoints in the score
        self.unique_timepoints = np.unique(
            np.hstack((self.note_onsets, self.note_offsets))
        )
        # Sort them in ascending order
        self.unique_timepoints.sort()

        # shortcut
        self.utp = self.unique_timepoints

        # Initialize dictionary of sounding notes at each unique time point
        self._sounding_notes = dict()

        for tp in self.unique_timepoints:
            # boolean array of the notes ending after the time point
            # (and therefore sounding at this timepoint)
            ending_after_tp = self.note_offsets > tp

            # boolean array of the notes starting before or at this time point
            starting_before_tp = self.note_onsets <= tp

            # boolean array of the notes starting at this timepoint
            sounding_idxs = np.logical_and(starting_before_tp, ending_after_tp)

            # Set notes in dictionary
            self._sounding_notes[tp] = sort_by_pitch(list(self.notes[sounding_idxs]))
```

--------------------------------

### Add Object to Timeline

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Adds an object to the timeline based on its start and/or end times. Ensures that start and end times are non-negative integers.

```python
def add(self, o, start=None, end=None):
        """Add an object to the timeline.

        An object can be added by start time, end time, or both,
        depending on which of the `start` and `end` keywords are
        provided. If neither is provided this method does nothing.

        `start` and `end` should be non-negative integers.

        Parameters
        ----------
        o : :class:`TimedObject`
            Object to be removed
        start : int, optional
            The start time of the object
        end : int, optional
            The end time of the object

        """
        if start is not None:
            if start < 0:
                raise InvalidTimePointException(
                    "TimePoints should have non-negative integer values"
                )
            self.get_or_add_point(start).add_starting_object(o)
        if end is not None:
            if end < 0:
                raise InvalidTimePointException(
                    "TimePoints should have non-negative integer values"
                )
            self.get_or_add_point(end).add_ending_object(o)
```

--------------------------------

### Prepare for Tempo Curve Comparison

Source: https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html

This snippet demonstrates how to get all match files in a directory and set up a score time array for comparing tempo curves. It uses `glob` to find files and `np.linspace` to create time points.

```python
# get all match files
matchfiles = glob.glob(os.path.join(MATCH_DIR, 'Chopin_op10_no3_p*.match'))
matchfiles.sort()

# Score time from the first to the last onset
score_time = np.linspace(snote_array['onset_beat'].min(),
                         snote_array['onset_beat'].max(),
                         100)
```

--------------------------------

### TimedObject Class

Source: https://partitura.readthedocs.io/en/latest/modules/partitura.score.html

Base class for all objects with start and end points. Its start and end attributes are managed by the Part's add() and remove() methods.

```APIDOC
## class partitura.score.TimedObject

### Description
This is the base class of all classes that have a start and end point. The start and end attributes initialized to None, and are set/unset when the object is added to/removed from a Part, using its `add()` and `remove()` methods, respectively.

### Attributes
- **start** (`TimePoint`): Start time of the object.
- **end** (`TimePoint`): End time of the object.

### Properties
- **duration** (`int` or `None`): The duration of the timed object in divisions. Returns None if start or end is None.
```

--------------------------------

### Handle New Page and New System Directives

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmusicxml.html

Processes MusicXML elements that indicate a new page or a new system. It calls helper functions `_handle_new_page` and `_handle_new_system` based on the element's attributes.

```python
def _handle_print(e, position, part, ongoing):
    if "new-page" in e.attrib:
        _handle_new_page(position, part, ongoing)
        _handle_new_system(position, part, ongoing)
    if "new-system" in e.attrib:
        _handle_new_system(position, part, ongoing)
```

--------------------------------

### Prepare Note Array with Pitch Spelling and Key Signature

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/musicanalysis/tonal_tension.html

Prepares a note array by ensuring pitch spelling and key signature information is present, estimating them if necessary.

```python
def prepare_note_array(note_info):
    note_array = ensure_notearray(
        note_info, include_pitch_spelling=True, include_key_signature=True
    )

    onset_unit, duration_unit = get_time_units_from_note_array(note_array)

    pitch_spelling_fields = ("step", "alter", "octave")
    key_signature_fields = ("ks_fifths", "ks_mode")

    if len(set(pitch_spelling_fields).difference(note_array.dtype.names)) > 0:
        warnings.warn(
            "No pitch spelling information! Estimating pitch spelling...", stacklevel=2
        )
        from partitura.musicanalysis.pitch_spelling import estimate_spelling

        spelling = estimate_spelling(note_array)

        note_array = add_field(note_array, spelling.dtype)

        for field in spelling.dtype.names:
            note_array[field] = spelling[field]

    if len(set(key_signature_fields).difference(note_array.dtype.names)) > 0:
        warnings.warn("No key information! Estimating key...", stacklevel=2)
        from partitura.musicanalysis.key_identification import estimate_key
        from partitura.utils.music import key_name_to_fifths_mode, key_mode_to_int

        key_name = estimate_key(note_array)
        fifths, mode = key_name_to_fifths_mode(key_name)

        note_array = add_field(note_array, [("ks_fifths", "i4"), ("ks_mode", "i4")])

        note_array["ks_fifths"] = np.ones(len(note_array)) * fifths
        note_array["ks_mode"] = np.ones(len(note_array)) * key_mode_to_int(mode)

    return note_array
```

--------------------------------

### TimedObject Class

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

The base class for all objects that have a start and end point. It manages the start and end time attributes, which are set when the object is added to or removed from a Part.

```APIDOC
class TimedObject(ReplaceRefMixin):
    """This is the base class of all classes that have a start and end
    point. The start and end attributes initialized to None, and are
    set/unset when the object is added to/removed from a Part, using
    its :meth:`~Part.add` and :meth:`~Part.remove` methods,
    respectively.

    Attributes
    ----------
    start : :class:`TimePoint`
        Start time of the object
    end : :class:`TimePoint`
        End time of the object

    """

    def __init__(self):
        super().__init__()
        self.start = None
        self.end = None

    def __str__(self):
        start = "" if self.start is None else f"{self.start.t}"
        end = "" if self.end is None else f"{self.end.t}"
        return start + "--" + end + " " + type(self).__name__

    @property
    def duration(self):
        """The duration of the timed object in divisions. When either
        the start or the end property of the object are None, the
        duration is None.

        Returns
        -------
        int or None

        """
        if self.start is None or self.end is None:
            return None
        else:
            return self.end.t - self.start.t

```

--------------------------------

### Iterate Forwards in Time

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Iterates forwards in time from the current timepoint over starting object(s) of a specified class. Can include subclasses and start at the current timepoint if `eq` is True.

```python
def iter_next(
        self,
        cls: Type[TimedObject] | Iterable[Type[TimedObject]] | None = None,
        eq: bool = False,
        include_subclasses: bool = False,
    ) -> Generator[TimedObject, None, None]:
        """Iterate forwards in time from the current timepoint over
        starting object(s) of type `cls`. When `cls` is a list/tuple
        of classes, include objects of any class in `cls`.

        Parameters
        ----------
        cls : class or list/tuple of classes
            Class(es) of objects to iterate over
        eq : bool, optional
            If True start iterating at the current timepoint, rather
            than its successor. Defaults to False.
        include_subclasses : bool, optional
            If True include subclasses of `cls` in the iteration.
            Defaults to False.

        Yields
        ------
        cls
            Instances of `cls`

        """
        return self._iter_next_prev(cls, eq, include_subclasses, mode="next")
```

--------------------------------

### Print First 5 Notes from Performance Note Array

Source: https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html

Displays the first 5 notes from a performance's note array, showing onset time, duration, pitch, velocity, track, and channel.

```python
print(performance_note_array[:5])
```

--------------------------------

### Initialize MeiParser

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmei.html

Instantiate the `MeiParser` class with the path to an MEI file. This constructor parses the MEI file, initializes namespaces, and prepares for part creation and content filling. It raises `FileNotFoundError` if the specified file does not exist.

```python
from partitura.io.importmei import MeiParser

parser = MeiParser("path/to/your/score.mei")
```

--------------------------------

### Iterate Backwards in Time

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Iterates backwards in time from the current timepoint over starting object(s) of a specified class. Can include subclasses and start at the current timepoint if `eq` is True.

```python
def iter_prev(
        self,
        cls: Type[TimedObject] | Iterable[Type[TimedObject]] | None = None,
        eq: bool = False,
        include_subclasses: bool = False,
    ) -> Generator[TimedObject, None, None]:
        """Iterate backwards in time from the current timepoint over
        starting object(s) of type `cls`. When `cls` is a list/tuple of
        classes, include objects of any class in `cls`.

        Parameters
        ----------
        cls : class or list/tuple of classes
            Class(es) of objects to iterate over
        eq : bool, optional
            If True start iterating at the current timepoint, rather
            than its predecessor. Defaults to False.
        include_subclasses : bool, optional
            If True include subclasses of `cls` in the iteration.
            Defaults to False.

        Yields
        ------
        cls
            Instances of `cls`

        """
        return self._iter_next_prev(cls, eq, include_subclasses, mode="prev")
```

--------------------------------

### Tempo and Meter Analysis with Multiple Agents

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/musicanalysis/meter.html

This snippet demonstrates how to aggregate note onsets and saliences, then use the MultipleAgents algorithm to estimate tempo, meter numerator, and beats. It's useful for analyzing rhythmic patterns in music.

```python
        prev_note_on = aggregated_notes[-1][0]
        prev_note_salience = aggregated_notes[-1][1]
        if abs(note_on - prev_note_on) < CHORD_SPREAD_TIME:
            aggregated_notes[-1] = (note_on, prev_note_salience + 1)
        else:
            aggregated_notes.append((note_on, 1))

    onsets, saliences = list(zip(*aggregated_notes))

    ma = MultipleAgents()
    ma.run(onsets, saliences)

    return dict(tempo=ma.getTempo(), meter_numerator=ma.getNum(), beats=ma.getBeats())
```

--------------------------------

### Sort and Process Slurs in MusicXML

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmusicxml.html

Sorts slurs by number and processes start and stop slur events. Handles cases where slur stops might appear before starts or are rogue.

```python
slurs.sort(
        key=lambda x: get_value_from_attribute(x, "number", int) or note.voice or 1
    )

    for slur_e in slurs:
        slur_number = get_value_from_attribute(slur_e, "number", int) or note.voice
        slur_type = get_value_from_attribute(slur_e, "type", str)
        start_slur_key = ("start_slur", slur_number)
        stop_slur_key = ("stop_slur", slur_number)

        if slur_type == "start":
            # check if we have a stopped_slur in ongoing that corresponds to
            # this stop
            slur = ongoing.pop(stop_slur_key, None)

            # if slur.end_note.start.t < position then the slur stop is
            # rogue. We drop it and treat the slur start like a fresh start
            if slur is None or slur.end_note.start.t < position:
                if slur and slur.end_note.start.t < position:
                    msg = (
                        "Dropping slur {} starting at {} ({}) and ending "
                        "at {} ({})"
                    ).format(
                        slur_number,
                        position,
                        note.id,
                        slur.end_note.start.t,
                        slur.end_note.id,
                    )
                    warnings.warn(msg)
                    # remove the slur from the timeline
                    slur.end_note.start.remove_ending_object(slur)
                    # remove the reference to the slur in the end note
                    slur.end_note.slur_stops.remove(slur)

                slur = score.Slur(note)
                ongoing[start_slur_key] = slur

            else:
                slur.start_note = note

            starting_slurs.append(slur)

        elif slur_type == "stop":
            slur = ongoing.pop(start_slur_key, None)

            if slur is None or slur.start_note.start.t > position:
                if slur and slur.start_note.start.t > position:
                    msg = (
                        "Dropping slur {} starting at {} ({}) and ending "
                        "at {} ({})"
                    ).format(
                        slur_number,
                        slur.start_note.start.t,
                        slur.start_note.id,
                        position,
                        note.id,
                    )
                    warnings.warn(msg)
                    # remove the slur from the timeline
                    slur.start_note.start.remove_starting_object(slur)
                    # remove the reference to the slur in the end note
                    slur.start_note.slur_starts.remove(slur)

                # slur stop occurs before slur start in document order, that
                # is a valid scenario
                slur = score.Slur(None, note)
                ongoing[stop_slur_key] = slur

            else:
                slur.end_note = note

            stopping_slurs.append(slur)

    return starting_slurs, stopping_slurs
```

--------------------------------

### Handle Dashes Start/Stop

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmusicxml.html

Manages the 'start' and 'stop' states for 'dashes' elements, updating the ongoing directions. It issues a warning if a 'stop' dash is encountered without a preceding 'start'.

```python
for dashes_key, dashes_type in dashes_keys.items():
        if dashes_type == "start":
            ongoing[dashes_key] = starting_directions

        elif dashes_type == "stop":
            oo = ongoing.get(dashes_key)
            if oo is None:
                warnings.warn("Dashes end without dashes start")
            else:
                ending_directions.extend(oo)
                del ongoing[dashes_key]
```

--------------------------------

### Handle New System Element in MusicXML

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmusicxml.html

Creates score.System objects for <new-system> elements. It manages the start and end of systems, ignoring non-informative tags at the score's beginning and incrementing system numbers.

```python
if "system" in ongoing:
    if position == 0:
        return

    part.add(ongoing["system"], None, position)
    system_nr = ongoing["system"].number + 1
else:
    system_nr = 1

system = score.System(system_nr)
part.add(system, position)
ongoing["system"] = system
```

--------------------------------

### Staff Class Initialization

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Initializes a Staff object with a staff number and an optional number of lines. Defaults to 5 lines if not specified.

```python
class Staff(TimedObject):
    """A staff.

    Parameters
    ----------
    number : int
        The staff number
    lines : int, optional (default: 5)

    Attributes
    ----------
    number : int
        See parameters

    """

    def __init__(self, number, lines=5):
        super().__init__()
        self.number = number
        self.lines = lines

    def __str__(self):
        return f"{super().__str__()} number={self.number} lines={self.lines}"
```

--------------------------------

### Segment Performed Part by Start and End Times

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/utils/music.html

Segments a performed part into smaller parts based on provided start and end times, with an option to enforce a minimum segment duration.

```APIDOC
## segment_ppart_by_start_end_times

### Description
Segment a performed part by given start and end times and return a list of the segmented performed parts.

### Parameters
#### Parameters
- **ppart** (PerformedPart) - A PerformedPart object representing the performed part.
- **start_times** (list) - A list of start times in seconds for each segment.
- **end_times** (list) - A list of end times in seconds for each segment.
- **min_segment_duration** (float) - The minimum duration of a segment in seconds. The default is 10.0.

### Returns
- **Tuple[list_pparts, start_end_times]**:
    - **list_pparts** (list) - A list of PerformedPart objects representing the segmented performed parts.
    - **start_end_times** (list) - A list of tuples where each tuple contains the start and end times of each segment in the performed part. This is useful to later split the corresponding audio files.
```

--------------------------------

### Handle Initial Staff Definition

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmei.html

Processes the definition of a single staff, extracting its ID, name, and PPQ value to create a Partitura Part object.

```python
    def _handle_initial_staffdef(self, staffdef_el):
        """
        Handles the definition of a single staff.

        Parameters
        ----------
        staffdef_el : Element tree
            A subtree of a particular Staff from a score.

        Returns
        -------
        part : partitura.Part
            Returns a partitura part filled with meter, time signature, key signature information.
        """
        # Fetch the namespace of the staff.
        id = staffdef_el.attrib[self._ns_name("id", XML_NAMESPACE)]
        label_el = staffdef_el.find(self._ns_name("label"))
        name = label_el.text if label_el is not None else ""
        ppq_attrib = staffdef_el.get("ppq")
        if ppq_attrib is not None:
            ppq = int(ppq_attrib)
        else:
            ppq = self._find_ppq()
        # generate the part
        part = score.Part(id, name, quarter_duration=ppq)
        # fill it with other info, e.g. meter, time signature, key signature
        self._handle_staffdef(staffdef_el, 0, part)
        return part
```

--------------------------------

### Handle Ending Element in MusicXML

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmusicxml.html

Processes <ending> elements, creating score.Ending objects. It manages the start and stop of endings, including cases where a stop is found without a preceding start.

```python
if e.get("type") == "start":
    o = score.Ending(e.get("number")),
    ongoing[key] = o
    part.add(o, position)

elif e.get("type") in ("stop", "discontinue"):
    o = ongoing.pop(key, None)

    if o is None:
        warnings.warn(
            "Found ending[stop] without a preceding ending[start]\n" 
            + "Single measure bracket is assumed"
        )
        o = score.Ending(e.get("number")),
        part.add(o, None, position)

    else:
        part.add(o, None, position)
```

--------------------------------

### Sanitize and insert repetitions

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io/importmei.html

Sanitizes and inserts repetition marks (starts and stops) into the score. It handles unmatched repetitions by adding missing start or stop symbols and ensures correct alternation.

```python
    def _insert_repetitions(self):
        if len(self.repetitions) == 0:
            return
        ## sanitize the found repetitions in case a starting rep is missing
        if self.repetitions[0]["type"] == "stop":
            # add a start symbol at 0
            print(
                "WARNING : unmatched repetitions. adding a repetition start at position 0"
            )
            self.repetitions.insert(0, {"type": "start", "pos": 0})

        status = "stop"
        sanitized_repetition_list = []
        # check if start-stop are alternate
        for i_rep, rep in enumerate(self.repetitions):
            if rep["type"] != status:
                sanitized_repetition_list.append(rep)
            else:
                if (
                    rep["type"] == "start"
                ):  # missing stop, inserting one right before start
                    print(
                        f"WARNING : unmatched repetitions. adding a repetition stop at position {rep['pos']}"
                    )
                    sanitized_repetition_list.append(
                        {"type": "stop", "pos": rep["pos"]}
                    )
                else:  # missing start, inserting one at the last stop
                    print(
                        f"WARNING : unmatched repetitions. adding a repetition start at position {sanitized_repetition_list[-1]['pos']}"
                    )
                    sanitized_repetition_list.append(
                        {"type": "start", "pos": sanitized_repetition_list[-1]["pos"]}
                    )
                # proceed by inserting rep
                sanitized_repetition_list.append(rep)
            # switch the status
            status = "stop" if status == "start" else "start"
        # check if ending with a start
        if sanitized_repetition_list[-1] == "start":
            print("WARNING : unmatched repetitions. Ignoring last start")
        ## sanitize the found repetitions to remove duplicates
        sanitized_repetition_list = list(
            OrderedDict(
                (tuple(d.items()), d) for d in sanitized_repetition_list
            ).values()
        )
        self.repetitions = sanitized_repetition_list

        ## insert the repetitions to all parts
        for rep_start, rep_stop in zip(self.repetitions[:-1:2], self.repetitions[1::2]):
            assert (
                rep_start["type"] == "start" and rep_stop["type"] == "stop"
            ), "Something wrong with repetitions"
            for part in score.iter_parts(self.parts):
                part.add(score.Repeat(), rep_start["pos"], rep_stop["pos"])
```

--------------------------------

### Import Core Libraries

Source: https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html

Imports essential libraries for music processing, including partitura, numpy, and matplotlib for data manipulation and visualization.

```python
import glob
import partitura as pt
import numpy as np
import matplotlib.pyplot as plt


```

--------------------------------

### Iterate Over Timed Objects

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Iterates over all instances of specified classes within a given time range, filtering by whether they start or end within that range. Defaults to iterating over all objects starting in the entire timeline.

```python
def iter_all(
        self,
        cls: Type[TimedObject] | Iterable[Type[TimedObject]] | None = None,
        start: TimePoint | None = None,
        end: TimePoint | None = None,
        include_subclasses: bool = False,
        mode: Literal["starting", "ending"] = "starting",
    ) -> Generator[TimedObject, None, None]:
        """Iterate (in direction of increasing time) over all
        instances of `cls` that either start or end (depending on
        `mode`) in the interval `start` to `end`.  When `start` and
        `end` are omitted, the whole timeline is searched.

        Parameters
        ----------
        cls : class or list/tuple of classes, optional
            The class of objects to iterate over. If omitted, iterate
            over all objects in the part. When cls is list/tuple of
            classes, instances of any class in the list/tuple will be
            yielded.
        start : :class:`TimePoint`, optional
            The start of the interval to search. If omitted or None,
            the search starts at the start of the timeline. Defaults
            to None.
        end : :class:`TimePoint`, optional
            The end of the interval to search. If omitted or None,
            the search ends at the end of the timeline. Defaults to
            None.

```

--------------------------------

### Initialize Part and Generate Durations/Pitches

Source: https://partitura.readthedocs.io/en/latest/Tutorial/notebook.html

Initializes a Part object and generates random durations and pitches for a specified number of notes.

```python
l = 200
p = pt.score.Part('CoK', 'Cat on Keyboard', quarter_duration=8)
dur = np.random.randint(1,20, size=(4,l+1))
ons = np.cumsum(dur, axis = 1)
pitch = np.row_stack((np.random.randint(20,40, size=(1,l+1)),
                      np.random.randint(60,80, size=(1,l+1)),
                      np.random.randint(40,60, size=(1,l+1)),
                      np.random.randint(40,60, size=(1,l+1))
                     ))
```

--------------------------------

### Load Performance from File

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/io.html

Loads a performance from a specified file, supporting MIDI and matchfiles. It allows for default BPM, track merging, and adjusting the first note to start at time zero. Handles potential errors during loading by reporting them.

```python
from partitura.utils.music import remove_silence_from_performed_part

performance = None

# Catch exceptions
exception_dictionary = dict()
try:
    performance = load_performance_midi(
        filename=filename,
        default_bpm=default_bpm,
        merge_tracks=merge_tracks,
    )

    # set threshold for sustain pedal
    performance[0].sustain_pedal_threshold = pedal_threshold

    if first_note_at_zero:
        remove_silence_from_performed_part(performance[0])

except Exception as e:
    exception_dictionary["midi"] = e

try:
    performance, _ = load_match(
        filename=filename,
        first_note_at_zero=first_note_at_zero,
        pedal_threshold=pedal_threshold,
    )
except Exception as e:
    exception_dictionary["match"] = e

if performance is None:
    for file_format, exception in exception_dictionary.items():
        print(f"Error loading score as {file_format}:")
        print(exception)
    raise NotSupportedFormatError

return performance
```

--------------------------------

### Convert Repeats to Start/End TimePoints

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Calculates the start and end time points for repeat sections. It handles cases where repeat start or end times are not explicitly defined by using adjacent repeat information or the overall score boundaries.

```python
    t = first
    starts = []
    ends = []
    for repeat in repeats:
        starts.append(t if repeat.start is None else repeat.start)
        if repeat.end is not None:
            t = repeat.end

    t = last
    for repeat in reversed(repeats):
        ends.append(t if repeat.end is None else repeat.end)
        if repeat.start is not None:
            t = repeat.start
    ends.reverse()
    return list(zip(starts, ends))
```

--------------------------------

### Iterate Over Starting/Ending Objects

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/score.html

Provides a generic way to iterate over starting or ending objects within a timepoint. The `prepare_cls` flag optimizes by preparing the class argument only once if needed.

```python
def _iter_objects(
        self,
        cls: Type[TimedObject] | Iterable[Type[TimedObject]],
        include_subclasses: bool = False,
        mode: Literal["starting", "ending"] = "starting",
        prepare_cls: bool = True,
    ) -> Generator[TimedObject, None, None]:
        """
        Generic code to iterate over starting/ending objects.  The `prepare_cls`
        flag can be used to indicate that there is no need to prepare the `cls`
        argument.  This is for efficiency, since `_iter_objects` is typically
        called for many timepoints with the same `cls` (e.g. from
        `Part.iter_all`), so it makes sense to prepare `cls` only once in
        advance, and then pass `prepare_cls=False`.
        """

        if mode == "starting":
            items = self.starting_objects
        elif mode == "ending":
            items = self.ending_objects
        else:
            raise ValueError(f"Invalid mode {mode} (must be 'starting' or 'ending')")
        if prepare_cls:
            # handle default value, warn on potential issues
            cls, include_subclasses = prepare_iter_cls(cls, include_subclasses)

        if isinstance(cls, type):
            # single target class
            if include_subclasses:
                for key in items.keys():
                    if issubclass(key, cls):
                        yield from items[key]
            elif cls in items:
                yield from items[cls]
        else:
            # multiple target classes
            yielded = set()
            for c in cls:
                if include_subclasses:
                    for key, objects in items.items():
                        if issubclass(key, c):
                            for obj in objects:
                                if obj not in yielded:
                                    yield obj
                                    yielded.add(obj)
                else:
                    if c in items:
                        for obj in items[c]:
                            if obj not in yielded:
                                yield obj
                                yielded.add(obj)
```

--------------------------------

### partitura.score.pretty_segments

Source: https://partitura.readthedocs.io/en/latest/modules/partitura.score.html

Gets a pretty string of all the segments in a part.

```APIDOC
## partitura.score.pretty_segments

### Description
Gets a pretty string of all the segments in a part.
```

--------------------------------

### Initialize Tonal Tension Calculation

Source: https://partitura.readthedocs.io/en/latest/_modules/partitura/musicanalysis/tonal_tension.html

Initializes the necessary components for tonal tension calculation, including pitch coordinates, key mapping, and the main tension calculation classes.

```python
note_idxs = notes_to_idx(note_array)

# Get coordinates of the notes in the piece in the spiral array space
piece_coordinates = PITCH_COORDINATES[note_idxs]

# Initialize classes for computing tonal tension
cd = CloudDiameter()
cm = CloudMomentum()

# Get key of the piece from key signature information
# Perhaps add an automatic method in the future (for
# inferring modulations?)
km = key_map_from_keysignature(note_array, onset_unit=onset_unit)
fifths, mode = km(unique_onsets.min()).astype(int)
ts = TensileStrain(tonic_idx=C_IDX + fifths, mode=mode)
```
Tokens:
Raw