TimeToAlign!

This library is described in the TISMIR article Time to Align! Modelling Musical Timelines for Music Information Retrieval and Digital Musicology (2026): https://doi.org/10.5334/tismir.296.

A Python library for representing and aligning musical timelines.

Documentation: https://timetoalign.github.io/ · Source: https://github.com/timetoalign/timetoalign

Installation

pip install timetoalign         # Core only — lightweight

The core install pulls in only PyArrow, pandas, NetworkX, typing_extensions, and pydantic. This gives you the full timeline / map / alignment framework but no file-format-specific loaders. If you need loaders, plotting, or Jupyter support, install one of the optional extras described below. To run the tutorial notebooks (see below), for example:

pip install "timetoalign[tutorial]"    # Loaders + plotting + Jupyter

Optional Dependencies

TimeToAlign! organises its optional dependencies into atomic extras (one concern each) and composite extras (convenience bundles that include several atomic ones). You can mix and match freely: pip install "timetoalign[midi,plot]" is perfectly valid.

Atomic extras

Each atomic extra adds support for a single loader backend or feature.

Composite extras

Composite extras are convenience bundles that pull in several atomic extras at once. Runtime levels include everything below them; docs and testing target documentation builds and test-suite execution.

The inclusion chain is:

all  ⊃  tutorial  ⊃  loaders  ⊃  { midi, scores, audio, graphical }
                                 +  plot, examples, jupytext, jupyter
                   +  delta, rdf

docs     ⊃  tutorial, quartodoc, griffe
testing  ⊃  all, examples, pytest, pytest-cov, pytest-xdist, pytest-benchmark, hypothesis

Examples

pip install timetoalign                  # Core only
pip install "timetoalign[midi]"          # Core + MIDI loading
pip install "timetoalign[partitura]"     # Core + partitura score parsing
pip install "timetoalign[scores]"        # Core + all score-loader backends
pip install "timetoalign[loaders]"       # Core + every loader
pip install "timetoalign[tutorial]"      # Loaders + plotting + Jupyter
pip install "timetoalign[docs]"          # Tutorial stack + documentation build tools
pip install "timetoalign[testing]"       # Runtime features + test tools
pip install "timetoalign[all]"           # All runtime features

Development install

Contributing or running the test suite requires an editable, source install with the dev extra:

git clone https://github.com/timetoalign/timetoalign.git
pip install -e "./timetoalign[dev]"      # Editable install + everything + dev tooling

Quick Start

import timetoalign as tta

# Create a 60-second audio timeline
audio = tta.ContinuousPhysicalTimeline(length=60.0, uid="audio", name="Piano Recording")

# Add beats and notes -- IDs and temporal_type are inferred automatically
audio.add_events([
    {"event_type": "Beat", "instant": 0.0},
    {"event_type": "Beat", "instant": 0.5},
    {"event_type": "Beat", "instant": 1.0},
    {"event_type": "Note", "start": 0.0, "end": 0.5},
    {"event_type": "Note", "start": 8.0, "end": 12.0},   # spans Intro -> Verse
])

# Nest children (sections of the same recording)
intro  = audio.create_child(length=10.0, offset=0.0,  uid="intro",  name="Intro")
verse  = audio.create_child(length=20.0, offset=10.0, uid="verse",  name="Verse")
chorus = audio.create_child(length=15.0, offset=30.0, uid="chorus", name="Chorus")

# Attach ConversionMaps (seconds -> milliseconds, seconds -> samples at 48 kHz)
audio.add_conversion_map(tta.ScalarMap(scalar=1000, source_unit="seconds", target_unit="milliseconds"))
audio.add_conversion_map(tta.SecondsToSamples(sample_rate=48000))

# The diagram shows the hierarchy at a glance
print(audio.diagram())

ContinuousPhysicalTimeline[audio] (5 events, 3 children, 2 cmaps)
                      0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 seconds
  ├─ Intro            0 ~~~~~                               10
  ├─ Verse           10      ~~~~~~~~~~~~                   30
  └─ Chorus          30                  ~~~~~~~~~          45

# A TimeStamp is a cross-section through the entire hierarchy at a given coordinate.
# Only children whose span covers the coordinate appear:
ts = audio.get_timestamp(25.0)
print(ts)

TimeStamp @25 seconds
  audio         25 seconds
  verse         15 seconds
  milliseconds  25000 milliseconds
  samples       1200000 samples

# A TimeIntervalStamp gives the cross-section for a [start, end) range.
# The note at [8, 12) straddles Intro [0, 10) and Verse [10, 30):
# its start falls in Intro, its end in Verse.
tis = audio.get_interval_stamp(8.0, 12.0)
print(tis)

TimeIntervalStamp [8, 12) seconds
                 start     end
  audio              8      12 seconds
  intro              8       - seconds
  verse              -       2 seconds
  milliseconds    8000   12000
  samples       384000  576000

Tutorial Notebooks

The docs/tuto-notebooks/ and docs/howto-notebooks/ directories contain Jupytext percent-script notebooks covering the library from first principles to full alignment workflows. Make sure you have installed the tutorial extra (see Installation), then generate the paired .ipynb files and launch Jupyter:

jupytext --sync docs/*-notebooks/*.py
jupyter notebook docs/tuto-notebooks/

Development

# Run the test suite
pytest

# Run linting / pre-commit hooks
tox -e lint

Glossary

Citing

If you use TimeToAlign!, please cite:

Hentschel, Johannes; Berndt, Axel; Cancino-Chacón, Carlos; Dixon, Simon; Foo, Anne; Gotham, Mark; Hu, Patricia; Köster, Maik; Martins, Felipe D.; Mauro, Davide A.; Müller, Meinard; Neuwirth, Markus; Pacha, Alexander; Page, Kevin R.; Peter, Silvan; Polyakov, Egor; Pugin, Laurent; Weigl, David M.; Weiß, Christof; and Widmer, Gerhard. 2026. "Time to Align! Modelling Musical Timelines for Music Information Retrieval and Digital Musicology." Transactions of the International Society for Music Information Retrieval 9 (1): 384--404. https://doi.org/10.5334/tismir.296.

@article{Hentschel2026TimeToAlign,
  author  = {Hentschel, Johannes and Berndt, Axel and Cancino-Chacón, Carlos and Dixon, Simon and Foo, Anne and Gotham, Mark and Hu, Patricia and Köster, Maik and Martins, Felipe D. and Mauro, Davide A. and Müller, Meinard and Neuwirth, Markus and Pacha, Alexander and Page, Kevin R. and Peter, Silvan and Polyakov, Egor and Pugin, Laurent and Weigl, David M. and Weiß, Christof and Widmer, Gerhard},
  title   = {Time to Align! Modelling Musical Timelines for Music Information Retrieval and Digital Musicology},
  journal = {Transactions of the International Society for Music Information Retrieval},
  year    = {2026},
  volume  = {9},
  number  = {1},
  pages   = {384--404},
  doi     = {10.5334/tismir.296}
}

License

MIT