Understanding coneOuterAngle in Howler.js

This article explains the coneOuterAngle setting in the howler.js JavaScript audio library, focusing on how it shapes spatial audio directionality. You will learn what this property does, how it works in conjunction with other Web Audio API properties, and how to use it to create realistic 3D soundscapes in your web applications.

In howler.js, spatial audio allows you to position sound sources in a 3D coordinate space. By default, these sounds are omnidirectional, meaning they project equally in all directions. The coneOuterAngle property is used to change this behavior, turning an omnidirectional sound source into a directional one, much like a megaphone, a flashlight beam, or a human voice.

The coneOuterAngle represents an angle, in degrees, that defines a cone of sound emission. Specifically, it determines the outer boundary of the sound projection. Outside of this designated angle, the sound volume drops to a constant, lower level defined by the coneOuterGain property.

To understand how coneOuterAngle behaves, it is helpful to look at how it interacts with two other spatial audio properties inside the howler.js pannerAttr method:

• coneInnerAngle: The inner cone angle (in degrees) within which the sound is played at its full, original volume.
• coneOuterAngle: The outer cone angle (in degrees) outside of which the sound is attenuated to the level set by coneOuterGain.
• coneOuterGain: A value between 0.0 and 1.0 that defines the volume of the sound outside the coneOuterAngle.

When a listener is positioned within the coneInnerAngle, they hear the audio at 100% volume. As the listener moves from the edge of the coneInnerAngle to the edge of the coneOuterAngle, the sound volume gradually transitions (fades) down. Once the listener passes outside the coneOuterAngle boundary, the volume remains constant at the specified coneOuterGain level.

Implementation Example

To use coneOuterAngle, you must define the spatial properties of your Howl instance using the pannerAttr method. You must also set an orientation for the sound so the system knows which way the sound cone is pointing.

const spatialSound = new Howl({
  src: ['audio.mp3'],
  html5: false // Web Audio API is required for spatial audio
});

// Position the sound in 3D space [x, y, z]
spatialSound.pos(0, 0, 0);

// Point the sound direction [x, y, z]
spatialSound.orientation(1, 0, 0);

// Configure the sound cone
spatialSound.pannerAttr({
  coneInnerAngle: 60,   // Full volume within a 60-degree cone
  coneOuterAngle: 120,  // Sound fades out between 60 and 120 degrees
  coneOuterGain: 0.1    // Volume drops to 10% outside the 120-degree cone
});

By default, both coneInnerAngle and coneOuterAngle are set to 360 degrees, which maintains an omnidirectional sound source. Adjusting coneOuterAngle to a smaller value is essential for creating realistic directional sound effects, such as a character speaking in a specific direction or a speaker playing music forward into a room.