From cc2b681ca0a7ee0d14f1f18a83b77f18cd229853 Mon Sep 17 00:00:00 2001 From: James Simpson Date: Fri, 18 Aug 2017 16:10:12 -0500 Subject: [PATCH] Fix various issues with the descriptions for the spatial audio plugin --- README.md | 30 +++++++++++------------ src/plugins/howler.spatial.js | 45 +++++++++++++++++++---------------- 2 files changed, 39 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 4260c189..9d90603b 100644 --- a/README.md +++ b/README.md @@ -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` @@ -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. diff --git a/src/plugins/howler.spatial.js b/src/plugins/howler.spatial.js index 767a5990..04fa9d00 100644 --- a/src/plugins/howler.spatial.js +++ b/src/plugins/howler.spatial.js @@ -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]. */ @@ -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. */ @@ -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 { @@ -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. @@ -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) { @@ -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 {