Sound Field Synthesis Toolbox for Python

Python implementation of the Sound Field Synthesis Toolbox.

Documentation:
http://sfs.rtfd.org/
Code:
http://github.com/sfstoolbox/sfs-python/
Python Package Index:
http://pypi.python.org/pypi/sfs/
License:
MIT – see the file LICENSE for details.

Requirements

Obviously, you’ll need Python. We normally use Python 3.x, but it should also work with Python 2.x. NumPy and SciPy are needed for the calculations. If you also want to plot the resulting sound fields, you’ll need matplotlib.

Instead of installing all of them separately, you should probably get a Python distribution that already includes everything, e.g. Anaconda.

Installation

Once you have installed the above-mentioned dependencies, you can use pip to download and install the latest release of the Sound Field Synthesis Toolbox with a single command:

pip install sfs --user

If you want to install it system-wide for all users (assuming you have the necessary rights), you can just drop the --user option.

To un-install, use:

pip uninstall sfs

How to Get Started

Various examples are located in the directory examples/

  • sound_field_synthesis.py:

    Illustrates the general usage of the toolbox

  • horizontal_plane_arrays.py:

    Computes the sound fields for various techniques, virtual sources and loudspeaker array configurations

  • soundfigures.py:

    Illustrates the synthesis of sound figures with Wave Field Synthesis

Contributing

If you find errors, omissions, inconsistencies or other things that need improvement, please create an issue or a pull request at http://github.com/sfstoolbox/sfs-python/. Contributions are always welcome!

Instead of pip-installing the latest release from PyPI, you should get the newest development version from Github:

git clone https://github.com/sfstoolbox/sfs-python.git
cd sfs-python
python setup.py develop --user

This way, your installation always stays up-to-date, even if you pull new changes from the Github repository.

If you prefer, you can also replace the last command with:

pip install --user -e .

... where -e stands for --editable.

If you make changes to the documentation, you can re-create the HTML pages using Sphinx. You can install it and a few other necessary packages with:

pip install -r doc/requirements.txt --user

To create the HTML pages, use:

python setup.py build_sphinx

The generated files will be available in the directory build/sphinx/html/.

New releases are made using the following steps:

  1. Bump version number in sfs/__init__.py
  2. Update NEWS.rst
  3. Commit those changes as “Release x.y.z”
  4. Create an (annotated) tag with git tag -a x.y.z
  5. Clear the dist/ directory
  6. Create a source distribution with python3 setup.py sdist
  7. Create a wheel distribution with python3 setup.py bdist_wheel --universal
  8. Check that both files have the correct content
  9. Upload them to PyPI with twine: twine upload dist/*
  10. Push the commit and the tag to Github and add release notes containing a link to PyPI and the bullet points from NEWS.rst
  11. Check that the new release was built correctly on RTD, delete the “stable” version and select the new release as default version

API Documentation

Loudspeaker Arrays

Tapering

Monochromatic Sources

Monochromatic Driving Functions

Monochromatic Sound Fields

Plotting

Utilities

Index

Index

Version History

Version 0.3.1 (2016-04-08): * Fixed metadata of release

Version 0.3.0 (2016-04-08): * Dirichlet Green’s function for the scattering of a line source at an edge * Driving functions for the synthesis of various virtual source types with edge-shaped arrays by the equivalent scattering appoach * Driving functions for the synthesis of focused sources by WFS * Several refactorings, bugfixes and other improvements

Version 0.2.0 (2015-12-11):
  • Ability to calculate and plot particle velocity and displacement fields
  • Several function name and parameter name changes
  • Several refactorings, bugfixes and other improvements
Version 0.1.1 (2015-10-08):
  • Fix missing sfs.mono subpackage in PyPI packages
Version 0.1.0 (2015-09-22):
Initial release.