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. 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

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

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.
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-phase 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, the two coordinates as float64) rather than as one frozen MatchClaim object per claim. 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 and, with conversion_maps=True, C-map conversion values. 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()) is opt-in and defaults to False. 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() returns a raw coordinate, get_coordinate() returns a unit-bearing , 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-phase 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-phase 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-phase 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 parent containing only contiguous s. Enables cumulative coordinate conversion across all segments. 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. 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. TimeStamp implements the shared Stamp interface used by and , including raw get(), unit-bearing get_coordinate(), present_timelines, and is_interpolated access. See Nested timelines.

W

WarpMap: An interpolation-based coordinate mapping derived from a ; enables non-linear coordinate transfer between s. See Alignment.