Music Demixing Challenge - Starter Kit

This repository is the Music Demixing Challenge Submission template and Starter kit!

Clone the repository to compete now!

This repository contains:

Documentation on how to submit your models to the leaderboard
The procedure for best practices and information on how we evaluate your agent, etc.
Starter code for you to get started!

Competition Procedure
How to access and use dataset
How to start participating
How do I specify my software runtime / dependencies?
What should my code structure be like ?
How to make submission
Other concepts
Important links

Competition Procedure

The Music Demixing (MDX) Challenge is an opportunity for researchers and machine learning enthusiasts to test their skills by creating a system able to perform audio source separation.

In this challenge, you will train your models locally and then upload them to AIcrowd (via git) to be evaluated.

The following is a high level description of how this process works

Sign up to join the competition on the AIcrowd website.
Clone this repo and start developing your solution.
Train your models for audio seperation and write prediction code in test.py.
Submit your trained models to AIcrowd Gitlab for evaluation (full instructions below). The automated evaluation setup will evaluate the submissions against the test dataset to compute and report the metrics on the leaderboard of the competition.

How to access and use the dataset

You are allowed to train your system either exclusively on the training part of MUSDB18-HQ dataset or you can use your choice of data. According to the dataset used, you will be eligible for different leaderboards.

👉 Download MUSDB18-HQ dataset

In case you are using external dataset, please mention it in your aicrowd.json.

{
  [...],
  "external_dataset_used": true
}

The MUSDB18 dataset contains 150 songs (100 songs in train and 50 songs in test) together with their seperations in the following manner:

|
├── train
│   ├── A Classic Education - NightOwl
│   │   ├── bass.wav
│   │   ├── drums.wav
│   │   ├── mixture.wav
│   │   ├── other.wav
│   │   └── vocals.wav
│   └── ANiMAL - Clinic A
│       ├── bass.wav
│       ├── drums.wav
│       ├── mixture.wav
│       ├── other.wav
│       └── vocals.wav
[...]

Here the mixture.wav file is the original music on which you need to do audio source seperation.
While bass.wav, drums.wav, other.wav and vocals.wav contain files for your training purposes.
Please note again: To be eligible for Leaderboard A, you are only allowed to train on the songs in train.

How to start participating

Setup

Add your SSH key to AIcrowd GitLab

You can add your SSH Keys to your GitLab account by going to your profile settings here. If you do not have SSH Keys, you will first need to generate one.

Clone the repository

git clone git@github.com:AIcrowd/music-demixing-challenge-starter-kit.git

Install competition specific dependencies!

cd music-demixing-challenge-starter-kit
pip3 install -r requirements.txt

Try out random prediction codebase present in test.py.

How do I specify my software runtime / dependencies ?

We accept submissions with custom runtime, so you don't need to worry about which libraries or framework to pick from.

The configuration files typically include requirements.txt (pypi packages), environment.yml (conda environment), apt.txt (apt packages) or even your own Dockerfile.

You can check detailed information about the same in the 👉 RUNTIME.md file.

What should my code structure be like ?

Please follow the example structure as it is in the starter kit for the code structure. The different files and directories have following meaning:

.
├── aicrowd.json           # Submission meta information - like your username
├── apt.txt                # Packages to be installed inside docker image
├── data                   # Your local dataset copy - you don't need to upload it (read DATASET.md)
├── requirements.txt       # Python packages to be installed
├── test.py                # IMPORTANT: Your testing/prediction code, must be derived from MusicDemixingPredictor (example in test.py)
└── utility                # The utility scripts to provide smoother experience to you.
    ├── docker_build.sh
    ├── docker_run.sh
    ├── environ.sh
    └── verify_or_download_data.sh

Finally, you must specify an AIcrowd submission JSON in aicrowd.json to be scored!

The aicrowd.json of each submission should contain the following content:

{
  "challenge_id": "evaluations-api-music-demixing",
  "authors": ["your-aicrowd-username"],
  "description": "(optional) description about your awesome agent",
  "external_dataset_used": false
}