API Reference

Core Types

Fundamental types for coordinates, units, domains, and cross-section timestamps.

Coordinate	A position on a timeline, defined by a value and unit.
CoordinateField	Semantic field for coordinate fields.
Coord
CoordinateSpec
CoordinateValue
IdCoordinate	A Coordinate that carries the ID of the timeline it belongs to.
OptionalCoordinate
ResolvedCoordinate	Decomposed form of a CoordinateSpec input.
resolve_coordinate_spec	Decompose a coordinate specification without converting its unit.
Domain	The temporal domain of a timeline.
TimeUnit	Units of measurement for coordinates.
NumberType	The numeric type used for coordinate values.
EventType	Whether an event is an instant or interval.
ColumnNaming	How to name columns in timestamp DataFrames.
ColumnRole	Semantic role of a column in the table.
ScopedId	An identifier with a scope prefix and local part.
IdGenerator	Generates unique IDs within a given scope.
TimeStamp	A synchronized instant across a timeline hierarchy.
TimeIntervalStamp	An interval defined by start and end TimeStamps.
GroupTimestamp	A synchronized instant across all timelines in a group.

Timelines

Timeline classes for all six domain/modality combinations.

Timeline	A positive coordinate axis with events and nested child timelines.
ContinuousLogicalTimeline	A logical timeline with continuous coordinates.
DiscreteLogicalTimeline	A logical timeline with discrete (integer) coordinates.
ContinuousPhysicalTimeline	A physical timeline with continuous coordinates.
DiscretePhysicalTimeline	A physical timeline with discrete (integer) coordinates.
ContinuousGraphicalTimeline	A graphical timeline with continuous coordinates.
DiscreteGraphicalTimeline	A graphical timeline with discrete (integer) coordinates.
LogicalTimeline	A timeline representing logical/musical time.
PhysicalTimeline	A timeline representing physical/acoustic time.
GraphicalTimeline	A timeline representing graphical/spatial coordinates.
BeatGrid	A metrical timeline whose native coordinate axis is quarter notes.

Flow Control

Score flow-graph traversal, atomic-section labelling, and structural diagnostics.

Flow	A computed flow (sequence of measure visitations).
FlowMap	Coordinate transformation map for flow control.
FlowMapSection	A section mapping in a FlowMap.
FlowControllerBase	Abstract base class for computing flow control transformations.
ScoreFlowController	Score flow controller specialized for score data (MeasureData).
SegmentNameGenerator	Assign display labels to a run of atomic sections.
AtomicSection	Smallest indivisible traversal unit (similar to partitura’s segment model).
PlaythroughSection	A contiguous group of atomic sections in a specific traversal.
FlowDiagnostic	A structural-invariant violation found in an atomic flow graph.
load_valid_flows	Load all valid flows from a .flow.csv file, grouped by flow_mode.
create_unfolded_timeline	Create an unfolded timeline from a folded source via structural slicing.

Conversion Maps

Functions for transforming coordinates between units.

ConversionMap	Abstract base class for coordinate conversion maps.
ScalarMap	Pure scaling transformation: y = scalar * x.
LinearMap	Affine transformation: y = scalar * x + offset.
ShiftMap	Pure offset transformation: y = x + offset.
TableMap	Lookup table with interpolation between anchor points.
ChainMap	Composition of multiple maps: f(g(h(x))).
ConstantMap	A ConversionMap that returns a constant value for any input.
IntervalToConstantMap	Interval-to-constant map: each interval [x_i, x_{i+1}) maps to value_i.
InterpolationMap	Bidirectional coordinate mapping using numpy.interp.
PiecewiseMap	Map defined by different maps on different intervals.
SecondsToSamples	Convert seconds to audio samples by multiplying by sample rate.
QuartersToFloatingMeasures	Map quarters to measure coordinates (with linear interpolation).
QuartersToMeasureNumber	Map quarters to measure number labels (no interpolation).

Alignment

Classes for connecting and aligning timelines.

TimelineGroup	Container for commensurable timelines.
AlignmentBundle	The primary entry point for all alignment workflows.
SupportPolicy	How to treat a transferred coordinate that falls outside alignment support.
AlignmentAnchor	A coordinate pair associating one coordinate on timeline A with one
MatchClaim	A claim that two events or coordinates on different timelines correspond.
ClaimType	The semantic kind of a MatchClaim, derived from its structure.
MatchClaimField	A SemanticField[MatchClaim] columnar store for pairwise claims.
MatchMetadata	Provenance information for a match claim.
Agent	The author of a match claim — a human annotator or a software aligner.
MatchGraph	A graph of MatchClaims connecting events across timelines/groups.
MatchStamp	A synchronized timestamp across multiple timelines.
MatchLine	Ordered sequence of MatchStamps for a source timeline.
WarpMap	Bidirectional coordinate warping derived from alignment data.
ClaimFilter	Reusable filter for querying MatchClaims and related objects.
MatchFileContext	Supplementary data required for .match file export.
NoteRecord	Performance note record for .match format export.
SnoteRecord	Score note record for .match format export.
TimelineIdGenerator	Generates systematic timeline IDs based on type.

Loaders

Data ingestion from various file formats.

Loader	Shared lifecycle for all loader families.
EventData	PyArrow-based storage for timeline events.
EventStore	Abstract base class for collections of EventData.
SingleStore	Store wrapper for a single EventData.
DictStore	Generic EventStore with arbitrary named EventData tables.
EventLoader	Abstract base class for event-producing loaders.
AudioLoader	Load audio file metadata for creating physical timelines.
AudioInfo	Metadata for an audio file.
RepoVizzLoader	Load RepoVizz XML manifests or single CSV files for creating physical timelines.
RepoVizzInfo	Parsed metadata from a RepoVizz CSV file (legacy mode).
EepNotesLoader	Loader for EEP .notes alignment files.
CsvLoader	Loader for CSV (comma-separated values) files.
TsvLoader	Loader for TSV (tab-separated values) files.
LabLoader	Loader for Audacity/Praat label files (.lab, .txt).
SoloLoader	Loader for .solo performance-precision specimen files.
TabularLoader	Vectorized base class for loading tabular data with column/field specs.
JsonLoader	Configurable JSON normaliser producing flat pa.Table objects.
XmlLoader	Configurable XML normaliser producing flat pa.Table objects.
Music21Loader	Load symbolic scores using music21.
PartituraLoader	Load symbolic scores using partitura.
Ms3Loader	Load symbolic scores from DCML-style TSV files.
MeasureMapLoader	Load MeasureMap JSON files into ScoreStore.
MidiLoader	Abstract base class for MIDI loaders.
PerformanceMidiLoader	Load performance MIDI files using mido.
ScoreMidiLoader	Load score MIDI files using partitura.
GraphicalLoader	Factory for building GraphicalStore objects.
IIIFManifestLoader	Load image metadata from IIIF Presentation API manifests.
ATONLoader	Load ATON format files (piano roll analysis data).
MatchfileLoader	Load Vienna Match (.match) alignment files via partitura.
TiliaJsonLoader	Loader for TiLiA JSON annotation exports.
TiliaDictStore	DictStore subclass with convenience properties for TiLiA timeline types.
PerformancePrecisionLoader	Load a Performance Precision specimen directory as an AlignmentBundle.
ParangonadaLoader	Load a parangonada CSV export as one multimodal AlignmentBundle.
MpmLoader	Load an MPM-Toolbox MSM+MPM+MPR triple as one multimodal AlignmentBundle.
ListenHereLoader	Load a Listen Here! alignment JSON file as one AlignmentBundle.