Merge pull request #28 from zfox23/v0.5.1

v0.5.1
highfidelity · Mar 11, 2021 · d3e3a52 · d3e3a52
2 parents dc9d26a + 80f4d56
commit d3e3a52
Show file tree

Hide file tree

Showing 7 changed files with 81 additions and 65 deletions.
diff --git a/RELEASE_INSTRUCTIONS.md b/RELEASE_INSTRUCTIONS.md
@@ -1,12 +1,14 @@
 ## Making a New Release of the High Fidelity Spatial Audio Client Library
-1. [Appropriately bump](https://semver.org/) the version of the Client Library by using the `npm version` command. For example, you might do the following:
-    1. Check out a new branch on your fork of this repository with `git checkout -b <new branch name>`.
-    2. Run `npm version <major | minor | patch>` (depending on whether you want to rev the `major`, `minor`, or `patch` version number).
-    3. Run `git push -u origin <new branch name>` to push the version changes to your branch.
-    4. Make a new PR against the base repository containing your version changes.
-    5. Have someone at High Fidelity merge the PR.
-2. Make a Pull Request to pull all of the code from the `main` branch into the `release` branch.
-    - [Click here for a quick link to do this.](https://github.com/highfidelity/hifi-spatial-audio-js/compare/release...main?expand=1)
+1. [Appropriately bump](https://semver.org/) the version of the Client Library by using the `npm version` command. It's easiest to do the following:
+    1. Ensure you've forked `hifi-spatial-audio-js`.
+    2. Check out `main` on your fork of this repo, using a command like: `git checkout main && git pull upstream main && git push -u origin main`
+    3. Check out a new branch on your fork of this repository with `git checkout -b <new branch name>`.
+    4. Run `npm version <major | minor | patch>` (depending on whether you want to rev the `major`, `minor`, or `patch` version number).
+    5. Run `git push -u origin <new branch name>` to push the version changes to your branch.
+    6. Make a new PR against the base repository containing your version changes.
+    7. Have someone at High Fidelity merge the PR.
+2. Make a Pull Request to pull all of the code from the `main` branch **of your fork** into the `release` branch.
+    - If you followed the instructions from step (1) above, you can make a pull request with a base of `main` and a compare branch of `<new branch name>`.
 3. Have the PR reviewed and merged.
 4. Once the PR is merged and the latest code is now on the `release` branch, [click here to start drafting a new release](https://github.com/highfidelity/hifi-spatial-audio-js/releases/new).
 5. Under "Tag version", input `v<Package Version>`

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hifi-spatial-audio",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "hifi-spatial-audio allows developers to integrate High Fidelity's spatial audio technology into their JavaScript projects.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

diff --git a/src/classes/HiFiAudioAPIData.ts b/src/classes/HiFiAudioAPIData.ts
@@ -58,7 +58,7 @@ export class OrientationQuat3D {
     z: number;
 
     /**
-     * Construct a new `OrientationQuat3D` object. All parameters are required.
+     * Construct a new `OrientationQuat3D` object.
      */
     constructor({ w = 1, x = 0, y = 0, z = 0 }: { w?: number, x?: number, y?: number, z?: number } = {}) {
         this.w = clampNonan(w, -1, 1, 1);
@@ -371,49 +371,50 @@ export function eulerFromQuaternion(quat: OrientationQuat3D, order: OrientationE
  * Member data of this class that is sent to the Server will affect the final mixed spatial audio for all listeners in the server's virtual space.
  */
 export class HiFiAudioAPIData {
-    position: Point3D;
-    orientationQuat: OrientationQuat3D;
-    orientationEuler: OrientationEuler3D;
-    volumeThreshold: number;
-    hiFiGain: number;
-    userAttenuation: number;
-    userRolloff: number;
-
     /**
-     * 
-     * @param __namedParameters
-     * @param position If you don't supply a `position` when constructing instantiations of this class, `position` will be `null`.
+     * If you don't supply a `position` when constructing instantiations of this class, `position` will be `null`.
      * 
      * ✔ The client sends `position` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called.
      * 
      * ✔ The server sends `position` data to all clients connected to a server during "peer updates".
-     * @param orientationQuat If you don't supply an `orientationQuat` when constructing instantiations of this class, `orientationQuat` will be `null`.
+     */
+    position: Point3D;
+    /**
+     * If you don't supply an `orientationQuat` when constructing instantiations of this class, `orientationQuat` will be `null`.
      * 
      * ✔ The client sends `orientationQuat` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called.
      * 
      * ✔ The server sends `orientationQuat` data to all clients connected to a server during "peer updates".
-     * @param orientationEuler For convenience, a Euler representation of the orientation is supported.
-     *  This is an alternative way to specify the orientationQuat field in the AudioData to send to or received from the server.
+     */
+    orientationQuat: OrientationQuat3D;
+    /**
+     * For convenience, a Euler representation of the orientation is supported.
+     * This is an alternative way to specify the `orientationQuat` field in the `HiFiAudioAPIData` that is sent to or received from the server.
      * 
-     *  ✔ When using euler representation to update the client orientation, the equivalent quaternion is evaluated in _updateUserData
-     *  ✔ When requesting orientation euler from server updates, the euler representation is evaluated in _handleUserDataUpdates
+     *  ✔ When using euler representation to update the client orientation, the equivalent Quaternion is evaluated in `_updateUserData()`
      * 
-     *
-     * @param volumeThreshold A volume level below this value is considered background noise and will be smoothly gated off.
+     *  ✔ When requesting orientation Euler from server updates, the Euler representation is evaluated in `_handleUserDataUpdates()`
+     */
+    orientationEuler: OrientationEuler3D;
+    /**
+     * A volume level below this value is considered background noise and will be smoothly gated off.
      * The floating point value is specified in dBFS (decibels relative to full scale) with values between -96 dB (indicating no gating)
      * and 0 dB. It is in the same decibel units as the VolumeDecibels component of UserDataSubscription.
-     *
-
-     * @param hiFiGain This value affects how loud User A will sound to User B at a given distance in 3D space.
+     */
+    volumeThreshold: number;
+    /**
+     * This value affects how loud User A will sound to User B at a given distance in 3D space.
      * This value also affects the distance at which User A can be heard in 3D space.
      * Higher values for User A means that User A will sound louder to other users around User A, and it also means that User A will be audible from a greater distance.
      * If you don't supply an `hiFiGain` when constructing instantiations of this class, `hiFiGain` will be `null`.
      * 
      * ✔ The client sends `hiFiGain` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called.
      * 
      * ✔ The server sends `hiFiGain` data to all clients connected to a server during "peer updates".
-
-     * @param userAttenuation This value affects how far a user's sound will travel in 3D space, without affecting the user's loudness.
+     */
+    hiFiGain: number;
+    /**
+     * This value affects how far a user's sound will travel in 3D space, without affecting the user's loudness.
      * By default, there is a global attenuation value (set for a given space) that applies to all users in a space. This default space
      * attenuation is usually 0.5, which represents a reasonable approximation of a real-world fall-off in sound over distance.
      * Lower numbers represent less attenuation (i.e. sound travels farther); higher numbers represent more attenuation (i.e. sound drops
@@ -437,7 +438,9 @@ export class HiFiAudioAPIData {
      * ✔ The client sends `userAttenuation` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called.
      * 
      * ❌ The server never sends `userAttenuation` data.
-     *
+     */
+    userAttenuation: number;
+    /**
      * @param userRolloff This value represents the progressive high frequency roll-off in meters, a measure of how the higher frequencies 
      * in a user's sound are dampened as the user gets further away. By default, there is a global roll-off value (set for a given space), currently 16 
      * meters, which applies to all users in a space. This value represents the distance for a 1kHz rolloff. Values in the range of 
@@ -452,6 +455,8 @@ export class HiFiAudioAPIData {
      * 
      * ❌ The server never sends `userRolloff` data.
      */
+    userRolloff: number;
+
     constructor({ position = null, orientationQuat = null, orientationEuler = null, volumeThreshold = null, hiFiGain = null, userAttenuation = null, userRolloff = null }: { position?: Point3D, orientationQuat?: OrientationQuat3D, orientationEuler?: OrientationEuler3D, volumeThreshold?: number, hiFiGain?: number, userAttenuation?: number, userRolloff?: number } = {}) {
         this.position = position;
         this.orientationQuat = orientationQuat;
@@ -470,24 +475,31 @@ export class HiFiAudioAPIData {
  * See {@link HiFiAudioAPIData} for data that can both be sent to and received from the Server (i.e. `position`).
  */
 export class ReceivedHiFiAudioAPIData extends HiFiAudioAPIData {
+    /**
+     * This User ID is an arbitrary string provided by an application developer which can be used to identify the user associated with a client.
+     * We recommend that this `providedUserID` is unique across all users, but the High Fidelity API will not enforce uniqueness across clients for this value.
+     */
     providedUserID: string;
-    hashedVisitID: string;
-    volumeDecibels: number;
-
     /**
+     * This string is a hashed version of the random UUID that is generated automatically.
      * 
-     * @param params 
-     * @param params.providedUserID This User ID is an arbitrary string provided by an application developer which can be used to identify the user associated with a client.
-     * We recommend that this `providedUserID` is unique across all users, but the High Fidelity API will not enforce uniqueness across clients for this value.
-     * @param params.hashedVisitID This string is a hashed version of the random UUID that is generated automatically.
      * A connecting client sends this value as the `session` key inside the argument to the `audionet.init` command.
+     * 
      * It is used to identify a given client across a cloud of mixers and is guaranteed ("guaranteed" given the context of random UUIDS) to be unique.
      * Application developers should not need to interact with or make use of this value, unless they want to use it internally for tracking or other purposes.
+     * 
      * This value cannot be set by the application developer.
-     * @param params.volumeDecibels The current volume of the user in decibels.
+     */
+    hashedVisitID: string;
+    /**
+     * The current volume of the user in decibels.
+     * 
      * ❌ The client never sends `volumeDecibels` data to the server.
+     * 
      * ✔ The server sends `volumeDecibels` data to all clients connected to a server during "peer updates".
      */
+    volumeDecibels: number;
+
     constructor(params: { providedUserID?: string, hashedVisitID?: string, volumeDecibels?: number, position?: Point3D, orientationQuat?: OrientationQuat3D, hiFiGain?: number } = {}) {
         super(params);
         this.providedUserID = params.providedUserID;

diff --git a/src/classes/HiFiAxisConfiguration.ts b/src/classes/HiFiAxisConfiguration.ts
@@ -57,7 +57,7 @@ export class HiFiAxisConfiguration {
 /**
  * Contains the application's 3D axis configuration. By default:
  * - `+x` is to the right and `-x` is to the left
- * - `+y` is up and `-z` is down
+ * - `+y` is up and `-y` is down
  * - `+z` is back and `-z` is front
  * - The coordinate system is right-handed.
  * - Euler order is `OrientationEuler3DOrder.YawPitchRoll`
@@ -108,58 +108,58 @@ export class HiFiAxisUtilities {
 
         // START into-screen/out-of-screen axis error checking
         if (axisConfiguration.intoScreenAxis === HiFiAxes.PositiveX && axisConfiguration.outOfScreenAxis !== HiFiAxes.NegativeX) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.intoScreenAxis}, and Left Axis is ${axisConfiguration.outOfScreenAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nIntoScreen Axis is ${axisConfiguration.intoScreenAxis}, and OutOfScreen Axis is ${axisConfiguration.outOfScreenAxis}!`);
             isValid = false;
         }
         if (axisConfiguration.outOfScreenAxis === HiFiAxes.PositiveX && axisConfiguration.intoScreenAxis !== HiFiAxes.NegativeX) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.intoScreenAxis}, and Left Axis is ${axisConfiguration.outOfScreenAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nIntoScreen Axis is ${axisConfiguration.intoScreenAxis}, and OutOfScreen Axis is ${axisConfiguration.outOfScreenAxis}!`);
             isValid = false;
         }
 
         if (axisConfiguration.intoScreenAxis === HiFiAxes.PositiveY && axisConfiguration.outOfScreenAxis !== HiFiAxes.NegativeY) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.intoScreenAxis}, and Left Axis is ${axisConfiguration.outOfScreenAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nIntoScreen Axis is ${axisConfiguration.intoScreenAxis}, and OutOfScreen Axis is ${axisConfiguration.outOfScreenAxis}!`);
             isValid = false;
         }
         if (axisConfiguration.outOfScreenAxis === HiFiAxes.PositiveY && axisConfiguration.intoScreenAxis !== HiFiAxes.NegativeY) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.intoScreenAxis}, and Left Axis is ${axisConfiguration.outOfScreenAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nIntoScreen Axis is ${axisConfiguration.intoScreenAxis}, and OutOfScreen Axis is ${axisConfiguration.outOfScreenAxis}!`);
             isValid = false;
         }
 
         if (axisConfiguration.intoScreenAxis === HiFiAxes.PositiveZ && axisConfiguration.outOfScreenAxis !== HiFiAxes.NegativeZ) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.intoScreenAxis}, and Left Axis is ${axisConfiguration.outOfScreenAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nIntoScreen Axis is ${axisConfiguration.intoScreenAxis}, and OutOfScreen Axis is ${axisConfiguration.outOfScreenAxis}!`);
             isValid = false;
         }
         if (axisConfiguration.outOfScreenAxis === HiFiAxes.PositiveZ && axisConfiguration.intoScreenAxis !== HiFiAxes.NegativeZ) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.intoScreenAxis}, and Left Axis is ${axisConfiguration.outOfScreenAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nIntoScreen Axis is ${axisConfiguration.intoScreenAxis}, and OutOfScreen Axis is ${axisConfiguration.outOfScreenAxis}!`);
             isValid = false;
         }
         // END into-screen/out-of-screen axis error checking
 
         // START up/down axis error checking
         if (axisConfiguration.upAxis === HiFiAxes.PositiveX && axisConfiguration.downAxis !== HiFiAxes.NegativeX) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.upAxis}, and Left Axis is ${axisConfiguration.downAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nUp Axis is ${axisConfiguration.upAxis}, and Down Axis is ${axisConfiguration.downAxis}!`);
             isValid = false;
         }
         if (axisConfiguration.downAxis === HiFiAxes.PositiveX && axisConfiguration.upAxis !== HiFiAxes.NegativeX) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.upAxis}, and Left Axis is ${axisConfiguration.downAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nUp Axis is ${axisConfiguration.upAxis}, and Down Axis is ${axisConfiguration.downAxis}!`);
             isValid = false;
         }
 
         if (axisConfiguration.upAxis === HiFiAxes.PositiveY && axisConfiguration.downAxis !== HiFiAxes.NegativeY) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.upAxis}, and Left Axis is ${axisConfiguration.downAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nUp Axis is ${axisConfiguration.upAxis}, and Down Axis is ${axisConfiguration.downAxis}!`);
             isValid = false;
         }
         if (axisConfiguration.downAxis === HiFiAxes.PositiveY && axisConfiguration.upAxis !== HiFiAxes.NegativeY) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.upAxis}, and Left Axis is ${axisConfiguration.downAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nUp Axis is ${axisConfiguration.upAxis}, and Down Axis is ${axisConfiguration.downAxis}!`);
             isValid = false;
         }
 
         if (axisConfiguration.upAxis === HiFiAxes.PositiveZ && axisConfiguration.downAxis !== HiFiAxes.NegativeZ) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.upAxis}, and Left Axis is ${axisConfiguration.downAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nUp Axis is ${axisConfiguration.upAxis}, and Down Axis is ${axisConfiguration.downAxis}!`);
             isValid = false;
         }
         if (axisConfiguration.downAxis === HiFiAxes.PositiveZ && axisConfiguration.upAxis !== HiFiAxes.NegativeZ) {
-            HiFiLogger.error(`Invalid axis configuration!\nRight Axis is ${axisConfiguration.upAxis}, and Left Axis is ${axisConfiguration.downAxis}!`);
+            HiFiLogger.error(`Invalid axis configuration!\nUp Axis is ${axisConfiguration.upAxis}, and Down Axis is ${axisConfiguration.downAxis}!`);
             isValid = false;
         }
         // END up/down axis error checking

diff --git a/src/classes/HiFiCommunicator.ts b/src/classes/HiFiCommunicator.ts
@@ -89,7 +89,7 @@ export class HiFiCommunicator {
     /**
      * Constructor for the HiFiCommunicator object. Once you have created a HiFiCommunicator, you can use the
      * {@link setInputAudioMediaStream} method to assign an input audio stream to the connection, and
-     * once the connection has been established, use the {@link getOutputAudioMediaStrem} method to
+     * once the connection has been established, use the {@link getOutputAudioMediaStream} method to
      * retrieve the output audio from the server.
      * @param {Object} __namedParameters
      * @param initialHiFiAudioAPIData - The initial position, orientation, etc of the user.