Parangonar

Parangonar is a Python package for note alignment of symbolic music. Parangonar contains offline and online note alignment algorithms as well as task-agnostic dynamic programming sequence alignment algorithms. Note alignments produced by Parangonar can be visualized using the web tool Parangonda. Parangonar uses Partitura as file I/O utility.

Installation

The easiest way to install the package is via pip from the PyPI (Python Package Index):

pip install parangonar

This will install the latest release of the package and will install all dependencies automatically.

Getting Started

There is a getting_started.ipynb notebook which covers the basic note alignment functions.

To demonstrate Parangonar the contents of performance and score alignment file (encoded in the match file format) are loaded, which returns a score object, a performance objects, and an alignment list. A new alignment is computed using different note matchers and the predicted alignment are compared to the ground truth.

Documentation: creation of note alignments

Parangonar contains implementations of note alignments algorithms:

1. Offline Note Matching:

   • AutomaticNoteMatcher: piano roll-based, hierarchical DTW and combinatorial optimization for pitch-wise note distribution. requires scores and performances in the current implementation, but not necessarily.
   • DualDTWNoteMatcher: symbolic note set-based DTW, pitch-wise onsetDTW, separate handling of ornamentations possible. requires scores and performances for sequence representation. Default and SOTA for standard score to performance matching.
   • TheGlueNoteMatcher: pre-trained neural network for note similarity, useful for large mismatches between versions. works on any two MIDI files.
   • AnchorPointNoteMatcher: semi-automatic version of the AutomaticNoteMatcher, useful if annotations can be leveraged as anchor points.

2. Online / Real-time Note Matching:

   • OnlineTransformerMatcher:: pre-trained neural network for local alignment decisions. post-processing by a tempo model.
   • OnlinePureTransformerMatcher pre-trained neural network for local alignment decisions. no post-processing.
   • TempoOLTWMatcher: tba.
   • OLTWMatcher: tba.

Documentation: dynamic programming

Parangonar contains implementations of (non-)standard dynamic programming sequence alignment algorithms:

1. DTW (multiple versions, using numpy/numba/jit)

   • vanilla DTW
   • weightedDTW: generalized directions, weights, and penalites
   • FlexDTW: flexible start and end points, Bükey at al.

2. NWTW (multiple versions, using numpy/numba/jit)

   • Needleman-Wunsch: using distances on scalars, minimizing version
   • NWDTW: Needleman-Wunsch Time Warping, Grachten et al.
   • weightedNWDTW: generalized directions, weights, and penalites
   • original Needleman-Wunsch: using binary gamma on scalars, maximizing version
   • original Smith-Waterman: using binary gamma on scalars, maximizing version

3. OLTW:

   • On-Line Time Warping: standard OLTW, Dixon et al.
   • Tempo OLTW: path-wise tempo models

Documentation: note alignment utilities

Parangonar contains several utilities around note matching:

1. Alignment Visualization:

   • parangonar.evaluate.plot_alignment
   • parangonar.evaluate.plot_alignment_comparison
   • parangonar.evaluate.plot_alignment_mappings

2. Alignment Evaluation

   • parangonar.evaluate.fscore_alignments
   • parangonar.evaluate.fscore_alignments
   • parangonar.evaluate.fscore_alignments

3. File I/O for note alignments

   Most I/O functions are handled by Partitura.

   For Parangonada:

   • partitura.io.importparangonada.load_parangonada_alignment
   • partitura.io.importparangonada.load_parangonada_csv
   • partitura.io.exportparangonada.save_parangonada_alignment
   • partitura.io.exportparangonada.save_parangonada_csv

   For (n)ASAP alignments

   • partitura.io.importparangonada.load_alignment_from_ASAP
   • partitura.io.exportparangonada.save_alignment_for_ASAP

   For match files

   • partitura.io.importmatch.load_match
   • partitura.io.exportmatch.save_match

   and a basic interface for saving parangonada-ready csv files is also available in parangonagar:

   • parangonar.match.save_parangonada_csv

4. Aligned Data

   These note-aligned datasets are publically available:

   • Vienna 4x22
   • (n)ASAP note alignments
   • Batik Dataset

Publications

Two publications are associated with models available in Parangonar. The anchor point-enhanced AnchorPointNoteMatcher and the automatic AutomaticNoteMatcher are this described in:

@article{nasap-dataset,
 title = {Automatic Note-Level Score-to-Performance Alignments in the ASAP Dataset},
 author = {Peter, Silvan David and Cancino-Chacón, Carlos Eduardo and Foscarin, Francesco and McLeod, Andrew Philip and Henkel, Florian and Karystinaios, Emmanouil and Widmer, Gerhard},
 doi = {10.5334/tismir.149},
 journal = {Transactions of the International Society for Music Information Retrieval {(TISMIR)}},
 year = {2023}
}

and the AnchorPointNoteMatcher is used in the creation of the note-aligned (n)ASAP Dataset.

The improved automatic DualDTWNoteMatcher and the online / realtime OnlineTransformerMatcher / OnlinePureTransformerMatcher are described in:

@inproceedings{peter-offline2023,
  title={Online Symbolic Music Alignment with Offline Reinforcement Learning},
  author={Peter, Silvan David},
  booktitle={International Society for Music Information Retrieval Conference {(ISMIR)}},
  year={2023}
}

The pre-trained TheGlueNoteMatcher is described in:

@inproceedings{peter-thegluenote2024,
  title={TheGlueNote: Learned Representations for Robust and Flexible Note Alignment},
  author={Peter, Silvan David and Widmer, Gerhard},
  booktitle={International Society for Music Information Retrieval Conference {(ISMIR)}},
  year={2024}
}

Acknowledgments

This work is supported by the European Research Council (ERC) under the EU’s Horizon 2020 research & innovation programme, grant agreement No. 10101937 (”Wither Music?”).

License

The code in this package is licensed under the Apache 2.0 License. For details, please see the LICENSE file.