forked from huggingface demucs

CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at <opensource-conduct@fb.com>. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing to Demucs
+
+## Pull Requests
+
+In order to accept your pull request, we need you to submit a CLA. You only need
+to do this once to work on any of Facebook's open source projects.
+
+Complete your CLA here: <https://code.facebook.com/cla>
+
+Demucs is the implementation of a research paper.
+Therefore, we do not plan on accepting many pull requests for new features.
+We certainly welcome them for bug fixes.
+
+
+## Issues
+
+We use GitHub issues to track public bugs. Please ensure your description is
+clear and has sufficient instructions to be able to reproduce the issue.
+
+
+## License
+By contributing to this repository, you agree that your contributions will be licensed
+under the LICENSE file in the root directory of this source tree.

Demucs.ipynb

@@ -0,0 +1,115 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "colab_type": "text",
+    "id": "Be9yoh-ILfRr"
+   },
+   "source": [
+    "# [*Colab code for Demucs*](https://github.com/facebookresearch/demucs/)\n",
+    "\n",
+    "Original version by marlluslustosa **https://github.com/marlluslustosa/demucs/blob/master/Demucs.ipynb**\n",
+    "\n",
+    "However, now things are much simpler with Demucs v2, so this might not be so useful. There is now a Colab version:\n",
+    "https://colab.research.google.com/drive/1jCegIzLIuqqcM85uVs3WCeAJiSoYq3oh?usp=sharing"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 139
+    },
+    "colab_type": "code",
+    "executionInfo": {
+     "elapsed": 12277,
+     "status": "ok",
+     "timestamp": 1583778134659,
+     "user": {
+      "displayName": "Marllus Lustosa",
+      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14GgLl2RbW64ZyWz3Y8IBku0zhHCMnt7fz7fEl0LTdA=s64",
+      "userId": "14811735256675200480"
+     },
+     "user_tz": 180
+    },
+    "id": "kOjIPLlzhPfn",
+    "outputId": "c75f17ec-b576-4105-bc5b-c2ac9c1018a3"
+   },
+   "outputs": [],
+   "source": [
+    "!pip install demucs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "colab_type": "text",
+    "id": "Y1BdlzOQi3y7"
+   },
+   "source": [
+    "\n",
+    "\n",
+    "---\n",
+    "\n",
+    "\n",
+    "# **Here begins the code for separating the audio source (model pretrained)**\n",
+    "###**- Upload your song to demucs/ folder and edit YOUR-SONG-PATH.mp3**\n",
+    "\n",
+    "\n",
+    "---\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "colab": {},
+    "colab_type": "code",
+    "id": "5lYOzKKCKAbJ"
+   },
+   "outputs": [],
+   "source": [
+    "!python3 -m demucs.separate test.mp3"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "authorship_tag": "ABX9TyM9xpVr1M86NRcjtQ7g9tCx",
+   "collapsed_sections": [],
+   "name": "Demucs.ipynb",
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,6 @@
+include *.md
+include LICENSE
+include setup.cfg
+incude demucs.png
+include requirements.txt
+recursive-include docs *.md

Makefile

@@ -0,0 +1,19 @@
+default: tests
+
+all: linter tests docs dist
+
+linter:
+	flake8 demucs
+
+tests:
+	python3 -m demucs.separate -n demucs_unittest test.mp3
+	python3 -m demucs.separate -n demucs_unittest --mp3 test.mp3
+
+dist:
+	python3 setup.py sdist
+
+clean:
+	rm -r dist build *.egg-info
+
+
+.PHONY: linter tests dist

README.md

@@ -1,13 +1,379 @@
----
-title: Demucs Playground
-emoji: 🌍
-colorFrom: green
-colorTo: yellow
-sdk: gradio
-sdk_version: 3.12.0
-app_file: app.py
-pinned: false
-license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Music Source Separation in the Waveform Domain
+
+![tests badge](https://github.com/facebookresearch/demucs/workflows/tests/badge.svg)
+![linter badge](https://github.com/facebookresearch/demucs/workflows/linter/badge.svg)
+
+**Branch was rename to main**: Run `git pull && git checkout main` to switch to the new branch.
+
+**Demucs was just updated!**: much better SDR, smaller models, more data augmentation and PyPI support.
+
+**For the initial version of Demucs:** [Go this commit][original_demucs].
+If you are experiencing issues and want the old Demucs back, please fill an issue, and then you can get back to the v1 with
+`git checkout v1`.
+
+We provide an implementation of Demucs and Conv-Tasnet for music source separation on the [MusDB][musdb] dataset.
+They can separate drums, bass and vocals from the rest with state-of-the-art results, surpassing previous waveform or spectrogram based methods.
+The architecture and results obtained are detailed in our paper
+[Music Source Separation in the waveform domain][demucs_arxiv].
+
+Demucs is based on U-Net convolutional architecture inspired by [Wave-U-Net][waveunet] and
+[SING][sing], with GLUs, a BiLSTM between the encoder and decoder, specific initialization of weights
+and transposed convolutions in the decoder.
+
+[Conv-Tasnet](https://arxiv.org/abs/1809.07454)
+is a separation model developed for speech which predicts a mask on a learnt over-complete linear representation
+using a purely convolutional model with stride of 1 and dilated convolutional blocks.
+We reused the code from the [kaituoxu/Conv-TasNet][tasnet]
+repository and added support for multiple audio channels.
+
+
+Demucs achieves a state-of-the-art SDR performance of 6.3 when trained only on MusDB.
+Conv-Tasnet achieves an SDR of 5.7, to be compared with the best performing spectrogram domain model [D3Net][d3net]
+with an average SDR of 6.
+Unlike Conv-Tasnet, Demucs reacts positively to pitch/tempo shift augmentation (+0.5 SDR). However, Demucs
+still suffers from leakage from other sources, in particular between the vocals and other sources, which is less of a problem
+for Conv-Tasnet. When trained with 150 extra tracks, Demucs reaches an SDR of 6.8, and even surpasses the IRM oracle
+for the bass source (7.6 against 7.1 for the oracle).
+See [our paper][demucs_arxiv] Section 6 for more details or listen to our
+[audio samples][audio] .
+
+<p align="center">
+<img src="./demucs.png" alt="Schema representing the structure of Demucs,
+    with a convolutional encoder, a BiLSTM, and a decoder based on transposed convolutions."
+width="800px"></p>
+
+
+## Important news if you are already using Demucs
+
+See the [release notes](./docs/release.md) for more details.
+
+- 11/05/2021: Adding support for MusDB-HQ and arbitrary wav set, for the MDX challenge. For more information
+on joining the challenge with Demucs see [the Demucs MDX instructions](docs/mdx.md)
+- 28/04/2021: **Demucs v2**, with extra augmentation and DiffQ based quantization.
+  **EVERYTHING WILL BREAK**, please restart from scratch following the instructions hereafter.
+  This version also adds overlap between prediction frames, with linear transition from one to the next,
+  which should prevent sudden changes at frame boundaries. Also, Demucs is now on PyPI, so for separation
+  only, installation is as easy as `pip install demucs` :)
+- 13/04/2020: **Demucs released under MIT**: We are happy to release Demucs under the MIT licence.
+    We hope that this will broaden the impact of this research to new applications.
+
+
+## Comparison with other models
+
+An audio comparison of Demucs and Conv-Tasnet with other state-of-the-art methods such as [Wave-U-Net][waveunet], [OpenUnmix][openunmix] or
+[MMDenseLSTM][mmdenselstm] is available on [the audio comparison page][audio].
+We provide hereafter a summary of the different metrics presented in the paper.
+You can also compare [Spleeter][spleeter], Open-Unmix, Demucs and Conv-Tasnet on one of my favorite
+songs on our [soundcloud playlist][soundcloud].
+
+### Comparison of accuracy
+
+`Overall SDR` is the mean of the SDR for each of the 4 sources, `MOS Quality` is a rating from 1 to 5
+of the naturalness and absence of artifacts given by human listeners (5 = no artifacts), `MOS Contamination`
+is a rating from 1 to 5 with 5 being zero contamination by other sources. We refer the reader to our [paper][demucs_arxiv], Section 5 and 6,
+for more details.
+
+| Model         | Domain     | Extra data?  | Overall SDR | MOS Quality | MOS Contamination |
+| ------------- |-------------| -----:|------:|----:|----:|
+| [Open-Unmix][openunmix]      | spectrogram | no | 5.3 | 3.0 | 3.3 |
+| [D3Net][d3net]  | spectrogram | no | 6.0 | - | - |
+| [Wave-U-Net][waveunet]      | waveform | no | 3.2 | - | - |
+| Demucs (this)      | waveform | no | **6.3** | **3.2** | 3.3 |
+| Conv-Tasnet (this)     | waveform | no | 5.7 | 2.9 | **3.4** |
+| Demucs  (this)    | waveform | 150 songs | **6.8** | - | - |
+| Conv-Tasnet  (this)    | waveform | 150 songs | 6.3 | - | - |
+| [MMDenseLSTM][mmdenselstm]      | spectrogram | 804 songs | 6.0 | - | - |
+| [D3Net][d3net]  | spectrogram | 1.5k songs | 6.7 | - | - |
+| [Spleeter][spleeter]  | spectrogram | 25k songs | 5.9 | - | - |
+
+
+
+## Requirements
+
+You will need at least Python 3.7. See `requirements.txt` for requirements for separation only,
+and `environment-[cpu|cuda].yml` if you want to train a new model.
+
+### For Windows users
+
+Everytime you see `python3`, replace it with `python.exe`. You should always run commands from the
+Anaconda console.
+
+### For musicians
+
+If you just want to use Demucs to separate tracks, you can install it with
+
+    python3 -m pip -U install demucs
+
+Advanced OS support are provided on the following page, **you must read the page for your OS before posting an issues**:
+- **If you are using Windows:** [Windows support](docs/windows.md).
+- **If you are using MAC OS X:** [Mac OS X support](docs/mac.md).
+- **If you are using Linux:** [Linux support](docs/linux.md).
+
+### For machine learning scientists
+
+If you have anaconda installed, you can run from the root of this repository:
+
+    conda env update -f environment-cpu.yml # if you don't have GPUs
+    conda env update -f environment-cuda.yml # if you have GPUs
+    conda activate demucs
+    pip install -e .
+
+This will create a `demucs` environment with all the dependencies installed.
+
+
+You will also need to install [soundstretch/soundtouch](https://www.surina.net/soundtouch/soundstretch.html): on Mac OSX you can do `brew install sound-touch`,
+and on Ubuntu `sudo apt-get install soundstretch`. This is used for the
+pitch/tempo augmentation.
+
+### Running in Docker
+
+Thanks to @xserrat, there is now a Docker image definition ready for using Demucs. This can ensure all libraries are correctly installed without interfering with the host OS. See his repo [Docker Facebook Demucs](https://github.com/xserrat/docker-facebook-demucs) for more information.
+
+
+### Running from Colab
+
+I made a Colab to easily separate track with Demucs. Note that
+transfer speeds with Colab are a bit slow for large media files,
+but it will allow you to use Demucs without installing anything.
+
+[Demucs on Google Colab](https://colab.research.google.com/drive/1jCegIzLIuqqcM85uVs3WCeAJiSoYq3oh?usp=sharing)
+
+## Separating tracks
+
+In order to try Demucs or Conv-Tasnet on your tracks, simply run from the root of this repository
+
+```bash
+python3 -m demucs.separate PATH_TO_AUDIO_FILE_1 [PATH_TO_AUDIO_FILE_2 ...] # for Demucs
+python3 -m demucs.separate --mp3 PATH_TO_AUDIO_FILE_1 --mp3-bitrate BITRATE # output files saved as MP3
+python3 -m demucs.separate -n tasnet PATH_TO_AUDIO_FILE_1 ... # for Conv-Tasnet
+```
+
+If you have a GPU, but you run out of memory, please add `-d cpu` to the command line. See the section hereafter for more details on the memory requirements for GPU acceleration.
+
+Separated tracks are stored in the `separated/MODEL_NAME/TRACK_NAME` folder. There you will find four stereo wav files sampled at 44.1 kHz: `drums.wav`, `bass.wav`,
+`other.wav`, `vocals.wav` (or `.mp3` if you used the `--mp3` option).
+
+All audio formats supported by `torchaudio` can be processed (i.e. wav, mp3, flac, ogg/vorbis etc.).
+Audio is resampled on the fly if necessary.
+The output will be a wave file, either in int16 format or float32 (if `--float32` is passed).
+You can pass `--mp3` to save as mp3 instead, and set the bitrate with `--mp3-bitrate` (default is 320kbps).
+
+Other pre-trained models can be selected with the `-n` flag.
+The list of pre-trained models is:
+- `demucs`: Demucs trained on MusDB,
+- `demucs_quantized`: Quantized Demucs with [diffq](https://github.com/facebookresearch/diffq),
+    this is much smaller (150MB instead of 1GB) and quality should be exactly the same. Let me know if you disagree.
+    As a result, this is the one used by default.
+- `demucs_extra`: Demucs trained with extra training data,
+- `demucs48_hq`: Demucs with 48 initial hidden channels, trained on [MusDB-HQ](https://zenodo.org/record/3338373),
+ used as a baseline for the [Music Demixing Challenge 2021](https://www.aicrowd.com/challenges/music-demixing-challenge-ismir-2021),
+- `tasnet`: Conv-Tasnet trained on MusDB,
+- `tasnet_extra`: Conv-Tasnet trained with extra training data.
+
+
+The `--shifts=SHIFTS` performs multiple predictions with random shifts (a.k.a the *shift trick*) of the input and average them. This makes prediction `SHIFTS` times
+slower but improves the accuracy of Demucs by 0.2 points of SDR.
+It has limited impact on Conv-Tasnet as the model is by nature almost time equivariant.
+The value of 10 was used on the original paper, although 5 yields mostly the same gain.
+It is deactivated by default but it does make vocals a bit smoother.
+
+The `--overlap` option controls the amount of overlap between prediction windows (for Demucs one window is 10 seconds).
+Default is 0.25 (i.e. 25%) which is probably fine.
+
+
+### Memory requirements for GPU acceleration
+
+If you want to use GPU acceleration, you will need at least 8GB of RAM on your GPU for `demucs` and 4GB for `tasnet`. Sorry, the code for demucs is not super optimized for memory! If you do not have enough memory on your GPU, simply add `-d cpu` to the command line to use the CPU. With Demucs, processing time should be roughly equal to the duration of the track.
+
+
+## Examining the results from the paper experiments
+
+The metrics for our experiments are stored in the `results` folder. In particular
+`museval` json evaluations are stored in `results/evals/EXPERIMENT NAME/results`.
+You can aggregate and display the results using
+```bash
+python3 valid_table.py -p # show valid loss, aggregated with multiple random seeds
+python3 result_table.py -p # show SDR on test set, aggregated with multiple random seeds
+python3 result_table.py -p SIR # also SAR, ISR, show other metrics
+```
+The `std` column shows the standard deviation divided by the square root of the number of runs.
+
+## Training Demucs and evaluating on the MusDB dataset
+
+If you want to train Demucs from scratch, you will need a copy of the MusDB dataset.
+It can be obtained on the [MusDB website][musdb].
+To start training on a single GPU or CPU, use:
+```bash
+python3 -m demucs -b 4  --musdb MUSDB_PATH # Demucs
+python3 -m demucs -b 4  --musdb MUSDB_PATH --tasnet --samples=80000 --split_valid # Conv-Tasnet
+```
+The `-b 4` flag will set the batch size to 4. The default is 4 and will crash on a single GPU.
+Demucs was trained on 8 V100 with 32GB of RAM.
+The default parameters (batch size, number of channels etc)
+might not be suitable for 16GB GPUs.
+To train on all available GPUs, use:
+```bash
+python3 run.py --musdb MUSDB_PATH [EXTRA_FLAGS]
+```
+
+This will launch one process per GPU and report the output of the first one. When interrupting
+such a run, it is possible some of the children processes are not killed properly, be mindful of that.
+If you want to use only some of the available GPUs, export the `CUDA_VISIBLE_DEVICES` variable to
+select those.
+
+To see all the possible options, use `python3 -m demucs --help`.
+
+
+### MusDB HQ
+
+To train on MusDB HQ, use the following flags:
+
+```bash
+python3 -m demucs -b 4 --musdb MUSDB_HQ_PATH --is_wav [...]
+```
+
+### Custom wav dataset
+
+You can trained on a custom wav dataset using the following command.
+At the moment, you still need to pass the MusDB path for evaluation, and the model
+must use the standard sources (bass, drums, other, vocals). However, it should be relatively
+easy to fork the code to support different patterns.
+
+```bash
+python3 -m demucs -b 4 --wav PATH_TO_WAV_DATASET [...]
+```
+
+The folder `PATH_TO_WAV_DATASET` should contain two sub-directories : `train` and `valid`. Each of those
+should contain one folder per track. Each track folder must contain one file for each source (`drums.wav`, `bass.wav`, `other.wav`, `vocals.wav`) and one file for the mixture (`mixture.wav`).
+
+By default, the custom wav dataset will replace MusDB. To concatenate it with MusDB, pass `--concat` (if you are using musdbhq, dont forget to pass `--is_wav`).
+
+### Fine tuning
+
+You can fine tune from one of the pre-trained models listed in the [Separating tracks Section](#separating-tracks)
+by passing the `--init=PRETRAINED_NAME`, i.e. for Demucs or ConvTasnet:
+
+```bash
+python3 -m demucs -b 4  --musdb MUSDB_PATH --init demucs # Demucs
+python3 -m demucs -b 4  --musdb MUSDB_PATH --tasnet --samples=80000 --split_valid --init tasnet # Conv-Tasnet
+```
+
+### About checkpointing
+
+Demucs will automatically generate an experiment name from the command line flags you provided.
+It will checkpoint after every epoch. If a checkpoint already exist for the combination of flags
+you provided, it will be automatically used. In order to ignore/delete a previous checkpoint,
+run with the `-R` flag.
+The optimizer state, the latest model and the best model on valid are stored. At the end of each
+epoch, the checkpoint will erase the one from the previous epoch.
+By default, checkpoints are stored in the `./checkpoints` folder. This can be changed using the
+`--checkpoints CHECKPOINT_FOLDER` flag.
+
+Not all options will impact the name of the experiment. For instance `--workers` is not
+shown in the name, therefore, changing this parameter will not impact the checkpoint file
+used. Refer to [parser.py](demucs/parser.py) for more details.
+
+
+### Test set evaluations
+
+Test set evaluations computed with [museval][museval] will be stored under
+`evals/EXPERIMENT NAME/results`. The experiment name
+is the first thing printed when running `python3 run.py`  or `python3 -m demucs`. If you used
+the flag `--save`, there will also be a folder `evals/EXPERIMENT NAME/wavs` containing
+all the extracted waveforms.
+
+
+#### Running on a cluster
+
+If you have a cluster available with Slurm, you can set the `run_slurm.py` as the target of a
+slurm job, using as many nodes as you want and a single task per node. `run_slurm.py` will
+create one process per GPU and run in a distributed manner. Multinode training is supported.
+
+### Extracting Raw audio for faster loading
+
+We observed that loading from compressed mp4 audio lead to unreliable speed, sometimes reducing by
+a factor of 2 the number of iterations per second. It is possible to extract all data
+to raw PCM f32e format. If you wish to store the raw data under `RAW_PATH`, run the following
+command first:
+
+```bash
+python3 -m demucs.raw [--workers=10] MUSDB_PATH RAW_PATH
+```
+
+You can then train using the `--raw RAW_PATH` flag, for instance:
+```bash
+python3 run.py --raw RAW_PATH --musdb MUSDB_PATH
+```
+You still need to provide the path to the MusDB dataset as we always load the test set
+from the original MusDB.
+
+
+### Results reproduction
+To reproduce the performance of the main Demucs model in our paper:
+```bash
+# Extract raw waveforms. This is optional
+python3 -m demucs.data MUSDB_PATH RAW_PATH
+export DEMUCS_RAW=RAW_PATH
+# Train models with default parameters and multiple seeds
+python3 run.py --seed 42 # for Demucs
+python3 run.py --seed 42 --tasnet --X=10 --samples=80000 --epochs=180 --split_valid # for Conv-Tasnet
+# Repeat for --seed = 43, 44, 45 and 46
+```
+
+You can visualize the results aggregated on multiple seeds using
+```bash
+python3 valid_table.py # compare validation losses
+python3 result_table.py # compare test SDR
+python3 result_table.py SIR # compare test SIR, also available ISR, and SAR
+```
+
+You can look at our exploration file [dora.py](dora.py) to see the exact flags
+for all experiments (grid search and ablation study). If you have a Slurm cluster,
+you can also try adapting it to run on your own.
+
+
+### Environment variables
+
+If you do not want to always specify the path to MUSDB, you can export the following variables:
+```bash
+export DEMUCS_MUSDB=PATH TO MUSDB
+# Optionally, if you extracted raw pcm data
+# export DEMUCS_RAW=PATH TO RAW PCM
+```
+
+## How to cite
+
+```
+@article{defossez2019music,
+  title={Music Source Separation in the Waveform Domain},
+  author={D{\'e}fossez, Alexandre and Usunier, Nicolas and Bottou, L{\'e}on and Bach, Francis},
+  journal={arXiv preprint arXiv:1911.13254},
+  year={2019}
+}
+```
+
+## License
+
+Demucs is released under the MIT license as found in the [LICENSE](LICENSE) file.
+
+The file `demucs/tasnet.py` is adapted from the [kaituoxu/Conv-TasNet][tasnet] repository.
+It was originally released under the MIT License updated to support multiple audio channels.
+
+
+[nsynth]: https://magenta.tensorflow.org/datasets/nsynth
+[sing_nips]: https://research.fb.com/publications/sing-symbol-to-instrument-neural-generator
+[sing]: https://github.com/facebookresearch/SING
+[waveunet]: https://github.com/f90/Wave-U-Net
+[musdb]: https://sigsep.github.io/datasets/musdb.html
+[museval]: https://github.com/sigsep/sigsep-mus-eval/
+[openunmix]: https://github.com/sigsep/open-unmix-pytorch
+[mmdenselstm]: https://arxiv.org/abs/1805.02410
+[demucs_arxiv]: https://hal.archives-ouvertes.fr/hal-02379796/document
+[musevalpth]: museval_torch.py
+[tasnet]: https://github.com/kaituoxu/Conv-TasNet
+[audio]: https://ai.honu.io/papers/demucs/index.html
+[spleeter]: https://github.com/deezer/spleeter
+[soundcloud]: https://soundcloud.com/voyageri/sets/source-separation-in-the-waveform-domain
+[original_demucs]: https://github.com/facebookresearch/demucs/tree/dcee007a350467abc3295dfe267034460f9ffa4e
+[diffq]: https://github.com/facebookresearch/diffq
+[d3net]: https://arxiv.org/abs/2010.01733

baselines/IRM2/test/AM Contra - Heart Peripheral.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a1e79ff415009526e480beba3666e14b163fe33c23dab4040e2077e25c61bbe
+size 26828

baselines/IRM2/test/Al James - Schoolboy Facination.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8caae5351b7dd0bc7fce2ee4cc915e291ed4636709dfbaf19962aee0f0a618ab
+size 24865

baselines/IRM2/test/Angels In Amplifiers - I'm Alright.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed9d8a341ceb370fa8e8b7cc6f336def7efa00941edac1cb834f573fd5c82253
+size 23052

baselines/IRM2/test/Arise - Run Run Run.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9066cfe82dc69614fae9338dcfdef5a65f7e2ebdb7dadadb6d27df321d6c3005
+size 25900

baselines/IRM2/test/BKS - Bulldozer.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9a54943bbd84ca3474a1bf2985d5c34796b1eebe8291f9d84807b1b81695cf24
+size 42911

baselines/IRM2/test/BKS - Too Much.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:57c5c90e3cbb955ce0210cc6d5aaad3af84ff23493aea10e6c30f189fc364c87
+size 21123

baselines/IRM2/test/Ben Carrigan - We'll Talk About It All Tonight.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed5db465dd93085a257b3044c55c2381ffd60845067ed47f0d6ad6d9b1061d10
+size 20579

baselines/IRM2/test/Bobby Nobody - Stitch Up.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:74f77a2bf52249b78c23a9be577de79d9168d95cf00fb3a674468ec35342f5ba
+size 23353

baselines/IRM2/test/Buitraker - Revo X.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:feee80b8fa70d36eb2ef8a7de45c087db7cec4b6b0145218d14a4be99ed9f785
+size 28203

baselines/IRM2/test/Carlos Gonzalez - A Place For Us.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3aaadf03103b92715015653ec7d5af59db586dc8d45c4ced2b2ef5e4db4f8e83
+size 31961

baselines/IRM2/test/Cristina Vane - So Easy.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8470eebddeb221bf2702c162cc7f19c2d5e7f8eb14d6520ad1e060165c7773b6
+size 28275

baselines/IRM2/test/Detsky Sad - Walkie Talkie.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bf8778f15c4ad7bb3fa30428ca2d780be40b22f3268227d01e5ae803afda180c
+size 11024

baselines/IRM2/test/Enda Reilly - Cur An Long Ag Seol.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:14e7d069a2840224a8876fdc7f328ca52a865e6540a2939c3c2aef0ccd6fe7df
+size 21139

baselines/IRM2/test/Forkupines - Semantics.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ba47a499b526cde808fbb10ca2858886c4606f1bccee921ae54721091573a80f
+size 21237

baselines/IRM2/test/Georgia Wonder - Siren.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cca85c851447e94539bfdefe0b00a6fcb4746e34197058b2dc8b4feb46b193a1
+size 36791

baselines/IRM2/test/Girls Under Glass - We Feel Alright.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9a7e24e0628f44ee1cc774e2c454ac4cea0a9c63064348af6e33225505c2f1d2
+size 21935

baselines/IRM2/test/Hollow Ground - Ill Fate.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f37c5bc36becaed3d9649b36e6d68b8f4a86960b4103fcc2f5710fa772dae37
+size 12330

baselines/IRM2/test/James Elder & Mark M Thompson - The English Actor.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:09faaffbfd9825a3104c935ac27da722700c895f1c5c095b6f9570ed551a189a
+size 20687

baselines/IRM2/test/Juliet's Rescue - Heartbeats.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a5ec942c2019fabba64dbbcad131b7ac986f126d87fdb9ebbd3c8d139217d158
+size 27498

baselines/IRM2/test/Little Chicago's Finest - My Own.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fdaf06d216ad224f0c78ca9163f190311157718618e17e462bd781d1b36c3e25
+size 31610

baselines/IRM2/test/Louis Cressy Band - Good Time.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f7191c053ebc148d9ca86e6583cb0ecafaa773e4e0107a5d7c0915bab034c03e
+size 21264

baselines/IRM2/test/Lyndsey Ollard - Catching Up.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a54bda98c9b061c4c994b173df4b1c895de56475484cb29973e2a86c5133699b
+size 25709

baselines/IRM2/test/M.E.R.C. Music - Knockout.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e81ed157dec77de057bbb712ad78bf574305d8d2ef4d24e84f2a8ca69ce88ee
+size 26605

baselines/IRM2/test/Moosmusic - Big Dummy Shake.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:164e3f93976f698750757c21dd5c77e932c90b7f5cbccae6c44a976abc86ff86
+size 22563

baselines/IRM2/test/Motor Tapes - Shore.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1938098d0212e9afdff2a0371887b66842718fdca141ce9c017ceadc9e2ef822
+size 25089

baselines/IRM2/test/Mu - Too Bright.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68ca54ac8985fbad1c47137ced2e302831bb9c5b35ddb2c6c45ec4f8848ea3bf
+size 22522

baselines/IRM2/test/Nerve 9 - Pray For The Rain.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:829f8efcda9469b277961892dff22d4b569a3e57f7cc29bc773e686d9a23455b
+size 32881

baselines/IRM2/test/PR - Happy Daze.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0d41b2eb0aff25e1e1ba1e884a50257bfb1e87905bc396a2cd2cf6eda0f5e7d
+size 21052

baselines/IRM2/test/PR - Oh No.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cd6a60a64165c2f4f427f041c6955a18776858201afc293c9eb50f92b82369bf
+size 9804

baselines/IRM2/test/Punkdisco - Oral Hygiene.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4186d9e9b295ffc6ef41e39534d1109d19b0182cb92288b7a7abdca8afb1aaff
+size 19114

baselines/IRM2/test/Raft Monk - Tiring.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:535a886ce8cdf756f489fc36cf7d73298d09839e241121f5039046c96be1d20b
+size 23263

baselines/IRM2/test/Sambasevam Shanmugam - Kaathaadi.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:648a338396f76e002c61f3bd10323cebc155a7675e630ac6dbee8335fcdf2828
+size 23183

baselines/IRM2/test/Secretariat - Borderline.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ac1a105faf4ee9bb3ec09273d21aeadf5de7752cb0eb0ca292f673210d77bfd3
+size 27299

baselines/IRM2/test/Secretariat - Over The Top.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2e1a432abaa8b5e5bf6fdc6df892706e047dc5bd96e2e2da874dca5f14684441
+size 21642

baselines/IRM2/test/Side Effects Project - Sing With Me.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:594dc701ab7ce759ff1006e8947688f1609e9bc87a18aba638b83432d9e2d32e
+size 28539

baselines/IRM2/test/Signe Jakobsen - What Have You Done To Me.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c9347bd26e385f06a0f7350534a7f205245765e6d3eb145922cdb4cf3de4f0f7
+size 22512

baselines/IRM2/test/Skelpolu - Resurrection.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:494b2d48e6d33b2167f542cc1b63c45377514f126245fd634d270f34495f8251
+size 14837

baselines/IRM2/test/Speak Softly - Broken Man.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8e049a84e184aed110458ca26ac929ddc79caef637dfa8decdcb4d438afb4232
+size 25457

baselines/IRM2/test/Speak Softly - Like Horses.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a29311792a22e9e15c970d8e9a84932e54ed969d0efc2dcd8ba188e409924a08
+size 27657

baselines/IRM2/test/The Doppler Shift - Atrophy.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3beaba378e7e0c92d1204fcd7712aeecc09c8ee63c3e56b45e9357d64ae426a1
+size 42460

baselines/IRM2/test/The Easton Ellises (Baumi) - SDRNR.json.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d6b5f83f1984d9440a4e5ceb5c68d80dc84d887861da24a9dc96017aa2a399f5
+size 29888