How To Use Attenuation and Audio Zones in High Fidelity's Spatial Audio API

There’s just something about a quiet whisper, a distant thunderclap, the voice of a good friend — all sounds that stir up emotions and memories.  Especially when they feel ‘real.’  Much goes into making sounds realistic: fidelity, latency, spatialization, frequency roll-off, attenuation. In this post, we’ll talk about attenuation, and how you can use it to create authentic or unusual audio environments.

Attenuation, What Is It?

As you move away from the source of a sound, it gets quieter. That’s attenuation.  Sure, there’s a lot of math involved, but the basic concept is really quite simple.

High Fidelity's Spatial Audio API approximates real-world attenuation based on an attenuation coefficient which is multiplied by the log2 of the distance.  Think of it this way — if the attenuation coefficient is 0.5, the amplitude of the audio signal would drop by half per doubling in distance (or -6dB.)  A sound would be half as loud if you move twice as far from it.

In the Spatial Audio API, the attenuation coefficient is represented by a floating point number that ranges from 0.0 to 1.0, where 1.0 is full attenuation (audio drops to silent immediately,) and 0.0 means there is no attenuation (audio travels forever at the same loudness.)

By default, we use an attenuation coefficient of 0.5, which is a fair approximation of the real world.

By changing the attenuation coefficient, you can achieve cool things like simulated underwater environments where sound travels farther, or you can make your environment more intimate by increasing the attenuation.

Audio Zones, The Why and How

The Spatial Audio API offers the ability to define zones within your 3-D space that have different audio characteristics, such as attenuation.  This allows you to create features in your application such as private rooms.

Audio Zones are simply cuboids (3d rectangles) in space, defined by minimum and maximum values along the three Cartesian axes.  Note that in audio zones, the Y coordinate is the vertical, with positive values being up, and negative values being down.

Attenuation coefficients within or between zones are managed as separate objects, called Zone Attenuations.  Each Zone Attenuation object comprises a source zone identifier, a listener zone identifier, and an attenuation coefficient.

When the Spatial Audio API processes audio, it determines which Audio Zone(s) contain the audio source and which Audio Zone(s) contain the listener.  It then iterates through the list of Zone Attenuation objects in order, searching for a one that matches the source’s Audio Zone(s), and the listener’s Audio Zone(s).  It will then use the Attenuation associated with that Zone Attenuation object.

If no Zone Attenuation objects are found that match the source and listener Audio Zones, or the source and/or listener are not within any Audio Zones, the default global attenuation will be used.

With a carefully chosen selection of Audio Zone and Zone Attenuation objects, you create interesting environments.

Private Rooms

One of the more common uses of Audio Zones is the creation of private rooms within a space, where audio from within the room is inaudible outside the room.  This is fairly easy to set up using Audio Zones and Zone Attenuations.

First, you’ll need to create a very large Audio Zone representing the world.  Then you’ll need to create a smaller Audio Zone representing the private room, set within the ‘world’ zone.

Audio Zones

You’ll then need to specify the attenuations between the zones.

Zone Attenuations

Finally, set the default global attenuation to 1.0.

Zone attenuations are evaluated in order, starting with the first, then the second, then the third, and so on.  This means if the speaker and the listener are both in the room, the first line in the Zone Attenuations table will match before the other lines, and the attenuation chosen will be 0.5, which is audible.  This means clients within the room can hear one another.

If the speaker is in the room, and the listener is outside the room, but in the world, then the attenuation will be chosen from the second line, with an attenuation of 1.0, or silent, which prevents the listener from hearing the speaker.

Ordering is important in the Zone Attenuations table, as any client within the ‘room’ zone is also within the ‘world’ zone.  If the order were reversed, then all clients, regardless of whether they were in the room or just in the world, could hear one another.

Presentation Space

Another example using Audio Zones is the presentation space, where a presenter needs to be heard clearly across a large audience, but the audience’s voices shouldn’t carry far.

This can be set up as follows:

Audio Zones

Zone Attenuations

You’ll then need to specify the attenuations between the zones.

Default Global Attenuation: 0.95

In this case, anyone standing at the podium will be highly audible across the entire audience, as the attenuation is 0.05.  Audience members themselves will use the default attenuation (0.95), and will only be audible to their nearest neighbors.

Zone Management in High Fidelity's Spatial Audio API

High Fidelity's Spatial Audio provides a RESTful API for management of Audio Zones and Zone Attenuations — High Fidelity Administrative REST API.

We’ve also provided an example using Audio Zones via the High Fidelity Administrative REST API in our Spatial Audio API Examples repository here: The Office. This example uses Audio Zones to create private rooms in a 2D space.

In this section, we’ll focus on the code that creates the Audio Zones using the RESTful API. That code, a simple node program, can be found in the /util subdirectory of The Office repository. Instructions for running the audio environment utility are found in the README.md of The Office project.

The audio environment utility simply reads a data file that defines the audio zones and some additional rendering data. A simplified version with one room embedded in an office space is shown below:

The coordinates of the zones should be clear. The attenuation_coefficient sections are there to override the coefficients that are automatically calculated by the code below, so they are not used here.  The doors definitions are used only in the client code, and are not of interest as far as audio zones are concerned.

The Audio Zones are then created in the generateZones function. The generateZones function contains a helper function to build the path to the specified endpoint, as follows:

Stack will be api.highfidelity.com, space is the ID of your space, and jwt is your Space Administrative Token (it’s important that this is an Admin token). See Get A JWT and Programmatic Space Management for details.

Initially, generateZones deletes all existing zones via the DELETE endpoint.

Then, it sets the default global attenuation to 1.0, or silent, using the POST endpoint.

Next, it creates a JSON containing all of the zones that needs to be created, and sends those to the POST endpoint.

The response to that endpoint contains the IDs of the create zones in order.  Those are saved to be used later when creating the Zone Attenuation objects.

Following is the JSON created by this code for the example data file given above:

Finally, the code generates and uploads the Zone Attenuation objects, using the POST endpoint.

Example JSON sent to the endpoint is as follows, with the room Audio Zone having an ID of 1, and the all Audio Zone having an ID of 2 (IDs may be anything, don’t assume they start at 1 and increment by 1):

Zone Attenuation objects are ordered, as discussed in the previous section, and that order is managed by the za-offset parameter.

Conclusion

Attenuation and Zones are powerful tools that let you emulate many real-world audio environments and even some that aren’t so real. Play with them. Have fun. We look forward to seeing the magical environments you come up with.

If you have questions, we’re here to help. The journey begins by creating your free developer account below...

Feature image credit to Unsplash.