Skip to main content

getSpatialPosition

Get the stored 3D position of a sound. Useful when you want to move a sound relative to where it is now.

getSpatialPosition(soundId: string): { x: number; y: number; z: number } | null;

Parameters​

ParameterTypeDefaultDescription
soundIdstringrequiredID of a loaded sound or of one of its instances.

Returns​

{ x: number; y: number; z: number } | null: the position last stored for the sound, or null when the id is unknown.

Example​

import { SoundHub } from 'soundhub';

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

soundHub.play('rain', { loop: true });
soundHub.setSpatialPosition(10, 0, -20, 'rain');

const position = soundHub.getSpatialPosition('rain'); // { x: 10, y: 0, z: -20 }
if (position) {
  // Nudge it one unit closer
  soundHub.setSpatialPosition(position.x, position.y, position.z + 1, 'rain');
}

Good to know​

  • A loaded sound that was never positioned returns defaultPanSpatialPosition from the hub config, { x: 0, y: 0, z: 0 } by default, not null.
  • The values are the rounded ones (2 decimals) that setSpatialPosition stored.
  • setPan and removeSpatialEffect put the stored position back to 0, 0, 0.
  • Streams are not looked up, so a stream id returns null.

See also​