Skip to content

Latest commit

 

History

History
177 lines (131 loc) · 6.85 KB

README.md

File metadata and controls

177 lines (131 loc) · 6.85 KB
Raw

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:

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.