# MidiTok
Python package to tokenize MIDI music files, presented at the ISMIR 2021 LBD.
[](https://pypi.python.org/pypi/miditok/)
[](https://www.python.org/downloads/release/)
[](https://miditok.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/Natooz/MidiTok/actions/workflows/pytest.yml)
[](https://codecov.io/gh/Natooz/MidiTok)
[](https://github.com/Natooz/MidiTok/blob/main/LICENSE)
[](https://pepy.tech/project/MidiTok)
[](https://github.com/psf/black)
Using Deep Learning with symbolic music ? MidiTok can take care of converting (tokenizing) your MIDI files into tokens, ready to be fed to models such as Transformer, for any generation, transcription or MIR task.
MidiTok features most known [MIDI tokenizations](https://miditok.readthedocs.io/en/latest/tokenizations.html) (e.g. [REMI](https://arxiv.org/abs/2002.00212), [Compound Word](https://arxiv.org/abs/2101.02402)...), and is built around the idea that they all share common parameters and methods. It supports [Byte Pair Encoding (BPE)](https://arxiv.org/abs/2301.11975) and data augmentation.
**Documentation:** [miditok.readthedocs.com](https://miditok.readthedocs.io/en/latest/index.html)
## Install
```shell
pip install miditok
```
MidiTok uses [MIDIToolkit](https://github.com/YatingMusic/miditoolkit), which itself uses [Mido](https://github.com/mido/mido) to read and write MIDI files, and BPE is backed by [Hugging Face 🤗tokenizers](https://github.com/huggingface/tokenizers) for super-fast encoding.
## Usage example
The most basic and useful methods are summarized here. And [here](colab-notebooks/Full_Example_HuggingFace_GPT2_Transformer.ipynb) is a simple notebook example showing how to use Hugging Face models to generate music, with MidiTok taking care of tokenizing MIDIs.
```python
from miditok import REMI, TokenizerConfig
from miditoolkit import MidiFile
from pathlib import Path
# Creating a multitrack tokenizer configuration, read the doc to explore other parameters
config = TokenizerConfig(nb_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(config)
# Loads a midi, converts to tokens, and back to a MIDI
midi = MidiFile('path/to/your_midi.mid')
tokens = tokenizer(midi) # calling the tokenizer will automatically detect MIDIs, paths and tokens
converted_back_midi = tokenizer(tokens) # PyTorch / Tensorflow / Numpy tensors supported
# Tokenize a whole dataset and save it at Json files
midi_paths = list(Path("path", "to", "dataset").glob("**/*.mid"))
data_augmentation_offsets = [2, 1, 1] # data augmentation on 2 pitch octaves, 1 velocity and 1 duration values
tokenizer.tokenize_midi_dataset(midi_paths, Path("path", "to", "tokens_noBPE"),
data_augment_offsets=data_augmentation_offsets)
# Constructs the vocabulary with BPE, from the token files
tokenizer.learn_bpe(
vocab_size=10000,
tokens_paths=list(Path("path", "to", "tokens_noBPE").glob("**/*.json")),
start_from_empty_voc=False,
)
# Saving our tokenizer, to retrieve it back later with the load_params method
tokenizer.save_params(Path("path", "to", "save", "tokenizer.json"))
# Applies BPE to the previous tokens
tokenizer.apply_bpe_to_dataset(Path('path', 'to', 'tokens_noBPE'), Path('path', 'to', 'tokens_BPE'))
```
## Tokenizations
MidiTok implements the tokenizations: (links to original papers)
* [REMI](https://dl.acm.org/doi/10.1145/3394171.3413671)
* [REMI+](https://openreview.net/forum?id=NyR8OZFHw6i)
* [MIDI-Like](https://link.springer.com/article/10.1007/s00521-018-3758-9)
* [TSD](https://arxiv.org/abs/2301.11975)
* [Structured](https://arxiv.org/abs/2107.05944)
* [CPWord](https://ojs.aaai.org/index.php/AAAI/article/view/16091)
* [Octuple](https://aclanthology.org/2021.findings-acl.70)
* [MuMIDI](https://dl.acm.org/doi/10.1145/3394171.3413721)
* [MMM](https://arxiv.org/abs/2008.06048)
You can find short presentations in the [documentation](https://miditok.readthedocs.io/en/latest/tokenizations.html).
## Contributions
Contributions are gratefully welcomed, feel free to open an issue or send a PR if you want to add a tokenization or speed up the code. You can read the [contribution guide](CONTRIBUTING.md) for details.
### Todos
* Extend unimplemented additional tokens to all compatible tokenizations;
* Control Change messages;
* Option to represent pitch values as pitch intervals, as [it seems to improve performances](https://ismir2022program.ismir.net/lbd_369.html);
* Speeding up MIDI read / load (using a Rust / C++ io library + Python binding ?);
* Data augmentation on duration values at the MIDI level.
## Citation
If you use MidiTok for your research, a citation in your manuscript would be gladly appreciated. ❤️
[**MidiTok paper**](https://archives.ismir.net/ismir2021/latebreaking/000005.pdf)
```bibtex
@inproceedings{miditok2021,
title={{MidiTok}: A Python package for {MIDI} file tokenization},
author={Fradet, Nathan and Briot, Jean-Pierre and Chhel, Fabien and El Fallah Seghrouchni, Amal and Gutowski, Nicolas},
booktitle={Extended Abstracts for the Late-Breaking Demo Session of the 22nd International Society for Music Information Retrieval Conference},
year={2021},
url={https://archives.ismir.net/ismir2021/latebreaking/000005.pdf},
}
```
The BibTeX citations of all tokenizations can be found [in the documentation](https://miditok.readthedocs.io/en/latest/citations.html)
## Acknowledgments
Special thanks to all the contributors.
We acknowledge [Aubay](https://blog.aubay.com/index.php/language/en/home/?lang=en), the [LIP6](https://www.lip6.fr/?LANG=en), [LERIA](http://blog.univ-angers.fr/leria/n) and [ESEO](https://eseo.fr/en) for the initial financing and support.
Raw data
{
"_id": null,
"home_page": "https://github.com/MusicLang/MidiTok",
"name": "miditok-for-musiclang",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "artificial intelligence,deep learning,transformer,midi,tokenization,music,mir",
"author": "Nathan Fradet",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# MidiTok\n\nPython package to tokenize MIDI music files, presented at the ISMIR 2021 LBD.\n\n![MidiTok Logo](docs/assets/logo.png?raw=true \"\")\n\n[](https://pypi.python.org/pypi/miditok/)\n[](https://www.python.org/downloads/release/)\n[](https://miditok.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/Natooz/MidiTok/actions/workflows/pytest.yml)\n[](https://codecov.io/gh/Natooz/MidiTok)\n[](https://github.com/Natooz/MidiTok/blob/main/LICENSE)\n[](https://pepy.tech/project/MidiTok)\n[](https://github.com/psf/black)\n\nUsing Deep Learning with symbolic music ? MidiTok can take care of converting (tokenizing) your MIDI files into tokens, ready to be fed to models such as Transformer, for any generation, transcription or MIR task.\nMidiTok features most known [MIDI tokenizations](https://miditok.readthedocs.io/en/latest/tokenizations.html) (e.g. [REMI](https://arxiv.org/abs/2002.00212), [Compound Word](https://arxiv.org/abs/2101.02402)...), and is built around the idea that they all share common parameters and methods. It supports [Byte Pair Encoding (BPE)](https://arxiv.org/abs/2301.11975) and data augmentation.\n\n**Documentation:** [miditok.readthedocs.com](https://miditok.readthedocs.io/en/latest/index.html)\n\n## Install\n\n```shell\npip install miditok\n```\nMidiTok uses [MIDIToolkit](https://github.com/YatingMusic/miditoolkit), which itself uses [Mido](https://github.com/mido/mido) to read and write MIDI files, and BPE is backed by [Hugging Face \ud83e\udd17tokenizers](https://github.com/huggingface/tokenizers) for super-fast encoding.\n\n## Usage example\n\nThe most basic and useful methods are summarized here. And [here](colab-notebooks/Full_Example_HuggingFace_GPT2_Transformer.ipynb) is a simple notebook example showing how to use Hugging Face models to generate music, with MidiTok taking care of tokenizing MIDIs.\n\n```python\nfrom miditok import REMI, TokenizerConfig\nfrom miditoolkit import MidiFile\nfrom pathlib import Path\n\n# Creating a multitrack tokenizer configuration, read the doc to explore other parameters\nconfig = TokenizerConfig(nb_velocities=16, use_chords=True, use_programs=True)\ntokenizer = REMI(config)\n\n# Loads a midi, converts to tokens, and back to a MIDI\nmidi = MidiFile('path/to/your_midi.mid')\ntokens = tokenizer(midi) # calling the tokenizer will automatically detect MIDIs, paths and tokens\nconverted_back_midi = tokenizer(tokens) # PyTorch / Tensorflow / Numpy tensors supported\n\n# Tokenize a whole dataset and save it at Json files\nmidi_paths = list(Path(\"path\", \"to\", \"dataset\").glob(\"**/*.mid\"))\ndata_augmentation_offsets = [2, 1, 1] # data augmentation on 2 pitch octaves, 1 velocity and 1 duration values\ntokenizer.tokenize_midi_dataset(midi_paths, Path(\"path\", \"to\", \"tokens_noBPE\"),\n data_augment_offsets=data_augmentation_offsets)\n\n# Constructs the vocabulary with BPE, from the token files\ntokenizer.learn_bpe(\n vocab_size=10000,\n tokens_paths=list(Path(\"path\", \"to\", \"tokens_noBPE\").glob(\"**/*.json\")),\n start_from_empty_voc=False,\n)\n\n# Saving our tokenizer, to retrieve it back later with the load_params method\ntokenizer.save_params(Path(\"path\", \"to\", \"save\", \"tokenizer.json\"))\n\n# Applies BPE to the previous tokens\ntokenizer.apply_bpe_to_dataset(Path('path', 'to', 'tokens_noBPE'), Path('path', 'to', 'tokens_BPE'))\n```\n\n## Tokenizations\n\nMidiTok implements the tokenizations: (links to original papers)\n* [REMI](https://dl.acm.org/doi/10.1145/3394171.3413671)\n* [REMI+](https://openreview.net/forum?id=NyR8OZFHw6i)\n* [MIDI-Like](https://link.springer.com/article/10.1007/s00521-018-3758-9)\n* [TSD](https://arxiv.org/abs/2301.11975)\n* [Structured](https://arxiv.org/abs/2107.05944)\n* [CPWord](https://ojs.aaai.org/index.php/AAAI/article/view/16091)\n* [Octuple](https://aclanthology.org/2021.findings-acl.70)\n* [MuMIDI](https://dl.acm.org/doi/10.1145/3394171.3413721)\n* [MMM](https://arxiv.org/abs/2008.06048)\n\nYou can find short presentations in the [documentation](https://miditok.readthedocs.io/en/latest/tokenizations.html).\n\n## Contributions\n\nContributions are gratefully welcomed, feel free to open an issue or send a PR if you want to add a tokenization or speed up the code. You can read the [contribution guide](CONTRIBUTING.md) for details.\n\n### Todos\n\n* Extend unimplemented additional tokens to all compatible tokenizations;\n* Control Change messages;\n* Option to represent pitch values as pitch intervals, as [it seems to improve performances](https://ismir2022program.ismir.net/lbd_369.html);\n* Speeding up MIDI read / load (using a Rust / C++ io library + Python binding ?);\n* Data augmentation on duration values at the MIDI level.\n\n## Citation\n\nIf you use MidiTok for your research, a citation in your manuscript would be gladly appreciated. \u2764\ufe0f\n\n[**MidiTok paper**](https://archives.ismir.net/ismir2021/latebreaking/000005.pdf)\n```bibtex\n@inproceedings{miditok2021,\n title={{MidiTok}: A Python package for {MIDI} file tokenization},\n author={Fradet, Nathan and Briot, Jean-Pierre and Chhel, Fabien and El Fallah Seghrouchni, Amal and Gutowski, Nicolas},\n booktitle={Extended Abstracts for the Late-Breaking Demo Session of the 22nd International Society for Music Information Retrieval Conference},\n year={2021},\n url={https://archives.ismir.net/ismir2021/latebreaking/000005.pdf},\n}\n```\n\nThe BibTeX citations of all tokenizations can be found [in the documentation](https://miditok.readthedocs.io/en/latest/citations.html)\n\n\n## Acknowledgments\n\nSpecial thanks to all the contributors.\nWe acknowledge [Aubay](https://blog.aubay.com/index.php/language/en/home/?lang=en), the [LIP6](https://www.lip6.fr/?LANG=en), [LERIA](http://blog.univ-angers.fr/leria/n) and [ESEO](https://eseo.fr/en) for the initial financing and support.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A convenient MIDI tokenizer for Deep Learning networks, with multiple encoding strategies",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/MusicLang/MidiTok"
},
"split_keywords": [
"artificial intelligence",
"deep learning",
"transformer",
"midi",
"tokenization",
"music",
"mir"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a724636cd3058f5ee401b456904ecc4b51449b60e765394d06ee48858bf5fbf",
"md5": "10d180f5841ff39dfb1d485459ffbe5d",
"sha256": "25e3967511e034a728e87c451d8c49f32176e14f026ace24375c89fbec78956c"
},
"downloads": -1,
"filename": "miditok_for_musiclang-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10d180f5841ff39dfb1d485459ffbe5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 100831,
"upload_time": "2023-11-23T17:31:40",
"upload_time_iso_8601": "2023-11-23T17:31:40.071621Z",
"url": "https://files.pythonhosted.org/packages/5a/72/4636cd3058f5ee401b456904ecc4b51449b60e765394d06ee48858bf5fbf/miditok_for_musiclang-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-23 17:31:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MusicLang",
"github_project": "MidiTok",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "miditoolkit",
"specs": [
[
">=",
"0.1.16"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.64.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.19"
],
[
"<",
"1.24"
]
]
},
{
"name": "tokenizers",
"specs": [
[
">=",
"0.13.2"
]
]
},
{
"name": "scipy",
"specs": []
},
{
"name": "matplotlib",
"specs": []
}
],
"lcname": "miditok-for-musiclang"
}
JSON
