High Fidelity Administrative REST API (v1.4.0)

Spaces

The spaces API endpoint can be used to create, manage, and delete audio spaces for an app, as well as moderate users currently connected to a space.

A space is a virtual 3D environment which allows clients to send positionally localized audio streams and receive spatial audio. The spatial audio heard by clients combines audio streams from nearby sources according to the position of each client. By default, audio sources that are farther away from a client will sound quieter and more muffled.

A space can optionally contain zones. A zone is a region inside of a space which may have different rules for combining spatial audio, such that it is easier to hear from some zones than others, depending on where a client is located in the space. Zone attenuations specify rules for how to combine spatial audio between zones.

List spaces

This endpoint allows you to get the list of all spaces currently associated with a spatial audio app

query Parameters
token
required
string

An admin JSON Web Token for the app in which this operation takes place

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a space

This endpoint allows you to create a space for an existing spatial audio app.

query Parameters
token
required
string

An admin JSON Web Token for the app in which this operation takes place

client-limit
integer
Example: client-limit=50

The configurable max allowed number of connected clients in this space. When the number of connected clients meets or exceeds this number, additional clients will no longer be able to connect to the space. The max number of connected users also cannot exceed the max-client-limit property of the space, which can vary from 5 to over 100 depending on what tier of space is provisioned. (Note: Setting this value to 0 will use the max-client-limit for the max allowed number of connected clients.)

ignore-token-signing
boolean
Default: false

If set to true, then this space ignores the cryptographic signature on tokens from users attempting to connect to the space. This allows users to connect using arbitrary identities. It should always be set to false in production apps.

global-directional-attenuation-enabled
boolean
Example: global-directional-attenuation-enabled=true

This setting determines if the orientation of a speaking user with a microphone, or other mono output stream, sounds quieter to a listening user when the speaking user is facing away from the listening user. By default, this setting is null, which means the space will have global directional attenuation enabled (true).

For example:

  • User A is speaking to two other users B and C
  • Users B and C are both 2 meters away from user A
  • User A is directly facing user B
  • User A is facing 180 degrees away from user C
  • Therefore, user A will by default sound louder to user B than to user C
  • If global-directional-attenuation-enabled is set to false, then user A will sound equally loud to user B and user C

A speaking user with a stereo output stream is not affected by this setting, and will sound just as loud to a listener regardless of the speaking user's orientation. However, a speaking user with a stereo output stream is still affected by other audio settings such as global-attenuation and global-frequency-rolloff.

space-version
string
Example: space-version=50-user

A string that describes the type of hardware that the server will run on. This is most commonly used to set the capacity for a space, as described in the Configure Space Capacity User Guide. Available values are Regular, 50-user, 100-user, and 150-user. NOTE: THIS SETTING IS ONLY AVAILABLE TO PRO USERS.

global-frequency-rolloff
number
Example: global-frequency-rolloff=16

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which means the space will instead have a global frequency rolloff of 16.0. This means that at 16.0 meters, the high frequency parts of sounds above 1kHz will be reduced by a fixed amount. This is effectively a distance-dependent lowpass filter. Like attenuation, frequency rolloff makes sounds less distinguishable at greater distances, but it does so without quieting the sound entirely.

In addition to global frequency rolloff, it is possible to set frequency rolloff on a per-zone or per-user basis.

global-attenuation
number
Example: global-attenuation=0.5

Affects how quickly the volume of a sound decreases as one moves away from the sound source. This does not affect the initial volume of the sound at the sound source. By default, this setting is null, which means the space will instead have a global attenuation value of 0.5. The default approximates real-world sound attenuation. More attenuation will cause sounds to decrease in volume more quickly over the same distance. Less attenuation will cause sounds to decrease in volume more slowly.

Attenuation behaves differently depending on the number used:

  • A setting between 0 and 1 represents logarithmic attenuation. This sounds more natural and is recommended. Settings closer to 0, for example 0.2 and 0.02, represent less attenuation respectively. A number such as 0.00001 effectively disables attenuation within a reasonably sized space, so that all sound sources can be heard.
  • A setting less than 0 represents linear attenuation. This does not sound as natural as logarithmic attenuation. Linear attenuation causes a sound source to become completely silent after a distance in meters. For example, with an attenuation setting of -10.0, the sound from a source becomes silent at 10 meters from the source.

In addition to global attenuation, it is possible to set attenuation on a per-zone or per-user basis.

new-connections-allowed
boolean
Default: true

If set to true, then users can connect to this space.

name
string
Example: name=example_space_name

The name of the space

Responses

Response samples

Content type
application/json
{
  • "client-limit": 50,
  • "ignore-token-signing": false,
  • "global-directional-attenuation-enabled": true,
  • "space-version": "50-user",
  • "global-frequency-rolloff": 16,
  • "global-attenuation": 0.5,
  • "max-client-limit": 135,
  • "space-id": "00000000-0000-0000-0000-000000000000",
  • "app-id": "00000000-0000-0000-0000-000000000000",
  • "new-connections-allowed": true,
  • "name": "example_space_name"
}

Create a space

This endpoint allows you to create a space for an existing spatial audio app.

query Parameters
token
required
string

An admin JSON Web Token for the app in which this operation takes place

Request Body schema: application/json
client-limit
integer

The configurable max allowed number of connected clients in this space. When the number of connected clients meets or exceeds this number, additional clients will no longer be able to connect to the space. The max number of connected users also cannot exceed the max-client-limit property of the space, which can vary from 5 to over 100 depending on what tier of space is provisioned. (Note: Setting this value to 0 will use the max-client-limit for the max allowed number of connected clients.)

ignore-token-signing
boolean
Default: false

If set to true, then this space ignores the cryptographic signature on tokens from users attempting to connect to the space. This allows users to connect using arbitrary identities. It should always be set to false in production apps.

global-directional-attenuation-enabled
boolean

This setting determines if the orientation of a speaking user with a microphone, or other mono output stream, sounds quieter to a listening user when the speaking user is facing away from the listening user. By default, this setting is null, which means the space will have global directional attenuation enabled (true).

For example:

  • User A is speaking to two other users B and C
  • Users B and C are both 2 meters away from user A
  • User A is directly facing user B
  • User A is facing 180 degrees away from user C
  • Therefore, user A will by default sound louder to user B than to user C
  • If global-directional-attenuation-enabled is set to false, then user A will sound equally loud to user B and user C

A speaking user with a stereo output stream is not affected by this setting, and will sound just as loud to a listener regardless of the speaking user's orientation. However, a speaking user with a stereo output stream is still affected by other audio settings such as global-attenuation and global-frequency-rolloff.

space-version
string

A string that describes the type of hardware that the server will run on. This is most commonly used to set the capacity for a space, as described in the Configure Space Capacity User Guide. Available values are Regular, 50-user, 100-user, and 150-user. NOTE: THIS SETTING IS ONLY AVAILABLE TO PRO USERS.

global-frequency-rolloff
number

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which means the space will instead have a global frequency rolloff of 16.0. This means that at 16.0 meters, the high frequency parts of sounds above 1kHz will be reduced by a fixed amount. This is effectively a distance-dependent lowpass filter. Like attenuation, frequency rolloff makes sounds less distinguishable at greater distances, but it does so without quieting the sound entirely.

In addition to global frequency rolloff, it is possible to set frequency rolloff on a per-zone or per-user basis.

global-attenuation
number

Affects how quickly the volume of a sound decreases as one moves away from the sound source. This does not affect the initial volume of the sound at the sound source. By default, this setting is null, which means the space will instead have a global attenuation value of 0.5. The default approximates real-world sound attenuation. More attenuation will cause sounds to decrease in volume more quickly over the same distance. Less attenuation will cause sounds to decrease in volume more slowly.

Attenuation behaves differently depending on the number used:

  • A setting between 0 and 1 represents logarithmic attenuation. This sounds more natural and is recommended. Settings closer to 0, for example 0.2 and 0.02, represent less attenuation respectively. A number such as 0.00001 effectively disables attenuation within a reasonably sized space, so that all sound sources can be heard.
  • A setting less than 0 represents linear attenuation. This does not sound as natural as logarithmic attenuation. Linear attenuation causes a sound source to become completely silent after a distance in meters. For example, with an attenuation setting of -10.0, the sound from a source becomes silent at 10 meters from the source.

In addition to global attenuation, it is possible to set attenuation on a per-zone or per-user basis.

new-connections-allowed
boolean
Default: true

If set to true, then users can connect to this space.

name
string

The name of the space

Responses

Request samples

Content type
application/json
{
  • "client-limit": 50,
  • "ignore-token-signing": false,
  • "global-directional-attenuation-enabled": true,
  • "space-version": "50-user",
  • "global-frequency-rolloff": 16,
  • "global-attenuation": 0.5,
  • "new-connections-allowed": true,
  • "name": "example_space_name"
}

Response samples

Content type
application/json
{
  • "client-limit": 50,
  • "ignore-token-signing": false,
  • "global-directional-attenuation-enabled": true,
  • "space-version": "50-user",
  • "global-frequency-rolloff": 16,
  • "global-attenuation": 0.5,
  • "max-client-limit": 135,
  • "space-id": "00000000-0000-0000-0000-000000000000",
  • "app-id": "00000000-0000-0000-0000-000000000000",
  • "new-connections-allowed": true,
  • "name": "example_space_name"
}

Create a space by name

This endpoint allows you to create a space by-name for an existing spatial audio app.

query Parameters
token
required
string

An admin JSON Web Token for the app in which this operation takes place

client-limit
integer
Example: client-limit=50

The configurable max allowed number of connected clients in this space. When the number of connected clients meets or exceeds this number, additional clients will no longer be able to connect to the space. The max number of connected users also cannot exceed the max-client-limit property of the space, which can vary from 5 to over 100 depending on what tier of space is provisioned. (Note: Setting this value to 0 will use the max-client-limit for the max allowed number of connected clients.)

ignore-token-signing
boolean
Default: false

If set to true, then this space ignores the cryptographic signature on tokens from users attempting to connect to the space. This allows users to connect using arbitrary identities. It should always be set to false in production apps.

global-directional-attenuation-enabled
boolean
Example: global-directional-attenuation-enabled=true

This setting determines if the orientation of a speaking user with a microphone, or other mono output stream, sounds quieter to a listening user when the speaking user is facing away from the listening user. By default, this setting is null, which means the space will have global directional attenuation enabled (true).

For example:

  • User A is speaking to two other users B and C
  • Users B and C are both 2 meters away from user A
  • User A is directly facing user B
  • User A is facing 180 degrees away from user C
  • Therefore, user A will by default sound louder to user B than to user C
  • If global-directional-attenuation-enabled is set to false, then user A will sound equally loud to user B and user C

A speaking user with a stereo output stream is not affected by this setting, and will sound just as loud to a listener regardless of the speaking user's orientation. However, a speaking user with a stereo output stream is still affected by other audio settings such as global-attenuation and global-frequency-rolloff.

space-version
string
Example: space-version=50-user

A string that describes the type of hardware that the server will run on. This is most commonly used to set the capacity for a space, as described in the Configure Space Capacity User Guide. Available values are Regular, 50-user, 100-user, and 150-user. NOTE: THIS SETTING IS ONLY AVAILABLE TO PRO USERS.

global-frequency-rolloff
number
Example: global-frequency-rolloff=16

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which means the space will instead have a global frequency rolloff of 16.0. This means that at 16.0 meters, the high frequency parts of sounds above 1kHz will be reduced by a fixed amount. This is effectively a distance-dependent lowpass filter. Like attenuation, frequency rolloff makes sounds less distinguishable at greater distances, but it does so without quieting the sound entirely.

In addition to global frequency rolloff, it is possible to set frequency rolloff on a per-zone or per-user basis.

global-attenuation
number
Example: global-attenuation=0.5

Affects how quickly the volume of a sound decreases as one moves away from the sound source. This does not affect the initial volume of the sound at the sound source. By default, this setting i