Constructor for the HiFiCommunicator object. Once you have created a HiFiCommunicator, you can use the setInputAudioMediaStream method to assign an input audio stream to the connection, and once the connection has been established, use the {@link getOutputAudioMediaStrem} method to retrieve the output audio from the server.
Cannot be set later. The 3D axis configuration. See ourHiFiAxisConfiguration for defaults.
The initial position, orientation, etc of the user.
A function that will be called when the connection state to the High Fidelity Audio API Server changes. See HiFiConnectionStates.
A function that will be called when a peer disconnects from the Space.
User Data updates will not be sent to the server any more frequently than this number in milliseconds.
Cannot be set later. See HiFiUserDataStreamingScopes.
Ingests user data updates from the server and, if relevant, calls the relevant callback functions associated with the User Data Subscriptions. See addUserDataSubscription.
Contains all of the new user data most recently received from the server.
Clears the clientside rate limit timeout used to prevent user data from being sent to the High Fidelity Audio API server too often.
A simple wrapper function called by our instantiation of HiFiMixerSession that calls the user-provided onUsersDisconnected()
function if one exists.
Library users can provide an onUsersDisconnected() callback function when instantiating the HiFiCommunicator object, or by setting
HiFiCommunicator.onUsersDisconnected after instantiation.
An Array of ReceivedHiFiAudioAPIData regarding the users who disconnected.
Formats the local user data properly, then sends that user data to the High Fidelity Audio API server. This transfer is rate limited.
There is no reason a library user would need to call this function without also simultaneously updating User Data, so this function is private.
true if we should ignore the clientside rate limiter and send the data regardless of its status; false otherwise.
If this operation is successful, returns { success: true, rawDataTransmitted: <the raw data that was transmitted to the server>}. If unsuccessful, returns
{ success: false, error: <an error message> }.
We keep a clientside copy of the data that we last transmitted to the High Fidelity Audio API server. We use this data to ensure that we only send to the server the minimum set of data necessary - i.e. the difference between the data contained on the server about the user and the new data that the client has locally. We use this function here to update the clientside copy of the data that we last transmitted.
The data that we just transmitted to the High Fidelity Audio API server.
Updates the internal copy of the User Data associated with the user associated with this client. Does NOT update
the user data on the High Fidelity Audio API server. There are no good reasons for a client to call this function
and not update the server User Data, and thus this function is private.
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.
The new orientationEuler of the user.
The new orientationQuat of the user.
The new position of the user.
This value affects how far a user's voice will travel in 3D space. The new attenuation value for the user.
This value affects the frequency rolloff for a given user. The new rolloff value for the user.
The new volumeThreshold of the user.
Adds a new User Data Subscription to the list of clientside Subscriptions. User Data Subscriptions are used to obtain User Data about other Users. For example, if you set up a User Data Subscription for your own User Data, you can use that subscription to ensure that the data on the High Fidelity Audio API Server is the same as the data you are sending to it from the client.
The new User Data Subscription associated with a user.
Connects to the High Fidelity Audio API server and transmits the initial user data to the server.
This JSON Web Token (JWT) is used by callers to associate a user with a specific High Fidelity Spatial Audio API Server. JWTs are an industry-standard method for securely representing claims between two applications.
Important information about JWTs:
To generate a JWT for use with the High Fidelity Audio API:
jose:hiFiSampleJWT = await new SignJWT({
"app_id": APP_ID,
"space_id": SPACE_ID
})
.setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
.sign(crypto.createSecretKey(Buffer.from(APP_SECRET, "utf8")));
connectToHiFiAudioAPIServer().As of 2021-01-21, we've added code in this function which, in the browser context, searches for a token URL query parameter and, if a JWT
isn't supplied as an argument to this function, uses the value of that token URL query parameter as the JWT.
We should remove that later, because we almost certainly don't want this to stay in the API code, but it's very convenient for sample apps for right now.
An URL that will be used to create a valid WebRTC signaling address. The passed hostURL parameter does not need to contain the protocol
or port - e.g. server.highfidelity.com - and it will be used to construct a signaling address of the form: wss://${hostURL}:8001/?token=
If the developer does not pass a hostURL parameter, a default URL will be used instead. See: DEFAULT_PROD_HIGH_FIDELITY_ENDPOINT
Reading this parameter from the URL should be implemented by the developer as part of the application code.
If this operation is successful, the Promise will resolve with { success: true, audionetInitResponse: <The response to audionet.init from the server in Object format>}.
If unsuccessful, the Promise will reject with { success: false, error: <an error message> }.
Disconnects from the High Fidelity Audio API. After this call, user data will no longer be transmitted to High Fidelity, the audio input stream will not be transmitted to High Fidelity, and the user will no longer be able to hear the audio stream from High Fidelity.
A bunch of info about this HiFiCommunicator instantiation, including Server Version.
The final mixed audio MediaStream coming from the High Fidelity Audio Server.
Use this function to set the MediaStream associated with the user. This MediaStream will be sent up to the High Fidelity Audio Servers and
mixed with other users' audio streams. The resultant mixed stream will be sent to all connected clients.
Be mindful of supplying this stream upon initial connection when you anticipate that the user is using Bluetooth audio input and Bluetooth audio output simultaneously. Many Bluetooth audio devices do not support stereo (spatialized) audio output and microphone audio input simultaneously, including the popular combination of an iPhone and AirPods. Your users may have a better experience if they join the Server in "listen-only" mode - i.e. without microphone input - and then are asked for microphone permission later (which will force their Bluetooth output device into a lower-quality, unspatialized mono mode).
The new MediaStream to send to the High Fidelity Audio Server. If this
is set to an undefined value, the existing input stream (if one is set) will be cleared.
true if the input stream should be treated as stereo, false for mono (default).
true if the new MediaStream was successfully set, false otherwise.
Use this function to set whether or not the user's input audio MediaStream should be "muted".
A muted stream will have the enabled property of each of its MediaStreamTracks set to false
(and an unmuted stream -- the default -- will have the enabled property set to true). Be
aware that if you are using the same MediaStream object in other ways, it will be affected by
calling this method. So, if you would like to mute/unmute the input audio stream separately for the
High Fidelity audio vs. some other use of it, it is recommended to clone the audio stream separately
for each use.
true if the stream was successfully muted/unmuted, false if it was not. (The user should
assume that if this returns false, no change was made to the mute (track enabled) state of the stream.)
Start collecting data about the WebRTC connection between Client and Server. Note that the data inside the reports pertains only to payload data internal to the WebRTC connection and does not include total data sent over the wire or received over the wire in your application.
Callback functions will be provided two Array arguments: stats and prevStats.
Each of those Array items contains one or more Objects, which are reports of WebRTC stats data,
including data such as "a timestamp", "the number of bytes received since the last report" and "current jitter buffer delay".
Stop collecting data about the WebRTC connection between Client and Server.
A simple function that calls _updateUserData, followed by _transmitHiFiAudioAPIDataToServer.
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,
the most up-to-date data will be transmitted.
The new user data that we want to send to the High Fidelity Audio API server.
Returns the return value of _transmitHiFiAudioAPIDataToServer.
This class exposes properties and methods useful for communicating from the High Fidelity Audio API Client to the High Fidelity Audio API Server.