SpatDIF

h1. IRCAM Spatialisateur

{{toc}}

h1. Summary

    * *Description:* The Spatialisateur project started in 1991 as a collaboration between Espaces Nouveaux and Ircam. Its goal is to propose a virtual acoustics processor which allows composers, performers or sound engineers to control the diffusion of sounds in a real or virtual space. This project stems from research carried out within the Ircam room acoustics laboratory on the objective and perceptive characterization of room acoustic quality. It also incorporates research done at Télécom Paris on digital signal processing algorithms for the spatialization and artificial reverberation of sounds. Spat~ is an effort to organize and optimize the experimental patches developped in the Spatialisateur project, in order to make them accessible to musicians and researchers who work with Max/MSP. The current release allows reproduction on multi-channel loudspeaker systems in studios or concert halls. It also integrates 3D stereo reproduction modes for headphones (binaural) or 2 loudspeakers (transaural), as well as Vector Based Amplitude Panning and Ambisonics.

    * *Manufacturer / Developer:* Ircam / Espaces Nouveaux

    * *Version:* 4.1.5

    * *Platform:* Spat 4 runs on Max/MSP version 5.0.0 or higher.

    * *OS:* Spat 4 is compatible with both Mac OS X (Universal Binary) and Windows XP/Vista.

    *  "Flux":http://www.fluxhome.com/products/plug_ins/ircam_spat has ported Spatialisateur to DAW environments

    * *License:* The use of Spatialisateur and its documentation is restricted to members of the "Ircam software users group":http://forumnet.ircam.fr/?L=1.

    * *Trademark:* Spatialisateur is an IRCAM registered trademarks.

    * *Patents:* The design of Spat and the reverberation module are protected under different French and international patents ([FR] 92 02528; [US] 5,491,754, [FR] 95 10111; [US] 5,812,674).	

    * *Status of this entry:* In progress

h1. Parameter definition

h2. Coordinate system convention

    * what is the underlying coordinate system?

    * any relation to the [[proposed coordinate systems]] ?

Spat 4 implements several coordinate systems, all defined from the listener’s point of view (i.e. the listener is the origin of the coordinate system). In Max/MSP these different coordinate systems are : 

    * xyz : 3D Cartesian coordinates

    * xy : 2D Cartesian coordinate within xy plane

    * ade : azimuth, distance, elevation

    * aed : azimuth, elevation, distance

    * ad : azimuth, distance (2D within xy plane)

    * az : azimuth only (distance = 1 m)

    * spat3 : azimuth, distance, elevation format for backward compatibility with Spat 3.x convention

Spat 4 external objects can interpret messages formatted in any of these coordinate formats. Furthermore utilities objects are provided to perform conversions between the different coordinate systems.

h3. Cartesian coordinates (xyz)

X axis on the right of the listener Y axis in front Z axis to the top

p=. !http://redmine.spatdif.org/attachments/89/spat.xyz.1.png!

_Top view (xy plane)_

p=. !http://redmine.spatdif.org/attachments/90/spat.xyz.2.png!

_Front view (xz plane)_

h3. Navigational coordinates (ade)

The default coordinate system in Spat 4 is called the navigational coordinate system. Positions are expressed in term of azimuth, elevation and distance (format “ade” in Max/MSP). Azimuth is measured toward the y axis, with 0° in front of the listener.

Elevation is 0° within xy plane. +90° on top, -90° bottom.

p=. !http://redmine.spatdif.org/attachments/91/spat.azimuth.png!

_Navigational coordinates: Azimuth convention_

p=. !http://redmine.spatdif.org/attachments/92/spat.elevation.png!

_Navigational coordinates: Elevation convention_

h3. Spat 3.x coordinate system (spat3)

p=. !http://redmine.spatdif.org/attachments/93/spat.spat3-backwards-compatibility.png!

_Spat 3.x coordinate system for backwards compatibility_

h2. Parameters configuring the system

|_. *parameter*  |_. *description*|_. *data format*|_. *range*|_. *initial state*|_. *unit*|_. *example*|_. *misc*|

|numsources      |number of sources                                 |int|1-64 |1|N/A|@numsources 5  |Declared as an attribute to the external @spat.spat~@. This attribute can not be dynamically reconfigured.| 

|numspeakers     |number of speakers                                |int|0-128|1|N/A|@numspeakers 8 |Declared as an attribute to the external @spat.spat~@. This attribute can not be dynamically reconfigured.|

|numreverbs      |number of shared reverbs                          |int|1-64 |1|N/A|@numreverbs 8  |Declared as an attribute to the external @spat.spat~@. This attribute can not be dynamically reconfigured.|

|numinternals    |number of internal feedback channels              |int|1-64 |1|N/A|@numinternals 8|Declared as an attribute to the external @spat.spat~@. This attribute can not be dynamically reconfigured.| 

|numcascades     |number of cascaded filters for output equalization|int|1-8  |1|N/A|@numcascades 5 |Declared as an attribute to the external @spat.spat~@. This attribute can not be dynamically reconfigured.|

|panning         |panning type (angular, binaural, xy, ms, ab, surround, panr, angular, vbap2d, vbap, dbap, bformat, hoa2d, hoa3d, null)|symbol|N/A|angular|N/A|@panning vbap|Declared as an attribute to the external @spat.spat~@. This attribute can not be dynamically reconfigured.|

| directsoundrerouting  | enable/disable direct sound rerouting (for wfs)  | int  | 0 .. 1 | 0|   |   |   |

| stereo  | stereo source as input  | int  | 0 .. 1 | 0|   |   |   |

h2. Parameter describing a sound source

|_. *parameter*     |_. *description*|_. *data format*|_. *range*|_. *initial state*|_. *unit*|_. *example*|_. *misc*|

| pres   | source presence [list of float]   | list   | 0 .. 120 | 90 |   |   |    |

| warmth  | source warmth [list of float]  | list  | 0 .. 60 | 30 |   |   |    |

| bril  | source brillance [list of float]  | list  | 0 .. 60 | 30 |   |   |    |

| prer  | room presence [list of float]  | list  | 0 .. 120 | 48 |   |   |    |

| revp  | running reverberance [list of float]  | list  | 0 .. 50 | 34 |   |   |    |

| env  | envelopment [list of float]  | list  | 0 .. 50 | 25 |   |   |    |

| pitch  | source pitch [list of float]  | list  | -90 .. 90 | 0 |   |   |    |

| sourcemute  | mute/unmute sources [list of int]  | list  | 0 .. 1 | 0 |   |   |    |

| sourcesolo  | enable/disable solo mode [list of int]  | list  | 0 .. 1 | 0 |   |   |    |

| sourceairabsorption  | enable/disable air absorption filtering [list of int]  | list  | 0 .. 1 | 1 |   |   |    |

| doppler  | enable/disable doppler effect [list of int]  | list  | 0 .. 1 | 1 |   |   |    |

| omni  | source omni filter parameters [list of float]  | list  |  |  |   |   |    |

| axis  | source axis filter paramaters [list of float]  | list  |  |  |   |   |    |

| reverbid  | index of reverb associated with source [list of int]  | list  |  |  |   |   |    |

| drop  | drop factor [list of float]  | list  | -10 .. 30 | 6 |   |   |    |

| dropmode  | drop mode [list of int] (0: log drop; 1:linear drop)  | list  | 0 .. 1 | 0 |   |   |    |

| pan_rev  | pan/rev factor [list of float]  | list  | 0 .. 1 | 0 |   |   |    |

| sourceinputgain  | source input gain [list of float]  | list  | -30 .. 10 | 0 |   |   |    |

| sourceoutputgain  | source output gain [list of float]  | list  | -30 .. 10 | 0 |   |   |    |

| source [index] [coordinates format] [list of coordinates]  | sets source positions  | anything  |  | |   |   |   |

| source [index] color [symbol]  | "sets source color (green, blue, red, yellow) " | anything  |  | |   |   |   |

| source [index] name [symbol]  | sets source name  | anything  |   |  |  |   |

| source [index] yaw [float]  | sets source yaw  | anything |   |   |   |   |   |

| source [index] aperture [float]  | sets source aperture  | anything |   |   |   |   |   |

| source [index] radius [float]  | sets source radius  | anything |   |   |   |   |   |

| source [index] pres [float]  | sets source presence  | anything |   |   |   |   |   |

| source [index] warmth [float]  | sets source warmth  | anything |   |   |   |   |   |

| source [index] bril [float]  | sets source brillance  | anything |   |   |   |   |   |

| source [index] prer [float]  | sets source room presence  | anything |   |   |   |   |   |

| source [index] revp [float]  | sets source running reverberance  | anything |   |   |   |   |   |

| source [index] env [float]  | sets source envelopment  | anything |   |   |   |   |   |

| source [index] pitch [float]  | sets source pitch  | anything |   |   |   |   |   |

| source [index] drop [float]  | sets source drop factor  | anything |   |   |   |   |   |

| source [index] dropmode [int]  | sets source drop mode (0: log drop; 1:linear drop)  | anything |   |   |   |   |   |

| source [index] pan_rev [float]  | sets source pan/rev factor  | anything |   |   |   |   |   |

| source [index] air [int]  | enable/disable air absorption filtering  | anything |   |   |   |   |   |

| source [index] doppler [int]  | enable/disable doppler effect  | anything |   |   |   |   |   |

| source [index] mute [int]  | mute/unmute sources  | anything |   |   |   |   |   |

| source [index] reverb [int]  | sets index of reverb associated with source  | anything |   |   |   |   |   |

| source [index] azim [float]        | sets azimuth and keep current elevation and distance unchanged |   |   |   |   |   |   |

| source [index] elev [float]        | sets elevation and keep current azimuth and distance unchanged |   |   |   |   |   |   |

| source [index] dist [float]        | sets distance and keep current azimuth and elevation unchanged |   |   |   |   |   |   |

| source [index] az [float]          | sets azimuth but use default elevation (0 deg) and distance (1m) |   |   |   |   |   |   |

| source [index] ae [float][float]   | sets azimuth and elevation but use default distance (1m) |   |   |   |   |   |   |

| source [index] ad [float][float]   | sets azimuth and distance but use default elevation (0 deg) |   |   |   |   |   |   |

| source [index] xy [float][float]   | sets x,y but use default z (0) |   |   |   |   |   |   |

| source [index] azim++ [float]      | increments azimuth and keep current elevation and distance unchanged |   |   |   |   |   |   |

| source [index] elev++ [float]      | increments elevation and keep current azimuth and distance unchanged |   |   |   |   |   |   |

| source [index] dist++ [float]      | increments distance and keep current elevation and azimuth unchanged |   |   |   |   |   |   |

| source [index] x++ [float]         | increments x and keep y and z unchanged |   |   |   |   |   |   |

| source [index] y++ [float]         | increments y and keep x and z unchanged |   |   |   |   |   |   |

| source [index] z++ [float]         | increments z and keep x and y unchanged |   |   |   |   |   |   |

h2. Parameter describing a virtual space

|_. *parameter*     |_. *description*|_. *data format*|_. *range*|_. *initial state*|_. *unit*|_. *example*|_. *misc*|

| reverberance  | room reverberance [list of float]  | list  | 0 .. 100 | 65 |   |   |    |

| heaviness  | room heaviness [list of float]  | list  | 0 .. 50 | 25 |   |   |    |

| liveness  | room liveness [list of float]  | list  | 0 .. 50 | 35 |   |   |    |

| early_start  | early start time [list of float]  | list  | 1 .. 120 | 20 |   |   |    |

| early_end  | early end time [list of float]  | list  | 1 .. 120 | 40 |   |   |    |

| early_distr  | early distribution centroid [list of float]  | list  | 0.1 .. 0.9 | 0.5 |   |   |    |

| early_shape  | early shape factor [list of float]  | list  | 0 .. 1 | 0.5 |   |   |    |

| early_width  | early width [list of float]  | list  | 10 .. 180 | 30 |   |   |    |

| cluster_start  | cluster start time [list of float]  | list  | 1 .. 300 | 40 |   |   |    |

| cluster_end  | cluster end time [list of float]  | list  | 1 .. 300 | 100 |   |   |    |

| cluster_distr  | cluster distribution centroid [list of float]  | list  | 0.1 .. 0.9 | 0.5 |   |   |    |

| reverb_start  | reverb start time [list of float]  | list  | 1 .. 500 | 95 |   |   |    |

| modaldensity  | reverb modal density [list of float]  | list  | 0.2 .. 2 | 0.9 |   |   |    |

| roomactive  | enable/disable reverb [list of int]  | list  | 0 .. 1 | 1 |   |   |    |

| roomairabsorption  | enable/disable air absorption in reverb [list of int]  | list  | 0 .. 1 | 1 |   |   |    |

| infinite  | enable/disable infinite reverb  | list  | 0 .. 1 | 0 |   |   |    |

| roomairrolloff  | air absorption filtering roll off frequency [list of float]  | list  | 20 .. 20000 | 10000 |   |   |    |

| roominputgain  | reverb input gain [list of float]  | list  | -30 .. 10 | 0 |   |   |    |

| roomoutputgain  | reverb output gain [list of float]  | list  | -30 .. 10 | 0 |   |   |   |

| room [index] reverberance [float]  | sets room reverberance  | anything |   |   |   |   |   |

| room [index] heaviness [float]  | sets room heaviness  | anything |   |   |   |   |   |

| room [index] liveness [float]  | sets room liveness  | anything |   |   |   |   |   |

| room [index] air [int]  | enable/disable air absorption filtering  | anything |   |   |   |   |   |

| room [index] active [int]  | enable/disable reverb  | anything |   |   |   |   |   |

| room [index] early start [float]  | sets early start time  | anything |   |   |   |   |   |

| room [index] early end [float]  | sets early end time  | anything |   |   |   |   |   |

| room [index] early distr [float]  | sets early distribution  | anything |   |   |   |   |   |

| room [index] early shape [float]  | sets early shape factor  | anything |   |   |   |   |   |

| room [index] early width [float]  | sets early width  | anything |   |   |   |   |   |

| room [index] cluster start [float]  | sets cluster start time  | anything |   |   |   |   |   |

| room [index] cluster end [float]  | sets cluster end time  | anything |   |   |   |   |   |

| room [index] cluster distr [float]  | sets cluster distribution  | anything |   |   |   |   |   |

| room [index] reverb start [float]  | sets reverb start time  | anything |   |   |   |   |   |

| room [index] reverb modaldensity [float]  | sets reverb modal density  | anything |   |   |   |   |   |

h2. Parameter describing the position of loudspeakers

|_. *parameter* |_. *description*|_. *data format*|_. *range*|_. *initial state*|_. *unit*|_. *example*|_. *misc*|

| speakers [coordinates format] [list of speakers coordinates]  | sets speakers positions  | anything  |  | |   |   |   |

| speaker [index] [coordinates format] [list of speakers coordinates]  | sets speaker position  | anything  |  | |   |   |   |

| speaker [index] name [symbol]  | sets speaker name  | anything |   |   |   |   |   |

h2. Parameter describing the post-processing of loudspeaker signals

|_. *parameter* |_. *description*|_. *data format*|_. *range*|_. *initial state*|_. *unit*|_. *example*|_. *misc*|

| delays   | output channel delays for time alignment [list of float]   | list   | 0 .. 100 | 0|   |   |   |

| outputfiltersfreq  | output channel equalizer cutoff/center frequency [list of float]  | list  | 50 .. 20000 | 1000|   |   |   |

| outputfiltersQ  | output channel equalizer resonance factor [list of float]  | list  | 0.5 .. 25 | 1|   |   |   |

| outputfiltersgain  | output channel equalizer gain [list of float]  | list  | -30 .. 30 | 0|   |   |   |

| outputfilterstype  | output channel equalizer filter type [list of symbol]  | list  |  | null |   |   |   |

| channel [index] delay [float]  | sets output channel delay  | anything |   |   |   |   |   |

| channel [index] cascade [index] freq [float]  | sets output channel equalizer cutoff/center frequency  | anything |   |   |   |   |   |

| channel [index] cascade [index] Q [float]  | sets output channel equalizer resonance factor  | anything |   |   |   |   |   |

| channel [index] cascade [index] gain [float]  | sets output channel equalizer gain  | anything |   |   |   |   |   |

| channel [index] cascade [index] type [symbol]  | sets output channel equalizer type  | anything |   |   |   |   |   |

h2. Other parameter

|_. *parameter* |_. *description*|_. *data format*|_. *range*|_. *initial state*|_. *unit*|_. *example*|_. *misc*|

| version   | prints object version in Max window   |  |  | |   |   |   |

| info  | prints infos (when available) in Max Window  |  |  | |   |   |   |

| hrtffile  | binaural filter set  | smybol  |  | |   |   |   |

| transauralfile  | transaural filter set  | symbol  |  | |   |   |   |

| clear  | clears internal buffers and filters memories |   |   |   |   |   |

| read [symbol]  | loads binaural filters from file  | anything |   |   |   |   |   |

| readtrans [symbol]  | loads transaural filters from file | anything |   |   |   |   |   |

h1. Projects, sound, and music

    * art or research projects utilizing this spatial renderer

h1. References

    * Bibliography

h1. External Links

    * http://forumnet.ircam.fr/692.html?&L=1

    * DAW plug-in version: http://www.fluxhome.com/products/plug_ins/ircam_spat

h1. Media

    * GUI screenshots

    * Example patches

    * things which might explain the listed content better

    * you can add files to a wiki page by clicking on "new file" at the bottom