High Fidelity Administrative REST API (v1.1.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

name
string
Example: name=example_space_name

The name of the space

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-user basis.

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

new-connections-allowed
boolean
Default: true

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

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

Responses

Response samples

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

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
name
string

The name of the space

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-user basis.

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

new-connections-allowed
boolean
Default: true

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

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

Responses

Request samples

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

Response samples

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

Delete a space

This endpoint will permanently delete a space from a spatial audio app. By default, this endpoint will not delete the space if clients are still connected to the space

path Parameters
space_id
required
string

The unique ID of the space to be deleted

query Parameters
token
required
string

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

force-shutdown
string
Default: true

If false, then the space will not be deleted if there are still clients connected to the space. If set to true, the space will be deleted even if clients are connected

Responses

Response samples

Content type
application/json
{
  • "space-id": "00000000-0000-0000-0000-000000000000",
  • "app-id": "00000000-0000-0000-0000-000000000000"
}

Get space details

This endpoint contacts the mixer servers which manage the space, to get live operational information about the space, such as user count and mixer status.

path Parameters
space_id
required
string
Example: 00000000-0000-0000-0000-000000000000

The unique ID of the space from which to get details

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
{
  • "status": "ok",
  • "mixer_build_version": "string",
  • "app_id": "00000000-0000-0000-0000-000000000000",
  • "connected_user_count": 3,
  • "space_id": "00000000-0000-0000-0000-000000000000",
  • "space-version": "c5x"
}