Skip to main content

setSpatialOrientation

Point a sound in a direction. On its own this does nothing audible: it works together with the cone settings on the panner, such as a television facing into the room or a character talking away from you.

setSpatialOrientation(soundId: string, x: number, y: number, z: number, skipDispatchEvent?: boolean): void;

Parameters​

ParameterTypeDefaultDescription
soundIdstringrequiredID of a loaded sound or of one of its instances.
xnumberrequiredx part of the direction vector.
ynumberrequiredy part of the direction vector.
znumberrequiredz part of the direction vector. 0, 0, -1 points the same way the default listener looks.
skipDispatchEventbooleanfalseSet to true to leave out the spatial_orientation_changed event.

Returns​

Nothing.

Example​

coneInnerAngle and coneOuterAngle describe a cone. This method says where the cone points.

import { SoundHub } from 'soundhub';

const soundHub = new SoundHub();
await soundHub.loadSound('television', '/audio/television.mp3');

soundHub.play('television', { loop: true });
soundHub.setSpatialPosition(0, 0, 2, 'television');

soundHub.updatePannerConfigById('television', {
  coneInnerAngle: 60,    // full volume inside this cone
  coneOuterAngle: 180,   // quieter between the two
  coneOuterGain: 0.2,    // and this much outside it
});

soundHub.setSpatialOrientation('television', 0, 0, -1); // facing into the room

The same direction can be given when the sound starts, through panSpatialOrientation in the play options:

import { SoundPanType } from 'soundhub';

soundHub.play('television', {
  panType: SoundPanType.Spatial,
  panSpatialPosition: { x: 0, y: 0, z: 2 },
  panSpatialOrientation: { x: 0, y: 0, z: -1 },
});

Good to know​

  • Added in 6.2.0.
  • A sound without a 3D panner gets one at its current position, without a spatial_position_changed event, so calling this first is safe. That also switches the sound to spatial and removes its stereo panner.
  • The values are rounded to 2 decimals and written to the sound's play options, so the next play() points the same way.
  • Does nothing when spatial audio is off or unsupported. An unknown id is ignored without an error.
  • Every change dispatches SoundEventsEnum.SPATIAL_ORIENTATION_CHANGED ('spatial_orientation_changed') with orientation.
  • For the master panner, use setMasterSpatialOrientation.

See also​