Project Complexity: ★★★★☆
When your application uses the High Fidelity Spatial Audio API, it makes a connection to the High Fidelity servers using the
HiFiCommunicator class and its
connectToHiFiAudioAPIServer() method. Your users will only be able to talk to each other while they are connected to High Fidelity servers. This guide explores the different ways in which your application can get information about the state of a user's connection, and explains how to manage reconnections due to failed connections either automatically or manually.
The rest of this guide assumes that you are comfortable with creating and using
HiFiCommunicator class provides the method
getConnectionState() to return the current state of a
HiFiCommunicator object. The possible connection states are listed in the
HiFiConnectionStates enumeration, and are summarized here:
Disconnected- the initial state of a
HiFiCommunicatorbefore it has been connected to the server, and the final state after the connection has been terminated.
Connecting- the state while the
HiFiCommunicatoris in the process of opening a connection to the server.
Connected- the state of a stable connection
Reconnecting- the state if the
HiFiCommunicatoris in the process of automatically reconnecting (see "Configuring Auto-Reconnects" below)
Disconnecting- the state when the connection is in the process of being manually disconnected through the use of the
Failed- a temporary state that indicates the connection has failed. This state will immediately transition automatically to "Disconnected."
At any time during a session,
HiFiCommunicator.getConnectionState() can be called to determine the current state of the connection.
The following diagram illustrates the life cycle of a connection. Please note that the automatic retry behavior and the "Reconnecting" state will only be used if auto-reconnects are enabled (see "Configuring Auto-Reconnects" below).
(Click the image below to make it larger.)
By default, the HiFiCommunicator will NOT attempt to automatically reconnect dropped sessions or retry initial connection attempts! To enable the auto-reconnect feature, you MUST use the ConnectionRetryAndTimeoutConfig settings to enable and configure it.
When constructing a
HiFiCommunicator object, you can specify a
connectionRetryAndTimeoutConfig parameter that will define how the
HiFiCommunicator should handle the situation where an initial connection attempt fails, or when an existing connection is inadvertently disconnected (e.g. due to a network disruption).
Warning: Automatic reconnection of an existing connection does NOT currently take into account what caused the connection to fail. It will therefore attempt to reconnect ALL connections, including connections that were terminated due to an administrator issuing the "Kick" command to remove a user from a space.
For the moment, High Fidelity does NOT recommend enabling the autoRetryOnDisconnect capability if you rely on the "Kick" functionality to remove bad actors. (This will likely change in the future; watch our release notes for updates!)
The format of the
connectionRetryAndTimeoutConfig parameter is specified by the
ConnectionRetryAndTimeoutConfig interface, defined inside the
HiFiCommunicator class. There are several different settings that can be used to enable and configure the automatic reconnection attempts. Retries for the initial connection attempt can be configured separately from retries for disconnected connections.
The most important properties of a
ConnectionRetryAndTimeoutConfig object are the booleans
autoRetryOnDisconnect. To enable basic, default auto-reconnection capabilities, set both of these to true when creating a
HiFiCommunicator object. With these set to true, the initial attempt to connect will retry for 15 seconds, and any subsequent disconnects after the first connection will retry for 60 seconds (1 minute). Here is an example of a
HiFiCommunicator that has been configured to use the default auto-reconnect behavior:
If the defaults are not suitable for your application, you can directly configure the amount of time spent trying to reconnect either initial connections or disconnected sessions. For instance, you may not want to attempt to retry failed connections for a full minute, but rather to provide the user with an alternate course of action after only 30 seconds. In this situation, you can include either or both of the
maxSecondsToSpendRetryingOnDisconnect properties in your
connectionRetryAndTimeoutConfig object, like so:
connectionRetryAndTimeoutConfig interface provides two additional configuration parameters that can be useful for configuring connections:
pauseBetweenRetriesMSconfigures the amount of time to wait in between retries. A higher value for this property will allow more time to pass between attempts to retry (both initial connections and reconnects of dropped sessions). This can be useful if you want to allow more time for the user's network connection to recover before attempting each reconnect. This defaults to 500ms, and can not be set lower than 100ms.
timeoutPerConnectionAttemptMSconfigures the amount of time to wait before timing out a specific individual connection attempt (for instance, in the case of a slow network or a problem with domain name resolution). This defaults to 5000ms, or 5 seconds. In certain situations where a user is physically located very far away from the High Fidelity servers (which are primarily located on the West Coast of the United States), it may be necessary to increase this value in order to give the client and the server time to establish a connection with each other.
When you specify a connection state change handler, the function you provide will be called for every change to the connection state, including transient or informational states like "Connecting" or "Failed". Please refer to the "Life Cycle" diagram above for details about the different states, and design your handler to take action only for those states that are relevant to your application. Remember that the "Failed" state is transitory and will automatically trigger a disconnection, causing the state to then transition to "Disconnected."
HiFiCommunicator state changes, it will trigger a call to your custom state change handler, with the new
HiFiConnectionState passed as the first parameter to the handler. Additionally, a "message" object that conforms to the
HiFiCommunicator.HiFiConnectionAttemptResult interface will be passed as the second parameter. This object will always contain a
success boolean indicating whether or not the state change was due to a successful transition (e.g. a state change from "
Connecting" to "
Connected"), as well as an optional
error string containing errors or other informational messages. Additionally, the
HiFiConnectionAttemptResult interface contains an optional
audionetInitResponse object when the new state is "
audionetInitResponse object is primarily used for debugging, and contains general information about the High Fidelity server to which the
HiFiCommunicator is connected.
To provide a connection state change handler, specify the name of your function when constructing your
HiFiCommunciator, by setting the
onConnectionStateChanged parameter. For example:
A connection state change handler can be used to provide feedback to the user, or to take action when different states occur. For instance, if you would prefer finer-grained control over reconnection behavior, you could use a connection state handler to implement your own reconnection logic and disable the High Fidelity auto-reconnect capability. Or, if you are using the auto-reconnect capability, you can also use a state change handler in order to provide notifications to your users when reconnects are attempted.
You can use a state change handler regardless of whether or not you are using High Fidelity's automatic reconnection capability. However, if you are using High Fidelity's auto-reconnect feature, we recommend that your state change handler not attempt to affect the connection (for instance, by attempting to reconnect failed connections), because it could conflict with the auto-reconnect behavior.
HiFiCommunicator sessions will always attempt to fully disconnect if a connection is interrupted. Therefore, a "Failure" state is transitory and you do not need to explicitly tell the HiFiCommunicator to disconnect when you receive this notification. A session that has been disconnected inadvertently will have its state changed to "Failure," but the state will then immediately proceed to "Disconnected." This ensures that all connections are completely disconnected if a failure occurs. If you are implementing custom reconnection logic through the use of state change handlers, we recommend that you do not attempt a new connection until the final "Disconnected" state is reached, to avoid attempting to reconnect a session that is still in the process of disconnecting.
One final way in which your application interacts with the connection state of the
Promises that are returned by the methods
HiFiCommunicator.disconnectFromHiFiAudioAPIServer(). When invoked, each of these two methods will immediately return a
Promise, and the
Promise will either resolve or reject once the attempt to connect or disconnect has completed.
When your application uses the auto-retry capability for initial connection attempts described in the "Configuring Auto-Reconnects" section above, the
Promise that is returned from the
connectToHiFiAudioAPIServer() method will only resolve or reject once all retry attempts have completed. If the final state of the session is "
Promise will resolve; if all attempts to connect have failed and the final state of the session is "
Promise will reject.
Note that these
Promises are only relevant when your application code explicitly calls the
HiFiCommunicator.disconnectFromHiFiAudioAPIServer() methods, and so you may want to use them in combination with a state change handler. These
Promises will be updated at the same time as the state changes, and will match the observed connection state of the
HiFiCommunicator. Specifically, if the
Promise has rejected, the state of the
HiFiCommunicator will have gone to "
Failed" and then to "
Disconnected." if the
Promise has resolved, the state will be at "
In this guide, you learned how to inspect and react to changes in the connection state of a High Fidelity audio session. You also learned how to configure and use the High Fidelity auto-reconnect capabilities.
For detailed technical information about the High Fidelity Spatial Audio Client API, visit the API documentation.
If you have any questions or comments, please reach out to firstname.lastname@example.org.