- An acoustic pattern generation tool

Copyright (c) Emmanouil Theofanis Chourdakis <> is a collection of tools to synthesize an audio scene from independent sound events.
It is inspired by Lagrange et al. simScene ( but takes
a different direction. The goal of is to (1) have a python implementation of such a
system since python is the platform of choice for developers accustomed with deep learning packages
or other python package candy and (2) to allow generating audio scenes from graph-based patterns.

Currently it can only batch-generate acoustic scenes with target EBRs

Please direct any comments, suggestions, etc. to Emmanouil Chourdakis <>

This code is licensed under GPLv3. Please see LICENSE for more info.


The best way to show usage of the tool is through an example of generating 10 scenes of bird sounds in the forest. First, clone the simscene repository (requires git):

git clone

Then switch to the python directory:

cd python

Install the necessary libraries

pip install -r requirements.txt

Then open the files forest_backgrounds.xls and forest_events.xls in the examples folder which contain information about the event and background tracks (for now do not change them, just see that you can open them). Note that you can view the same files as .txt files in the same directory. allows both formats.

Here is a preview of the forest_backgrounds.xls in Calc:

An explanation of the fields follows:
  • label - The name of the track
  • sampleid - Prefix of the filename the track uses. If there are many files with sampleid as their prefix, one as random is picked and used for generation.
  • snr - For the first row, it is just the amplitude of that track. For the second row and below, it is the SNR (not dB) of the track of that row, relative to the sum of the other tracks.

Backgrounds sounds are looped throughout the scene.

The events file (forest_events.xls) is a bit more complicated:

  • label and sampleid - same as above.
  • ebr - The desired Energy-to-background ratio relative to the sum of the background tracks.
  • ebr_stddev - How much the desired EBR can deviate (standard deviation).
  • mean_time_between_events - The mean time successive events of that type can occur. Note that it is the mean time between successive start_times unless that value is zero. In that case, the next events starts right after the previous events finishes.
  • time_between_events_stddev - The standard deviation of the starting times of successive events.
  • start_time - The starting time of the track. Note that this is different than the starting time of individual event sounds (in seconds).
  • end_time - The ending time of the track (in seconds).
  • fade_in_time/fade_out_time - Fade in and out times of individual sound events in seconds.

After viewing those files, we can generate an acoustic scene and generate some plots on the screen. First of all, create a directory to save the resulting files:

mkdir output

Then run

python example/sound/ output/ 10 -e example/forest_events.xls -b example/forest_backgrounds.xls -vvv

And it will show on screen some plots, and also generate some files in the output directory. Go on and listen to it! Some explanations:

  • example/sound/ is a directory containing event sounds in example/sound/event and background sounds in example/sound/background.
  • output/ is the files where generated plots and audio files reside.
  • 10 is the duration of the scene in seconds. In our case, 10 seconds.
  • -e is a switch pointing at the event file (see above).
  • -b is a switch pointing at the background file (see above).
  • -vvv Is the maximum verbosity level which will show piano roll, will shade over individual events and also plot them on screen.

It will generate plots like this one:

It can also generate 5 instances of the same scene at once with:

python example/sound/ output/ 10 -e example/forest_events.xls -b example/forest_backgrounds.xls -vv -N 5

Note that you cannot use -vvv when using the -N switch (it will be ignored). To see more on the available switches, run it with:

python -h

Starting 5th October, you can also create pattern files to use in place of .wav files for events or backrounds. For example you can have the following file in sound/event:

And add annother event in forest_events.xls with sampleid: _approaching to create a scene where a series of footsteps with increasing amplitude is heard.

Screenshot from 2017-10-03 19-07-11.png 141 KB, downloaded 38 times Emmanouil Theofanis Chourdakis, 2017-10-03 07:10 PM

forest_backgrounds.png 37.5 KB, downloaded 156 times Emmanouil Theofanis Chourdakis, 2017-10-04 07:27 PM

forest_events.png 57.8 KB, downloaded 152 times Emmanouil Theofanis Chourdakis, 2017-10-04 07:27 PM

scene.png 149 KB, downloaded 240 times Emmanouil Theofanis Chourdakis, 2017-10-04 07:54 PM

scene.wav 3.36 MB, downloaded 24 times Emmanouil Theofanis Chourdakis, 2017-10-04 08:05 PM

patterns.png 71.5 KB, downloaded 130 times Emmanouil Theofanis Chourdakis, 2017-10-05 03:10 PM