Glossary

Alphabetical reference of TimeToAlign! model terminology

This page collects all terms introduced in the Conceptual Model. Hover over any -highlighted term elsewhere on this site to see its definition.

For the full context in which each term is introduced, follow the cross-references to the relevant section of the conceptual model.

A

AlignmentAnchor: A coordinate pair associating one coordinate on timeline A with one on timeline B; a neutral record with no claim semantics—provenance is carried by the enclosing . Only synchronous MatchClaims produce AlignmentAnchors. From a of s, one derives a StartAnchor and an EndAnchor. See Alignment.
AlignmentBundle: A collection of s with inter-group connections; provides coordinate transfer via offset arithmetic, interpolation, and s. See Alignment.
AlignmentMatrix: An audio-to-audio alignment in which several recordings of one work are each warped onto a single shared, equidistant reference grid. Per recording, a parallel onset-time array gives that recording’s clock-time at each grid column; because every array indexes the same grid they are equal length, so together they form a dense matrix of shape (recordings × grid columns). A single such file encodes an entire directly — every pair of recordings is related at every grid column — rather than only one score-to-performance correspondence. The complete pairwise claim set is held in a . See Alignment.

B

Break: A that voids at its . TimeIntervals cannot span a Break, and Breaks cannot be inserted into existing TimeIntervals. See Flow control.

C

ChainMap: A that applies multiple s in sequence, creating a conversion path from a source unit to a target unit. See Conversion maps.
Child: A nested within a parent, sharing its measuring unit but defining its own origin. Children are locked upon insertion to prevent side effects from modifications. See Nested timelines.
ClaimType: The semantic kind of a , derived from its structure rather than stored — read from whether the claim is explicit, whether it is synchronous, and how many of its two sides name an event. Six members: event_match (synchronous, both sides name an event; the case that yields s), projection (synchronous, exactly one side names an event, the other a bare coordinate), anchor (synchronous, neither side names an event — two anonymous coordinates), nomatch (non-synchronous, exactly one side names an event whose counterpart is absent; see ), conceptual (non-synchronous, neither or both sides name an event — a structural correspondence with no temporal commitment), and implicit (inferred by graph extension; overrides all the above). See Alignment.
CombinationMap: A yielding outputs from multiple s simultaneously (e.g., (x, y) coordinate pairs). See Conversion maps.
Commensurability: Two timelines are commensurable if connected by a chain of s, membership in the same , or cross-group s, enabling coordinate translation between them. See Alignment.
Commensurable: See .
ConcatenationMap: A combining bounded s such that each coordinate region is handled by a specific map. See Conversion maps.
Contiguity: A is contiguous if it monotonically spans all coordinates between its start and end. An is contiguous with a TimeInterval if it is synchronous with its . See Flow control.
ControlEvent: An event affecting flow control: either a (voiding contiguity) or a (creating new contiguity). See Flow control.
ConversionMap: A typed function attached to a that maps each coordinate to exactly one value (coordinate, label, or filename); also permits inverse conversion back to the timeline’s own unit. Also called C-map. See Conversion maps.
Coordinate: A position on a , expressed as the distance from the origin in the timeline’s measuring unit. Combines a numeric value with a TimeUnit. The unit alone decides the number policy: quarters and beats are exact Fractions, discrete units (ticks, samples, frames, pixels) are locked to int, and the remaining continuous units (seconds, points, centimeters, …) are float. That declared number type is preserved at every boundary — authored, converted, offset-computed, interpolated, queried or retrieved — so a fraction-canonical axis always yields Fractions and a float-canonical axis always yields floats. An explicit number_type= overrides the default, and exact input is never degraded. See Foundations.

D

DictStore: A generic EventStore subclass holding a dict[str, EventData] with arbitrary keys. Used internally by AlignmentLoaders to store one EventData table per timeline-to-be (e.g., "score:clt1", "perf:Chopin_op10_no3_p01:cpt1"). Maintains the uniform EventStore interface. See the API reference.
Discrete: A timeline is discrete when coordinates exist only at discrete points (e.g., pixels, samples, ticks). Contrast with Continuous timelines where coordinates can take any real value (e.g., seconds, quarters). See Foundations.
Domain: One of three temporal categories: Graphical (visual/spatial), Logical (symbolic/musical), or Physical (audio/sound). Each domain has both discrete and continuous timeline variants. See Foundations.

E

EndInstant: An marking the end of a . Its coordinate must be greater than or equal to the corresponding ’s coordinate. See Foundations.
Event: Anything associated with a via s. An has zero duration; a has duration defined by start and end coordinates. See Foundations.

F

Flow: One computed path through a score’s control structure — the ordered sequence of measure visitations that results from following its repeats, s and voltas. A ScoreFlowController computes one from the parsed measure records, or one can be loaded from a .flow.csv ground truth and compared with is_equivalent(). A Flow is section-based; measure-count ranges follow the library’s right-open [start, end) convention. It is the input a is built from, not itself a mapping between coordinates. See Flow control.
FlowMap: A path through a score’s control structure (repeats, jumps), expressed as an ordered sequence of s; not itself a . Used for unfolding a score into performance order. A FlowMap is built from one uniform argument — a single interval-like value (a , a coordinate pair, a , or an interval event) or an iterable of them, which concatenate in performance order — or from a score’s computed flow of s and s. Timeline.create_flow_map(intervals) resolves region names against the timeline’s own s, attaches the FlowMap, and returns it. See Derivative timelines.

G

GroupTimestamp: A cross-section through a at a given coordinate. Contains one coordinate per timeline in the group plus (optionally) C-map conversion values. A is the union of GroupTimestamps from each participating group. Produced by TimelineGroup.get_timestamp_at(). Exported from the package root as timetoalign.GroupTimestamp. See Alignment.

I

IdCoordinate: A that also names the it belongs to. It is the default return of every coordinate getter in the library — stamps, timelines, groups, bundles, match lines, graphs and warp maps all hand back IdCoordinate(value, unit, timeline_id) unless an explicit format= asks for something else. Carrying identity is what lets a retrieved coordinate be handed straight back as a query without restating which axis it came from. An IdCoordinate never compares equal to a plain Coordinate in either direction; use format="coordinate" when timeline identity should be discarded. See Foundations.
Instant: Associates a (a “time-point”) with a signification such as “start of event e”. Instants sharing a coordinate are synchronous. See Foundations.
InstantEvent: An defined by a single , having zero duration. See Foundations.
Interval: A frozen scalar pairing two plain s as a half-open span [start, end): the start is inclusive, the end exclusive. Both endpoints must share one TimeUnit and one number type, which makes the interval’s own unit and number_type unambiguous; its duration is exactly end - start, returned as a Duration. Reversed intervals raise; zero-length ones are valid. It renders through the same formatter the scalars use, so an interval on a quarters axis prints [1/2, 3/2) quarters rather than [0.5, 1.5). Interval is the scalar leaf of interval retrieval: TimeIntervalStamp.get_interval() and TimelineGroup.get_interval_for() both return one. See Nested timelines.
IntervalField: The SemanticField paired with . It stores a struct of start and end coordinate structs under one unit, domain, and number_type metadata triple, materialises Interval | None per row, and exposes vectorized start, end, and duration accessors returning CoordinateField, CoordinateField, and DurationField. See Nested timelines.
InverseMap: The reverse transformation of a bijective . See Conversion maps.

J

Jump: A with JumpFrom and JumpTo s. When active, makes events at JumpTo contiguous with those ending at JumpFrom (e.g., repeats, dal segno). See Flow control.

L

Length: The distance between a ’s origin and its last . See Foundations.
Locked: A timeline state that fixes its coordinate axis: no s may be added after the last time-point, so its length cannot change. Locking governs the coordinate axis only — non-structural annotations such as s may still be added to a locked timeline. timelines are automatically locked when embedded in a parent. See Nested timelines.

M

Match

See .

MatchfileLoader

Loader for Vienna Match (.match) alignment files. Uses the standard two-step load() → create_*() pattern. A single instance processes all .match files that share the same score, building a shared score timeline on the first file and verifying subsequent files against it. Returns an directly via create_bundle(). Score goes into its own group; performances are standalone timelines; s connect score to performances. See the API reference.

MatchClaim

A claim of equivalence between events on different timelines, with provenance metadata (the authoring agent and a certainty). May be synchronous (producing s) or conceptual (structural equivalence without temporal commitment). Always knows which pair of timelines it connects. Four cases: (a) event-to-event,

projection, (c) , (d) implicit (from group extension). Held individually, or columnar at scale in a . See Alignment.

MatchClaimField

A columnar, PyArrow-backed store holding a whole set of synchronous-instant pairwise s as Arrow columns (the two timeline ids dictionary-encoded, each coordinate as a struct of value, numerator, denominator and unit) rather than as one frozen MatchClaim object per claim. Storing the exact ratio beside the float mirror is what lets a claim’s coordinate come back in its axis’s declared number type instead of being flattened on the way through the column. Individual MatchClaims are materialised on demand when a row is indexed or iterated. Built vectorized via from_columns(), it is the scalable backing for dense alignments, where the complete pairwise topology of a whole work runs to roughly a million claims. Shared provenance is held once at field level, never per row. See Alignment.

MatchGraph

An auxiliary structure formed by extending s through shared coordinates; may be viewed as a hyperedge connecting multiple coordinates from different timelines. Connected components yield s. Each Match box M1–M15 in the Hendrix figure is a MatchGraph. See Alignment.

MatchLine

An ordered sequence of s derived from s, sorted by coordinate on a source timeline; input for generation. See Alignment.

MatchPath

A path traversal connecting matched events across multiple timelines (e.g., A -> B -> C), enabling indirect alignment. See Alignment.

MatchStamp

The union of s from groups synchronously connected by a . Contains one coordinate per participating timeline. C-map conversion values are opt-in here: unlike , where C-Maps are visible by default, conversion_maps on a MatchStamp getter (bundle.get_matchstamp_at(), get_matchstamps(), get_matchstamp_table(), MatchClaim.get_matchstamp()) defaults to False — across a large bundle they would bury the alignment answer. This is a per-context default value for a shared parameter, not a structural difference: MatchStamp implements the same Stamp interface as every other stamp type — get_coordinate_for(timeline_id) returns an by default and a plain number under format="float"/"int"/"fraction", get_unit() converts through a C-map, get_conversion_for() reads label and structured map values, present_timelines lists available timelines, and is_interpolated identifies interpolation fallback. A stamp from any source keeps the identical structure, methods, and behaviour the Stamp contract guarantees; only the caller-visible default for one keyword argument varies by producing context. See Alignment.

MetricMap

A table-based from a quarter position to its measure count, built from explicit measure-boundary anchors rather than a uniform measure length. Correctly handles anacrusis (an incomplete first measure), irregular measures, varying time signatures, and repeat structure. Built directly from a Verovio timemap via MetricMap.from_verovio_timemap(). Not invertible — many quarters map to the same measure. See Conversion maps.

MetricalPositionMap

A pairing a with a beat-in-measure map to return a metrical position {mc, beat} from a quarter coordinate. Adds a reverse lookup quarters_at(mc, beat) (metrical position to quarters) and mn_at(quarters) (quarters to measure-number label). See Conversion maps.

MpmLoader

Loader for an MPM-Toolbox project: a sibling .msm score, .mpm modelled performance, and .mpr project file (carrying an observed audio-to-score alignment) for one work. Uses the standard two-step load() → create_*() pattern. Builds a shared logical "score" group holding the notes in two units — a ticks (also carrying every MPM markup event: Tempo, Dynamics, Articulation, …) and a quarters — with a TicksToQuarters map and a modelled quarters→seconds TableMap integrated from the performance’s tempo markup; and a physical "perf" group of observed onsets in seconds and samples. Emits one synchronous cross-group per score note (the MSM xml:id ↔︎ MPR ref join is a bijection). Reads the modelled performance and the observed alignment; never runs an aligner. Returns an via create_bundle().

MultiMap

An umbrella term for composed s: (sequential), (parallel outputs), and (regional). See Conversion maps.

N

NOMATCH: A sentinel value in a explicitly encoding the absence of a corresponding event on the other timeline. The MatchClaim records both timeline IDs but has no s; is_synchronous is always False. See Alignment.

O

Origin: The zero coordinate of a , from which all positions are measured. See Foundations.

P

Parent: A that contains one or more timelines. The parent and all its children must share the same measuring unit. See Nested timelines.
PerformancePrecisionLoader: Loader for audio-to-score alignment specimens: a directory bundling a .solo score, a Verovio timemap, and per-performer alignment files at the note, bar, and beat granularities. Uses the standard two-step load() → create_*() pattern. Resolves every "<measure>+<offset>" label to absolute quarters via a , builds one logical score (quarters) and one physical performance per recording (seconds), and emits a per alignment row — synchronous for located onsets, for the dangling ones. Returns an via create_bundle(). See the API reference.
ParangonadaLoader: Loader for a parangonar parangonada export: per-performance CSV triples (score notes, performed notes, note-level correspondences) for one work. Uses the standard two-step load() → create_*() pattern. Parses the shared score once into two logical s (quarters and division-grid ticks, linked by a divs→quarters LinearMap), builds one performance group per recording with two physical s (seconds and samples, linked by a SamplesToSeconds map), and emits one cross-group per correspondence — synchronous for a matched note, for a score-only or performance-only note. Reads the existing alignment; never runs an aligner. Returns an via create_bundle().

R

raw_quarters: The conventional name for the (specifically a ShiftMap) attached to a score timeline. The timeline stores normalised (non-negative) coordinates — shifted so the minimum onset is 0.0 — and this map converts them back to the raw quarter values of the source. Its offset equals min(raw_onsets). Added by and PartituraLoader so downstream code can detect and apply the same shift when comparing coordinates across loaders.
Region: A named part of a defined by a (e.g., “Chorus”, “Verse”). Regions are not timelines and cannot hold events or maps directly. See Regions.
Root: The top-level in a hierarchy of nested timelines. Only the root timeline can be extended; all descendants are locked. See Nested timelines.
RotationMap: A periodic that wraps coordinates cyclically (e.g., an ostinato part that repeats while the main timeline advances). See Conversion maps.

S

Segment: A timeline that is contiguous with its siblings. Segments enable concatenation of local coordinate systems. See Nested timelines.
SegmentLine: A runtime class parameterized by its segment class, such as SegmentLine[DiscreteGraphicalTimeline], whose contiguous s tile its full length. A line is also an instance of that segment class. Any timeline can check the structure with is_segment_line() and adopt enforcement with as_segment_line(); a line returns to an unenforced timeline with to_timeline(). Use create_children_from_boundaries() for boundary-driven tiling. Appending extends an unlocked line, while appending to an embedded, length-locked line raises RuntimeError. See Nested timelines.
StartInstant: An marking the start of a . See Foundations.
SupportPolicy: How a cross-timeline treats a timeline whose transferred coordinate falls outside alignment support — the entering coordinate lies beyond the transferring ’s anchor hull, or the produced coordinate would fall outside the target timeline’s [0, length] span. omit (the default) drops that timeline; clamp reports the nearest in-support boundary coordinate; extrapolate keeps the linear extrapolation clipped to [0, length]. No policy ever yields a negative coordinate, and the queried timeline’s own coordinate is never altered. Set per call on AlignmentBundle.get_matchstamp_at(..., support_policy=...) or persistently via AlignmentBundle.support_policy. See Alignment.
Synchrony: Strict synchrony: s sharing identical coordinates. Pragmatic synchrony: Instants binned together based on a threshold (e.g., for quantisation). See Foundations.

T

TimeInterval: Defined by a and ; left-inclusive and right-exclusive [s, e). The EndInstant’s coordinate must be >= the StartInstant’s. See Foundations.
TimeIntervalEvent: An with duration, defined by a . Contrast with . See Foundations.
TimeIntervalStamp: Combination of a start and an end TimeStamp, representing a cross-section of an interval through the timeline hierarchy. It stores one per timeline ID; get_interval(timeline_id) returns that Interval, get_intervals() the whole mapping, get_duration_for() an IdDuration, and get_interval_in(unit) the span converted through a C-map. Interval retrieval takes no format argument — its scalar leaf is always an Interval. See Nested timelines.
Timeline: A positive coordinate axis defined by an origin and a measuring unit; continuous (real) or discrete (integer). Accommodates events and potentially timelines. See Foundations.
TimelineGroup: A container for timelines claimed to be commensurable; placing timelines in a group asserts regardless of underlying units. Coordinates transfer via interpolation. See Alignment.
TimeStamp: A cross-section through a timeline or group at a given coordinate, capturing positions in all connected systems plus values converted by all attached s. It stores one per timeline ID, so each entry carries its own unit and number type. TimeStamp implements the shared Stamp interface used by and : a typed axis, get_coordinate_for() and get_coordinates_for() returning s by default, get_unit() for unit conversion, get_conversion_for() for label and structured map values, present_timelines, and is_interpolated. A bare number is an explicit format="float"/"int"/"fraction" request; there is no ambient float view. See Nested timelines.

W

WarpMap: An interpolation-based coordinate mapping derived from a ; enables non-linear coordinate transfer between s. It declares both axes — source and target unit and number type — and is queried through get_coordinate_at(position) for one position or get_coordinates_at([...]) for a batch; the object is not callable and exposes no raw arrays. inverse() returns a WarpMap with both units and both number types swapped. See Alignment.