PerformancePrecisionLoader

loader.alignment.performance_precision.PerformancePrecisionLoader(
    score_unit=TimeUnit.quarters,
    media_unit=TimeUnit.seconds,
)

Load a Performance Precision specimen directory as an AlignmentBundle.

The loader composes :class:SoloLoader internally for the .solo score and :meth:MetricMap.from_verovio_timemap for the measure structure, then resolves every "<measure>+<offset>" label — both the score notes and the per-performer alignment rows — into absolute quarter-note positions.

Usage follows the standard loader two-phase pattern:

1. loader.load(specimen_dir) — ingests the whole directory.
2. loader.create_bundle() — assembles the AlignmentBundle.
3. loader.create_timeline(uid) / create_timelines() — retrieve individual timelines.

Parameters

Name	Type	Description	Default
score_unit	TimeUnit	Unit for the score timeline. Default TimeUnit.quarters.	TimeUnit.quarters
media_unit	TimeUnit	Unit for the performance timelines. Default TimeUnit.seconds.	TimeUnit.seconds

Attributes

Name	Description
metric_map	The MetricMap of measure boundaries (built from the timemap).
metrical_position_map	The MetricalPositionMap linking quarters ↔︎ measure/beat.

Methods

Name	Description
create_bundle	Assemble an AlignmentBundle from the loaded specimen.
create_timeline	Return a single timeline by uid, role, or performer key.
create_timelines	Return all timelines: [score, performer_1, ..., performer_n].
load	Ingest a whole Performance Precision specimen directory.

create_bundle

loader.alignment.performance_precision.PerformancePrecisionLoader.create_bundle(
)

Assemble an AlignmentBundle from the loaded specimen.

Returns

Name	Type	Description
	'AlignmentBundle'	An AlignmentBundle with the score timeline in its own
	'AlignmentBundle'	"score" group, each performer timeline standalone, and all
	'AlignmentBundle'	MatchClaims as cross-group claims.

Raises

Name	Type	Description
	RuntimeError	If load() has not been called yet.

create_timeline

loader.alignment.performance_precision.PerformancePrecisionLoader.create_timeline(
    uid=None,
    **kwargs,
)

Return a single timeline by uid, role, or performer key.

Parameters

Name	Type	Description	Default
uid	str | None	"score" (or the score uid) for the score timeline; a performer key ("Chopin_Ashkenazy") or its uid ("perf:Chopin_Ashkenazy:cpt1") for a performance timeline.	None

Raises

Name	Type	Description
	KeyError	If no timeline matches.
	RuntimeError	If load() has not been called yet.

create_timelines

loader.alignment.performance_precision.PerformancePrecisionLoader.create_timelines(
    id_pattern=None,
)

Return all timelines: [score, performer_1, ..., performer_n].

Parameters

Name	Type	Description	Default
id_pattern	str | None	Optional regex pattern to filter timeline IDs.	None

load

loader.alignment.performance_precision.PerformancePrecisionLoader.load(
    specimen_dir,
)

Ingest a whole Performance Precision specimen directory.

Parameters

Name	Type	Description	Default
specimen_dir	str | Path	Path to the directory containing the .solo file, the Verovio timemap .json, and the Alignments/ subdirectory.	required

Returns

Name	Type	Description
	Self	Self, for method chaining.

Raises

Name	Type	Description
	FileNotFoundError	If the directory or a required artifact is missing.
	ValueError	If more than one .solo or timemap is present.