README.md

AUDIOMATE

Audiomate is a library for easy access to audio datasets. It provides the datastructures for accessing/loading different datasets in a generic way. This should ease the use of audio datasets for example for machine learning tasks.

import audiomate
from audiomate.corpus import io

# Download a dataset
esc_downloader = io.ESC50Downloader()
esc_downloader.download('/local/path')

# Load and work with the dataset
esc50 = audiomate.Corpus.load('/local/path', reader='esc-50')

# e.g. Read the audio signal and the label of specific sample/utterance
utterance = esc50.utterances['1-100032-A-0']
samples = utterance.read_samples()
label_list = utterance.label_lists[audiomate.corpus.LL_SOUND_CLASS]

for label in label_list:
  print(label.start, label.value)

Furthermore it provides tools for interacting with datasets (validation, splitting, subsets, merge, filter), extracting features, feeding samples for training ML models and more.

• Documentation
• Examples
• Changelog

Currently supported datasets:

• Acoustic Event Dataset
• AudioMNIST
• Mozilla Common Voice
• ESC-50
• Fluent Speech Commands
• Free Spoken Digit Dataset
• German Distant Speech Corpus
• Google Speech Commands
• GTZAN
• LibriSpeech
• M-AILABS Speech Dataset
• MUSAN
• LITIS Rouen Audio scene dataset
• Spoken Wikipedia Corpora
• Tatoeba
• TIMIT
• Urbansound8k
• Voxforge

Currently supported formats:

• Kaldi
• Mozilla DeepSpeech
• Wav2Letter
• NVIDIA Jasper
• Custom Formats

Installation

pip install audiomate

Install the latest development version:

pip install git+https://github.com/ynop/audiomate.git

Dependencies

sox

For parts of the functionality (e.g. audio format conversion) sox is used. In order to use it, you have to install sox.

# macos
brew install sox

# with support for specific formats
brew install sox --with-lame --with-flac --with-libvorbis

# linux
apt-get install sox

# anaconda for macOS/windows/linux:
conda install -c conda-forge sox

Development

Prerequisites

• A supported version of Python > 3.5

It's recommended to use a virtual environment when developing audiomate. To create one, execute the following command in the project's root directory:

python -m venv .

To install audiomate and all it's dependencies, execute:

pip install -e .

Running the test suite

pip install -e .[dev]
pytest

With PyCharm you might have to change the default test runner. Otherwise, it might only suggest to use nose. To do so, go to File > Settings > Tools > Python Integrated Tools (on the Mac it's PyCharm > Preferences > Settings > Tools > Python Integrated Tools) and change the test runner to py.test.

Benchmarks

In order to check the runtime of specific parts, pytest-benchmark is used. Benchmarks are normal test functions, but call the benchmark fixture for the code under test.

To run benchmarks:

# Run all
pytest bench

# Specific benchmark
pytest bench/corpus/test_merge_corpus.py

To compare between different runs:

pytest-benchmark compare

Editing the Documentation

The documentation is written in reStructuredText and transformed into various output formats with the help of Sphinx.

• Syntax reference reStructuredText
• Sphinx-specific additions to reStructuredText

To generate the documentation, execute:

pip install -e .[dev]
cd docs
make html

The generated files are written to docs/_build/html.

Versions

Versions is handled using bump2version. To bump the version:

bump2version [major,minor,patch,release,num]

In order to directly go to a final relase version (skip .dev/.rc/...):

bump2version [major,minor,patch] --new-version x.x.x

Release

Commands to create a new release on pypi.

rm -rf build
rm -rf dist

python setup.py sdist
python setup.py bdist_wheel
twine upload dist/*