Documentation Powered by ReDoc

High Fidelity Administrative REST API (v1.4.1)

Spaces

The spaces API endpoints 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

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.

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

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.

global-volume-threshold
number
Example: global-volume-threshold=-40

Default audio level threshold under which audio automatically mutes. Audio above this level will be heard. This value can be overridden by the client on a per-client basis by the volumeThreshold value of updateUserDataAndTransmit.

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.

Responses

Response samples

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

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

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.

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

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.

global-volume-threshold
number

Default audio level threshold under which audio automatically mutes. Audio above this level will be heard. This value can be overridden by the client on a per-client basis by the volumeThreshold value of updateUserDataAndTransmit.

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.

Responses

Request samples

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

Response samples

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

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

name
required
string
Example: name=example_space_name

The name of the space

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.

space-template-name
string
Example: space-template-name=tmpl

The name of an existing space from which default parameters will be copied when a space is created-by-name.

space-template-id
string
Example: space-template-id=00000000-0000-0000-0000-000000000000

The unique ID of an existing space from which default parameters will be copied when a space is created-by-name

new-connections-allowed
boolean
Default: true

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

space-id
string
Example: space-id=00000000-0000-0000-0000-000000000000

The unique ID of the space

app-id
string
Example: app-id=00000000-0000-0000-0000-000000000000

The unique ID of the app which contains this space

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

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.

global-volume-threshold
number
Example: global-volume-threshold=-40

Default audio level threshold under which audio automatically mutes. Audio above this level will be heard. This value can be overridden by the client on a per-client basis by the volumeThreshold value of updateUserDataAndTransmit.

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.

Responses

Response samples

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

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

Request Body schema: application/json
name
required
string

The name of the space

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.

space-template-name
string

The name of an existing space from which default parameters will be copied when a space is created-by-name.

space-template-id
string

The unique ID of an existing space from which default parameters will be copied when a space is created-by-name

new-connections-allowed
boolean
Default: true

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

space-id
string

The unique ID of the space

app-id
string

The unique ID of the app which contains this space

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

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.

global-volume-threshold
number

Default audio level threshold under which audio automatically mutes. Audio above this level will be heard. This value can be overridden by the client on a per-client basis by the volumeThreshold value of updateUserDataAndTransmit.

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.

Responses

Request samples

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

Response samples

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

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

Restart a space

This endpoint will restart a space on a new mixer. If the space wasn't already allocated, this endpoint has no effect. By default, this endpoint will not restart the space if clients are still connected to the space

path Parameters
space_id
required
string

The unique ID of the space to be restarted

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 restarted if there are still clients connected to the space. If set to true, the clients will be kicked from the space and the space will be restarted

Responses

Response samples

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

Get or change space settings

This endpoint allows you to change zero or more editable properties of the space. When requested without specifying any properties to update, this endpoint returns the specified space unaltered.

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

The unique ID of the space to be changed

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

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.

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

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.

global-volume-threshold
number
Example: global-volume-threshold=-40

Default audio level threshold under which audio automatically mutes. Audio above this level will be heard. This value can be overridden by the client on a per-client basis by the volumeThreshold value of updateUserDataAndTransmit.

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.

Responses

Response samples

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

Get or change space settings

This endpoint allows you to change zero or more editable properties of the space. When requested without specifying any properties to update, this endpoint returns the specified space unaltered.

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

The unique ID of the space to be changed

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

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.

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

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.

global-volume-threshold
number

Default audio level threshold under which audio automatically mutes. Audio above this level will be heard. This value can be overridden by the client on a per-client basis by the volumeThreshold value of updateUserDataAndTransmit.

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.

Responses

Request samples

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

Response samples

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

Get zones for a space

This endpoint allows you to get the list of zones for a given space

path Parameters
space_id
required
string

The unique ID of the space

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 zones

This endpoint allows you to create multiple zones at once in a space.

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

The unique ID of the space in which zones will be created

query Parameters
token
required
string

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

Request Body schema: application/json
Array ()
name
required
string

The name of the zone

z-max
required
number

The maximim z coordinate of the box which encloses the zone

y-max
required
number

The maximum y coordinate of the box which encloses the zone

x-max
required
number

The maximum x coordinate of the box which encloses the zone

x-min
required
number

The minimum x coordinate of the box which encloses the zone

z-min
required
number

The minimum z coordinate of the box which encloses the zone

y-min
required
number

The minimum y coordinate of the box which encloses the zone

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Delete all zones

This endpoint allows you to permanently delete all zones at once in a space

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

The unique ID of the space in which all zones will be deleted

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
[
  • {
    }
]

Get or change a zone

This endpoint allows you to change zero or more editable properties of a zone in a space. When requested without specifying any properties to update, this endpoint returns the zone unaltered.

path Parameters
zone_id
required
integer
Example: 7

The unique ID of the zone to be updated

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

The unique ID of the space containing the zone to be updated

query Parameters
token
required
string

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

name
string
Example: name=zone_example_name

The name of the zone

z-max
number
Example: z-max=5

The maximim z coordinate of the box which encloses the zone

y-max
number
Example: y-max=5

The maximum y coordinate of the box which encloses the zone

x-max
number
Example: x-max=5

The maximum x coordinate of the box which encloses the zone

x-min
number
Example: x-min=-5

The minimum x coordinate of the box which encloses the zone

z-min
number
Example: z-min=-5

The minimum z coordinate of the box which encloses the zone

y-min
number
Example: y-min=0

The minimum y coordinate of the box which encloses the zone

Responses

Response samples

Content type
application/json
{
  • "name": "zone_example_name",
  • "z-max": 5,
  • "id": 7,
  • "y-max": 5,
  • "x-max": 5,
  • "x-min": -5,
  • "z-min": -5,
  • "y-min": 0
}

Get or change a zone

This endpoint allows you to change zero or more editable properties of a zone in a space. When requested without specifying any properties to update, this endpoint returns the zone unaltered.

path Parameters
zone_id
required
integer
Example: 7

The unique ID of the zone to be updated

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

The unique ID of the space containing the zone to be updated

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 zone

z-max
number

The maximim z coordinate of the box which encloses the zone

y-max
number

The maximum y coordinate of the box which encloses the zone

x-max
number

The maximum x coordinate of the box which encloses the zone

x-min
number

The minimum x coordinate of the box which encloses the zone

z-min
number

The minimum z coordinate of the box which encloses the zone

y-min
number

The minimum y coordinate of the box which encloses the zone

Responses

Request samples

Content type
application/json
{
  • "name": "zone_example_name",
  • "z-max": 5,
  • "y-max": 5,
  • "x-max": 5,
  • "x-min": -5,
  • "z-min": -5,
  • "y-min": 0
}

Response samples

Content type
application/json
{
  • "name": "zone_example_name",
  • "z-max": 5,
  • "id": 7,
  • "y-max": 5,
  • "x-max": 5,
  • "x-min": -5,
  • "z-min": -5,
  • "y-min": 0
}

Delete a zone

This endpoint allows you to permanently delete a zone from a space. This will also delete any zone attenuations with a listener-zone-id or a source-zone-id equal to the deleted zone's ID.

path Parameters
zone_id
required
integer
Example: 7

The unique ID of the zone to be deleted

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

The unique ID of the space the zone will be deleted from

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
{
  • "id": 7
}

Create a zone

This endpoint allows you to create a zone in a space with the provided properties.

path Parameters
space_id
required
string

The unique ID of the space in which the zone will be created

query Parameters
token
required
string

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

name
required
string
Example: name=zone_example_name

The name of the zone

z-max
required
number
Example: z-max=5

The maximim z coordinate of the box which encloses the zone

y-max
required
number
Example: y-max=5

The maximum y coordinate of the box which encloses the zone

x-max
required
number
Example: x-max=5

The maximum x coordinate of the box which encloses the zone

x-min
required
number
Example: x-min=-5

The minimum x coordinate of the box which encloses the zone

z-min
required
number
Example: z-min=-5

The minimum z coordinate of the box which encloses the zone

y-min
required
number
Example: y-min=0

The minimum y coordinate of the box which encloses the zone

Responses

Response samples

Content type
application/json
{
  • "name": "zone_example_name",
  • "z-max": 5,
  • "id": 7,
  • "y-max": 5,
  • "x-max": 5,
  • "x-min": -5,
  • "z-min": -5,
  • "y-min": 0
}

Create a zone

This endpoint allows you to create a zone in a space with the provided properties.

path Parameters
space_id
required
string

The unique ID of the space in which the zone will be created

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

The name of the zone

z-max
required
number

The maximim z coordinate of the box which encloses the zone

y-max
required
number

The maximum y coordinate of the box which encloses the zone

x-max
required
number

The maximum x coordinate of the box which encloses the zone

x-min
required
number

The minimum x coordinate of the box which encloses the zone

z-min
required
number

The minimum z coordinate of the box which encloses the zone

y-min
required
number

The minimum y coordinate of the box which encloses the zone

Responses

Request samples

Content type
application/json
{
  • "name": "zone_example_name",
  • "z-max": 5,
  • "y-max": 5,
  • "x-max": 5,
  • "x-min": -5,
  • "z-min": -5,
  • "y-min": 0
}

Response samples

Content type
application/json
{
  • "name": "zone_example_name",
  • "z-max": 5,
  • "id": 7,
  • "y-max": 5,
  • "x-max": 5,
  • "x-min": -5,
  • "z-min": -5,
  • "y-min": 0
}

Get zone attenuations for a space

This endpoint allows you to get the list of all zone attenuations in the given space

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

The unique ID of the space to get zone attenuations from

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 zone attenuations

This endpoint allows you to create multiple zone attenuations at once in a space.

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

The unique ID of the space in which to create zone attenuations

query Parameters
token
required
string

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

Request Body schema: application/json
Array ()
listener-zone-id
required
integer

The unique ID of the zone in which this attenuation is experienced. Any clients listening to audio in this zone will perceive a difference in loudness in clients in the source zone as a result of this zone attenuation.

frequency-rolloff
number or null
Default: null

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source in the source zone. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which causes it to inherit the global frequency rolloff of the space, which is 16.0 by default. 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 global or per-user basis.

za-offset
required
integer

This setting affects the priority at which this zone attenuation gets applied. It can be either positive or negative. A lower value of this setting will cause this zone attenuation to be applied with higher priority. This is particularly useful when a smaller zone is inside a larger zone, and one wants to change how sound is produced by or heard in the smaller zone. In this case, if the zone attenuations related to the larger zone have za-offsets of 0, then the zone attenuations related to the smaller zone should have za-offsets smaller than that, such as -5, to override the attenuations of the larger zone.

attenuation
number or null
Default: null

Affects how quickly the volume of a sound decreases as one moves away from the sound source in the source zone. This does not affect the initial volume of the sound at the sound source. By default, this setting is null, which causes it to inherit the global attenuation of the space, which is 0.5 by default. 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.

Zone attenuations are particularly useful for creating distinct spatial audio environments within a space. It is also possible to create a 'stage' zone, such that audio sources within the zone are easily heard from other specified zones.

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.

It is also possible to set attenuation on a per-space or per-user basis.

source-zone-id
required
integer

The unique ID of the zone this attenuation affects the loudness of. Any clients producing audio in this zone will be perceived to have their loudness affected by this zone attenuation, from the perspective of clients in the listener zone.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Delete all zone attenuations

This endpoint allows you to permanently delete all zone attenuations in a space.

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

The unique ID of the space in which to delete all zone attenuations

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 zone attenuation

This endpoint allows you to create a zone attenuation for a space.

path Parameters
space_id
required
string

The unique ID of the space in which to create the zone attenuation

query Parameters
token
required
string

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

listener-zone-id
required
integer
Example: listener-zone-id=7

The unique ID of the zone in which this attenuation is experienced. Any clients listening to audio in this zone will perceive a difference in loudness in clients in the source zone as a result of this zone attenuation.

frequency-rolloff
number or null
Default: null
Example: frequency-rolloff=16

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source in the source zone. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which causes it to inherit the global frequency rolloff of the space, which is 16.0 by default. 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 global or per-user basis.

za-offset
required
integer
Example: za-offset=-5

This setting affects the priority at which this zone attenuation gets applied. It can be either positive or negative. A lower value of this setting will cause this zone attenuation to be applied with higher priority. This is particularly useful when a smaller zone is inside a larger zone, and one wants to change how sound is produced by or heard in the smaller zone. In this case, if the zone attenuations related to the larger zone have za-offsets of 0, then the zone attenuations related to the smaller zone should have za-offsets smaller than that, such as -5, to override the attenuations of the larger zone.

attenuation
number or null
Default: null
Example: attenuation=0.5

Affects how quickly the volume of a sound decreases as one moves away from the sound source in the source zone. This does not affect the initial volume of the sound at the sound source. By default, this setting is null, which causes it to inherit the global attenuation of the space, which is 0.5 by default. 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.

Zone attenuations are particularly useful for creating distinct spatial audio environments within a space. It is also possible to create a 'stage' zone, such that audio sources within the zone are easily heard from other specified zones.

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.

It is also possible to set attenuation on a per-space or per-user basis.

source-zone-id
required
integer
Example: source-zone-id=3

The unique ID of the zone this attenuation affects the loudness of. Any clients producing audio in this zone will be perceived to have their loudness affected by this zone attenuation, from the perspective of clients in the listener zone.

Responses

Response samples

Content type
application/json
{
  • "listener-zone-id": 7,
  • "frequency-rolloff": 16,
  • "za-offset": -5,
  • "id": 20,
  • "attenuation": 0.5,
  • "source-zone-id": 3
}

Create a zone attenuation

This endpoint allows you to create a zone attenuation for a space.

path Parameters
space_id
required
string

The unique ID of the space in which to create the zone attenuation

query Parameters
token
required
string

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

Request Body schema: application/json
listener-zone-id
required
integer

The unique ID of the zone in which this attenuation is experienced. Any clients listening to audio in this zone will perceive a difference in loudness in clients in the source zone as a result of this zone attenuation.

frequency-rolloff
number or null
Default: null

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source in the source zone. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which causes it to inherit the global frequency rolloff of the space, which is 16.0 by default. 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 global or per-user basis.

za-offset
required
integer

This setting affects the priority at which this zone attenuation gets applied. It can be either positive or negative. A lower value of this setting will cause this zone attenuation to be applied with higher priority. This is particularly useful when a smaller zone is inside a larger zone, and one wants to change how sound is produced by or heard in the smaller zone. In this case, if the zone attenuations related to the larger zone have za-offsets of 0, then the zone attenuations related to the smaller zone should have za-offsets smaller than that, such as -5, to override the attenuations of the larger zone.

attenuation
number or null
Default: null

Affects how quickly the volume of a sound decreases as one moves away from the sound source in the source zone. This does not affect the initial volume of the sound at the sound source. By default, this setting is null, which causes it to inherit the global attenuation of the space, which is 0.5 by default. 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.

Zone attenuations are particularly useful for creating distinct spatial audio environments within a space. It is also possible to create a 'stage' zone, such that audio sources within the zone are easily heard from other specified zones.

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.

It is also possible to set attenuation on a per-space or per-user basis.

source-zone-id
required
integer

The unique ID of the zone this attenuation affects the loudness of. Any clients producing audio in this zone will be perceived to have their loudness affected by this zone attenuation, from the perspective of clients in the listener zone.

Responses

Request samples

Content type
application/json
{
  • "listener-zone-id": 7,
  • "frequency-rolloff": 16,
  • "za-offset": -5,
  • "attenuation": 0.5,
  • "source-zone-id": 3
}

Response samples

Content type
application/json
{
  • "listener-zone-id": 7,
  • "frequency-rolloff": 16,
  • "za-offset": -5,
  • "id": 20,
  • "attenuation": 0.5,
  • "source-zone-id": 3
}

Get or change a zone attenuation

This endpoint allows you to update zero or more editable properties of a zone attenuation in a space. When requested without specifying any properties to update, this endpoint returns the specified zone attenuation unaltered.

path Parameters
zone_attenuation_id
required
integer
Example: 20

The unique ID of the zone attenuation to be changed

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

The unique ID of the space containing the zone attenuation

query Parameters
token
required
string

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

listener-zone-id
integer
Example: listener-zone-id=7

The unique ID of the zone in which this attenuation is experienced. Any clients listening to audio in this zone will perceive a difference in loudness in clients in the source zone as a result of this zone attenuation.

frequency-rolloff
number or null
Example: frequency-rolloff=16

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source in the source zone. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which causes it to inherit the global frequency rolloff of the space, which is 16.0 by default. 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 global or per-user basis.

za-offset
integer
Example: za-offset=-5

This setting affects the priority at which this zone attenuation gets applied. It can be either positive or negative. A lower value of this setting will cause this zone attenuation to be applied with higher priority. This is particularly useful when a smaller zone is inside a larger zone, and one wants to change how sound is produced by or heard in the smaller zone. In this case, if the zone attenuations related to the larger zone have za-offsets of 0, then the zone attenuations related to the smaller zone should have za-offsets smaller than that, such as -5, to override the attenuations of the larger zone.

attenuation
number or null
Example: attenuation=0.5

Affects how quickly the volume of a sound decreases as one moves away from the sound source in the source zone. This does not affect the initial volume of the sound at the sound source. By default, this setting is null, which causes it to inherit the global attenuation of the space, which is 0.5 by default. 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.

Zone attenuations are particularly useful for creating distinct spatial audio environments within a space. It is also possible to create a 'stage' zone, such that audio sources within the zone are easily heard from other specified zones.

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.

It is also possible to set attenuation on a per-space or per-user basis.

source-zone-id
integer
Example: source-zone-id=3

The unique ID of the zone this attenuation affects the loudness of. Any clients producing audio in this zone will be perceived to have their loudness affected by this zone attenuation, from the perspective of clients in the listener zone.

Responses

Response samples

Content type
application/json
{
  • "listener-zone-id": 7,
  • "frequency-rolloff": 16,
  • "za-offset": -5,
  • "id": 20,
  • "attenuation": 0.5,
  • "source-zone-id": 3
}

Get or change a zone attenuation

This endpoint allows you to update zero or more editable properties of a zone attenuation in a space. When requested without specifying any properties to update, this endpoint returns the specified zone attenuation unaltered.

path Parameters
zone_attenuation_id
required
integer
Example: 20

The unique ID of the zone attenuation to be changed

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

The unique ID of the space containing the zone attenuation

query Parameters
token
required
string

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

Request Body schema: application/json
listener-zone-id
integer

The unique ID of the zone in which this attenuation is experienced. Any clients listening to audio in this zone will perceive a difference in loudness in clients in the source zone as a result of this zone attenuation.

frequency-rolloff
number or null

Affects how quickly the volume of a sound decreases at high frequencies as one moves away from the sound source in the source zone. This causes sounds to seem more 'muffled' at greater distances. By default, this setting is null, which causes it to inherit the global frequency rolloff of the space, which is 16.0 by default. 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 global or per-user basis.

za-offset
integer

This setting affects the priority at which this zone attenuation gets applied. It can be either positive or negative. A lower value of this setting will cause this zone attenuation to be applied with higher priority. This is particularly useful when a smaller zone is inside a larger zone, and one wants to change how sound is produced by or heard in the smaller zone. In this case, if the zone attenuations related to the larger zone have za-offsets of 0, then the zone attenuations related to the smaller zone should have za-offsets smaller than that, such as -5, to override the attenuations of the larger zone.

attenuation
number or null

Affects how quickly the volume of a sound decreases as one moves away from the sound source in the source zone. This does not affect the initial volume of the sound at the sound source. By default, this setting is null, which causes it to inherit the global attenuation of the space, which is 0.5 by default. 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.

Zone attenuations are particularly useful for creating distinct spatial audio environments within a space. It is also possible to create a 'stage' zone, such that audio sources within the zone are easily heard from other specified zones.

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.

It is also possible to set attenuation on a per-space or per-user basis.

source-zone-id
integer

The unique ID of the zone this attenuation affects the loudness of. Any clients producing audio in this zone will be perceived to have their loudness affected by this zone attenuation, from the perspective of clients in the listener zone.

Responses

Request samples

Content type
application/json
{
  • "listener-zone-id": 7,
  • "frequency-rolloff": 16,
  • "za-offset": -5,
  • "attenuation": 0.5,
  • "source-zone-id": 3
}

Response samples

Content type
application/json
{
  • "listener-zone-id": 7,
  • "frequency-rolloff": 16,
  • "za-offset": -5,
  • "id": 20,
  • "attenuation": 0.5,
  • "source-zone-id": 3
}

Delete a zone attenuation

This endpoint allows you to permanently delete a zone attenuation from a space.

path Parameters
zone_attenuation_id
required
integer
Example: 20

The unique ID of the zone attenuation to be deleted

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

The unique ID of the space the zone attenuation will be deleted from

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
{
  • "id": 20
}

Get a setting for a space

This endpoint allows you to request a single setting for a space. The content returned by this endpoint varies based on the setting name provided. See documentation on getting a space for possible settings that can be requested.

path Parameters
setting_name
required
string
Example: global-volume-threshold

The name of the setting

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

The unique ID of the space from which to get the setting

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
{
  • "{setting_name}": null
}

Moderate a user in a space

This endpoint allows you to mute or unmute a user that is currently connected to the space

See also the JavaScript client API, which allows users to adjust the gain or mute other users for themselves only.

path Parameters
user_id
required
string
Example: example_user_id

The app-provided ID of the user that will be affected

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

The unique ID of the space in which the user is located

query Parameters
token
required
string

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

Request Body schema: application/json
mute
required
boolean

If 'true', the user will be silent to everyone in the space. In contrast to the mute functionality provided by the client-side API, this mute state is server-side and cannot be overridden by the client. The user must have this mute state set to 'false' through the Administrative REST API in order to be heard by other users again.

This mute state does not persist across user sessions. When a user muted on the server side reconnects to a space, or connects to a different space, they will no longer be muted on the server side.

Whenever a user is muted or unmuted on the server side, the server will also send a message to the user's client. In the JavaScript client API, this message toggles the ability of the client to umute audio devices. Clients using the Javascript client API can register an OnMuteChangedCallback to detect when the client has been muted or unmuted by an admin and display this information to the user.

Responses

Request samples

Content type
application/json
{
  • "mute": true
}

Response samples

Content type
application/json
Example
Success
Success
Error: Mixer connection
Error: Mixer error
{
  • "status": "success"
}

Kick a user from a space

This endpoint allows you to kick a user that is currently connected to the space

path Parameters
user_id
required
string
Example: example_user_id

The app-provided ID of the user that will be kicked from the space

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

The unique ID of the space from which the user will be kicked

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
Example
Success
Success
Error: Mixer connection
Error: Mixer error
{
  • "status": "success"
}

Retrieve users currently in a space

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

The unique ID of the space for which all users will have the given moderation action applied

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
[
  • {
    }
]

Moderate all users in a space

This endpoint allows you to mute or unmute all users that are currently connected to the space

See also the JavaScript client API, which allows users to adjust the gain or mute other users for themselves only.

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

The unique ID of the space for which all users will have the given moderation action applied

query Parameters
token
required
string

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

Request Body schema: application/json
mute
required
boolean

If 'true', all users currently connected to the space will be silent to everyone in the space. In contrast to the mute functionality provided by the client-side API, this mute state is server-side and cannot be overridden by the clients. All affected users must have this mute state set to 'false' through the Administrative REST API in order to be heard by other users again.

This mute state does not persist across user sessions. When a user muted on the server side reconnects to a space, or connects to a different space, they will no longer be muted on the server side.

Whenever a user is muted or unmuted on the server side, the server will also send a message to the user's client. In the JavaScript client API, this message toggles the ability of the client to umute audio devices. Clients using the Javascript client API can register an OnMuteChangedCallback to detect when the client has been muted or unmuted by an admin and display this information to the user.

Responses

Request samples

Content type
application/json
{
  • "mute": true
}

Response samples

Content type
application/json
Example
Success
Success
Error: Mixer connection
Error: Mixer error
{
  • "status": "success"
}

Kick all users from a space

This endpoint allows you to kick all users that are currently connected to the space

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

The unique ID of the space from which all users will be kicked

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
Example
Success
Success
Error: Mixer connection
Error: Mixer error
{
  • "status": "success"
}

Apps

The apps API endpoints can be used to manage apps for an account. You can create an app through your High Fidelity developer account. To manage spaces within an app, use the space API endpoints.

Update an app

This endpoint allows you to set a secret for signing webhook events for an app. Other properties of an app can be updated through the High Fidelity developer account.

For more information about how to set up a webserver to process webhook events, and what a webhook event looks like, please see the Express Webhook Endpoint Example.

path Parameters
app_id
required
string
Example: d463fabf-eda5-7907-338e-fc18aabf0f69

The unique ID of the 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
webhook-secret
required
string <uuid>

A secret key UUID that will be used by the servers to sign the webhook event payload using the HS256 algorithm. The UUID should be created using a cryptographically secure random number generator. This API will not disclose the secret once it is set. Do not share this secret.

Your server should always verify the signature in X-HighFidelity-Signature is correct, and that the expiration field (exp) is not in the past. For more information about how to set up a webserver to process webhook events, and what a webhook event looks like,, please see the Express Webhook Endpoint Example.

Responses

Request samples

Content type
application/json
{
  • "webhook-secret": "fb6f66df-9ace-4764-9d6e-ab786e7bf669"
}

Response samples

Content type
application/json
{
  • "id": "d463fabf-eda5-7907-338e-fc18aabf0f69"
}

Get webhooks for an app

This endpoint returns the list of webhooks which currently receive events for an app. Each webhook receives events whenever one or more users connect or disconnect from a space in the app.

For more information about how to set up a webserver to process webhook events, and what a webhook event looks like, please see the Express Webhook Endpoint Example.

path Parameters
app_id
required
string
Example: d463fabf-eda5-7907-338e-fc18aabf0f69

The unique ID of the 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 webhook

A webhook receives events for an app from a URL. Each webhook receives events whenever one or more users connect or disconnect from a space in the app.

For more information about how to set up a webserver to process webhook events, and what a webhook event looks like, please see the Express Webhook Endpoint Example.

path Parameters
app_id
required
string
Example: d463fabf-eda5-7907-338e-fc18aabf0f69

The unique ID of the 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
url
required
string <url> <= 4096 characters

The URL which receives webhook events.

Warning: HTTP webhook URLs should only be used for testing. Always use HTTPS webhook URLs in production to ensure security.

The URL must be able to receive POST requests which have the custom field X-HighFidelity-Signature in the HTTP header. The body of the request is the JSON payload containing the event information.

Your server should always verify the signature in X-HighFidelity-Signature is correct, and that the expiration field (exp) is not in the past. For more information about how to set up a webserver to process webhook events, and what a webhook event looks like, please see the Express Webhook Endpoint Example.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete a webhook

When a webhook is deleted, its URL no longer receives events.

path Parameters
webhook_id
required
integer
Example: 14

The unique ID of the webhook to be deleted

app_id
required
string
Example: d463fabf-eda5-7907-338e-fc18aabf0f69

The unique ID of the app from which the webhook will be deleted

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
{
  • "id": 14
}