gaojunchen / ambiscaper

Ambiscaper: a tool for automatic dataset generation and annotation of reverberant Ambisonics audio. Originally forked from http://github.com/justinsalamon/scaper

AmbiScaper

Ambiscaper: a tool for automatic dataset generation and annotation of reverberant Ambisonics audio

Please refer to the documentation for implementation details.

Originally forked from Scaper (commit e0cc1c9, 17th October 2017)

Motivation

Due to the recent developments on the field of immersive media and virtual reality, there has been a renewed interest into Ambisonics, specially motivated by its potential to capture the spacial qualities of the sound, and the methodologies to dynamically render it to binaural.

Despite the common approach to Ambisonics recordings as "ambiences", some modern Ambisonics microphones feature dozens of capsules. Therefore, it is possible to use such microphones as beamforming devices, with an accurate spatial resolution.

As a consequence, Ambisonics recordings might be useful in the auditory scene analysis field. More specifically, the intrinsic spatial audio representation can be exploited in the Sound Source Localization and Blind Source Separation fields.

However, there is an important lack of Ambisonics recordings databases, specially in the case of Higher Order Ambisonics. Annotation is also needed to design, train and evaluate the algorithms. The related works presented in last years have used custom databases, which hinder experiment reproducibility. A flexible reverberation configuration is as well needed for the state-of-the-art methods. Manual recording and annotation of sound scenes on that scale would imply an excessive amount of work.

We present AmbiScaper, a python library for procedural creation and annotation of reverberant Ambisonics databases. The software is based on a related work by Justin Salamon ( Scaper ) in the context of scene recognition.

Installation

Installing Scaper

To install the latest version of AmbiScaper from source, clone or pull the lastest version:

git clone https://github.com/andresperezlopez/ambiscaper.git

Then enter the source folder and install using pip to handle python dependencies:

cd ambiscaper
sudo pip install -e .

This procedure will automatically install the required python and non-python dependencies.

Pip online installer comming soon!

Non-python dependencies (manual installation)

AmbiScaper has two non-python dependencies:

• SoX: http://sox.sourceforge.net/
• FFmpeg: https://ffmpeg.org/

On macOS these can be installed using homebrew:

brew install sox
brew install ffmpeg

On linux you can use your distribution's package manager, e.g. on Ubuntu (15.04 "Vivid Vervet" or newer):

sudo apt-get install sox
sudo apt-get install ffmpeg

NOTE: on earlier versions of Ubuntu ffmpeg may point to a Libav binary which is not the correct binary. If you are using anaconda, you can install the correct version by calling conda install -c conda-forge ffmpeg. Otherwise, you can obtain a static binary from the ffmpeg website.

On windows you can use the provided installation binaries:

• SoX: https://sourceforge.net/projects/sox/files/sox/
• FFmpeg: https://ffmpeg.org/download.html#build-windows

Tutorial

To help you get started with scaper, please see this step-by-step tutorial.

Furthermore, we have prepared a bunch of reference examples.

Example

import ambiscaper
import numpy as np
import os

# AmbiScaper settings
soundscape_duration = 5.0
ambisonics_order = 1
foreground_folder = os.path.abspath('./samples/Acoustics_Book')

### Create an ambiscaper instance
ambiscaper = ambiscaper.AmbiScaper(duration=soundscape_duration,
                                   ambisonics_order=ambisonics_order,
                                   fg_path=foreground_folder)
                                   
### Add an event
ambiscaper.add_event(source_file=('choose', ['adult_female_speech.wav','bagpipe_music.wav']),
                     source_time=('const', 0),
                     event_time=('const', 0),
                     event_duration=('const', soundscape_duration),
                     event_azimuth=('uniform', 0, 2*np.pi),
                     event_elevation=('uniform', -np.pi/2, np.pi/2),
                     event_spread=('const', 0),
                     snr=('const', 0),
                     pitch_shift=('const', 1),
                     time_stretch=('const', 1))
                     
### Genereate the audio and the annotation
outfolder = '/Volumes/Dinge/ambiscaper/testing/' # watch out! outfolder must exist
destination_path = os.path.join(outfolder,"my_first_ambisonics_soundscape")

ambiscaper.generate(destination_path=destination_path,
                    generate_txt=True)

Example Dataset

An example dataset consisting of 100 first order reverberant Ambisonics soundscapes can be accessed here