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](https://sildater.github.io/parangonada/).
**Parangonar** uses [Partitura](https://github.com/CPJKU/partitura) as file I/O utility.
Installation
-------
The easiest way to install the package is via `pip` from the [PyPI (Python
Package Index)](https://pypi.org/project/parangonar/>):
```shell
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](https://cpjku.github.io/matchfile/)) 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.
3. 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](https://github.com/CPJKU/partitura).
For [Parangonada](https://sildater.github.io/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](https://github.com/CPJKU/asap-dataset)
- partitura.io.importparangonada.load_alignment_from_ASAP
- partitura.io.exportparangonada.save_alignment_for_ASAP
For [match files](https://cpjku.github.io/matchfile/)
- 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](https://github.com/CPJKU/vienna4x22)
- [(n)ASAP note alignments](https://github.com/CPJKU/asap-dataset)
- [Batik Dataset](https://github.com/huispaty/batik_plays_mozart)
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](https://github.com/CPJKU/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](LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/sildater/parangonar",
"name": "parangonar",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "match alignment midi performance score",
"author": "Silvan Peter, Carlos Cancino-Chac\u00f3n, Florian Henkel",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b3/f2/452aa9ca38f73778f399fe9f1dc817787da4d9cad3354c306e3f51b7ced2/parangonar-2.0.0.tar.gz",
"platform": null,
"description": "\r\nParangonar\r\n==========\r\n\r\n**Parangonar** is a Python package for note alignment of symbolic music. \r\n**Parangonar** contains offline and online note alignment algorithms as well as task-agnostic dynamic programming sequence alignment algorithms.\r\nNote alignments produced by **Parangonar** can be visualized using the web tool [Parangonda](https://sildater.github.io/parangonada/).\r\n**Parangonar** uses [Partitura](https://github.com/CPJKU/partitura) as file I/O utility.\r\n\r\n\r\nInstallation\r\n-------\r\n\r\nThe easiest way to install the package is via `pip` from the [PyPI (Python\r\nPackage Index)](https://pypi.org/project/parangonar/>):\r\n```shell\r\npip install parangonar\r\n```\r\nThis will install the latest release of the package and will install all dependencies automatically.\r\n\r\n\r\nGetting Started\r\n-------\r\n\r\nThere is a `getting_started.ipynb` notebook which covers the basic note alignment functions.\r\n\r\nTo demonstrate **Parangonar** the contents of performance and score alignment file (encoded in the [match file format](https://cpjku.github.io/matchfile/)) 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.\r\n\r\n\r\nDocumentation: creation of note alignments\r\n-------\r\n\r\n**Parangonar** contains implementations of note alignments algorithms:\r\n\r\n1. Offline Note Matching: \r\n - `AutomaticNoteMatcher`: \r\n piano roll-based, hierarchical DTW and combinatorial optimization for pitch-wise note distribution.\r\n requires scores and performances in the current implementation, but not necessarily.\r\n - `DualDTWNoteMatcher`: \r\n symbolic note set-based DTW, pitch-wise onsetDTW, separate handling of ornamentations possible.\r\n requires scores and performances for sequence representation.\r\n **Default and SOTA** for standard score to performance matching.\r\n - `TheGlueNoteMatcher`:\r\n pre-trained neural network for note similarity, useful for large mismatches between versions.\r\n works on any two MIDI files.\r\n - `AnchorPointNoteMatcher`: \r\n semi-automatic version of the `AutomaticNoteMatcher`, useful if annotations can be leveraged as anchor points. \r\n\r\n\r\n3. Online / Real-time Note Matching: \r\n - `OnlineTransformerMatcher`::\r\n pre-trained neural network for local alignment decisions.\r\n post-processing by a tempo model.\r\n - `OnlinePureTransformerMatcher` \r\n pre-trained neural network for local alignment decisions.\r\n no post-processing.\r\n - `TempoOLTWMatcher`: \r\n tba.\r\n - `OLTWMatcher`:\r\n tba. \r\n\r\nDocumentation: dynamic programming \r\n-------\r\n\r\n**Parangonar** contains implementations of (non-)standard dynamic programming sequence alignment algorithms:\r\n\r\n1. DTW (multiple versions, using numpy/numba/jit)\r\n - vanilla DTW\r\n - weightedDTW: generalized directions, weights, and penalites\r\n - FlexDTW: flexible start and end points, B\u00fckey at al.\r\n\r\n2. NWTW (multiple versions, using numpy/numba/jit)\r\n - Needleman-Wunsch: using distances on scalars, minimizing version\r\n - NWDTW: Needleman-Wunsch Time Warping, Grachten et al.\r\n - weightedNWDTW: generalized directions, weights, and penalites\r\n - original Needleman-Wunsch: using binary gamma on scalars, maximizing version\r\n - original Smith-Waterman: using binary gamma on scalars, maximizing version\r\n\r\n3. OLTW:\r\n - On-Line Time Warping: standard OLTW, Dixon et al.\r\n - Tempo OLTW: path-wise tempo models\r\n\r\n\r\nDocumentation: note alignment utilities\r\n-------\r\n\r\n**Parangonar** contains several utilities around note matching:\r\n\r\n1. Alignment Visualization:\r\n - parangonar.evaluate.plot_alignment \r\n - parangonar.evaluate.plot_alignment_comparison\r\n - parangonar.evaluate.plot_alignment_mappings \r\n\r\n2. Alignment Evaluation\r\n - parangonar.evaluate.fscore_alignments\r\n - parangonar.evaluate.fscore_alignments\r\n - parangonar.evaluate.fscore_alignments\r\n\r\n3. File I/O for note alignments\r\n\r\n Most I/O functions are handled by [Partitura](https://github.com/CPJKU/partitura). \r\n\r\n For [Parangonada](https://sildater.github.io/parangonada/):\r\n - partitura.io.importparangonada.load_parangonada_alignment\r\n - partitura.io.importparangonada.load_parangonada_csv\r\n - partitura.io.exportparangonada.save_parangonada_alignment\r\n - partitura.io.exportparangonada.save_parangonada_csv\r\n\r\n For [(n)ASAP alignments](https://github.com/CPJKU/asap-dataset)\r\n - partitura.io.importparangonada.load_alignment_from_ASAP\r\n - partitura.io.exportparangonada.save_alignment_for_ASAP\r\n\r\n For [match files](https://cpjku.github.io/matchfile/)\r\n - partitura.io.importmatch.load_match\r\n - partitura.io.exportmatch.save_match\r\n\r\n and a basic interface for saving parangonada-ready csv files is also available in parangonagar:\r\n - parangonar.match.save_parangonada_csv\r\n\r\n4. Aligned Data\r\n\r\n These note-aligned datasets are publically available:\r\n - [Vienna 4x22](https://github.com/CPJKU/vienna4x22)\r\n - [(n)ASAP note alignments](https://github.com/CPJKU/asap-dataset)\r\n - [Batik Dataset](https://github.com/huispaty/batik_plays_mozart)\r\n\r\n\r\nPublications\r\n-------\r\n\r\nTwo publications are associated with models available in **Parangonar**.\r\nThe anchor point-enhanced `AnchorPointNoteMatcher` and the automatic `AutomaticNoteMatcher` are this described in:\r\n\r\n```\r\n@article{nasap-dataset,\r\n title = {Automatic Note-Level Score-to-Performance Alignments in the ASAP Dataset},\r\n author = {Peter, Silvan David and Cancino-Chac\u00f3n, Carlos Eduardo and Foscarin, Francesco and McLeod, Andrew Philip and Henkel, Florian and Karystinaios, Emmanouil and Widmer, Gerhard},\r\n doi = {10.5334/tismir.149},\r\n journal = {Transactions of the International Society for Music Information Retrieval {(TISMIR)}},\r\n year = {2023}\r\n}\r\n```\r\n\r\nand the `AnchorPointNoteMatcher` is used in the creation of the [note-aligned (n)ASAP Dataset](https://github.com/CPJKU/asap-dataset).\r\n\r\nThe improved automatic `DualDTWNoteMatcher` and the online / realtime `OnlineTransformerMatcher` / `OnlinePureTransformerMatcher` are described in:\r\n\r\n```\r\n@inproceedings{peter-offline2023,\r\n title={Online Symbolic Music Alignment with Offline Reinforcement Learning},\r\n author={Peter, Silvan David},\r\n booktitle={International Society for Music Information Retrieval Conference {(ISMIR)}},\r\n year={2023}\r\n}\r\n```\r\n\r\nThe pre-trained `TheGlueNoteMatcher` is described in:\r\n\r\n```\r\n@inproceedings{peter-thegluenote2024,\r\n title={TheGlueNote: Learned Representations for Robust and Flexible Note Alignment},\r\n author={Peter, Silvan David and Widmer, Gerhard},\r\n booktitle={International Society for Music Information Retrieval Conference {(ISMIR)}},\r\n year={2024}\r\n}\r\n```\r\n\r\nAcknowledgments\r\n-------\r\n\r\nThis work is supported by the European Research Council (ERC) under the EU\u2019s Horizon 2020 research & innovation programme, grant agreement No. 10101937 (\u201dWither Music?\u201d).\r\n\r\nLicense\r\n-------\r\n\r\nThe code in this package is licensed under the Apache 2.0 License. For details,\r\nplease see the [LICENSE](LICENSE) file.\r\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Symbolic music alignment",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/sildater/parangonar"
},
"split_keywords": [
"match",
"alignment",
"midi",
"performance",
"score"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "737d2c1b90ca85776c740c9929a9171628c9f3b10cf91a253fbf4a8b3378b068",
"md5": "1f60ee41f24f55afd9d78cee06b8a315",
"sha256": "8a9195b7a2bbd5abfe06f7fc26c93a2dc5e416f784aca8cf43eaa2fb0e362ac3"
},
"downloads": -1,
"filename": "parangonar-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f60ee41f24f55afd9d78cee06b8a315",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 63577,
"upload_time": "2024-10-30T17:55:21",
"upload_time_iso_8601": "2024-10-30T17:55:21.355709Z",
"url": "https://files.pythonhosted.org/packages/73/7d/2c1b90ca85776c740c9929a9171628c9f3b10cf91a253fbf4a8b3378b068/parangonar-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b3f2452aa9ca38f73778f399fe9f1dc817787da4d9cad3354c306e3f51b7ced2",
"md5": "babc4bebdf5b235f31579f8f66433b91",
"sha256": "b9e9b5f447205791b9a63697f66c70a0835fb829a00af0b2633a57c73938ceb5"
},
"downloads": -1,
"filename": "parangonar-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "babc4bebdf5b235f31579f8f66433b91",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 59241,
"upload_time": "2024-10-30T17:55:22",
"upload_time_iso_8601": "2024-10-30T17:55:22.770838Z",
"url": "https://files.pythonhosted.org/packages/b3/f2/452aa9ca38f73778f399fe9f1dc817787da4d9cad3354c306e3f51b7ced2/parangonar-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 17:55:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sildater",
"github_project": "parangonar",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "parangonar"
}
JSON
