Skip to main content

setListenerPosition

setListenerPosition(x: number, y: number, z: number, skipDispatchEvent?: boolean): void;
setListenerOrientation(
  forwardX: number, forwardY: number, forwardZ: number,
  upX?: number, upY?: number, upZ?: number,
  skipDispatchEvent?: boolean
): void;

The listener is the ear in the scene. Moving sounds around a fixed ear works for a menu or a map. A first-person camera needs the other way round: the sounds stay where they are and you move.

Added in 6.2.0.

function onFrame() {
  soundHub.setListenerPosition(player.x, 0, player.z);
  soundHub.setListenerOrientation(camera.forwardX, 0, camera.forwardZ);
}

Both ways use the same panner nodes, so you can mix them: move the listener with the camera and keep moving a helicopter with setSpatialPosition.

The two vectors​

setListenerOrientation takes a forward vector and an up vector. Forward is where the head is looking. Up is which way is up, so tilting the camera does not roll the sound around your head. The defaults are the Web Audio ones: looking down negative z, up along y.

soundHub.setListenerOrientation(0, 0, -1);          // straight ahead, the default
soundHub.setListenerOrientation(1, 0, 0);           // turned a quarter to the right
soundHub.setListenerOrientation(0, 0, -1, 0, 0, 1); // lying on your side

Reading it back​

soundHub.getListenerPosition();     // { x: 3, y: 0, z: -4 }
soundHub.getListenerOrientation();  // { forward: { x, y, z }, up: { x, y, z } }
soundHub.resetListener();           // back to the centre, looking down negative z

Every change puts a listener_changed event on the bus, carrying position, orientation and up.

Spatial audio has to be enabled for any of this, which it is by default. On a browser without the audio params for the listener, the older setPosition and setOrientation are used instead, so nothing extra is needed for old Safari.

See also​