Skip to main content

setSpatialOrientation

setSpatialOrientation(soundId: string, x: number, y: number, z: number, skipDispatchEvent?: boolean): void;
getSpatialOrientation(soundId: string): { x: number; y: number; z: number } | null;

Point a sound in a direction.

Added in 6.2.0.

On its own this does nothing audible. It gets interesting together with coneInnerAngle and coneOuterAngle on the panner config: those describe a cone, and this says where the cone points. A television facing into the room, a character talking away from you, a speaker aimed at the stage.

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

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:

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

A sound with no panner yet gets one, positioned where it already is, so calling this first is safe. Every change puts a spatial_orientation_changed event on the bus.

The master panner​

setMasterSpatialOrientation(x, y, z) does the same for the master panner, for when you position the whole mix at once, with getMasterSpatialOrientation() to read it back.

See also​