Natooz/MidiTok

MidiTok – Tokenizing Music for AI Models

What it is – MidiTok is a Python library that turns symbolic music files (MIDI and abc) into sequences of discrete tokens, and can convert those tokens back into music. The token streams are ready to be fed to machine‑learning models such as Transformers for tasks like music generation, transcription, or music‑information‑retrieval (MIR).

Why it matters – Modern generative models work with text‑like token streams. By providing a unified, well‑documented way to represent music as tokens, MidiTok lets researchers and developers experiment with a wide range of music‑AI approaches without writing their own low‑level parsers.

Key features

• Supports most published music tokenizations (REMI, REMI+, MIDI‑Like, TSD, BEAT, Structured, CPWord, Octuple, MuMIDI, MMM, PerTok, etc.).
• Tokenizers share a common configuration API (TokenizerConfig).
• Vocabulary can be learned with BPE, Unigram, or WordPiece via the fast 🤗 tokenizers library.
• Built on Symusic for robust MIDI/abc I/O and integrates with the Hugging Face Hub for sharing tokenizers and models.
• Provides PyTorch‑compatible dataset, collator, and utilities for chunking long files into training‑ready sequences.
• Includes data‑augmentation helpers and plans for future extensions (MusicXML support, drum‑specific options, control‑change handling, Rust/C++ speed‑ups).

Installation

pip install miditok

The package requires Python ≥ 3.9 and pulls in symusic and huggingface‑tokenizers automatically.

Quick start

from miditok import REMI, TokenizerConfig
from symusic import Score

# configure a multitrack tokenizer
cfg = TokenizerConfig(num_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(cfg)

# load a MIDI file, tokenize, and decode back
midi = Score("my_song.mid")
toks = tokenizer(midi)               # also works with file paths or raw token lists
recovered = tokenizer(toks)          # returns a Symusic Score object

Training a model – end‑to‑end example

from pathlib import Path
from miditok import REMI, TokenizerConfig
from miditok.pytorch_data import DatasetMIDI, DataCollator
from miditok.utils import split_files_for_training
from torch.utils.data import DataLoader

cfg = TokenizerConfig(num_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(cfg)

# 1️⃣ Learn a vocabulary from a corpus of MIDI files
files = list(Path("/data/midis").rglob("*.mid"))
tokenizer.train(vocab_size=30_000, files_paths=files)

tokenizer.save(Path("tokenizer.json"))
# optional: push to Hugging Face hub
# tokenizer.push_to_hub("username/miditok-remi")

# 2️⃣ Split long files into fixed‑length chunks for training
chunks_dir = Path("chunks")
split_files_for_training(files, tokenizer, chunks_dir, max_seq_len=1024)

# 3️⃣ Build a PyTorch dataset / dataloader
train_set = DatasetMIDI(
    files_paths=list(chunks_dir.rglob("*.mid")),
    tokenizer=tokenizer,
    max_seq_len=1024,
    bos_token_id=tokenizer["BOS_None"],
    eos_token_id=tokenizer["EOS_None"],
)
collator = DataCollator(tokenizer.pad_token_id, copy_inputs_as_labels=True)
loader = DataLoader(train_set, batch_size=64, collate_fn=collator)

# 4️⃣ Iterate – plug into any Transformer‑style model
for batch in loader:
    # replace with your model's forward pass
    print("batch ready for training")

The README also links a Colab notebook that demonstrates using a Hugging Face Mistral‑style transformer to generate music with MidiTok.

Documentation & community – Full API docs are hosted at https://miditok.readthedocs.io, the project is on PyPI, CI‑tested on GitHub, and contributions are welcomed via the usual GitHub workflow.

Citation – If you use the library in research, cite the ISMIR 2021 demo paper (and the arXiv pre‑print linked in the README).