Howler.js Spatial Audio distanceModel Explained

In modern web development, creating immersive 3D audio environments requires precise control over how sound behaves over distances. This article explains the distanceModel attribute in Howler.js, a popular JavaScript audio library. You will learn what the distanceModel attribute is, how it controls audio attenuation in spatial audio environments, and how to configure its various algorithms to achieve realistic 3D soundscapes.

What is the distanceModel Attribute?

In Howler.js, the distanceModel attribute determines the algorithm used to reduce the volume (attenuate) of a sound source as it moves further away from the listener. It is a direct binding to the Web Audio API’s PannerNode.distanceModel property.

When positioning audio in a 3D space, simply moving a sound to the left or right is not enough; the sound must also get quieter as the virtual distance between the listener and the audio source increases. The distanceModel defines the mathematical formula that calculates this volume reduction.

The Three Distance Models

Howler.js supports three distinct distance models, each suited for different acoustic scenarios:

1. Linear Model ('linear')

The linear model decreases the volume at a constant rate relative to the distance between the listener and the sound source.

• Behavior: The sound fades out in a straight line. Once the sound source reaches the defined maximum distance, the volume drops to zero.
• Best Used For: Simple UI sounds, directional cues, or situations where you need strict, predictable control over when a sound becomes completely silent.

2. Inverse Model ('inverse')

The inverse model decreases the volume inversely proportional to the distance. This is the default model used by Howler.js.

• Behavior: This model closely mimics how sound behaves in the real physical world. The volume drops off quickly as you first move away from the source, but the rate of decrease slows down the further away you get.
• Best Used For: Realistic physical environments, natural ambient sounds, and general 3D game audio.

3. Exponential Model ('exponential')

The exponential model decreases the volume at an exponential rate.

• Behavior: The sound volume drops extremely rapidly as the distance increases, fading to near silence very quickly.
• Best Used For: Simulating highly dampening environments (like being underwater or in a heavily padded room) or for dramatic audio focus shifts.

Configuring distanceModel in Howler.js

To utilize spatial audio and configure the distanceModel in Howler.js, you must ensure that your sound is loaded using the Web Audio API (by default, html5: false) and use the pannerAttr method on your Howl instance.

Here is a practical example of how to implement and configure the distanceModel:

// Initialize a spatial sound
const 3dSound = new Howl({
  src: ['ambient_space.mp3'],
  html5: false // Must be false to use the Web Audio API spatial features
});

// Configure the spatial attributes
3dSound.pannerAttr({
  distanceModel: 'inverse', // Options: 'linear', 'inverse', 'exponential'
  refDistance: 1,           // The distance at which volume starts to reduce
  maxDistance: 1000,        // The distance past which volume stops reducing
  rolloffFactor: 1          // How quickly the volume fades
});

// Position the sound in 3D space (X, Y, Z coordinates)
3dSound.pos(5, 0, -10);

// Play the sound
3dSound.play();

Supporting Attributes

The distanceModel does not work in isolation. Its behavior is directly scaled and modified by three other key properties inside the pannerAttr object:

• refDistance: The distance at which the sound volume begins to decrease. Inside this range, the sound plays at its maximum volume.
• rolloffFactor: A multiplier that dictates how fast the sound attenuates. A higher factor causes the volume to drop off much faster as distance increases.
• maxDistance: Used primarily by the linear model, this defines the distance limit beyond which the sound is no longer attenuated (or becomes completely silent, depending on the model).