From 3d5af4fbb8e1eb0c956f085f7e42afd3bacb4b32 Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Mon, 30 Aug 2021 11:37:12 -0700 Subject: [PATCH 01/16] Fix some types in HiFiMixerSession.ts not being documented --- src/classes/HiFiMixerSession.ts | 24 ++++++++++++++++++++++-- tsconfig.json | 5 +++-- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/src/classes/HiFiMixerSession.ts b/src/classes/HiFiMixerSession.ts index 4b466721..696a1328 100644 --- a/src/classes/HiFiMixerSession.ts +++ b/src/classes/HiFiMixerSession.ts @@ -1,6 +1,9 @@ /** - * Code in this module is used internally by the [[HiFiCommunicator]] object to manage the connection between client and server. - * Developers do not need to and should not consider this module when writing their applications. + * Code in this module is used by [[HiFiCommunicator]] object to manage the connection between client and server. + * This module is also home to some types used to manage client volume state, for example + * {@link OnMuteChangedCallback}. + * The class HiFiMixerSession is an internal class. Developers do not need to and should not consider it + * when writing their applications. * @packageDocumentation */ @@ -32,17 +35,33 @@ const PERSONAL_VOLUME_ADJUST_TIMEOUT_MS = 5000; type ConnectionStateChangeHandler = (state: HiFiConnectionStates, result: HiFiConnectionAttemptResult) => void; +/** @internal */ interface AudionetSetOtherUserGainsForThisConnectionResponse { success: boolean, reason?: string } +/** + * The result of calling {@link HiFiCommunicator.setOtherUserGainsForThisConnection}, which adjusts the + * gain of one or more users for the communicator's current connection only. + */ export interface SetOtherUserGainsForThisConnectionResponse { + /** + * `true` if the gains of other users were adjusted, `false` otherwise + */ success: boolean, + /** + * if {@link success} is `false`, then a message explaining why the gains of other users could not be adjusted + */ error?: string, + /** @internal */ audionetSetOtherUserGainsForThisConnectionResponse?: AudionetSetOtherUserGainsForThisConnectionResponse } +/** + * The result of calling {@link HiFiCommunicator.setOtherUserGainForThisConnection}, which adjusts the + * gain of another user for the communicator's current connection only. + */ export type SetOtherUserGainForThisConnectionResponse = SetOtherUserGainsForThisConnectionResponse; /** @@ -114,6 +133,7 @@ export type OnMuteChangedCallback = (muteChangedEvent: MuteChangedEvent) => void /** * Instantiations of this class contain data about a connection between a client and a mixer. * Client library users shouldn't have to care at all about the variables and methods contained in this class. + * @internal */ export class HiFiMixerSession { /** diff --git a/tsconfig.json b/tsconfig.json index 1992e486..2316b2c9 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -17,12 +17,13 @@ "src/classes/HiFiAudioAPIData.ts", "src/classes/HiFiAxisConfiguration.ts", "src/classes/HiFiCommunicator.ts", + "src/classes/HiFiMixerSession.ts", "src/classes/HiFiUserDataSubscription.ts", "src/controls/HiFiControls.ts", "src/constants/HiFiConstants.ts", "src/libravi/RaviSession.ts", "src/utilities/HiFiLogger.ts", - "src/utilities/HiFiUtilities.ts", + "src/utilities/HiFiUtilities.ts" ], "out": "docs", "readme": "./tsdocIndexPage.md", @@ -33,4 +34,4 @@ "excludeInternal": true, "exclude": ["dist"] } -} \ No newline at end of file +} From c33c06fd075518d719d452443be79d72e6b003dd Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Mon, 30 Aug 2021 11:39:05 -0700 Subject: [PATCH 02/16] In index.ts, export public API types in HiFiMixerSession.ts --- src/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/index.ts b/src/index.ts index 440fbf9a..2b0cde06 100644 --- a/src/index.ts +++ b/src/index.ts @@ -21,6 +21,7 @@ export { apiVersion }; // Scroll down to check out those shorter synonyms. export { HiFiAudioAPIData, ReceivedHiFiAudioAPIData, OrientationEuler3D, OrientationQuat3D, Point3D, eulerToQuaternion, eulerFromQuaternion} from "./classes/HiFiAudioAPIData"; export { HiFiCommunicator, HiFiConnectionStates, HiFiUserDataStreamingScopes } from "./classes/HiFiCommunicator"; +export { SetOtherUserGainForThisConnectionResponse, SetOtherUserGainsForThisConnectionResponse, MuteReason, MuteChangedEvent, OnMuteChangedCallback } from "./classes/HiFiMixerSession"; export { WebRTCSessionParams } from "./libravi/RaviSession"; export { AvailableUserDataSubscriptionComponents, UserDataSubscription } from "./classes/HiFiUserDataSubscription"; export { HiFiLogLevel, HiFiLogger } from "./utilities/HiFiLogger"; From 779a99398f3855fdc921e9807e0311089b20b824 Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Thu, 9 Sep 2021 11:45:07 -0700 Subject: [PATCH 03/16] Fix wholeLength calculation in Quaternion.getAxis() --- src/utilities/HiFiMath.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/utilities/HiFiMath.ts b/src/utilities/HiFiMath.ts index b4863b68..5e5b1e66 100644 --- a/src/utilities/HiFiMath.ts +++ b/src/utilities/HiFiMath.ts @@ -132,7 +132,7 @@ export class Quaternion { axis.x = this.x / imaginaryLength; axis.y = this.y / imaginaryLength; axis.z = this.z / imaginaryLength; - let wholeLength = Math.sqrt(imaginaryLength + this.w * this.w); + let wholeLength = Math.sqrt(imaginaryLength2 + this.w * this.w); let angle = 2.0 * Math.acos(this.w / wholeLength); if (angle < 0.0) { // we choose the axis that corresponds to positive angle From 0c29f99e2b377cf11bbd899560ca7bc85c9e8ed2 Mon Sep 17 00:00:00 2001 From: Zach Fox Date: Thu, 9 Sep 2021 14:50:15 -0400 Subject: [PATCH 04/16] Fix deploy-main-build.yml --- .github/workflows/deploy-main-build.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/deploy-main-build.yml b/.github/workflows/deploy-main-build.yml index bd7ee56d..76969092 100644 --- a/.github/workflows/deploy-main-build.yml +++ b/.github/workflows/deploy-main-build.yml @@ -15,8 +15,6 @@ jobs: run: echo "The last push was made by a user named ${{ github.event.pusher.name }}." - uses: actions/checkout@v2 - with: - token: ${{ secrets.GUSTAVO_TOKEN }} - name: Bump npm prerelease version run: | From 0d4f50678bac75c1faf46be6d76ed12f8d620202 Mon Sep 17 00:00:00 2001 From: Zach Fox Date: Thu, 9 Sep 2021 14:54:45 -0400 Subject: [PATCH 05/16] Revert "Fix deploy-main-build.yml" This reverts commit 0c29f99e2b377cf11bbd899560ca7bc85c9e8ed2. --- .github/workflows/deploy-main-build.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/deploy-main-build.yml b/.github/workflows/deploy-main-build.yml index 76969092..bd7ee56d 100644 --- a/.github/workflows/deploy-main-build.yml +++ b/.github/workflows/deploy-main-build.yml @@ -15,6 +15,8 @@ jobs: run: echo "The last push was made by a user named ${{ github.event.pusher.name }}." - uses: actions/checkout@v2 + with: + token: ${{ secrets.GUSTAVO_TOKEN }} - name: Bump npm prerelease version run: | From 5502741c9ba0eec5479230fa52d0b8b7cf87d82c Mon Sep 17 00:00:00 2001 From: hifibuild Date: Thu, 9 Sep 2021 18:55:47 +0000 Subject: [PATCH 06/16] Bump package version to 2.0.1-0 --- package-lock.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 73533345..a5cb019d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.0", + "version": "2.0.1-0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 408293cc..01c0a0b4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.0", + "version": "2.0.1-0", "description": "The High Fidelity Audio Client Library allows developers to integrate High Fidelity's spatial audio technology into their projects.", "main": "./dist/index.js", "types": "./dist/index.d.ts", From 1d2330891c37164c77ff72f731ac526ae75a6c0d Mon Sep 17 00:00:00 2001 From: hifibuild Date: Thu, 9 Sep 2021 21:49:34 +0000 Subject: [PATCH 07/16] Bump package version to 2.0.1-1 --- package-lock.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index a5cb019d..4e8a399e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-0", + "version": "2.0.1-1", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 01c0a0b4..50ec3f6b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-0", + "version": "2.0.1-1", "description": "The High Fidelity Audio Client Library allows developers to integrate High Fidelity's spatial audio technology into their projects.", "main": "./dist/index.js", "types": "./dist/index.d.ts", From c020b9431ffc412b218eab3afcc48399a661f62c Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Tue, 31 Aug 2021 13:30:08 -0700 Subject: [PATCH 08/16] Allow per-user attenuation/rolloff/threshold to be NaN, in which case the value for the zone/space is used. Update documentation to say 0/0/null are no longer the fallbacks respectively and NaN is the new fallback. --- src/classes/HiFiAudioAPIData.ts | 26 +++++++++++++++----------- src/classes/HiFiCommunicator.ts | 22 +++++++++++----------- src/classes/HiFiMixerSession.ts | 8 ++++---- 3 files changed, 30 insertions(+), 26 deletions(-) diff --git a/src/classes/HiFiAudioAPIData.ts b/src/classes/HiFiAudioAPIData.ts index b9a60781..f10a53da 100644 --- a/src/classes/HiFiAudioAPIData.ts +++ b/src/classes/HiFiAudioAPIData.ts @@ -44,6 +44,9 @@ export class HiFiAudioAPIData { * 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 (effectively muting the input from this user). It is in the same decibel units as the VolumeDecibels component of UserDataSubscription. + * Setting this value to `NaN` will cause the volume threshold from the space to be used instead. + * + * If you don't supply a `volumeThreshold` when constructing instantiations of this class, it will be ignored. */ volumeThreshold: number; /** @@ -61,23 +64,21 @@ export class HiFiAudioAPIData { * 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 - * off more quickly). * * When setting this value for an individual user, the following holds: - * - Positive numbers should be between 0 and 1, and they represent a logarithmic attenuation. This range is recommended, as it is + * - A value of `NaN` causes the user to inherit the global attenuation for a space, or, if zones are defined for the space, + * the attenuation settings at the user's position. + * - Positive numbers between 0 and 1 (excluding 0) represent logarithmic attenuation. This range is recommended, as it is * more natural sounding. Smaller numbers represent less attenuation, so a number such as 0.2 can be used to make a particular - * user's audio travel farther than other users', for instance in "amplified" concert type settings. Similarly, an extremely - * small non-zero number (e.g. 0.00001) can be used to effectively turn off attenuation for a given user within a reasonably - * sized space, resulting in a "broadcast mode" where the user can be heard throughout most of the space regardless of their location - * relative to other users. (Note: The actual value "0" is used internally to represent the default; for setting minimal attenuation, - * small non-zero numbers should be used instead. See also "userRolloff" below.) + * user's audio travel farther than other users', for instance in "amplified" concert type settings. A number such as 0.02 will + * make the user's audio travel even farther. + * - A value of 0 will turn off attenuation for a given user entirely, resulting in a "broadcast mode" where the user can be + * heard throughout the entire space regardless of their location relative to other users. * - Negative attenuation numbers are used to represent linear attenuation, and are a somewhat artificial, non-real-world concept. However, * this setting can be used as a blunt tool to easily test attenuation, and tune it aggressively in extreme circumstances. When using linear * attenuation, the setting is the distance in meters at which the audio becomes totally inaudible. * - * If you don't supply an `userAttenuation` when constructing instantiations of this class, `userAttenuation` will be `null` and the - * default will be used. + * If you don't supply a `userAttenuation` when constructing instantiations of this class, it will be ignored. * * ✔ The client sends `userAttenuation` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called. * @@ -93,7 +94,10 @@ export class HiFiAudioAPIData { * extremely high values (e.g. 99999) should be used in combination with "broadcast mode"-style userAttenuation settings to cause the * broadcasted voice to sound crisp and "up close" even at very large distances. * - * If you don't supply an `userRolloff` when constructing instantiations of this class, `userRolloff` will be `null`. + * A `userRolloff` of `NaN` will cause the user to inherit the global frequency rolloff for the space, or, if zones are defined + * for the space, the frequency rolloff settings at the user's position. + * + * If you don't supply a `userRolloff` when constructing instantiations of this class, it will be ignored. * * ✔ The client sends `userRolloff` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called. * diff --git a/src/classes/HiFiCommunicator.ts b/src/classes/HiFiCommunicator.ts index 9bdc3a2f..9d224242 100644 --- a/src/classes/HiFiCommunicator.ts +++ b/src/classes/HiFiCommunicator.ts @@ -979,15 +979,17 @@ export class HiFiCommunicator { * @param __namedParameters * @param position - The new position of the user. * @param orientation - The new orientation of the user (in Quaternion form) - * @param volumeThreshold - The new volumeThreshold of the user. Setting this to null will use the space default volume threshold. + * @param volumeThreshold - The new volumeThreshold of the user. Setting this to `NaN` will use the space default volume threshold. * @param hiFiGain - 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. * The new hiFiGain of the user. * @param userAttenuation - This value affects how far a user's voice will travel in 3D space. - * The new attenuation value for the user. + * Setting this to `NaN` will use the space default attenuation, or, if zones are defined for the space, + * the attenuation settings at the user's position. * @param userRolloff - This value affects the frequency rolloff for a given user. - * The new rolloff value for the user. + * Setting this to `NaN` will use the space default rolloff, or, if zones are defined for the space, + * the frequency rolloff settings at the user's position. */ private _updateUserData({ position, orientation, volumeThreshold, hiFiGain, userAttenuation, userRolloff }: { position?: Point3D, orientation?: Quaternion, volumeThreshold?: number, hiFiGain?: number, userAttenuation?: number, userRolloff?: number } = {}): void { if (position) { @@ -1011,17 +1013,16 @@ export class HiFiCommunicator { this._currentHiFiAudioAPIData.orientation.z = orientation.z ?? this._currentHiFiAudioAPIData.orientation.z; } - if (typeof (volumeThreshold) === "number" || - volumeThreshold === null) { + if (typeof (volumeThreshold) === "number") { // May be NaN this._currentHiFiAudioAPIData.volumeThreshold = volumeThreshold; } if (typeof (hiFiGain) === "number") { this._currentHiFiAudioAPIData.hiFiGain = Math.max(0, hiFiGain); } - if (typeof (userAttenuation) === "number") { + if (typeof (userAttenuation) === "number") { // May be NaN this._currentHiFiAudioAPIData.userAttenuation = userAttenuation; } - if (typeof (userRolloff) === "number") { + if (typeof (userRolloff) === "number") { // May be NaN this._currentHiFiAudioAPIData.userRolloff = Math.max(0, userRolloff); } } @@ -1067,18 +1068,17 @@ export class HiFiCommunicator { this._lastTransmittedHiFiAudioAPIData.orientation.z = dataJustTransmitted.orientation.z ?? this._lastTransmittedHiFiAudioAPIData.orientation.z; } - if (typeof (dataJustTransmitted.volumeThreshold) === "number" || - dataJustTransmitted.volumeThreshold === null) { + if (typeof (dataJustTransmitted.volumeThreshold) === "number") { // May be NaN this._lastTransmittedHiFiAudioAPIData["volumeThreshold"] = dataJustTransmitted.volumeThreshold; } if (typeof (dataJustTransmitted.hiFiGain) === "number") { this._lastTransmittedHiFiAudioAPIData["hiFiGain"] = dataJustTransmitted.hiFiGain; } - if (typeof (dataJustTransmitted.userAttenuation) === "number") { + if (typeof (dataJustTransmitted.userAttenuation) === "number") { // May be NaN this._lastTransmittedHiFiAudioAPIData["userAttenuation"] = dataJustTransmitted.userAttenuation; } - if (typeof (dataJustTransmitted.userRolloff) === "number") { + if (typeof (dataJustTransmitted.userRolloff) === "number") { // May be NaN this._lastTransmittedHiFiAudioAPIData["userRolloff"] = dataJustTransmitted.userRolloff; } if (typeof (dataJustTransmitted._otherUserGainQueue) === "object") { diff --git a/src/classes/HiFiMixerSession.ts b/src/classes/HiFiMixerSession.ts index 21cd3469..5f738f74 100644 --- a/src/classes/HiFiMixerSession.ts +++ b/src/classes/HiFiMixerSession.ts @@ -1207,8 +1207,7 @@ export class HiFiMixerSession { } } - if (typeof (currentHifiAudioAPIData.volumeThreshold) === "number" || - currentHifiAudioAPIData.volumeThreshold === null) { + if (typeof (currentHifiAudioAPIData.volumeThreshold) === "number") { // May be NaN dataForMixer["T"] = currentHifiAudioAPIData.volumeThreshold; } @@ -1216,11 +1215,11 @@ export class HiFiMixerSession { dataForMixer["g"] = Math.max(0, currentHifiAudioAPIData.hiFiGain); } - if (typeof (currentHifiAudioAPIData.userAttenuation) === "number") { + if (typeof (currentHifiAudioAPIData.userAttenuation) === "number") { // May be NaN dataForMixer["a"] = currentHifiAudioAPIData.userAttenuation; } - if (typeof (currentHifiAudioAPIData.userRolloff) === "number") { + if (typeof (currentHifiAudioAPIData.userRolloff) === "number") { // May be NaN dataForMixer["r"] = Math.max(0, currentHifiAudioAPIData.userRolloff); } @@ -1272,6 +1271,7 @@ export class HiFiMixerSession { let commandController = this._raviSession.getCommandController(); if (commandController) { + // Stringified NaN values get converted to null, which the mixer interprets as unset let stringifiedDataForMixer = JSON.stringify(dataForMixer); commandController.sendInput(stringifiedDataForMixer); return { From c809e99e49b06b91a77555421e5e86dcb85443f7 Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Tue, 31 Aug 2021 16:39:47 -0700 Subject: [PATCH 09/16] (TODO: Revert) 0/0/null are still fallbacks for user attenuation/rolloff/volume threshold respectively. Add compatibility warnings that that will soon no longer be the case. --- src/classes/HiFiAudioAPIData.ts | 17 ++++++++++++----- src/classes/HiFiCommunicator.ts | 20 +++++++++++++++----- src/classes/HiFiMixerSession.ts | 3 ++- 3 files changed, 29 insertions(+), 11 deletions(-) diff --git a/src/classes/HiFiAudioAPIData.ts b/src/classes/HiFiAudioAPIData.ts index f10a53da..0f80a21f 100644 --- a/src/classes/HiFiAudioAPIData.ts +++ b/src/classes/HiFiAudioAPIData.ts @@ -44,7 +44,10 @@ export class HiFiAudioAPIData { * 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 (effectively muting the input from this user). It is in the same decibel units as the VolumeDecibels component of UserDataSubscription. - * Setting this value to `NaN` will cause the volume threshold from the space to be used instead. + * Setting this value to `NaN` or `null` will cause the volume threshold from the space to be used instead. + * + * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space volume threshold + * if the threshold is `NaN`. * * If you don't supply a `volumeThreshold` when constructing instantiations of this class, it will be ignored. */ @@ -66,13 +69,14 @@ export class HiFiAudioAPIData { * attenuation is usually 0.5, which represents a reasonable approximation of a real-world fall-off in sound over distance. * * When setting this value for an individual user, the following holds: - * - A value of `NaN` causes the user to inherit the global attenuation for a space, or, if zones are defined for the space, - * the attenuation settings at the user's position. + * - A value of `NaN` or 0 causes the user to inherit the global attenuation for a space, or, if zones are defined for the space, + * the attenuation settings at the user's position. **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server + * will only fall back to the space/zone attenuation if the user attenuation is `NaN`. * - Positive numbers between 0 and 1 (excluding 0) represent logarithmic attenuation. This range is recommended, as it is * more natural sounding. Smaller numbers represent less attenuation, so a number such as 0.2 can be used to make a particular * user's audio travel farther than other users', for instance in "amplified" concert type settings. A number such as 0.02 will * make the user's audio travel even farther. - * - A value of 0 will turn off attenuation for a given user entirely, resulting in a "broadcast mode" where the user can be + * - A value of near 0, such as 0.001, will greatly reduce attenuation for a given user, resulting effectively in a "broadcast mode" where the user can be * heard throughout the entire space regardless of their location relative to other users. * - Negative attenuation numbers are used to represent linear attenuation, and are a somewhat artificial, non-real-world concept. However, * this setting can be used as a blunt tool to easily test attenuation, and tune it aggressively in extreme circumstances. When using linear @@ -94,8 +98,11 @@ export class HiFiAudioAPIData { * extremely high values (e.g. 99999) should be used in combination with "broadcast mode"-style userAttenuation settings to cause the * broadcasted voice to sound crisp and "up close" even at very large distances. * - * A `userRolloff` of `NaN` will cause the user to inherit the global frequency rolloff for the space, or, if zones are defined + * A `userRolloff` of `NaN` or 0 will cause the user to inherit the global frequency rolloff for the space, or, if zones are defined * for the space, the frequency rolloff settings at the user's position. + * + * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space/zone rolloff + * if the user rolloff is `NaN`. * * If you don't supply a `userRolloff` when constructing instantiations of this class, it will be ignored. * diff --git a/src/classes/HiFiCommunicator.ts b/src/classes/HiFiCommunicator.ts index 9d224242..99121d29 100644 --- a/src/classes/HiFiCommunicator.ts +++ b/src/classes/HiFiCommunicator.ts @@ -979,17 +979,25 @@ export class HiFiCommunicator { * @param __namedParameters * @param position - The new position of the user. * @param orientation - The new orientation of the user (in Quaternion form) - * @param volumeThreshold - The new volumeThreshold of the user. Setting this to `NaN` will use the space default volume threshold. + * @param volumeThreshold - The new volumeThreshold of the user. Setting this to `NaN` or `null` will use the space default volume threshold. + * + * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space volume threshold if the threshold is `NaN`. * @param hiFiGain - 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. * The new hiFiGain of the user. + * * @param userAttenuation - This value affects how far a user's voice will travel in 3D space. - * Setting this to `NaN` will use the space default attenuation, or, if zones are defined for the space, + * Setting this to `NaN` or 0 will use the space default attenuation, or, if zones are defined for the space, * the attenuation settings at the user's position. + * + * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space/zone attenuation if the user attenuation is `NaN`. + * * @param userRolloff - This value affects the frequency rolloff for a given user. - * Setting this to `NaN` will use the space default rolloff, or, if zones are defined for the space, + * Setting this to `NaN` or 0 will use the space default rolloff, or, if zones are defined for the space, * the frequency rolloff settings at the user's position. + * + * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space/zone rolloff if the user rolloff is `NaN`. */ private _updateUserData({ position, orientation, volumeThreshold, hiFiGain, userAttenuation, userRolloff }: { position?: Point3D, orientation?: Quaternion, volumeThreshold?: number, hiFiGain?: number, userAttenuation?: number, userRolloff?: number } = {}): void { if (position) { @@ -1013,7 +1021,8 @@ export class HiFiCommunicator { this._currentHiFiAudioAPIData.orientation.z = orientation.z ?? this._currentHiFiAudioAPIData.orientation.z; } - if (typeof (volumeThreshold) === "number") { // May be NaN + if (typeof (volumeThreshold) === "number" || + volumeThreshold === null) { // May be NaN this._currentHiFiAudioAPIData.volumeThreshold = volumeThreshold; } if (typeof (hiFiGain) === "number") { @@ -1068,7 +1077,8 @@ export class HiFiCommunicator { this._lastTransmittedHiFiAudioAPIData.orientation.z = dataJustTransmitted.orientation.z ?? this._lastTransmittedHiFiAudioAPIData.orientation.z; } - if (typeof (dataJustTransmitted.volumeThreshold) === "number") { // May be NaN + if (typeof (dataJustTransmitted.volumeThreshold) === "number" || + dataJustTransmitted.volumeThreshold === null) { // May be NaN this._lastTransmittedHiFiAudioAPIData["volumeThreshold"] = dataJustTransmitted.volumeThreshold; } diff --git a/src/classes/HiFiMixerSession.ts b/src/classes/HiFiMixerSession.ts index 5f738f74..26d6b788 100644 --- a/src/classes/HiFiMixerSession.ts +++ b/src/classes/HiFiMixerSession.ts @@ -1207,7 +1207,8 @@ export class HiFiMixerSession { } } - if (typeof (currentHifiAudioAPIData.volumeThreshold) === "number") { // May be NaN + if (typeof (currentHifiAudioAPIData.volumeThreshold) === "number" || + currentHifiAudioAPIData.volumeThreshold === null) { // May be NaN dataForMixer["T"] = currentHifiAudioAPIData.volumeThreshold; } From 4ddad546c16a8c418a93ca655a171b34ed565ace Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Tue, 31 Aug 2021 16:49:54 -0700 Subject: [PATCH 10/16] Add hint to updateUserDataAndTransmit on what user data can be sent --- src/classes/HiFiCommunicator.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/classes/HiFiCommunicator.ts b/src/classes/HiFiCommunicator.ts index 99121d29..0321be9b 100644 --- a/src/classes/HiFiCommunicator.ts +++ b/src/classes/HiFiCommunicator.ts @@ -1182,6 +1182,7 @@ export class HiFiCommunicator { /** * A simple function that calls {@link _updateUserData}, followed by {@link _transmitHiFiAudioAPIDataToServer}. + * See {@link HiFiAudioAPIData} for what data can be sent to the High Fidelity Audio API Server. * Developers can call this function as often as they want. This function will update the internal data store of the user's * position, orientation, etc. No matter how often developers call this function, the internal data store transmission is rate-limited * and will only be sent to the server once every `transmitRateLimitTimeoutMS` milliseconds. When the internal data store is transmitted, From 4f2d3d0bf3dbfcd9206327e3666d214240986974 Mon Sep 17 00:00:00 2001 From: hifibuild Date: Fri, 10 Sep 2021 17:05:44 +0000 Subject: [PATCH 11/16] Bump package version to 2.0.1-2 --- package-lock.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 4e8a399e..0fbceda4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-1", + "version": "2.0.1-2", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 50ec3f6b..acc921af 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-1", + "version": "2.0.1-2", "description": "The High Fidelity Audio Client Library allows developers to integrate High Fidelity's spatial audio technology into their projects.", "main": "./dist/index.js", "types": "./dist/index.d.ts", From a8fa7bd471c1ec0116704c1af0aa66d064e93ad1 Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Fri, 10 Sep 2021 10:14:55 -0700 Subject: [PATCH 12/16] Clarify what happens when attenuation/rolloff/threshold are not supplied in user data --- src/classes/HiFiAudioAPIData.ts | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/classes/HiFiAudioAPIData.ts b/src/classes/HiFiAudioAPIData.ts index 0f80a21f..b7ec89fe 100644 --- a/src/classes/HiFiAudioAPIData.ts +++ b/src/classes/HiFiAudioAPIData.ts @@ -49,7 +49,8 @@ export class HiFiAudioAPIData { * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space volume threshold * if the threshold is `NaN`. * - * If you don't supply a `volumeThreshold` when constructing instantiations of this class, it will be ignored. + * If you don't supply a `volumeThreshold` when constructing instantiations of this class, the previous value of `volumeThreshold` will + * be used. If `volumeThreshold` has never been supplied, the volume threshold of the space will be used instead. */ volumeThreshold: number; /** @@ -82,7 +83,8 @@ export class HiFiAudioAPIData { * this setting can be used as a blunt tool to easily test attenuation, and tune it aggressively in extreme circumstances. When using linear * attenuation, the setting is the distance in meters at which the audio becomes totally inaudible. * - * If you don't supply a `userAttenuation` when constructing instantiations of this class, it will be ignored. + * If you don't supply a `userAttenuation` when constructing instantiations of this class, the previous value of `userAttenuation` will + * be used. If `userAttenuation` has never been supplied, the attenuation of the space will be used instead. * * ✔ The client sends `userAttenuation` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called. * @@ -104,7 +106,8 @@ export class HiFiAudioAPIData { * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space/zone rolloff * if the user rolloff is `NaN`. * - * If you don't supply a `userRolloff` when constructing instantiations of this class, it will be ignored. + * If you don't supply a `userRolloff` when constructing instantiations of this class, the previous value of `userRolloff` will + * be used. If `userRolloff` has never been supplied, the frequency rolloff of the space will be used instead. * * ✔ The client sends `userRolloff` data to the server when `_transmitHiFiAudioAPIDataToServer()` is called. * From 21b288c83515e252520b30b1fd58452e1d2bfc0d Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Fri, 10 Sep 2021 10:17:40 -0700 Subject: [PATCH 13/16] Move 'May be NaN' comments where the lines they were on didn't correspond to checks for the number type --- src/classes/HiFiCommunicator.ts | 8 ++++---- src/classes/HiFiMixerSession.ts | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/classes/HiFiCommunicator.ts b/src/classes/HiFiCommunicator.ts index 0321be9b..326d8bea 100644 --- a/src/classes/HiFiCommunicator.ts +++ b/src/classes/HiFiCommunicator.ts @@ -1021,8 +1021,8 @@ export class HiFiCommunicator { this._currentHiFiAudioAPIData.orientation.z = orientation.z ?? this._currentHiFiAudioAPIData.orientation.z; } - if (typeof (volumeThreshold) === "number" || - volumeThreshold === null) { // May be NaN + if (typeof (volumeThreshold) === "number" || // May be NaN + volumeThreshold === null) { this._currentHiFiAudioAPIData.volumeThreshold = volumeThreshold; } if (typeof (hiFiGain) === "number") { @@ -1077,8 +1077,8 @@ export class HiFiCommunicator { this._lastTransmittedHiFiAudioAPIData.orientation.z = dataJustTransmitted.orientation.z ?? this._lastTransmittedHiFiAudioAPIData.orientation.z; } - if (typeof (dataJustTransmitted.volumeThreshold) === "number" || - dataJustTransmitted.volumeThreshold === null) { // May be NaN + if (typeof (dataJustTransmitted.volumeThreshold) === "number" || // May be NaN + dataJustTransmitted.volumeThreshold === null) { this._lastTransmittedHiFiAudioAPIData["volumeThreshold"] = dataJustTransmitted.volumeThreshold; } diff --git a/src/classes/HiFiMixerSession.ts b/src/classes/HiFiMixerSession.ts index 26d6b788..57144003 100644 --- a/src/classes/HiFiMixerSession.ts +++ b/src/classes/HiFiMixerSession.ts @@ -1207,8 +1207,8 @@ export class HiFiMixerSession { } } - if (typeof (currentHifiAudioAPIData.volumeThreshold) === "number" || - currentHifiAudioAPIData.volumeThreshold === null) { // May be NaN + if (typeof (currentHifiAudioAPIData.volumeThreshold) === "number" || // May be NaN + currentHifiAudioAPIData.volumeThreshold === null) { dataForMixer["T"] = currentHifiAudioAPIData.volumeThreshold; } From f0ad12c85a509db48400899a36357a75490a9bb8 Mon Sep 17 00:00:00 2001 From: sabrina-shanman Date: Fri, 10 Sep 2021 11:31:33 -0700 Subject: [PATCH 14/16] Update description of fallback behavior and compatibility warnings --- src/classes/HiFiAudioAPIData.ts | 35 +++++++++++++++++++++++---------- src/classes/HiFiCommunicator.ts | 27 ++++++++++++++++++++----- 2 files changed, 47 insertions(+), 15 deletions(-) diff --git a/src/classes/HiFiAudioAPIData.ts b/src/classes/HiFiAudioAPIData.ts index b7ec89fe..d387b0b0 100644 --- a/src/classes/HiFiAudioAPIData.ts +++ b/src/classes/HiFiAudioAPIData.ts @@ -44,10 +44,14 @@ export class HiFiAudioAPIData { * 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 (effectively muting the input from this user). It is in the same decibel units as the VolumeDecibels component of UserDataSubscription. - * Setting this value to `NaN` or `null` will cause the volume threshold from the space to be used instead. - * - * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space volume threshold - * if the threshold is `NaN`. + * Setting this value to `NaN` will cause the volume threshold from the space to be used instead. + * + * **COMPATIBILITY WARNING:** Currently, setting `volumeThreshold` to `null` will also reset its value to the space default volume threshold. + * In the future, the value of `volumeThreshold` will only be reset if it is set to `NaN`. + * A `volumeThreshold` set to `null` will in the future will be treated as if `volumeThreshold` is not supplied. + * If your spatial audio client application is currently resetting `volumeThreshold` by setting it to `null`, please change + * it to set `volumeThreshold` to `NaN` instead, in order for it to continue working with future versions of + * High Fidelity's Spatial Audio API. * * If you don't supply a `volumeThreshold` when constructing instantiations of this class, the previous value of `volumeThreshold` will * be used. If `volumeThreshold` has never been supplied, the volume threshold of the space will be used instead. @@ -70,9 +74,15 @@ export class HiFiAudioAPIData { * attenuation is usually 0.5, which represents a reasonable approximation of a real-world fall-off in sound over distance. * * When setting this value for an individual user, the following holds: - * - A value of `NaN` or 0 causes the user to inherit the global attenuation for a space, or, if zones are defined for the space, - * the attenuation settings at the user's position. **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server - * will only fall back to the space/zone attenuation if the user attenuation is `NaN`. + * - A value of `NaN` causes the user to inherit the global attenuation for a space, or, if zones are defined for the space, + * the attenuation settings at the user's position. **COMPATIBILITY WARNING:** Currently, setting `userAttenuation` to 0 will + * also reset its value to the space/zone default attenuation. + * In the future, the value of `userAttenuation` will only be reset if it is set to `NaN`. + * A `userAttenuation` set to 0 will in the future be treated as a "broadcast mode", making + * the user audible throughout the entire space. + * If your spatial audio client application is currently resetting `userAttenuation` by setting it to 0, please change + * it to set `userAttenuation` to `NaN` instead, in order for it to continue working with future versions of + * High Fidelity's Spatial Audio API. * - Positive numbers between 0 and 1 (excluding 0) represent logarithmic attenuation. This range is recommended, as it is * more natural sounding. Smaller numbers represent less attenuation, so a number such as 0.2 can be used to make a particular * user's audio travel farther than other users', for instance in "amplified" concert type settings. A number such as 0.02 will @@ -100,11 +110,16 @@ export class HiFiAudioAPIData { * extremely high values (e.g. 99999) should be used in combination with "broadcast mode"-style userAttenuation settings to cause the * broadcasted voice to sound crisp and "up close" even at very large distances. * - * A `userRolloff` of `NaN` or 0 will cause the user to inherit the global frequency rolloff for the space, or, if zones are defined + * A `userRolloff` of `NaN` will cause the user to inherit the global frequency rolloff for the space, or, if zones are defined * for the space, the frequency rolloff settings at the user's position. * - * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space/zone rolloff - * if the user rolloff is `NaN`. + * **COMPATIBILITY WARNING:** Currently, setting `userRolloff` to 0 will also reset its value to the space/zone default rolloff + * In the future, the value of `userRolloff` will only be reset if it is set to `NaN` + * A `userRolloff` set to 0 will in the future be treated as a valid frequency rolloff value, + * which will cause the user's sound to become muffled over a short distance. + * If your spatial audio client application is currently resetting `userRolloff` by setting it to 0, please change + * it to set `userRolloff` to `NaN` instead, in order for it to continue working with future versions of + * High Fidelity's Spatial Audio API. * * If you don't supply a `userRolloff` when constructing instantiations of this class, the previous value of `userRolloff` will * be used. If `userRolloff` has never been supplied, the frequency rolloff of the space will be used instead. diff --git a/src/classes/HiFiCommunicator.ts b/src/classes/HiFiCommunicator.ts index 326d8bea..e5dd686c 100644 --- a/src/classes/HiFiCommunicator.ts +++ b/src/classes/HiFiCommunicator.ts @@ -979,25 +979,42 @@ export class HiFiCommunicator { * @param __namedParameters * @param position - The new position of the user. * @param orientation - The new orientation of the user (in Quaternion form) - * @param volumeThreshold - The new volumeThreshold of the user. Setting this to `NaN` or `null` will use the space default volume threshold. + * @param volumeThreshold - The new volumeThreshold of the user. Setting this to `NaN` will reset its value to the space default volume threshold. * - * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space volume threshold if the threshold is `NaN`. + * **COMPATIBILITY WARNING:** Currently, setting `volumeThreshold` to `null` will also reset its value to the space default volume threshold. + * In the future, the value of `volumeThreshold` will only be reset if it is set to `NaN`. + * A `volumeThreshold` set to `null` will in the future will be treated as if `volumeThreshold` is not supplied. + * If your spatial audio client application is currently resetting `volumeThreshold` by setting it to `null`, please change + * it to set `volumeThreshold` to `NaN` instead, in order for it to continue working with future versions of + * High Fidelity's Spatial Audio API. * @param hiFiGain - 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. * The new hiFiGain of the user. * * @param userAttenuation - This value affects how far a user's voice will travel in 3D space. - * Setting this to `NaN` or 0 will use the space default attenuation, or, if zones are defined for the space, + * Setting this to `NaN` will use the space default attenuation, or, if zones are defined for the space, * the attenuation settings at the user's position. * - * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space/zone attenuation if the user attenuation is `NaN`. + * **COMPATIBILITY WARNING:** Currently, setting `userAttenuation` to 0 will also reset its value to the space/zone default attenuation. + * In the future, the value of `userAttenuation` will only be reset if it is set to `NaN`. + * A `userAttenuation` set to 0 will in the future be treated as a "broadcast mode", making + * the user audible throughout the entire space. + * If your spatial audio client application is currently resetting `userAttenuation` by setting it to 0, please change + * it to set `userAttenuation` to `NaN` instead, in order for it to continue working with future versions of + * High Fidelity's Spatial Audio API. * * @param userRolloff - This value affects the frequency rolloff for a given user. * Setting this to `NaN` or 0 will use the space default rolloff, or, if zones are defined for the space, * the frequency rolloff settings at the user's position. * - * **COMPATIBILITY WARNING:** In the future, the High Fidelity Audio API server will only fall back to the space/zone rolloff if the user rolloff is `NaN`. + * **COMPATIBILITY WARNING:** Currently, setting `userRolloff` to 0 will also reset its value to the space/zone default rolloff + * In the future, the value of `userRolloff` will only be reset if it is set to `NaN` + * A `userRolloff` set to 0 will in the future be treated as a valid frequency rolloff value, + * which will cause the user's sound to become muffled over a short distance. + * If your spatial audio client application is currently resetting `userRolloff` by setting it to 0, please change + * it to set `userRolloff` to `NaN` instead, in order for it to continue working with future versions of + * High Fidelity's Spatial Audio API. */ private _updateUserData({ position, orientation, volumeThreshold, hiFiGain, userAttenuation, userRolloff }: { position?: Point3D, orientation?: Quaternion, volumeThreshold?: number, hiFiGain?: number, userAttenuation?: number, userRolloff?: number } = {}): void { if (position) { From 95cb7969ebbbfc97e0d27ca42ff7efad5289732d Mon Sep 17 00:00:00 2001 From: hifibuild Date: Fri, 10 Sep 2021 22:52:35 +0000 Subject: [PATCH 15/16] Bump package version to 2.0.1-3 --- package-lock.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 0fbceda4..1faa7723 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-2", + "version": "2.0.1-3", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index acc921af..fe7a801e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-2", + "version": "2.0.1-3", "description": "The High Fidelity Audio Client Library allows developers to integrate High Fidelity's spatial audio technology into their projects.", "main": "./dist/index.js", "types": "./dist/index.d.ts", From 1fac6ce080af4cbf8a0ed3a81d5067b125707bd8 Mon Sep 17 00:00:00 2001 From: bridie-hifi Date: Thu, 7 Oct 2021 09:09:52 -0700 Subject: [PATCH 16/16] 2.1.0 --- package-lock.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 1faa7723..d4d74243 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-3", + "version": "2.1.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index fe7a801e..390020eb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "hifi-spatial-audio", - "version": "2.0.1-3", + "version": "2.1.0", "description": "The High Fidelity Audio Client Library allows developers to integrate High Fidelity's spatial audio technology into their projects.", "main": "./dist/index.js", "types": "./dist/index.d.ts",