<img src="https://certify.alexametrics.com/atrk.gif?account=bIEZv1FYxz20cv" style="display:none" height="1" width="1" alt="">

Configure Space Capacity and the Maximum Number of Allowed Users in a Space

SECTIONS

Project Complexity: ★★★★☆

UPDATE: Coming in December 2021, your application will no longer need to programmatically manage Space capacity! It will seamlessly scale. Until early December, this guide and documentation for space-version are still valid. Read more details here (third FAQ question).

In this guide, we will review how to choose and specify the appropriate size for a space.

High Fidelity offers several different types of servers (known as "space versions") to support the needs of different customer use cases and event types. The following options are available for Pro customers:


Space Version

Number of Concurrent Users

Regular

20 concurrent users

(NOTE: This is currently the only available option for self-service API users.

If you need access to additional options, please submit a support request)

50-user

50

100-user

100

150-user

150



Here, you will learn how to:

  1. Create an administrative JWT
  2. Create a new space of the desired capacity using the Administrative REST API
  3. Adjust the size of an existing space
  4. Limit the number of users allowed to connect to a space
Caution Icon

To have a space version other than "Regular" is only available to our Pro customers. If you need access to space sizes that are larger than the default of 20 concurrent users, please visit support and submit a request. 

 

1. Create an Administrative JWT

Before you can create a new space, you will need to have a High Fidelity Developer Account, and to have created a new developer application. This guide assumes that you already have an account and have created at least one application, and that you are familiar with the basic usage of JWTs. Please refer to the "Get a JWT" guide for an introduction to JWTs if needed.

In order to use the Administrative REST API, you will need to create or get an admin JWT that is signed with the appropriate app secret for your application. There are two ways to do this, depending on whether you want to perform your administrative action as part of a scripted process, or for one-off testing.

  1. To create JWTs as part of a scripted process, include a key of admin with a value of true when you create an admin JWT programmatically. Include the relevant app_id as you would when creating any High Fidelity JWT, and sign the JWT using your APP_SECRET. (We also strongly recommend the use of expiration times for all JWTs, especially administrative ones.)

  2. To create a one-off admin JWT, you can use your High Fidelity Developer Account.
    1. On the "Account Overview" page, click on the app name that you want to manage
    2. On the "App Details" page, click on the name of any existing space (or create one manually to use for testing)
    3. Select the "Token is for space administration" check box.
    4. Click the "Make Test JWT" button.
Caution Icon

Admin JWTs created through the developer account pages can not be used to make connections to spaces! By default, an admin JWT is used only for administration via the Administrative REST API. It therefore does not contain any of the information needed for connecting to a specific space. It should be used solely for administering the configuration of spaces.

 

2. Create a New Space of the Desired Capacity

Once you have an admin JWT, the "Create a Space" REST endpoint allows you to create a space using a REST call as described in the Administrative REST API documentation. This endpoint is available at the following URL:
https://api.highfidelity.com/api/v1/spaces/create?token={admin_token}

As part of this space creation, a number of optional attributes can be included. Please refer to the REST API documentation for the complete list of available attributes that are available for you to customize your new space. 

By default, a space created via this endpoint will have a capacity of 20 concurrent users. This capacity is managed through the use of the space-version property on the space. The default for space-version is "Regular", which indicates that the space is of the standard, 20-user size.

Here is an example of creating a new space, with a name of "Hello-World" and the default capacity, using curl from a command line:

curl "https://api.highfidelity.com/api/v1/spaces/create?token={admin-JWT}&name=Hello-World"

This request will return a JSON packet containing the full information about the new space:

{"app-id":"00000000-0000-0000-0000-000000000000","client-limit":null,"global-attenuation":null,"global-frequency-rolloff":null,"ignore-token-signing":false,"max-client-limit":20,"name":"Hello-World","new-connections-allowed":true,"space-id":"00000000-0000-0000-0000-000000000000","space-version":"Regular"}

In particular, note that the space-version is set to Regular. This is the default, 20 concurrent users. This information is also available in the max-client-limit key, which confirms that the space-version called Regular is 20 users.

To create a space that is capable of handling more users, for instance for a large, scheduled event, you would specify one of the other available space-version values from the table above. 

As an example, if you need to create a space capable of handling 50 users (named "Hello-Big-World"), you would use the following request:

curl "https://api.highfidelity.com/api/v1/spaces/create?token={admin-JWT}&name=Hello-Big-World&space-version=50-user"

Similarly, this request will return a JSON packet containing the following information:

{"app-id":"be5126ee-ae73-4a35-a539-85ffe6fbb0bb","client-limit":null,"global-attenuation":null,"global-frequency-rolloff":null,"ignore-token-signing":false,"max-client-limit":50,"name":"Hello-Big-World","new-connections-allowed":true,"space-id":"fb12072f-4e57-40cd-b2f9-c4c4e40c10e0","space-version":"50-user"}

Note that the space-version value for this space is set to 50-user, indicating that the space is capable of supporting up to 50 total users, and the max-client-limit:50 setting confirms this.

 

3. Adjust the Capacity for an Existing Space

If you have an existing space that has already been configured for a certain number of users (for instance, if you have created a space using the default "Regular" space-version), you can use the Administrative REST Endpoint to get or change space settings to change its space-version property.

Info Icon

 Currently, changing the space-version of an existing space that already exists will NOT immediately take effect if there have been any connected users in the last 15 minutes. Changes to the space-version size will take effect up to 15 minutes after the last user has disconnected from the space. For example, if Space A has a space-version of 50-user and already has 45 users connected to it, any space-version changes will not be communicated to the server until those users have left the space and enough time has elapsed for the changes to take effect. (This behavior will be changed in future versions to allow for more real-time application of space-version changes. In the meantime, please plan space usage accordingly.)

 

For example, if you have an existing space that was created using the default space-version of Regular and was assigned a space-id of 00000000-0000-0000-0000-000000000000, and you want to increase the size of the space, you can use the space settings endpoint to update its space-version to 50-user using curl from a command line:

curl "https://api.highfidelity.com/api/v1/spaces/00000000-0000-0000-0000-000000000000/settings?token={admin-JWT}&space-version=50-user"

This request will return a JSON packet containing the full information about the updated space:

{"app-id":"00000000-0000-0000-0000-000000000000","client-limit":null,"global-attenuation":null,"global-frequency-rolloff":null,"ignore-token-signing":false,"max-client-limit":50,"name":"Hello-World","new-connections-allowed":true,"space-id":"00000000-0000-0000-0000-000000000000","space-version":"50-user"}

 

4. Limit the Number of Users Allowed to Connect to a Space

Sometimes, you may want to restrict the number of users who are allowed to join a space (for instance, if you have sold tickets to an event or otherwise want to control how many people are allowed to join). To do this, you can set the client-limit value for a space.

Info Icon

You can only set a client-limit up to the overall limit for the space, as indicated by the max-client-limit setting and controlled by the space-version.

For instance, you may want to use a Regular-sized space, but only allow a maximum of 10 users to connect. Because 10 is less than the overall limit for a Regular space (which is 20), you can achieve this with the client-limit setting. 

Example:

curl "https://api.highfidelity.com/api/v1/spaces/create?token={admin-JWT}&name=Hello-World&client-limit=10"

Returns the following:

{"app-id":"00000000-0000-0000-0000-000000000000","client-limit":10,"global-attenuation":null,"global-frequency-rolloff":null,"ignore-token-signing":false,"max-client-limit":20,"name":"Hello-World","new-connections-allowed":true,"space-id":"00000000-0000-0000-0000-000000000000","space-version":"Regular"}

For this particular space, because the client-limit has been set to 10, "velvet rope" functionality will kick in when the user count reaches 10 people, and no additional users will be allowed to join until the connected user count goes below 10. The max-client-limit, however, is still set to 20, indicating that if you as an administrator want to increase the actual client-limit, you can do so (up to 20).

And finally, note that you can also use the new-connections-allowed setting to immediately turn off access for any new connections. This can be useful if you have a particularly sensitive topic or conversation, and want to ensure that no additional users connect to the space.

Conclusion

In this guide, you learned how to set and adjust the total available capacity for a space, and how to set the "velvet rope" if you need fine-grained control over the number of allowed connections.

For detailed technical information about the High Fidelity Spatial Audio Administrative REST API, visit the REST API documentation.

If you have any questions or comments, please contact us via support.