ZFTurbo/Music-Source-Separation-Training

Music Source Separation – Universal Training Code (MSST)

무엇인가요 – 음악 트랙을 보컬, 드럼, 베이스, 기타 등 구성 요소로 분리하는 다양한 딥러닝 모델의 훈련, 평가, 추론을 위한 파이썬 라이브러리와 스크립트 세트입니다. 이 저장소에는 사용 가능한 모델 구현, 설정 파일, 데이터 처리 유틸리티, 그리고 작은 GUI가 포함되어 있으며, 실험을 빠르고 재현 가능하게 만드는 것을 목표로 합니다.

왜 중요한가요 – 음성 신호 처리의 핵심 작업이며, 생성형 및 판별형 오디오 모델의 대표적인 벤치마크입니다. 수십 가지 최신 아키텍처(MDX23C, Demucs-HT, RoFormer 기반 모델, Swin-Upernet, SCNet, Conformer 등)를 지원하는 단일 확장 가능한 훈련 프레임워크를 제공함으로써, 연구자와 애호가들이 반복 코드를 다시 작성하지 않고도 아이디어를 비교할 수 있게 합니다.

주요 구성 요소

모델 지오 – --model_type를 통해 선택 가능한 십여 가지 아키텍처. 많은 모델은 기존 오픈소스 프로젝트(예: Lucidrains의 RoFormer, Segmentation-Models-Pytorch 라이브러리, 원본 Demucs-HT 코드)를 래핑한 얇은 래퍼입니다. 래퍼는 훈련 루프와 체크포인트 처리를 표준화합니다.
설정 기반 훈련 – configs/ 디렉터리의 YAML 파일로 데이터셋 경로, 하이퍼파라미터, 배치 크기, 학습률 스케줄 등을 정의합니다. MUSDB18 벤치마크용 예제 설정 파일도 제공됩니다.
훈련 스크립트 – 단일 GPU용 train.py, 다중 GPU용 train_ddp.py (PyTorch Distributed Data Parallel). 둘 다 docs/LoRA.md 가이드에 따라 LoRA 미세조정을 지원합니다.
추론 유틸리티 – inference.py는 체크포인트를 로드하고 wav 파일 폴더를 처리하여 분리된 스템을 출력 디렉터리에 저장합니다.
앙상블 – ensemble.py는 여러 모델의 예측을 결합하여 SDR 점수를 향상시킬 수 있습니다.
GUI – 마우스 클릭 중심 워크플로우를 선호하는 사용자를 위한 가벼운 wxPython 인터페이스(gui-wx.py).
패키징 – pip install msst로 설치 가능하며, Python API, CLI, 그리고 docs/에 있는 문서를 제공합니다.

일반적인 워크플로우

모델 선택 – 예: mel_band_roformer.
설정 선택 – 예: configs/config_mel_band_roformer_vocals.yaml (경로, 배치 크기 등을 사용자 정의).

훈련 시작 –

python train.py \
    --model_type mel_band_roformer \
    --config_path configs/config_mel_band_roformer_vocals.yaml \
    --results_path results/ \
    --data_path datasets/train1 datasets/train2 \
    --valid_path datasets/musdb18hq/test \
    --num_workers 4 \
    --device_ids 0

추론 실행 –

python inference.py \
    --model_type mel_band_roformer \
    --config_path configs/config_mel_band_roformer_vocals.yaml \
    --start_check_point results/last.ckpt \
    --input_folder input/wavs/ \
    --store_dir separation_results/

(선택 사항) ensemble.py로 여러 체크포인트를 앙상블하여 분리 품질을 향상시킵니다.

하드웨어 참고 사항 – 기본 배치 크기는 NVIDIA A6000(48GB)을 타겟으로 합니다. VRAM이 적은 사용자는 YAML 설정 파일에서 training.batch_size를 낮추거나, training.gradient_accumulation_steps를 늘려야 합니다.

사전 학습된 모델 – 저장소는 지원되는 아키텍처의 많은 모델에 대해 공개된 체크포인트 목록(docs/pretrained_models.md)을 유지 관리하며, 빠른 추론이나 미세조정을 위한 초기화로 유용합니다.

커뮤니티 및 인용 – 이 프로젝트는 MVSep.com 팀이 유지 관리하며, SDX23 챌린지의 KUIELab 코드를 기반으로 합니다. 이 코드를 사용해 연구 결과를 발표할 경우, README에 링크된 벤치마크 논문을 인용해 주세요.

결론 – MSST는 실용적이고 잘 문서화된 도구 상자로, 음악 소스 분리 연구에서 반복적인 작업을 추상화하여 모델 아이디어, 데이터 증강, 대규모 실험에 집중할 수 있도록 도와줍니다.

ZFTurbo/Music-Source-Separation-Training

Music Source Separation – Universal Training Code (MSST)

관련