Package: openunmix
Open-Unmixfor PyTorchThis repository contains the PyTorch (1.8+) implementation ofOpen-Unmix, a deep neural network reference implementation for music source separation, applicable for researchers, audio engineers and artists.Open-Unmixprovides ready-to-use models that allow users to separate pop music into four stems:vocals,drums,bassand the remainingotherinstruments. The models were pre-trained on the freely availableMUSDB18dataset. See details atapply pre-trained model.⭐️ News03/07/2021: We addedumxl, a model that was trained on extra data which significantly improves the performance, especially generalization.14/02/2021: We released the new version of open-unmix as a python package. This comes with: a fully differentiable version ofnorbert, improved audio loading pipeline and large number of bug fixes. Seerelease notesfor further info.06/05/2020: We added a pre-trained speech enhancement modelumxseprovided by Sony.13/03/2020: Open-unmix was awarded 2nd place in thePyTorch Global Summer Hackathon 2020.Related Projects:open-unmix-pytorch |open-unmix-nnabla|musdb|museval|norbert🧠 The Model (for one source)To perform separation into multiple sources,Open-unmixcomprises multiple models that are trained for each particular target. While this makes the training less comfortable, it allows great flexibility to customize the training data for each target source.EachOpen-Unmixsource model is based on a three-layer bidirectional deep LSTM. The model learns to predict the magnitude spectrogram of a target source, likevocals, from the magnitude spectrogram of a mixture input. Internally, the prediction is obtained by applying a mask on the input. The model is optimized in the magnitude domain using mean squared error.Input StageOpen-Unmixoperates in the time-frequency domain to perform its prediction. The input of the model is either:models.Separator:A time domain signal tensor of shape(nb_samples, nb_channels, nb_timesteps), wherenb_samplesare the samples in a batch,nb_channelsis 1 or 2 for mono or stereo audio, respectively, andnb_timestepsis the number of audio samples in the recording. In this case, the model computes STFTs with eithertorchorasteroid_filterankson the fly.models.OpenUnmix:The core open-unmix takesmagnitude spectrogramsdirectly (e.g. when pre-computed and loaded from disk). In that case, the input is of shape(nb_frames, nb_samples, nb_channels, nb_bins), wherenb_framesandnb_binsare the time and frequency-dimensions of a Short-Time-Fourier-Transform.The input spectrogram isstandardizedusing the global mean and standard deviation for every frequency bin across all frames. Furthermore, we apply batch normalization in multiple stages of the model to make the training more robust against gain variation.Dimensionality reductionThe LSTM is not operating on the original input spectrogram resolution. Instead, in the first step after the normalization, the network learns to compresses the frequency and channel axis of the model to reduce redundancy and make the model converge faster.Bidirectional-LSTMThe core ofopen-unmixis a three layer bidirectionalLSTM network. Due to its recurrent nature, the model can be trained and evaluated on arbitrary length of audio signals. Since the model takes information from past and future simultaneously, the model cannot be used in an online/real-time manner.
An uni-directional model can easily be trained as describedhere.Output StageAfter applying the LSTM, the signal is decoded back to its original input dimensionality. In the last steps the output is multiplied with the input magnitude spectrogram, so that the models is asked to learn a mask.🤹‍♀️ Putting source models together: theSeparatormodels.Separatorputs togetherOpen-unmixspectrogram model for each desired target, and combines their output through a multichannel generalized Wiener filter, before application of inverse STFTs usingtorchaudio.
The filtering is differentiable (but parameter-free) version ofnorbert. The separator is currently currently only used during inference.🏁 Getting startedInstallationopenunmixcan be installed from pypi using:pip install openunmixNote, that the pypi version of openunmix uses [torchaudio] to load and save audio files. To increase the number of supported input and output file formats (such as STEMS export), please additionally installstempeg.Training is not part of the open-unmix package, please follow [docs/train.md] for more information.Using DockerWe also provide a docker container. Performing separation of a local track in~/Music/track1.wavcan be performed in a single line:docker run -v ~/Music/:/data -it faroit/open-unmix-pytorch "/data/track1.wav" --outdir /data/track1Pre-trained modelsWe provide three core pre-trained music separation models. All three models are end-to-end models that take waveform inputs and output the separated waveforms.umxl(default)trained on private stems dataset of compressed stems.Note, that the weights are only licensed for non-commercial use (CC BY-NC-SA 4.0).umxhqtrained onMUSDB18-HQwhich comprises the same tracks as in MUSDB18 but un-compressed which yield in a full bandwidth of 22050 Hz.umxis trained on the regularMUSDB18which is bandwidth limited to 16 kHz do to AAC compression. This model should be used for comparison with other (older) methods for evaluation inSiSEC18.Furthermore, we provide a model for speech enhancement trained bySony Corporationumxsespeech enhancement model is trained on the 28-speaker version of theVoicebank+DEMAND corpus.All four models are also available as spectrogram (core) models, which take magnitude spectrogram inputs and ouput separated spectrograms.
These models can be loaded usingumxl_spec,umxhq_spec,umx_specandumxse_spec.To separate audio files (wav,flac,ogg- but notmp3) files just run:umxinput_file.wavA more detailed list of the parameters used for the separation is given in theinference.mddocument.We provide ajupyter notebook on google colabto experiment with open-unmix and to separate files online without any installation setup.Using pre-trained models from within pythonWe implementes several ways to load pre-trained models and use them from within your python projects:When the package is installedLoading a pre-trained models is as simple as loadingseparator=openunmix.umxl(...)torch.hubWe also provide a torch.hub compatible modules that can be loaded. Note that this doesnoteven require to install the open-unmix packagen and should generally work when the pytorch version is the same.separator=torch.hub.load('sigsep/open-unmix-pytorch','umxl, device=device)Where,umxlspecifies the pre-trained model.Performing separationWith a created separator object, one can perform separation of someaudio(torch.Tensor of shape(channels, length), provided as at a sampling rateseparator.sample_rate) through:estimates=separator(audio,...)# returns estimates as tensorNote that this requires the audio to be in the right shape and sampling rate. For convenience we provide a pre-processing inopenunmix.utils.preprocess(..)` that takes numpy audio and converts it to be used for open-unmix.One-linerTo perform model loading, preprocessing and separation in one step, just use:fromopenunmiximportseparateestimates=separate.predict(audio,...)Load user-trained modelsWhen a path instead of a model-name is provided to--model, pre-trainedSeparatorwill be loaded from disk.
E.g. The following files are assumed to present when loading--model mymodel --targets vocalsmymodel/separator.jsonmymodel/vocals.pthmymodel/vocals.jsonNote that the separator usually joins multiple models for each target and performs separation using all models. E.g. if the separator containsvocalsanddrumsmodels, two output files are generated, unless the--residualoption is selected, in which case an additional source will be produced, containing an estimate of all that is not the targets in the mixtures.Evaluation usingmusevalTo perform evaluation in comparison to other SISEC systems, you would need to install themusevalpackage usingpip install musevaland then run the evaluation usingpython -m openunmix.evaluate --outdir /path/to/musdb/estimates --evaldir /path/to/museval/resultsResults compared to SiSEC 2018 (SDR/Vocals)Open-Unmix yields state-of-the-art results compared to participants fromSiSEC 2018. The performance ofUMXHQandUMXis almost identical since it was evaluated on compressed STEMS.Note that[STL1,TAK2,TAK3,TAU1,UHL3,UMXHQ] were omitted as they werenottrained on onlyMUSDB18.[HEL1,TAK1,UHL1,UHL2] are not open-source.Scores (Median of frames, Median of tracks)targetSDRSDRSDRmodelUMXUMXHQUMXLvocals6.326.257.21bass5.235.076.02drums5.736.047.15other4.024.284.89TrainingDetails on the training is provided in a separate documenthere.ExtensionsDetails on howopen-unmixcan be extended or improved for future research on music separation is described in a separate documenthere.Design Choiceswe favored simplicity over performance to promote clearness of the code. The rationale is to haveopen-unmixserve as abaselinefor future research while performance still meets current state-of-the-art (SeeEvaluation). The results are comparable/better to those ofUHL1/UHL2which obtained the best performance over all systems trained on MUSDB18 in theSiSEC 2018 Evaluation campaign.
We designed the code to allow researchers to reproduce existing results, quickly develop new architectures and add own user data for training and testing. We favored framework specifics implementations instead of having a monolithic repository with common code for all frameworks.How to contributeopen-unmixis a community focused project, we therefore encourage the community to submit bug-fixes and requests for technical support throughgithub issues. For more details of how to contribute, please follow ourCONTRIBUTING.md. For help and support, please use the gitter chat or the google groups forums.AuthorsFabian-Robert Stöter,Antoine Liutkus, Inria and LIRMM, Montpellier, FranceReferencesIf you use open-unmix for your research – Cite Open-Unmix@article{stoter19,  
  author={F.-R. St\\"oter and S. Uhlich and A. Liutkus and Y. Mitsufuji},  
  title={Open-Unmix - A Reference Implementation for Music Source Separation},  
  journal={Journal of Open Source Software},  
  year=2019,
  doi ={10.21105/joss.01667},
  url ={https://doi.org/10.21105/joss.01667}}If you use the MUSDB dataset for your research - Cite the MUSDB18 Dataset@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}}If compare your results with SiSEC 2018 Participants - Cite the SiSEC 2018 LVA/ICA Paper@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"}⚠️ Please note that the official acronym foropen-unmixisUMX.LicenseMITAcknowledgements