Natooz/MidiTok

MidiTok – AI 모델을 위한 음악 토큰화

무엇인가요 – MidiTok은 심볼릭 음악 파일(MIDI 및 abc)을 이산 토큰 시퀀스로 변환하고, 해당 토큰을 다시 음악으로 복원할 수 있는 Python 라이브러리입니다. 이 토큰 스트림은 음악 생성, 변환, 음악정보검색(MIR)과 같은 작업을 위해 Transformer와 같은 머신러닝 모델에 직접 입력할 수 있습니다.

왜 중요한가요 – 현대의 생성 모델은 텍스트와 유사한 토큰 스트림을 다룹니다. MidiTok은 음악을 토큰으로 일관되게 표현하는 명확한 방법을 제공함으로써, 연구자와 개발자가 자체 저수준 파서를 작성하지 않고도 다양한 음악 AI 접근 방식을 실험할 수 있게 해줍니다.

주요 기능

공개된 대부분의 음악 토큰화 방식을 지원합니다 (REMI, REMI+, MIDI-Like, TSD, BEAT, Structured, CPWord, Octuple, MuMIDI, MMM, PerTok 등).
토크나이저는 공통된 구성 API(TokenizerConfig)를 공유합니다.
fast 🤗 tokenizers 라이브러리를 사용해 BPE, Unigram, WordPiece로 어휘를 학습할 수 있습니다.
Symusic 기반으로 안정적인 MIDI/abc I/O를 제공하며, Hugging Face Hub와 통합되어 토크나이저와 모델을 공유할 수 있습니다.
긴 파일을 훈련용 시퀀스로 나누기 위한 PyTorch 호환 데이터셋, 콜레이터, 유틸리티를 제공합니다.
데이터 증강 헬퍼를 포함하고 있으며, 향후 확장 계획이 있습니다 (MusicXML 지원, 드럼 전용 옵션, 컨트롤 체인지 처리, Rust/C++ 기반 성능 향상).

설치

pip install miditok

이 패키지는 Python ≥ 3.9를 필요로 하며, 자동으로 symusic 및 huggingface-tokenizers를 가져옵니다.

빠른 시작

from miditok import REMI, TokenizerConfig
from symusic import Score

# 멀티트랙 토크나이저 설정
cfg = TokenizerConfig(num_velocities=16, use_chords=True, use_programs=True)
tokenizer = REMI(cfg)

# MIDI 파일 로드, 토큰화, 복원
midi = Score("my_song.mid")
toks = tokenizer(midi)               # 파일 경로 또는 원시 토큰 리스트도 가능
recovered = tokenizer(toks)          # Symusic Score 객체 반환

모델 훈련 – 엔드투엔드 예제

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️⃣ MIDI 파일 코퍼스에서 어휘 학습
files = list(Path("/data/midis").rglob("*.mid"))
tokenizer.train(vocab_size=30_000, files_paths=files)

tokenizer.save(Path("tokenizer.json"))
# 선택 사항: Hugging Face 허브에 푸시
# tokenizer.push_to_hub("username/miditok-remi")

# 2️⃣ 긴 파일을 고정 길이의 청크로 분할하여 훈련 준비
chunks_dir = Path("chunks")
split_files_for_training(files, tokenizer, chunks_dir, max_seq_len=1024)

# 3️⃣ PyTorch 데이터셋 / 데이터로더 구축
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️⃣ 반복 처리 – 어떤 Transformer 스타일 모델에도 연결 가능
for batch in loader:
    # 당신의 모델의 forward 패스로 교체
    print("batch ready for training")

README에는 Hugging Face Mistral 스타일의 트랜스포머를 사용하여 MidiTok으로 음악을 생성하는 방법을 보여주는 Colab 노트북 링크가 포함되어 있습니다.

문서 및 커뮤니티 – 전체 API 문서는 https://miditok.readthedocs.io 에 게시되어 있으며, 프로젝트는 PyPI에 등록되어 있으며 GitHub에서 CI 테스트가 수행됩니다. GitHub 워크플로우를 통해 기여를 환영합니다.

인용 – 연구에서 이 라이브러리를 사용할 경우, ISMIR 2021 데모 논문(README에 링크된 arXiv 프리프린트 포함)을 인용해 주세요.

Natooz/MidiTok

MidiTok – AI 모델을 위한 음악 토큰화

관련