TACOST: Test ACOustic Tracking

tacost allows you to test and characterise the accuracy of your acoustic tracking system. It allows you to create audio recordings to simulate sound emission from known points of your choice, and uncover the maximum expected accuracy of your acoustic tracking system.

If you’re reading this on PyPi - then see detailed documentation at: itsfm.rtfd.io

What TACOST does

  • Creates audio files which simulate sound arrival at each microphone in an array from user-specified points

  • Allows customisation of multiple parameters that may affect acoustic tracking accuracy

What TACOST does not do

  • Perform the actual acoustic tracking. You need to use a separate system (eg. Sound Finder, TOADSuite, Batalef, or the tracking system of your choice)

  • Simulate complex sound propagation (reflection, reverberation,etc). Sound is assumed to travel in straight line paths. In version 0.0.1 there’s no spherical spreading too!

Getting started

Creating an audio file to test your system is as simple as opening up your shell/command line and typing:

python -m tacost -run_example

The command above will generate a four channel WAV file with 500 kHz sampling rate based on the default array geometry and source positions. See the page on default array geometry and source position.

Installation

Update: tacost is currently on PyPi and so you can now pip install tacost!

However if you want the latest version, you can also use tacost with a local install. Head here https://github.com/thejasvibr/tacost and download the repo. From the downloaded repo open up a shell/prompt and type pip install ./ .

tacost without coding - the parameter file

STOP.!!!! ` - there are a couple of bugs with the parameter file mode to interact with `tacost. The audio file outputs don’t seem to work as expected. I will not be working on the bugs in the near future, but will update this page as soon as things are fixed. The Python package style of using tacost still remains stable and works as expected.

– last updated 18th August 2020

You can use tacost without any coding at all through the parameter file! All optional parameters can be fine tuned in the ‘parameter’ file. A parameter file is a YAML file. A YAML file basically looks and feels like a .txt file, except that it ends with .yml or .yaml. You can make your own parameters file in Windows by right-clicking and creating a new .txt file, and then changing the extension to .yml! In Unix systems you can do this with touch yourparamfile.yml.

A basic parameter file consists of the parameter to be specified and the entry in one row separated by a colon. If a certain parameter is not specified explicitly by the user, the default value is assumed. This can either save you a lot of work OR add a lot of agony - so please check the default values for each parameter to see if they make sense for your use case.

Using tacost

This is what an example parameter file would look like if you wanted the emitted sound to be a bird call (stored in a wav file), the final audio to have a sampling rate of 44.1kHz, and to generate the simulated sound arrival for your own microphone array. You also want to name this simulation run is called ‘birdsim’. This is what your parameter file would look like.

yourparameterfile.yml :

array_geometry : agm_yourcoolgeometry.csv
sample_rate    : 44100
source_sound   : bird_call.wav
sim_name       : bird_sim

Next, open up your Command Prompt (Windows) or Terminal (Unix) and feed the parameter file into tacost with the simple command below

python -m tacost -paramfile yourparameterfile.yml

And voila - you should get a wav file named bird_sim.wav that simulates sound sources as recorded by the mics in your cool array geometry. The sound simulated will the audio in the bird_call.wav file as played back from each of the positions. Here the default LMU position set is used because the source positions were not explicitly specified.

Attention

As of version 0.0.1 there is no spherical spreading or atmospheric absorption implemented in tacost. Only the time of arrivals are calculated. This means tacost is a tool for testing the inherent accuracy of your tracking system over different parts of space. Acoustic arrays are known to have non-homogenuous accuracies across a volume - and these can be characterised for your array configuration! tacost allows you to uncover the tracking accuracies under ‘best case’ scenarios, and not so much the real-world performance of your system.

You could of course implement a form of spherical spreading or atmospheric absorption by using a scaled version of the same source sound (see source sound). The better alternative is to interact with tacost through a script of course.

Array geometry

array_geometry : agm_yourownarraygeometry.csv

Attention : An array geometry file must contain at least 2 microphones with their x,y,z positions. The first row of the array geometry file must be named (eg.’x’, ‘y’ and ‘z’) with each microphone in a separate row.

Source positions

source_position : sourcepos_yourownsourcepositions.csv

Attention : An source position file must contain at least 1 position with its x,y,z positions. The first row of the source position file must be named (eg.’x’, ‘y’ and ‘z’) with each source position in a separate row.

Sampling rate

By default the sampling rate is set to 500 kHz (because, the package author works with ultrasound a lot). To set it to 44.1kHz for instance - add this in the parameter file.

sample_rate: 44100

Source sound

By default the sound assumed to be emitted is a linear frequency modulated chirp. You can provide your own sound in the form of a wav file. In the parameter file the entry would be

source_sound: example_sound.wav

Attention : The sampling rate of the input wav file must match the sampling rate of the output wav file! There is no explicit checking for a match between the default/user-set final sampling rate and the source sound’s sampling rate.

Inter-sound interval

Each simulated source position corresponds to a single sound in the multichannel audio file. The time gap between one sound to the next is the inter-sound interval. The default value is 100ms, and it can be specified in seconds so:

intersound_interval: 0.05

Here the inter sound interval has been set to 50ms.

Signal-to-Noise-Ratio

By default the signal-to-noise ratio of the emitted sound is assumed to be very high (>120dB). If you wish to set it to something else, then enter the SNR of your choice like so:

sound_snr: [30]

Here we’ve set the overall SNR to 30dB for all channels. Note : SNR values must be set inside a list (within square brackets). If all channels are to have the same SNR values, then one value in a list is enough.

If you’d like to define channel-specific SNR’s then specify unique values for each channel, eg:

sound_snr: [30, 20, 10,40]

API Reference

Module to make some simulated data testing the TOADsuite Created on Wed May 22 20:13:28 2019

@author: tbeleyur

tacost.simulate_LMU_playback_setup.assign_call_to_mic(audio_channel, call, t_arrivals, **kwargs)
tacost.simulate_LMU_playback_setup.create_audio_for_mic_arrival_times(t_arrivals, **kwargs)
Keyword Arguments

  • fs (float>0) – Sampling rate in Hz. Defaults to 500kHz.

  • background_noise (float.) – db rms of white noise. Defaults to -90 dB rms re 1.

  • call_SNR (tuple/list like.) – If a single entry is given, all channels will have the same call SNR. Otherwise, Nchannel entries are expected.

  • playback_sound (np.array, optional) – User’s own sound which needs to be incorporated into the playback. If not given, then the function uses make_bat_call

tacost.simulate_LMU_playback_setup.adjust_rms_to_reach_SNR(bat_call, SNR, empty_audio)
Parameters

  • bat_call (Nsamples np.array) –

  • SNR (float or array/list like.) – If a single entry is given, then only the

  • empty_audio (Msamples np.array) – Single channel audio without the bat calls in them - the ‘noise’

Returns

adjusted_bat_calls – Contains the rms adjusted versions fo the input bat call for each channel.

Return type

array/list like.

tacost.simulate_LMU_playback_setup.simulate_audio_for_LMU_experiment(**kwargs)
Keyword Arguments

points (Npoints x 3 np.array) – x,Y,Z coordinates of the emitted points