Skip to content

Commit

Permalink
Fix various issues with the descriptions for the spatial audio plugin
Browse files Browse the repository at this point in the history
  • Loading branch information
@goldfire
goldfire committed Aug 18, 2017
1 parent 09e9653 commit cc2b681
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 36 deletions.
30 changes: 15 additions & 15 deletions README.md
View file
Expand Up @@ -327,11 +327,11 @@ Unload and destroy all currently loaded Howl objects. This will immediately stop

### Options
#### orientation `Array` `[1, 0, 0]`
Sets the direction the audio source is pointing in the 3D cartesian coordinate space. Depending on how direction the sound is, based on the `cone` attributes, a sound pointing away from the listener can be quiet or silent.
Sets the direction the audio source is pointing in the 3D cartesian coordinate space. Depending on how directional the sound is, based on the `cone` attributes, a sound pointing away from the listener can be quiet or silent.
#### stereo `Number` `null`
Sets the stereo panning value of the audio source for this sound or group. This makes it easy to setup left/right panning with a value of `-1.0` being far left and a value of `1.0` being far right.
#### pos `Array` `null`
Sets the 3D spatial position of the audio source for this sound or group. Setting any value higher than `1.0` will begin to decrease the volume of the sound as it moves further away.
Sets the 3D spatial position of the audio source for this sound or group relative to the global listener.
#### pannerAttr `Object`
Sets the panner node's attributes for a sound or group of sounds. See the `pannerAttr` method for all available options.
#### onstereo `Function`
Expand All @@ -349,30 +349,30 @@ Get/set the stereo panning of the audio source for this sound or all in the grou
* **id**: `Number` `optional` The sound ID. If none is passed, all in group will be updated.

#### pos(x, y, z, [id])
Get/set the 3D spatial position of the audio source for this sound or group. Setting any value higher than `1.0` will begin to decrease the volume of the sound as it moves further away.
* **x**: `Number` The x-position of the audio from `-1000.0` to `1000.0`.
* **y**: `Number` The y-position of the audio from `-1000.0` to `1000.0`.
* **z**: `Number` The z-position of the audio from `-1000.0` to `1000.0`.
Get/set the 3D spatial position of the audio source for this sound or group relative to the global listener.
* **x**: `Number` The x-position of the audio source.
* **y**: `Number` The y-position of the audio source.
* **z**: `Number` The z-position of the audio source.
* **id**: `Number` `optional` The sound ID. If none is passed, all in group will be updated.

#### orientation(x, y, z, [id])
Get/set the direction the audio source is pointing in the 3D cartesian coordinate space. Depending on the direction of the sound, based on the `cone` attributes, a sound pointing away from the listener can be quiet or silent.
Get/set the direction the audio source is pointing in the 3D cartesian coordinate space. Depending on how directional the sound is, based on the `cone` attributes, a sound pointing away from the listener can be quiet or silent.
* **x**: `Number` The x-orientation of the source.
* **y**: `Number` The y-orientation of the source.
* **z**: `Number` The z-orientation of the source.
* **id**: `Number` `optional` The sound ID. If none is passed, all in group will be updated.

#### pannerAttr(o, [id])
Get/set the panner node's attributes for a sound or group of sounds. This method can optionall take 0, 1 or 2 arguments.
Get/set the panner node's attributes for a sound or group of sounds.
* **o**: `Object` All values to update.
* **coneInnerAngle** `360` There will be no volume reduction inside this angle.
* **coneOuterAngle** `360` The volume will be reduced to a constant value of `coneOuterGain` outside this angle.
* **coneOuterGain** `0` The amount of volume reduction outside of `coneOuterAngle`.
* **distanceModel** `inverse` Determines algorithm to use to reduce volume as audio moves away from listener. Can be `linear`, `inverse` or `exponential.
* **maxDistance** `10000` Volume won't reduce between source/listener beyond this distance.
* **coneInnerAngle** `360` A parameter for directional audio sources, this is an angle, in degrees, inside of which there will be no volume reduction.
* **coneOuterAngle** `360` A parameter for directional audio sources, this is an angle, in degrees, outside of which the volume will be reduced to a constant value of `coneOuterGain`.
* **coneOuterGain** `0` A parameter for directional audio sources, this is the gain outside of the `coneOuterAngle`. It is a linear value in the range `[0, 1]`.
* **distanceModel** `inverse` Determines algorithm used to reduce volume as audio moves away from listener. Can be `linear`, `inverse` or `exponential. You can find the implementations of each in the [spec](https://webaudio.github.io/web-audio-api/#idl-def-DistanceModelType).
* **maxDistance** `10000` The maximum distance between source and listener, after which the volume will not be reduced any further.
* **refDistance** `1` A reference distance for reducing volume as source moves further from the listener. This is simply a variable of the distance model and has a different effect depending on which model is used and the scale of your coordinates. Generally, volume will be equal to 1 at this distance.
* **rolloffFactor** `1` How quickly the volume reduces as source moves from listener. This is simply a variable of the distance model and can be in the range of `[0, 1]` with `linear` and `[0, ∞]` with `inverse` and `exponential`.
* **panningModel** `HRTF` Determines which spatialization algorithm is used to position audio. Can be `HRTF` or `equalpower`.
* **refDistance** `1` A reference distance for reducing volume as the source moves away from the listener.
* **rolloffFactor** `1` How quickly the volume reduces as source moves from listener.
* **id**: `Number` `optional` The sound ID. If none is passed, all in group will be updated.


Expand Down
45 changes: 24 additions & 21 deletions src/plugins/howler.spatial.js
View file
Expand Up @@ -228,13 +228,10 @@
};

/**
* Get/set the 3D spatial position of the audio source for this sound or
* all in the group. The most common usage is to set the 'x' position for
* left/right panning. Setting any value higher than 1.0 will begin to
* decrease the volume of the sound as it moves further away.
* @param {Number} x The x-position of the audio from -1000.0 to 1000.0.
* @param {Number} y The y-position of the audio from -1000.0 to 1000.0.
* @param {Number} z The z-position of the audio from -1000.0 to 1000.0.
* Get/set the 3D spatial position of the audio source for this sound or group relative to the global listener.
* @param {Number} x The x-position of the audio source.
* @param {Number} y The y-position of the audio source.
* @param {Number} z The z-position of the audio source.
* @param {Number} id (optional) The sound ID. If none is passed, all in group will be updated.
* @return {Howl/Array} Returns self or the current 3D spatial position: [x, y, z].
*/
Expand Down Expand Up @@ -388,18 +385,24 @@
* pannerAttr(o, id) -> Set's the values of passed sound id.
*
* Attributes:
* coneInnerAngle - (360 by default) There will be no volume reduction inside this angle.
* coneOuterAngle - (360 by default) The volume will be reduced to a constant value of
* `coneOuterGain` outside this angle.
* coneOuterGain - (0 by default) The amount of volume reduction outside of `coneOuterAngle`.
* distanceModel - ('inverse' by default) Determines algorithm to use to reduce volume as audio moves
* away from listener. Can be `linear`, `inverse` or `exponential`.
* maxDistance - (10000 by default) Volume won't reduce between source/listener beyond this distance.
* coneInnerAngle - (360 by default) A parameter for directional audio sources, this is an angle, in degrees,
* inside of which there will be no volume reduction.
* coneOuterAngle - (360 by default) A parameter for directional audio sources, this is an angle, in degrees,
* outside of which the volume will be reduced to a constant value of `coneOuterGain`.
* coneOuterGain - (0 by default) A parameter for directional audio sources, this is the gain outside of the
* `coneOuterAngle`. It is a linear value in the range `[0, 1]`.
* distanceModel - ('inverse' by default) Determines algorithm used to reduce volume as audio moves away from
* listener. Can be `linear`, `inverse` or `exponential.
* maxDistance - (10000 by default) The maximum distance between source and listener, after which the volume
* will not be reduced any further.
* refDistance - (1 by default) A reference distance for reducing volume as source moves further from the listener.
* This is simply a variable of the distance model and has a different effect depending on which model
* is used and the scale of your coordinates. Generally, volume will be equal to 1 at this distance.
* rolloffFactor - (1 by default) How quickly the volume reduces as source moves from listener. This is simply a
* variable of the distance model and can be in the range of `[0, 1]` with `linear` and `[0, ∞]`
* with `inverse` and `exponential`.
* panningModel - ('HRTF' by default) Determines which spatialization algorithm is used to position audio.
* Can be `HRTF` or `equalpower`.
* refDistance - (1 by default) A reference distance for reducing volume as the source
* moves away from the listener.
* rolloffFactor - (1 by default) How quickly the volume reduces as source moves from listener.
*
* @return {Howl/Object} Returns self or current panner attributes.
*/
Expand Down Expand Up @@ -429,9 +432,9 @@
coneOuterGain: typeof o.coneOuterGain !== 'undefined' ? o.coneOuterGain : self._coneOuterGain,
distanceModel: typeof o.distanceModel !== 'undefined' ? o.distanceModel : self._distanceModel,
maxDistance: typeof o.maxDistance !== 'undefined' ? o.maxDistance : self._maxDistance,
panningModel: typeof o.panningModel !== 'undefined' ? o.panningModel : self._panningModel,
refDistance: typeof o.refDistance !== 'undefined' ? o.refDistance : self._refDistance,
rolloffFactor: typeof o.rolloffFactor !== 'undefined' ? o.rolloffFactor : self._rolloffFactor
panningModel: typeof o.panningModel !== 'undefined' ? o.panningModel : self._panningModel,
};
}
} else {
Expand All @@ -458,9 +461,9 @@
coneOuterGain: typeof o.coneOuterGain !== 'undefined' ? o.coneOuterGain : pa.coneOuterGain,
distanceModel: typeof o.distanceModel !== 'undefined' ? o.distanceModel : pa.distanceModel,
maxDistance: typeof o.maxDistance !== 'undefined' ? o.maxDistance : pa.maxDistance,
panningModel: typeof o.panningModel !== 'undefined' ? o.panningModel : pa.panningModel,
refDistance: typeof o.refDistance !== 'undefined' ? o.refDistance : pa.refDistance,
rolloffFactor: typeof o.rolloffFactor !== 'undefined' ? o.rolloffFactor : pa.rolloffFactor
panningModel: typeof o.panningModel !== 'undefined' ? o.panningModel : pa.panningModel,
};

// Update the panner values or create a new panner if none exists.
Expand All @@ -471,9 +474,9 @@
panner.coneOuterGain = pa.coneOuterGain;
panner.distanceModel = pa.distanceModel;
panner.maxDistance = pa.maxDistance;
panner.panningModel = pa.panningModel;
panner.refDistance = pa.refDistance;
panner.rolloffFactor = pa.rolloffFactor;
panner.panningModel = pa.panningModel;
} else {
// Make sure we have a position to setup the node with.
if (!sound._pos) {
Expand Down Expand Up @@ -559,9 +562,9 @@
sound._panner.coneOuterGain = sound._pannerAttr.coneOuterGain;
sound._panner.distanceModel = sound._pannerAttr.distanceModel;
sound._panner.maxDistance = sound._pannerAttr.maxDistance;
sound._panner.panningModel = sound._pannerAttr.panningModel;
sound._panner.refDistance = sound._pannerAttr.refDistance;
sound._panner.rolloffFactor = sound._pannerAttr.rolloffFactor;
sound._panner.panningModel = sound._pannerAttr.panningModel;
sound._panner.setPosition(sound._pos[0], sound._pos[1], sound._pos[2]);
sound._panner.setOrientation(sound._orientation[0], sound._orientation[1], sound._orientation[2]);
} else {
Expand Down

0 comments on commit cc2b681

Please sign in to comment.