MidiTok

用于对音乐文件进行分词的 Python 包，在 ISMIR 2021 LBDs 上首次发布。

MidiTok 可以对 MIDI 和 abc 文件进行分词，即将其转换为可直接输入到 Transformer 等模型中的标记序列，适用于各种生成、转录或 MIR 任务。MidiTok 支持大多数已知的音乐分词方法（例如 REMI、Compound Word...），并且基于这些方法共享通用参数和方法的理念构建。分词器可以使用 Byte Pair Encoding (BPE)、Unigram 和 WordPiece 进行训练，同时还提供数据增强方法。

MidiTok 已集成到 Hugging Face Hub 🤗！请随时与社区分享您的模型！

文档： miditok.readthedocs.com

安装

pip install miditok

MidiTok 使用 Symusic 来读取和写入 MIDI 和 abc 文件，而 BPE/Unigram 则由 Hugging Face 🤗tokenizers 提供支持，实现超快速编码。

使用示例

可以通过调用分词器来完成分词和反分词操作：

from miditok import REMI, TokenizerConfig
from symusic import Score

# 创建一个多轨分词器，阅读文档以了解所有参数
config = TokenizerConfig(num_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(config)

# 加载一个 MIDI 文件，将其转换为标记，然后再转换回 MIDI
midi = Score("path/to/your_midi.mid")
tokens = tokenizer(midi)  # 调用分词器会自动检测 MIDI 文件、路径和标记
converted_back_midi = tokenizer(tokens)  # 支持 PyTorch、Tensorflow 和 Numpy 张量

以下是一个完整但简洁的示例，展示了如何使用 MidiTok 训练任何 PyTorch 模型。而 这里 是一个简单的笔记本示例，说明如何使用 Hugging Face 模型生成音乐，MidiTok 负责对音乐文件进行分词。

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
from pathlib import Path

# 创建一个多轨分词器，阅读文档以了解所有参数
config = TokenizerConfig(num_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(config)

# 使用 Byte Pair Encoding (BPE) 训练分词器
files_paths = list(Path("path", "to", "midis").glob("**/*.mid"))
tokenizer.train(vocab_size=30000, files_paths=files_paths)
tokenizer.save(Path("path", "to", "save", "tokenizer.json"))
# 并将其推送到 Hugging Face hub（您可以使用 .from_pretrained 方法重新下载）
tokenizer.push_to_hub("username/model-name", private=True, token="your_hf_token")

# 将 MIDI 文件拆分为更小的块以进行训练
dataset_chunks_dir = Path("path", "to", "midi_chunks")
split_files_for_training(
    files_paths=files_paths,
    tokenizer=tokenizer,
    save_dir=dataset_chunks_dir,
    max_seq_len=1024,
)

# 创建数据集、数据加载器和数据整理器以训练模型
dataset = DatasetMIDI(
    files_paths=list(dataset_chunks_dir.glob("**/*.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)
dataloader = DataLoader(dataset, batch_size=64, collate_fn=collator)

# 遍历数据加载器以训练模型
for batch in dataloader:
    print("在这一批数据上训练您的模型...")

分词方法

MidiTok 实现了以下分词方法（链接至原始论文）：

• REMI
• REMI+
• MIDI-Like
• TSD
• Structured
• CPWord
• Octuple
• MuMIDI
• MMM
• PerTok

您可以在 文档 中找到简短介绍。

贡献

我们非常欢迎贡献，如果您想添加新的分词方法或加快代码速度，请随时提出问题或发送 PR。有关详细信息，请参阅 贡献指南。

待办事项

• 支持 music-xml 文件；
• no_duration_drums 选项，忽略鼓音符的时长标记；
• 控制变化消息；
• 使用 Rust 或 C++ 绑定加速全局/轨道事件解析。

引用

如果您在研究中使用 MidiTok，我们非常乐意在您的论文中看到引用。❤️

[MidiTok 论文] [MidiTok 的 ISMIR 原始发表文章]

@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},
}

所有分词方法的 BibTeX 引用都可以在 文档 中找到。

致谢

@Natooz 感谢其雇主允许他开展该项目，按时间先后顺序分别为 Aubay、LIP6（索邦大学） 以及 Metacreation Lab（西蒙菲莎大学）。

衷心感谢所有贡献者

MidiTok 快速上手指南

MidiTok 是一个用于将 MIDI 和 abc 音乐文件转换为令牌（Token）序列的 Python 库，专为音乐生成、转录及音乐信息检索（MIR）任务设计。它支持多种主流音乐令牌化方案（如 REMI、Compound Word 等），并可结合 BPE、Unigram 等算法进行词表训练，完美适配 Transformer 等深度学习模型。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：≥ 3.9
• 核心依赖：
  • symusic：用于高效读写 MIDI 和 abc 文件。
  • tokenizers (Hugging Face)：用于加速 BPE/Unigram 编码。
  • 深度学习框架（可选）：PyTorch, TensorFlow 或 NumPy（用于处理张量数据）。

安装步骤

使用 pip 直接安装最新稳定版：

pip install miditok

提示：国内开发者若遇到下载缓慢问题，可使用清华或阿里镜像源加速安装：

pip install miditok -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 快速令牌化与还原

以下示例展示如何加载 MIDI 文件，将其转换为令牌序列，并还原回 MIDI 文件。MidiTok 自动支持 PyTorch、TensorFlow 和 NumPy 张量格式。

from miditok import REMI, TokenizerConfig
from symusic import Score

# 配置分词器：设置速度层级、启用和弦识别、启用乐器程序识别
config = TokenizerConfig(num_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(config)

# 加载 MIDI 文件
midi = Score("path/to/your_midi.mid")

# 转换为令牌序列
tokens = tokenizer(midi)  # 自动检测输入类型并转换

# 将令牌序列还原为 MIDI 对象
converted_back_midi = tokenizer(tokens)

2. 训练自定义分词器并构建数据集

若需训练生成模型，可先使用 BPE 算法训练专属分词器，随后构建 PyTorch DataLoader。

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
from pathlib import Path

# 初始化分词器配置
config = TokenizerConfig(num_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(config)

# 1. 训练分词器 (使用 BPE 算法)
files_paths = list(Path("path", "to", "midis").glob("**/*.mid"))
tokenizer.train(vocab_size=30000, files_paths=files_paths)
tokenizer.save(Path("path", "to", "save", "tokenizer.json"))

# (可选) 推送到 Hugging Face Hub
# tokenizer.push_to_hub("username/model-name", private=True, token="your_hf_token")

# 2. 切割长 MIDI 文件以适应训练序列长度
dataset_chunks_dir = Path("path", "to", "midi_chunks")
split_files_for_training(
    files_paths=files_paths,
    tokenizer=tokenizer,
    save_dir=dataset_chunks_dir,
    max_seq_len=1024,
)

# 3. 构建 Dataset 和 DataLoader
dataset = DatasetMIDI(
    files_paths=list(dataset_chunks_dir.glob("**/*.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)
dataloader = DataLoader(dataset, batch_size=64, collate_fn=collator)

# 4. 开始训练循环
for batch in dataloader:
    print("Train your model on this batch...")
    # 在此处添加你的模型训练代码