Python renderer for SpatOSC
===========================

Pyospat is a Python audio renderer for SpatOSC.

See http://code.sat.qc.ca/trac/spatosc for more information.

Update on 2016-02-24:

This is just a maintenance release to get this software out there for the sake of some sort of completeness. This software is basically abandonware at this point. It has, however, been used in two substantial sound installations:

- Re-Collect, by Jane Tingley and Michal Seta (http://janetingley.com/re-collect/), recipient of the First Prize at the iNTERFACES Interactive Art Competition (http://artes.ucp.pt/interfaces/index_en.html) ex-aequo with Distance by Li Zheng (China)

- OKTA project by Fieldsound duo (Steve Bates and Douglas Moffat) - http://oktaproject.ca/

There are no other projects planned and the developers do not really have the desire to pursue this project. Michal Seta is now involved with another sound spacialisation system called SATIE (https://github.com/nicobou/satie)


License
=======

Free/libre open source software under the GPL license.

Pyospat
Copyright (C) 2011 Alexandre Quessy
Copyright (C) 2011 Michal Seta

This file is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

Pyospat is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Pyospat.  If not, see <http://www.gnu.org/licenses/>.


Installation
============

Dependencies:

* libspatosc-0.6-dev
* python-pyo
* python-setuptools
* python-twisted-core
* python-txosc

To build and install pyo::

  $ sudo apt-get install libportmidi-dev portaudio19-dev liblo-dev libsndfile-dev python-dev python-tk subversion python-imaging-tk python-wxgtk2.8
  $ svn checkout http://pyo.googlecode.com/svn/trunk/ pyo-read-only
  $ cd pyo-read-only
  $ python setup.py build
  $ sudo python setup.py install

How to install::

  $ python setup.py build
  $ sudo python setup.py install
  $ cp dot_pyorc.xml ~/.pyorc


Developers
==========

How to use your Git repository as system-wide pyospat::

  $ python setup.py build
  $ sudo python setup.py develop

How to use a .pyorc fot file::

  $ cp dot_pyorc.xml ~/.pyorc
  $ python
  >>> from pyospat import server 
  >>> s = server.ServerWrapper()
  >>> s.run()

How to run the unit tests::

  $ trial pyospat

How to build the documentation::

  $ sudo apt-get install python-epydoc
  $ ./utils/build-doc

How to make an HTML page out of this README file::

  $ sudo apt-get install rst2html
  $ rst2html README > readme.html


Versioning
==========

This project uses the common "Linux kernel" versioning system, where even-numbered minor versions are stable and odd-numbered minor versions are development snapshots.

The micro version indicates the origin of the release: even micro numbers are only used for released archives; odd micro numbers are only used on the Git repository.

A stable series means that the command-line options and the interactive keyboard controls should not change much for all tags whose version number start with the same major-minor numbers. Some new features might be developped in that branch, but each release should be backward-compatible with their ancestor. Releases from a stable series should be use for production. 

In contrast, unstable branches consist of tags which are developer snapshots. They are not expected to be compatible with any other version. Some features might change between different stable branches.


How it works
============

Pyospat is an application that listens to OSC messages from SpatOSC. It dynamically creates Pyo objects and connects them together to make you hear stuff. It can be configured with an XML file in which you define how are configured your audio speakers, as well as how many audio inputs your system has and which driver to use, etc. It can play sound files as well as plugin generators and live input channels.

Use string properties when it's specific for a single renderer. 

Every sound sources should have a media URI.

Things that should be configurable in the XML file:

* loudspeakers configuration


How to compute audio
====================
It's done in a two-step process:

1) distance from listener: (meter)

* low-pass filter
* variable delay
* attenuation gain (configurable)

2) azimuth/elevation: (angle)

* two panners