Options
All
  • Public
  • Public/Protected
  • All
Menu

Class ReceivedHiFiAudioAPIData

Instantiations of this class contain all of the data that is possible to receive from the High Fidelity Audio API Server. See below for more details.

See HiFiAudioAPIData for data that can both be sent to and received from the Server (i.e. position).

Hierarchy

Index

Constructors

constructor

  • new ReceivedHiFiAudioAPIData(params?: { hashedVisitID?: string; isStereo?: boolean; orientation?: Quaternion; position?: Point3D; providedUserID?: string; volumeDecibels?: number }): ReceivedHiFiAudioAPIData
  • Parameters

    • params: { hashedVisitID?: string; isStereo?: boolean; orientation?: Quaternion; position?: Point3D; providedUserID?: string; volumeDecibels?: number } = ...
      • Optional hashedVisitID?: string
      • Optional isStereo?: boolean
      • Optional orientation?: Quaternion
      • Optional position?: Point3D
      • Optional providedUserID?: string
      • Optional volumeDecibels?: number

    Returns ReceivedHiFiAudioAPIData

Properties

hashedVisitID

hashedVisitID: string

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.

hiFiGain

hiFiGain: 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 does not send hiFiGain data to all clients as part of "peer updates".

isStereo

isStereo: boolean

Indicates that the peer is providing stereo audio.

The server sends isStereo data to all clients connected to a server during "peer updates".

orientation

orientation: Quaternion

If you don't supply an orientation when constructing instantiations of this class, orientation will be null.

✔ The client sends orientation data to the server when _transmitHiFiAudioAPIDataToServer() is called.

✔ The server sends orientation data to all clients connected to a server during "peer updates".

position

position: Point3D

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".

providedUserID

providedUserID: string

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.

userAttenuation

userAttenuation: 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.

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. 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 make the user's audio travel even farther.
  • 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 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, 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.

❌ The server never sends userAttenuation data.

userRolloff

userRolloff: number
param

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 12 to 32 meters provide a more "enclosed" sound, in which high frequencies tend to be dampened over distance as they are in the real world. Generally changes to roll-off values should be made for the entire space rather than for individual users, but 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 for the space, the frequency rolloff settings at the user's position.

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.

✔ The client sends userRolloff data to the server when _transmitHiFiAudioAPIDataToServer() is called.

❌ The server never sends userRolloff data.

volumeDecibels

volumeDecibels: number

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".

volumeThreshold

volumeThreshold: number

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.

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.