#type: node
#context: chop
#internal: spatial
#icon: CHOP/spatial

= Spatial Audio =

"""The rendering engine for producing 3D audio."""

The Spatial Audio CHOP is the rendering engine for producing 3D audio. It
uses the Sound and Microphone objects to define positional sources and
microphones, Geometry objects to define obstructions and [Acoustic CHOPs|acoustic]
to define sound materials and audio filters.

The first input is an optional lookup table for the volume dropoff over
distance. This is required if the __Distance Volume Loss__ parameter is set
to __Distance/Volume Lookup Table__. The second input is an optional
'Environment Filter' which describes how the environment affects the
frequencies of sound traveling through it (used with the __Distance Volume
Loss__ parameter).


@parameters

    == Environment ==

        Microphones:
            Specifies the microphone objects to use. One channel is
            created per microphone.
        Sound Sources:
            Specifies the sound objects to use.
        Meters Per Unit:
            #channels: /meterperunit

            Length of 1 world unit, in meters.
        Speed of Sound:
            #channels: /soundvel

            The speed of sound of the environment, in meters per second
            (default speed is for air).

    == Effects ==

        Enable Distance Delay:
            Enables delays over long distances, as well as the doppler
            effect (realistic if on).
        Distance Volume Loss:
            Method for calculating volume loss over distance.

            None:
                Distance does not diminish sound.
            Realistic Distance Dropoff:
                Natural volume dropoff `(1/d^2)`.
            Distance/Volume Lookup Table:
                Determine from the lookup table connected to the first
                input.
        10m Volume Loss:
            #channels: /volloss

            How much volume is decreased after traveling 10 meters
            (.4=40% decrease).
        Volume Lookup Range:
            #channels: /vollookup1-2

            The range of the distance lookup table; (10,100) means that
            the table describes how the volume behaves from 10-100
            meters.
        Use Microphone Filters:
            Enables or disables all microphone filters.
        Check For Obstacles:
            Turns on the algorithm for obstacle occlusion.
        Obstacles:
            Add geometry objects as an obstacles. The sound material for
            these object must be defined. The geometry detail should be
            low.
        Collision Detection:
            Specifies the collision detection algorithm.

            Object Bounding Box:
                Uses the bounding box of the entire object as the
                collision object (very fast).
            Primitive Bounding Box:
                Uses a bounding box per primitive. Good for objects that
                consist of separate geometries.
            Object Geometry:
                Uses the actual geometry as the collision object
                (slowest & most accurate).
        Obstacle Softness:
            #channels: /obstsoft

            If an object is between a microphone and a sound source,
            this parameter determines how abruptly the cutoff is (0 =
            abrupt, 1 = smooth).

    == Echo ==

        Echo Method:
            Computes static or dynamic environmental echoes.
        Number of Echoes:
            #channels: /numecho

            The number of echoes to compute.
        Echo Delay:
            #channels: /echodelay

            The time between echoes.
        Echo Volume:
            #channels: /echovol

            Adjusts the volume of all echoes.
        Dynamic Echo Effect:
            #channels: /dyneffect

            Percentage longer that echoes take to arrive than the
            initial sound (.5 = 50% longer)

    == Channel ==

        Compute Full Animation Range:
            #channels: /start /end

            Compute using the full animation range, otherwise use the
            start/end parameters.
        Preroll:
            #channels: /preroll

            The amount computed before the start of the interval.
        Object Sample Rate:
            #channels: /objsample

            The rate that object are sampled at.
        Audio Sample Rate:
            #channels: /audiosample

            The sample rate of the audio produced.

@related
    - [Node:chop/acoustic]
    - [Node:obj/sound]
    - [Node:obj/microphone]