# musdb
[](https://github.com/sigsep/sigsep-mus-db/actions?query=workflow%3ACI+branch%3Amaster+event%3Apush)
[](https://pypi.python.org/pypi/musdb/)
[](https://pypi.python.org/pypi/musdb/)
A python package to parse and process the [MUSDB18 dataset](https://sigsep.github.io/musdb), the largest open access dataset for music source separation. The tool was originally developed for the [Music Separation task](https://sisec18.unmix.app) as part of the [Signal Separation Evaluation Campaign (SISEC)](https://sisec.inria.fr/).
## Getting the data
`musdb` comes with 7 seconds excerpts (automatically downloaded) of the full dataset for quick evaluation or prototyping. The full dataset, however, needs to be downloaded [via Zenodo](https://zenodo.org/record/1117372) and stored (unzipped) separately.
> The dataset is hosted on Zenodo and requires that users request access, since the tracks can only be used for academic purposes. We manually check this requests. Please do not fill the form multiple times, it usually takes as less than a day to give you access.
## Installation and Setup
### Package installation
You can install `musdb` using pip:
```bash
pip install musdb
```
### Using STEMs (Default)
<img src="https://sigsep.github.io/assets/img/stems.a411b49d.png" width="300"/>
_MUSDB18_ comes encoded in [STEMS](http://www.stems-music.com/) which is a multitrack audio format that uses _lossy compression_. The `musdb` package, internally, relies on FFMPEG to decode the multi-stream files. For convenience, we developed a python package called [stempeg](https://github.com/faroit/stempeg) that allows to easily parse the stem files and decode them on-the-fly.
When you install _musdb_ (which depends on _stempeg_), it is therefore necessary to also install the FFMPEG library. The installation may differ among operating systems and python distributions:
* On [Anaconda](https://anaconda.org), you can install FFMPEG using `conda install -c conda-forge ffmpeg`.
Alternatively you can install FFMPEG manually as follows:
* on macOS, using homebrew: `brew install ffmpeg`
* on Ubuntu/Debian: `sudo apt-get install ffmpeg `
#### Using WAV files (Optional)
If you want to use WAV files (e.g. for faster audio decoding), `musdb` also supports parsing and processing pre-decoded PCM/wav files. `musdb` comes with the ability to convert a STEMS dataset into WAV version. This script can be used from the command line by
```
musdbconvert path/to/musdb-stems-root path/to/new/musdb-wav-root
```
If you don't want to use python for this, we also provide [docker based scripts](https://github.com/sigsep/sigsep-mus-io) to decode the dataset to WAV files.
__When you use the decoded MUSDB, use the `is_wav` parameter when initializing the dataset.__
## Usage
This package should nicely integrate with your existing python numpy, tensorflow or pytorch code. Most of the steps to use musdb in your project will probably use the same first steps:
### Setting up musdb
Import the `musdb` package in your main python function and iterate over the 7 seconds `musdb` tracks:
```python
import musdb
mus = musdb.DB(download=True)
mus[0].audio
```
To use the full dataset, set a dataset `root` directory
```python
mus = musdb.DB(root="/path/to/musdb)
```
where `root` is the path to the MUSDB18 dataset root folder. The root parameter can also be overridden using a system environment variable. Just ```export MUSDB_PATH=/path/to/musdb``` inside your bash environment. In that case no arguments would need to passed to `DB()`.
### Iterate over MUSDB18 tracks
Iterating over `musdb` and thus accessing the audio data is as simple as. Lets assume, we have a supervised training method `train(x, y)` that takes the __mixture__ as input and the __vocals__ as output, we can simple use:
```python
for track in mus:
train(track.audio, track.targets['vocals'].audio)
```
#### Tracks properties
The ```Track``` objects which makes it easy to process the audio and metadata in a pythonic way:
* ```Track.name```, the track name, consisting of `Track.artist` and `Track.title`.
* ```Track.path```, the absolute path of the mixture which might be handy to process with external applications.
* ```Track.audio```, stereo mixture as an numpy array of shape `(nb_samples, 2)`.
* ```Track.rate```, the sample rate of the mixture.
* ```Track.sources```, a dictionary of sources used for this track.
* ```Track.stems```, an numpy tensor of all five stereo sources of shape `(5, nb_samples, 2)`. The stems are always in the following order: `['mixture', 'drums', 'bass', 'other', 'vocals']`,
* ```Track.targets```, a dictionary of targets provided for this track.
Note that for MUSDB, the sources and targets differ only in the existence of the `accompaniment`, which is the sum of all sources, except for the vocals. MUSDB supports the following targets: `['mixture', 'drums', 'bass', 'other', 'vocals', 'accompaniment', 'linear_mixture']`. Note that some of the targets (such as __accompaniment__) are dynamically mixed on the fly.
#### Processing training and testing subsets separately
We provide subsets for _train_ and _test_ for machine learning methods:
```python
mus_train = musdb.DB(subsets="train")
mus_test = musdb.DB(subsets="test")
```
#### Use train / validation split
If you want to access individual tracks, you can access the `mus` tracks list by its indices, e.g. `mus[2:]`. To foster reproducible research, we provide a fixed validation dataset.
```python
mus_train = musdb.DB(subsets="train", split='train')
mus_valid = musdb.DB(subsets="train", split='valid')
```
The list of validation tracks can be edited using the [`mus.setup['validation_tracks']`](https://github.com/sigsep/sigsep-mus-tools/blob/b283da5b8f24e84172a60a06bb8f3dacd57aa6cd/musdb/configs/mus.yaml) object.
## Training Deep Neural Networks with `musdb`
Writing an efficient dataset generator varies across different deep learning frameworks. A very simple näive generator that
* draws random tracks with replacement
* draws random chunks of fixed length with replacement
can be easily implemented using musdb's `track.chunk_start` and `track.chunk_duration` properties which efficiently seeks to the start sample (provided in seconds) and does not load the full audio into memory first.
```python
while True:
track = random.choice(mus.tracks)
track.chunk_duration = 5.0
track.chunk_start = random.uniform(0, track.duration - track.chunk_duration)
x = track.audio.T
y = track.targets['vocals'].audio.T
yield x, y
```
### Evaluation
To Evaluate a `musdb` track using the popular BSSEval metrics, you can use our [museval](https://github.com/sigsep/sigsep-mus-eval) package. After `pip install museval` evaluation of a single `track`, can be done by
```python
import museval
# provide an estimate
estimates = {
'vocals': np.random.random(track.audio.shape),
'accompaniment': np.random.random(track.audio.shape)
}
# evaluates using BSSEval v4, and writes results to `./eval`
print(museval.eval_mus_track(track, estimates, output_dir="./eval")
```
## Baselines
### Oracles
For oracle methods, please check out our [open unmix oracle separation methods](https://github.com/sigsep/sigsep-mus-oracle).
This will show you how oracle performance is computed and gives indications for an upper bound for the quality of the separation.
### Open-Unmix
We provide a state-of-the-art deep learning based separation method for PyTorch, Tensorflow and NNable at [open.unmix.app](https://open.unmix.app).
## Frequently Asked Questions
##### The mixture is not exactly the sum of its sources, is that intended?
This is not a bug. Since we adopted the STEMS format, we used AAC compression. Here the residual noise of the mixture is different from the sum of the residual noises of the sources. This difference does not significantly affect separation performance.
```python
track.targets['linear_mixture'].audio
```
## Citations
<details><summary>If you use the MUSDB dataset for your research - Cite the MUSDB18 Dataset</summary>
<p>
```latex
@misc{MUSDB18,
author = {Rafii, Zafar and
Liutkus, Antoine and
Fabian-Robert St{\"o}ter and
Mimilakis, Stylianos Ioannis and
Bittner, Rachel},
title = {The {MUSDB18} corpus for music separation},
month = dec,
year = 2017,
doi = {10.5281/zenodo.1117372},
url = {https://doi.org/10.5281/zenodo.1117372}
}
```
</p>
</details>
<details><summary>If compare your results with SiSEC 2018 Participants - Cite the SiSEC 2018 LVA/ICA Paper</summary>
<p>
```latex
@inproceedings{SiSEC18,
author="St{\"o}ter, Fabian-Robert and Liutkus, Antoine and Ito, Nobutaka",
title="The 2018 Signal Separation Evaluation Campaign",
booktitle="Latent Variable Analysis and Signal Separation:
14th International Conference, LVA/ICA 2018, Surrey, UK",
year="2018",
pages="293--305"
}
```
</p>
</details>
## How to contribute
_musdb_ is a community focused project, we therefore encourage the community to submit bug-fixes and requests for technical support through [github issues](https://github.com/sigsep/sigsep-mus-db/issues/new). For more details of how to contribute, please follow our [`CONTRIBUTING.md`](CONTRIBUTING.md).
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/sigsep/sigsep-mus-db",
"name": "musdb",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Fabian-Robert Stoeter",
"author_email": "mail@faroit.com",
"download_url": "https://files.pythonhosted.org/packages/7d/16/8fbcf45be1afdbbf8e6b249df82f4ce717d0a6c178141cdee9c7fe410464/musdb-0.4.2.tar.gz",
"platform": null,
"description": "# musdb\n\n[](https://github.com/sigsep/sigsep-mus-db/actions?query=workflow%3ACI+branch%3Amaster+event%3Apush)\n[](https://pypi.python.org/pypi/musdb/)\n[](https://pypi.python.org/pypi/musdb/)\n\nA python package to parse and process the [MUSDB18 dataset](https://sigsep.github.io/musdb), the largest open access dataset for music source separation. The tool was originally developed for the [Music Separation task](https://sisec18.unmix.app) as part of the [Signal Separation Evaluation Campaign (SISEC)](https://sisec.inria.fr/). \n\n## Getting the data\n\n`musdb` comes with 7 seconds excerpts (automatically downloaded) of the full dataset for quick evaluation or prototyping. The full dataset, however, needs to be downloaded [via Zenodo](https://zenodo.org/record/1117372) and stored (unzipped) separately.\n\n> The dataset is hosted on Zenodo and requires that users request access, since the tracks can only be used for academic purposes. We manually check this requests. Please do not fill the form multiple times, it usually takes as less than a day to give you access.\n\n## Installation and Setup\n\n### Package installation\n\nYou can install `musdb` using pip:\n\n```bash\npip install musdb\n```\n\n### Using STEMs (Default)\n\n<img src=\"https://sigsep.github.io/assets/img/stems.a411b49d.png\" width=\"300\"/>\n\n_MUSDB18_ comes encoded in [STEMS](http://www.stems-music.com/) which is a multitrack audio format that uses _lossy compression_. The `musdb` package, internally, relies on FFMPEG to decode the multi-stream files. For convenience, we developed a python package called [stempeg](https://github.com/faroit/stempeg) that allows to easily parse the stem files and decode them on-the-fly.\nWhen you install _musdb_ (which depends on _stempeg_), it is therefore necessary to also install the FFMPEG library. The installation may differ among operating systems and python distributions:\n\n* On [Anaconda](https://anaconda.org), you can install FFMPEG using `conda install -c conda-forge ffmpeg`.\n\nAlternatively you can install FFMPEG manually as follows:\n\n* on macOS, using homebrew: `brew install ffmpeg`\n* on Ubuntu/Debian: `sudo apt-get install ffmpeg `\n\n#### Using WAV files (Optional)\n\nIf you want to use WAV files (e.g. for faster audio decoding), `musdb` also supports parsing and processing pre-decoded PCM/wav files. `musdb` comes with the ability to convert a STEMS dataset into WAV version. This script can be used from the command line by\n\n```\nmusdbconvert path/to/musdb-stems-root path/to/new/musdb-wav-root\n```\n\nIf you don't want to use python for this, we also provide [docker based scripts](https://github.com/sigsep/sigsep-mus-io) to decode the dataset to WAV files.\n\n__When you use the decoded MUSDB, use the `is_wav` parameter when initializing the dataset.__\n\n## Usage\n\nThis package should nicely integrate with your existing python numpy, tensorflow or pytorch code. Most of the steps to use musdb in your project will probably use the same first steps:\n\n### Setting up musdb\n\nImport the `musdb` package in your main python function and iterate over the 7 seconds `musdb` tracks:\n\n```python\nimport musdb\nmus = musdb.DB(download=True)\nmus[0].audio\n```\n\nTo use the full dataset, set a dataset `root` directory \n\n```python\nmus = musdb.DB(root=\"/path/to/musdb)\n```\n\nwhere `root` is the path to the MUSDB18 dataset root folder. The root parameter can also be overridden using a system environment variable. Just ```export MUSDB_PATH=/path/to/musdb``` inside your bash environment. In that case no arguments would need to passed to `DB()`.\n\n### Iterate over MUSDB18 tracks\n\nIterating over `musdb` and thus accessing the audio data is as simple as. Lets assume, we have a supervised training method `train(x, y)` that takes the __mixture__ as input and the __vocals__ as output, we can simple use:\n\n```python\nfor track in mus:\n train(track.audio, track.targets['vocals'].audio)\n```\n\n#### Tracks properties\n\nThe ```Track``` objects which makes it easy to process the audio and metadata in a pythonic way:\n\n* ```Track.name```, the track name, consisting of `Track.artist` and `Track.title`.\n* ```Track.path```, the absolute path of the mixture which might be handy to process with external applications.\n* ```Track.audio```, stereo mixture as an numpy array of shape `(nb_samples, 2)`.\n* ```Track.rate```, the sample rate of the mixture.\n* ```Track.sources```, a dictionary of sources used for this track.\n* ```Track.stems```, an numpy tensor of all five stereo sources of shape `(5, nb_samples, 2)`. The stems are always in the following order: `['mixture', 'drums', 'bass', 'other', 'vocals']`,\n* ```Track.targets```, a dictionary of targets provided for this track.\nNote that for MUSDB, the sources and targets differ only in the existence of the `accompaniment`, which is the sum of all sources, except for the vocals. MUSDB supports the following targets: `['mixture', 'drums', 'bass', 'other', 'vocals', 'accompaniment', 'linear_mixture']`. Note that some of the targets (such as __accompaniment__) are dynamically mixed on the fly.\n\n\n#### Processing training and testing subsets separately\n\nWe provide subsets for _train_ and _test_ for machine learning methods:\n\n```python\nmus_train = musdb.DB(subsets=\"train\")\nmus_test = musdb.DB(subsets=\"test\")\n```\n\n#### Use train / validation split\n\nIf you want to access individual tracks, you can access the `mus` tracks list by its indices, e.g. `mus[2:]`. To foster reproducible research, we provide a fixed validation dataset.\n\n```python\nmus_train = musdb.DB(subsets=\"train\", split='train')\nmus_valid = musdb.DB(subsets=\"train\", split='valid')\n```\n\nThe list of validation tracks can be edited using the [`mus.setup['validation_tracks']`](https://github.com/sigsep/sigsep-mus-tools/blob/b283da5b8f24e84172a60a06bb8f3dacd57aa6cd/musdb/configs/mus.yaml) object.\n\n## Training Deep Neural Networks with `musdb`\n\nWriting an efficient dataset generator varies across different deep learning frameworks. A very simple n\u00e4ive generator that\n\n* draws random tracks with replacement\n* draws random chunks of fixed length with replacement\n\ncan be easily implemented using musdb's `track.chunk_start` and `track.chunk_duration` properties which efficiently seeks to the start sample (provided in seconds) and does not load the full audio into memory first.\n\n```python\nwhile True:\n track = random.choice(mus.tracks)\n track.chunk_duration = 5.0\n track.chunk_start = random.uniform(0, track.duration - track.chunk_duration)\n x = track.audio.T\n y = track.targets['vocals'].audio.T\n yield x, y\n```\n\n### Evaluation\n\nTo Evaluate a `musdb` track using the popular BSSEval metrics, you can use our [museval](https://github.com/sigsep/sigsep-mus-eval) package. After `pip install museval` evaluation of a single `track`, can be done by\n\n```python\nimport museval\n# provide an estimate\nestimates = {\n 'vocals': np.random.random(track.audio.shape),\n 'accompaniment': np.random.random(track.audio.shape)\n}\n# evaluates using BSSEval v4, and writes results to `./eval`\nprint(museval.eval_mus_track(track, estimates, output_dir=\"./eval\")\n```\n\n## Baselines\n\n### Oracles\nFor oracle methods, please check out our [open unmix oracle separation methods](https://github.com/sigsep/sigsep-mus-oracle).\nThis will show you how oracle performance is computed and gives indications for an upper bound for the quality of the separation.\n\n### Open-Unmix\n\nWe provide a state-of-the-art deep learning based separation method for PyTorch, Tensorflow and NNable at [open.unmix.app](https://open.unmix.app).\n\n## Frequently Asked Questions\n\n##### The mixture is not exactly the sum of its sources, is that intended?\n\nThis is not a bug. Since we adopted the STEMS format, we used AAC compression. Here the residual noise of the mixture is different from the sum of the residual noises of the sources. This difference does not significantly affect separation performance.\n\n```python\ntrack.targets['linear_mixture'].audio\n```\n\n## Citations\n\n<details><summary>If you use the MUSDB dataset for your research - Cite the MUSDB18 Dataset</summary>\n<p>\n\n```latex\n@misc{MUSDB18,\n author = {Rafii, Zafar and\n Liutkus, Antoine and\n Fabian-Robert St{\\\"o}ter and\n Mimilakis, Stylianos Ioannis and\n Bittner, Rachel},\n title = {The {MUSDB18} corpus for music separation},\n month = dec,\n year = 2017,\n doi = {10.5281/zenodo.1117372},\n url = {https://doi.org/10.5281/zenodo.1117372}\n}\n```\n\n</p>\n</details>\n\n\n<details><summary>If compare your results with SiSEC 2018 Participants - Cite the SiSEC 2018 LVA/ICA Paper</summary>\n<p>\n\n```latex\n@inproceedings{SiSEC18,\n author=\"St{\\\"o}ter, Fabian-Robert and Liutkus, Antoine and Ito, Nobutaka\",\n title=\"The 2018 Signal Separation Evaluation Campaign\",\n booktitle=\"Latent Variable Analysis and Signal Separation:\n 14th International Conference, LVA/ICA 2018, Surrey, UK\",\n year=\"2018\",\n pages=\"293--305\"\n}\n```\n\n</p>\n</details>\n\n## How to contribute\n\n_musdb_ is a community focused project, we therefore encourage the community to submit bug-fixes and requests for technical support through [github issues](https://github.com/sigsep/sigsep-mus-db/issues/new). For more details of how to contribute, please follow our [`CONTRIBUTING.md`](CONTRIBUTING.md). \n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python parser for the SIGSEP MUSDB18 dataset",
"version": "0.4.2",
"project_urls": {
"Homepage": "https://github.com/sigsep/sigsep-mus-db"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae3123c23568e6ecbbabcde19dde1df9a1ad8951591ec9d4f5bbf2906732a2b7",
"md5": "96fc41b4f45aa3a6244e66349ab8fc74",
"sha256": "e26e5dcce87f90e2348a18c38b73c3fbf5b20ac2c6050111ae0a5f029c642037"
},
"downloads": -1,
"filename": "musdb-0.4.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "96fc41b4f45aa3a6244e66349ab8fc74",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 13792,
"upload_time": "2023-11-24T13:25:31",
"upload_time_iso_8601": "2023-11-24T13:25:31.767304Z",
"url": "https://files.pythonhosted.org/packages/ae/31/23c23568e6ecbbabcde19dde1df9a1ad8951591ec9d4f5bbf2906732a2b7/musdb-0.4.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7d168fbcf45be1afdbbf8e6b249df82f4ce717d0a6c178141cdee9c7fe410464",
"md5": "9cb36ff6437f791f7a9f5f384b877597",
"sha256": "f835246ee7b3bc54599fd146e8e18e64ff7ee617e2265bf17ba62afb3daf2ec4"
},
"downloads": -1,
"filename": "musdb-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "9cb36ff6437f791f7a9f5f384b877597",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18992,
"upload_time": "2023-11-24T13:25:33",
"upload_time_iso_8601": "2023-11-24T13:25:33.658299Z",
"url": "https://files.pythonhosted.org/packages/7d/16/8fbcf45be1afdbbf8e6b249df82f4ce717d0a6c178141cdee9c7fe410464/musdb-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-24 13:25:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sigsep",
"github_project": "sigsep-mus-db",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "musdb"
}
JSON
