API
API|
@babylonjs/core|
ISoundSourceOptions

Interface ISoundSourceOptions

Options for creating a sound source.

interface ISoundSourceOptions {
    analyzerEnabled: boolean;
    analyzerFFTSize: AudioAnalyzerFFTSizeType;
    analyzerMaxDecibels: number;
    analyzerMinDecibels: number;
    analyzerSmoothing: number;
    mediaStreamSinkEnabled: boolean;
    outBus: Nullable<PrimaryAudioBus>;
    outBusAutoDefault: boolean;
    spatialAutoUpdate: boolean;
    spatialConeInnerAngle: number;
    spatialConeOuterAngle: number;
    spatialConeOuterVolume: number;
    spatialDistanceModel: "linear" | "inverse" | "exponential";
    spatialEnabled: boolean;
    spatialMaxDistance: number;
    spatialMinDistance: number;
    spatialMinUpdateTime: number;
    spatialOrientation: Vector3;
    spatialPanningEnabled: boolean;
    spatialPanningModel: "equalpower" | "HRTF";
    spatialPosition: Vector3;
    spatialRolloffFactor: number;
    spatialRotation: Vector3;
    spatialRotationQuaternion: Quaternion;
    stereoEnabled: boolean;
    stereoPan: number;
    stopMediaStreamTracksOnDispose: boolean;
    volume: number;
}

Hierarchy (View Summary)

Index
analyzerEnabled analyzerFFTSize analyzerMaxDecibels analyzerMinDecibels analyzerSmoothing mediaStreamSinkEnabled outBus outBusAutoDefault spatialAutoUpdate spatialConeInnerAngle spatialConeOuterAngle spatialConeOuterVolume spatialDistanceModel spatialEnabled spatialMaxDistance spatialMinDistance spatialMinUpdateTime spatialOrientation spatialPanningEnabled spatialPanningModel spatialPosition spatialRolloffFactor spatialRotation spatialRotationQuaternion stereoEnabled stereoPan stopMediaStreamTracksOnDispose volume
analyzerEnabled: boolean

Enable the audio analyzer. Defaults to false.

analyzerFFTSize: AudioAnalyzerFFTSizeType

The size of the FFT (fast fourier transform) to use when converting time-domain data to frequency-domain data. Default is 2048.

analyzerMaxDecibels: number

The maximum decibel value for the range of the analyzer. Default is -30.

analyzerMinDecibels: number

The minimum decibel value for the range of the analyzer. Default is -100.

analyzerSmoothing: number

A number between 0 and 1 that determines how quickly the analyzer's value changes. Default is 0.8.

mediaStreamSinkEnabled: boolean

Whether a MediaStream-backed sound source (for example, a MediaStreamAudioSourceNode created from a remote WebRTC stream) is automatically kept audible by attaching its MediaStream to a hidden, muted HTMLAudioElement. Defaults to true.

Some browsers (notably Chromium) only deliver audio samples from a MediaStreamAudioSourceNode while the underlying MediaStream is also being pulled by an HTMLMediaElement. Without this, a remote WebRTC stream routed through the Web Audio graph is silent and therefore cannot be heard or spatialized. The attached element is muted so it does not add a second, non-spatial playback of the stream.

Set this to false if you are already routing the same MediaStream through your own HTMLMediaElement, to avoid creating a redundant one. Has no effect for sources that are not backed by a MediaStreamAudioSourceNode.

outBus: Nullable<PrimaryAudioBus>

The output bus for the sound source. Defaults to null.

  • If not set or null, and outBusAutoDefault is true, then the sound source is automatically connected to the audio engine's default main bus.

AudioEngineV2.defaultMainBus

outBusAutoDefault: boolean

Whether the sound's outBus should default to the audio engine's main bus. Defaults to true for all sound sources except microphones.

spatialAutoUpdate: boolean

Whether to automatically update the spatial properties of the audio node. Defaults to true.

spatialConeInnerAngle: number

The spatial cone inner angle, in radians. Defaults to 2π.

  • When the listener is inside the cone inner angle, the volume is at its maximum.
spatialConeOuterAngle: number

The spatial cone outer angle, in radians. Defaults to 2π.

  • When the listener is between the the cone inner and outer angles, the volume fades to its minimum as the listener approaches the outer angle.
  • When the listener is outside the cone outer angle, the volume is at its minimum.
spatialConeOuterVolume: number

The amount of volume reduction outside the spatialConeOuterAngle. Defaults to 0.

spatialDistanceModel: "linear" | "inverse" | "exponential"

The algorithm to use to reduce the volume of the audio source as it moves away from the listener. Defaults to "inverse".

Possible values are:

  • "linear": The volume is reduced linearly as the source moves away from the listener.
  • "inverse": The volume is reduced inversely as the source moves away from the listener.
  • "exponential": The volume is reduced exponentially as the source moves away from the listener.
spatialEnabled: boolean

Enable spatial audio. Defaults to false.

When set to true, the audio node's spatial properties will be initialized on creation and there will be no delay when setting the first spatial value.

When not specified, or set to false, the audio node's spatial properties will not be initialized on creation and there will be a small delay when setting the first spatial value.

  • This option is ignored if any other spatial options are set.
spatialMaxDistance: number

The maximum distance between the audio source and the listener, after which the volume is not reduced any further. Defaults to 10000.

spatialDistanceModel

spatialMinDistance: number

The distance for reducing volume as the audio source moves away from the listener – i.e. the distance the volume reduction starts at. Defaults to 1.

  • This value is used by all distance models.

spatialDistanceModel

spatialMinUpdateTime: number

The minimum update time in seconds of the spatialization if it is attached to a mesh or transform node. Defaults to 0.

  • The spatialization's position and rotation will not update faster than this time, but they may update slower depending on the frame rate.
spatialOrientation: Vector3

The spatial orientation used to determine the direction of the audio source. Defaults to (0, 0, -1).

spatialPanningEnabled: boolean

Whether to spatially pan the audio source. Defaults to true.

When set to false, the source keeps distance attenuation but does not pan between the left and right channels. Sound cone attenuation is not applied while panning is disabled.

spatialPanningModel: "equalpower" | "HRTF"

Possible values are:

  • "equalpower": Represents the equal-power panning algorithm, generally regarded as simple and efficient.
  • "HRTF": Renders a stereo output of higher quality than "equalpower" — it uses a convolution with measured impulse responses from human subjects.
spatialPosition: Vector3

The spatial position. Defaults to (0, 0, 0).

spatialRolloffFactor: number

How quickly the volume is reduced as the source moves away from the listener. Defaults to 1.

  • This value is used by all distance models.

spatialDistanceModel

spatialRotation: Vector3

The spatial rotation, as Euler angles. Defaults to (0, 0, 0).

spatialRotationQuaternion: Quaternion

The spatial rotation, as a quaternion. Defaults to (0, 0, 0, 1).

stereoEnabled: boolean

Enable stereo. Defaults to false.

When set to true, the audio node's stereo properties will be initialized on creation and there will be no delay when setting the first stereo value.

When not specified, or set to false, the audio node's stereo properties will not be initialized on creation and there will be a small delay when setting the first stereo value.

  • This option is ignored if any other stereo options are set.
stereoPan: number

The stereo pan from -1 (left) to 1 (right). Defaults to 0.

stopMediaStreamTracksOnDispose: boolean

Whether disposing the sound source stops the tracks of its backing MediaStream (via MediaStreamTrack.stop()). Defaults to false.

When the MediaStream is owned by the caller (for example, a remote WebRTC stream), stopping its tracks on dispose would permanently end them and could not be resumed without renegotiation, so the sound source leaves the stream lifecycle to the caller by default. The microphone source enables this so it releases the capture device it owns.

Set this to true if the sound source should own and stop the stream's tracks when disposed. Has no effect for sources that are not backed by a MediaStreamAudioSourceNode.

volume: number

The volume/gain. Defaults to 1.