/asteroid

The PyTorch-based audio source separation toolkit for researchers

Primary LanguagePythonMIT LicenseMIT

The PyTorch-based audio source separation toolkit for researchers.

PyPI Status Build Status codecov Code style: black Documentation Status Latest Docs Status

PRs Welcome Python Versions PyPI Status Slack


Asteroid is a Pytorch-based audio source separation toolkit that enables fast experimentation on common datasets. It comes with a source code that supports a large range of datasets and architectures, and a set of recipes to reproduce some important papers.

You use Asteroid or you want to?

Please, if you have found a bug, open an issue, if you solved it, open a pull request! Same goes for new features, tell us what you want or help us building it! Don't hesitate to join the slack and ask questions / suggest new features there as well! Asteroid is intended to be a community-based project so hop on and help us!

Contents

Installation

(↑up to contents) To install Asteroid, clone the repo and install it using conda, pip or python :

# First clone and enter the repo
git clone https://github.com/asteroid-team/asteroid
cd asteroid
  • With pip
# Install with pip in editable mode
pip install -e .
# Or, install with python in dev mode
# python setup.py develop
  • With conda (if you don't already have conda, see here.)
conda env create -f environment.yml
conda activate asteroid
  • Asteroid is also on PyPI, you can install the latest release with
pip install asteroid

Tutorials

(↑up to contents) Here is a list of notebooks showing example usage of Asteroid's features.

Running a recipe

(↑up to contents) Running the recipes requires additional packages in most cases, we recommend running :

# from asteroid/
pip install -r requirements.txt

Then choose the recipe you want to run and run it!

cd egs/wham/ConvTasNet
. ./run.sh

More information in egs/README.md.

Available recipes

(↑up to contents)

Supported datasets

(↑up to contents)

Pretrained models

(↑up to contents) See here

Contributing

(↑up to contents) We are always looking to expand our coverage of the source separation and speech enhancement research, the following is a list of things we're missing. You want to contribute? This is a great place to start!

Don't forget to read our contributing guidelines.

You can also open an issue or make a PR to add something we missed in this list.

TensorBoard visualization

The default logger is TensorBoard in all the recipes. From the recipe folder, you can run the following to visualize the logs of all your runs. You can also compare different systems on the same dataset by running a similar command from the dataset directiories.

# Launch tensorboard (default port is 6006)
tensorboard --logdir exp/ --port tf_port

If your launching tensorboard remotely, you should open an ssh tunnel

# Open port-forwarding connection. Add -Nf option not to open remote.
ssh -L local_port:localhost:tf_port user@ip

Then open http://localhost:local_port/. If both ports are the same, you can click on the tensorboard URL given on the remote, it's just more practical.

Guiding principles

(↑up to contents)

  • Modularity. Building blocks are thought and designed to be seamlessly plugged together. Filterbanks, encoders, maskers, decoders and losses are all common building blocks that can be combined in a flexible way to create new systems.
  • Extensibility. Extending Asteroid with new features is simple. Add a new filterbank, separator architecture, dataset or even recipe very easily.
  • Reproducibility. Recipes provide an easy way to reproduce results with data preparation, system design, training and evaluation in a single script. This is an essential tool for the community!

Citing Asteroid

(↑up to contents) If you loved using Asteroid and you want to cite us, use this :

@inproceedings{Pariente2020Asteroid,
    title={Asteroid: the {PyTorch}-based audio source separation toolkit for researchers},
    author={Manuel Pariente and Samuele Cornell and Joris Cosentino and Sunit Sivasankaran and
            Efthymios Tzinis and Jens Heitkaemper and Michel Olvera and Fabian-Robert Stöter and
            Mathieu Hu and Juan M. Martín-Doñas and David Ditter and Ariel Frank and Antoine Deleforge
            and Emmanuel Vincent},
    year={2020},
    booktitle={Proc. Interspeech},
}