How to Load an MPM-Toolbox Project (Score, Modelled Performance, Observed Alignment)

MpmLoader, score in ticks and quarters, MPM markup as events, modelled quarters/seconds TableMap, observed alignment MatchClaims

How to Load an MPM-Toolbox Project (Score, Modelled Performance, Observed Alignment)

An MPM-Toolbox project is a triple of sibling XML files describing one musical work: a .msm notated score, a .mpm modelled performance overlay (tempo, dynamics, articulation, … as expressive markup), and a .mpr project file carrying an observed audio-to-score alignment. This guide loads such a project in a single call and arranges it as one multimodal spanning the logical (score), physical (performance), and graphical (spectrogram) domains.

The work is Beethoven’s Eroica Variations, Op. 35 — Var. XIV — in a 1971 Curzon recording. By the end we will have, in one bundle: the notated score in two logical units, the performance markup carried as s, a modelled tempo curve mapping score quarters to seconds, the observed onsets tied back to the score note by note, and the recording’s spectrogram as a graphical time axis.

We load the modelled markup and the observed alignment exactly as they sit on disk. Nothing here runs an aligner, and the tempo model is read as written — we do not render a beat-accurate performance from it.

The arc:

1. Load the whole project in one call.
2. Read the logical score in two units, linked by a .
3. Read the performance markup carried as s on the score.
4. Read the modelled quarters→seconds tempo map.
5. Read the observed alignment — the physical performance and its cross-group s.
6. Read the recording’s spectrogram as a graphical (pixels) time axis.

Setup

from __future__ import annotations

from timetoalign.core import TimeUnit
from timetoalign.loader.alignment import MpmLoader
from timetoalign.testdata import ensure_data

ROOT = ensure_data("mpm_toolbox")
MPR = (
    ROOT
    / "MPRproject_1971Curzon_VariationXIV"
    / "Beethoven_op35_1971Curzon_Var14only.mpr"
)

/home/laser/miniconda3/envs/timetoalign/lib/python3.11/site-packages/partitura/__init__.py:9: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources

1. Load the project in one call

is given the .mpr project file; it resolves the sibling .msm and .mpm by the bare filenames the project names, parses the score, the selected performance’s markup, and the observed alignment, and binds the recording’s audio for its sample rate. from_file() is the one-line form of the standard two-phase loader pattern.

loader = MpmLoader.from_file(MPR)
loader

MpmLoader

Sources	3 file(s): Beethoven_op35_1971Curzon_Var14only.mpr, Beethoven_op35_1971Curzon_Var14only.msm, Beethoven_op35_1971Curzon_Var14only.mpm
Claims	251
Project	Beethoven_op35_1971Curzon_Var14only
Performance	MEI export performance
Timelines	5 in 2 group(s) (score, perf)
Try	create_timeline(), create_timelines(), create_bundle()

The .mpm may hold several <performance> blocks; by default the first is selected. The pulses-per-quarter grid (720) and the chosen performance name are read straight from the files. To select a different performance, pass MpmLoader().load(MPR, performance="...").

{
    "pulses per quarter": loader.ppq,
    "performance": loader.performance_name,
}

{'pulses per quarter': 720, 'performance': 'MEI export performance'}

create_bundle() assembles the : four timelines arranged in two groups — a shared logical "score" group and a physical "perf" group. Everything below reads from this single bundle.

bundle = loader.create_bundle()
bundle

AlignmentBundle[bundle:AlignmentBundle_1]

  TimelineGroup[score] (2 timelines, 2 timestamps)
  ┌────────────────────────────────────────────────────────────────────────────┐
  │ ContinuousLogicalTimeline[score:clt1] (251 events, 1 cmaps)                │
  │                       0 ____________________________________ 64.5 quarters │
  │                                                                            │
  │ DiscreteLogicalTimeline[score:dlt1] (499 events, 1 cmaps)                  │
  │                       0 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 46440 ticks │
  └────────────────────────────────────────────────────────────────────────────┘
  Timestamps: 2

  TimelineGroup[perf] (3 timelines, 2 timestamps)
  ┌────────────────────────────────────────────────────────────────────────────┐
  │ ContinuousPhysicalTimeline[perf:cpt1] (251 events)                         │
  │                       0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 75.4 seconds │
  │                                                                            │
  │ DiscretePhysicalTimeline[perf:dpt1] (251 events, 1 cmaps)                  │
  │                         0 ⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅⋅ 3324081 samples │
  │                                                                            │
  │ DiscreteGraphicalTimeline[perf:dgt1] (1 cmaps)                             │
  │                       0 ∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶ 26469 pixels │
  └────────────────────────────────────────────────────────────────────────────┘
  Timestamps: 2

  MatchClaims: 251

{
    "timelines": bundle.n_timelines,
    "groups": bundle.n_groups,
    "groups_listed": bundle.group_ids,
    "timelines_listed": bundle.timeline_ids,
}

{'timelines': 5,
 'groups': 2,
 'groups_listed': ['score', 'perf'],
 'timelines_listed': ['score:clt1',
  'score:dlt1',
  'perf:cpt1',
  'perf:dpt1',
  'perf:dgt1']}

---

2. The logical score, in two units

The score lives in the "score" group, in two logical units — the same notes, measured two ways:

• score:dlt1 carries integer tick onsets (the pulsesPerQuarter grid the score was notated on).
• score:clt1 carries quarter-note onsets (an exact rational).

score_dlt = bundle.get_timeline("score:dlt1")
score_dlt

DiscreteLogicalTimeline[score:dlt1] (499 events, 1 cmaps)
                      0 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, 46440 ticks

score_clt = bundle.get_timeline("score:clt1")
score_clt

ContinuousLogicalTimeline[score:clt1] (251 events, 1 cmaps)
                      0 ________________________________ 64.5 quarters

Both hold the same 251 notes. The .msm records each note’s MIDI pitch together with the spelling it was notated with (pitchname / octave); a look at the first few notes of score:clt1 shows what the score carried:

score_clt.get_events().table.slice(0, 5).to_pandas()[
    ["id", "pitch", "pitchname", "octave"]
]

	id	pitch	pitchname	octave
0	nbwxzb1	{'midi_number': 75}	e	4
1	n63xubs	{'midi_number': 82}	b	4
2	n1hksdx3	{'midi_number': 62}	d	3
3	n1vnikpu	{'midi_number': 65}	f	3
4	n5hfy1h	{'midi_number': 70}	b	3

The tick grid and the quarter grid are one conversion apart

The two logical timelines are not independent: a TicksToQuarters on score:dlt1 carries the tick grid to quarters — 720 ticks to the quarter. A on score:dlt1 exposes the conversion at any coordinate, so asking for the quarter reading at a tick is the continuous↔︎discrete link of the logical domain made visible:

{
    "tick 360 -> quarters": score_dlt.get_timestamp(360).get_unit(TimeUnit.quarters),
    "tick 720 -> quarters": score_dlt.get_timestamp(720).get_unit(TimeUnit.quarters),
    "tick 1440 -> quarters": score_dlt.get_timestamp(1440).get_unit(TimeUnit.quarters),
}

{'tick 360 -> quarters': 0.5,
 'tick 720 -> quarters': 1.0,
 'tick 1440 -> quarters': 2.0}

---

3. The performance markup, as events on the score

A .mpm overlays the score with expressive markup — tempo, dynamics, articulation, asynchrony, and any other map type the project carries. The loader places every markup entry on score:dlt1 as an at its tick onset, sitting alongside the Note events. A single logical timeline therefore carries both the notes and the modelled performance markup, read with the same event query used everywhere else — filter by event_type.

The coordinate (start) comes back as a number; the remaining markup columns currently round-trip as strings, so we cast them as we read.

Tempo

Each Tempo event carries a beats-per-minute reading. The MPM value may be an inline number or a style name declared in the performance’s style block; either way the loader resolves it to a number, keeping the original token in a *_label column. Here the style name "Meno mosso." resolves to 100 BPM:

tempo_events = score_dlt.get_events().filter(event_type="Tempo").to_dataframe()

tempo_table = tempo_events[["start", "bpm_label", "bpm"]].copy()
tempo_table["tick"] = tempo_table.pop("start").astype(int)
tempo_table["bpm"] = tempo_table["bpm"].astype(float)

tempo_table[["tick", "bpm_label", "bpm"]].head(7)

	tick	bpm_label	bpm
0	0	Meno mosso.	100.0
1	28440	25.0	25.0
2	28800	Meno mosso.	100.0
3	39960	25.0	25.0
4	40320	Meno mosso.	100.0
5	45000	25.0	25.0
6	46080	adagio	79.0

Dynamics

Dynamics events resolve the same way: the dynamic mark "p" is a style name that resolves to a MIDI volume of 48, with the mark preserved in volume_label:

dynamics_events = score_dlt.get_events().filter(event_type="Dynamics").to_dataframe()

dynamics_table = dynamics_events[["start", "volume_label", "volume"]].copy()
dynamics_table["tick"] = dynamics_table.pop("start").astype(int)
dynamics_table["volume"] = dynamics_table["volume"].astype(float)

dynamics_table[["tick", "volume_label", "volume"]].head(6)

	tick	volume_label	volume
0	0	p	48.0
1	6336	p	48.0
2	7560	f	72.0
3	9000	f	72.0
4	10440	p	48.0
5	17640	p	48.0

Articulation

Articulation events name an articulation (staccato, tenuto, …) and, where the performance declares a definition for it, resolve its numeric attributes. A staccato here resolves to an absolute played duration of 160 ms; the noteid it applies to is carried alongside (its leading # stripped):

articulation_events = (
    score_dlt.get_events().filter(event_type="Articulation").to_dataframe()
)

staccato = articulation_events[articulation_events["name"] == "staccato"].copy()
staccato["tick"] = staccato.pop("start").astype(int)
staccato["absolute_duration_ms"] = staccato["absolute_duration_ms"].astype(float)

staccato[["tick", "name", "absolute_duration_ms", "noteid"]].head(5)

	tick	name	absolute_duration_ms	noteid
173	29160	staccato	160.0	ngx1f26
174	29160	staccato	160.0	n14ahlx1
175	30600	staccato	160.0	nbeyber
176	30600	staccato	160.0	n1y3yzsw
177	32040	staccato	160.0	ncgjw5z

The point of this section: tempo and dynamics style names resolve to numeric values, articulations resolve to played durations and velocities, and every one of them is an event on the score timeline, queried the same way the notes are. Any map type the loader does not model specially is still emitted, with its raw attributes carried verbatim, so nothing in a project is silently dropped.

---

4. The modelled tempo, as quarters → seconds

The performance’s tempo markup also defines, segment by segment, how fast the score is taken. The loader integrates it into a modelled quarters→seconds — a TableMap it exposes directly:

tempo_map = loader.tempo_map
tempo_map

TableMap(n_points=8, source_unit=quarters, target_unit=seconds, kind=linear)

It is anchored at the score’s start (0 quarters → 0 seconds) and walks forward at each tempo segment’s pace. Converting a couple of quarter positions reads the modelled clock-time at which the score reaches them:

{
    "quarter 0 -> seconds": tempo_map(0),
    "quarter 39.5 -> seconds": tempo_map(39.5),
    "quarter 40.0 -> seconds": tempo_map(40.0),
}

{'quarter 0 -> seconds': 0.0,
 'quarter 39.5 -> seconds': 23.7,
 'quarter 40.0 -> seconds': 24.9}

This is a constant-tempo-per-segment model: each tempo entry sets a flat pace until the next. Accelerando / ritardando ramps (an entry’s transition.to) are preserved as a Tempo-event attribute but are not rendered into the curve — the map reads what the project modelled, deliberately stopping short of synthesising a beat-accurate performance.

---

5. The observed alignment

The model above is one account of the performance. The .mpr carries another: an observed alignment, recording for every score note the moment it was actually played in the recording. The loader places these onsets in the physical "perf" group, in two units — perf:cpt1 in seconds and perf:dpt1 in samples, linked (as in any physical timeline) by a SamplesToSeconds carrying the recording’s sample rate.

perf_cpt = bundle.get_timeline("perf:cpt1")
perf_cpt

ContinuousPhysicalTimeline[perf:cpt1] (251 events)
                      0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 75.4 seconds

The score group and the performance group are tied together by cross-group s — one per score note. The .mpr alignment is a perfect bijection (every score note has exactly one observed onset and vice versa), so every claim is synchronous: there are no gaps.

claims = bundle.cross_group_claims

{
    "total claims": len(claims),
    "synchronous (matched)": sum(1 for c in claims if c.is_synchronous),
    "NOMATCH": sum(1 for c in claims if not c.is_synchronous),
}

{'total claims': 251, 'synchronous (matched)': 251, 'NOMATCH': 0}

A single claim relates a score quarter to an observed performed second. This one anchors the note at score quarter 0.5 to the moment it was played, 0.8 seconds into the recording:

quarter_half_claims = [
    c
    for c in claims
    if c.is_synchronous
    and c.start_anchor is not None
    and float(c.start_anchor.coordinate_a) == 0.5
]
quarter_half_claims[0]

MatchClaim synchronous, instant

Timeline A	score:clt1	@0.5
Timeline B	perf:cpt1	@0.828019
Metadata	agent=mpm

Try: claim.get_matchstamp()

One score position, read across the domains

Because the performance is anchored back to the score, a single score coordinate resolves across the whole bundle. get_matchstamp_at takes a coordinate on score:clt1 (quarters) and returns the corresponding coordinate on every connected timeline — here score quarter 2.0 mapped to the second at which it was observed:

stamp = bundle.get_matchstamp_at(2.0, "score:clt1")
stamp

MatchStamp 2 timelines, 1 edges

ID	Coordinate	Type
score:clt1	2	anchor
perf:cpt1	2.177196	anchor

Try: stamp.get(<tl_id>), stamp.get_coordinate(<tl_id>)

Read across that : the same notated quarter resolves to a logical position (2.0 quarters) and an observed physical position (≈ 2.18 seconds), one query crossing from the score domain to the performance domain with no aligner ever run.

---

6. The spectrogram, a graphical axis

The project also ships a rendered spectrogram of the recording — a .png whose horizontal axis is time. The loader reads that axis as a third performance-group , perf:dgt1, measured in pixels (frame columns): one position per column of the image. This is the graphical domain — the same work, now reached visually.

Unlike the other timelines, this one carries no s. A spectrogram column is not a note; it is a tick mark on a picture’s time axis. The timeline’s job is to be that axis — its length is the image’s width in frame columns:

perf_dgt = bundle.get_timeline("perf:dgt1")
perf_dgt

DiscreteGraphicalTimeline[perf:dgt1] (1 cmaps)
                      0 ∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶∶ 26469 pixels

{
    "unit": perf_dgt.unit.name,
    "length (frame columns)": perf_dgt.length.value,
    "events (it is an axis, not events)": perf_dgt.n_events,
}

{'unit': 'pixels',
 'length (frame columns)': 26469,
 'events (it is an axis, not events)': 0}

A pixel column is only meaningful once tied to clock time. Each column advances the recording by a fixed hop of audio samples, so perf:dgt1 carries a px→seconds — a ScalarMap whose scalar is hopSize / sample_rate. Pulling it off the timeline and reading a couple of columns places the picture on the same seconds clock as the performance:

px_to_seconds = perf_dgt.get_conversion_map(TimeUnit.seconds)

last_column = perf_dgt.length.value
{
    "scalar (seconds per column)": px_to_seconds.scalar,
    "column 0 -> seconds": perf_dgt.get_timestamp(0).get_unit(TimeUnit.seconds),
    f"column {last_column} -> seconds": perf_dgt.get_timestamp(last_column).get_unit(
        TimeUnit.seconds
    ),
}

{'scalar (seconds per column)': 0.0029024943310657597,
 'column 0 -> seconds': 0.0,
 'column 26469 -> seconds': 76.82612244897959}

Column 0 sits at the start of the recording; the rightmost column lands at the spectrogram’s full time span — the audio duration. The picture’s x-axis and the performance’s seconds are now one conversion apart, exactly as ticks and quarters were on the score.

Recap

What the bundle expresses	How
Score, two logical units	score:dlt1 (ticks) + score:clt1 (quarters), one TicksToQuarters map
Performance markup	Tempo / Dynamics / Articulation events on score:dlt1, via filter(event_type=...)
Modelled tempo	a quarters→seconds TableMap (loader.tempo_map), constant-tempo-per-segment
Observed performance, two physical units	perf:cpt1 (s) + perf:dpt1 (samples), one SamplesToSeconds
Spectrogram, a graphical axis	perf:dgt1 (pixels), no events, one px→seconds ScalarMap
Score ↔︎ performance	one synchronous per note (a perfect bijection)
A score position read across domains	bundle.get_matchstamp_at(coord, "score:clt1")

One now expresses this single work across all three domains — logical (score ticks and quarters), physical (performance seconds and samples), and graphical (spectrogram pixels). Within each group the units are tied by s; across the groups the score and performance are tied note by note by s. A single object holds what was notated, how it was modelled, how it was actually played, and how it looks — the score, the model, the recording, and its picture, all on one set of linked clocks.