- Qt 6.8
- Qt Spatial Audio
- QML Types
- SpatialSound
- Technology Preview

# SpatialSound QML Type

A sound object in 3D space. More...

Import Statement: | `import QtQuick3D.SpatialAudio`

- List of all members, including inherited members

## Properties

- autoPlay : bool
- directivity : real
- directivityOrder : real
- distanceCutoff : real
- distanceModel : enumeration
- loops : int
- manualAttenuation : real
- nearFieldGain : real
- occlusionIntensity : real
- size : real
- source : url
- volume : real

## Methods

- pause()
- play()
- stop()

## Detailed Description

A SpatialSound represents an audible object in 3D space. You can define it's position and orientation in space, set the sound it is playing and define a volume for the object.

The object can have different attenuation behavior, emit sound mainly in one direction or spherically, and behave as if occluded by some other object.

## Property Documentation

autoPlay : bool

Determines whether the sound should automatically start playing when a source gets specified.

The default value is `true`.

directivity : real

Defines the directivity of the sound source. A value of 0 implies that the sound is emitted equally in all directions, while a value of 1 implies that the source mainly emits sound in the forward direction.

Valid values are between 0 and 1, the default is 0.

directivityOrder : real

Defines the order of the directivity of the sound source. A higher order implies a sharper localization of the sound cone.

The minimum value and default for this property is 1.

distanceCutoff : real

Defines a distance beyond which sound coming from the source will cutoff. If the listener is further away from the sound object than the cutoff distance it won't be audible anymore.

distanceModel : enumeration

Defines how the volume of the sound scales with distance to the listener. The volume starts scaling down from size to distanceCutoff. The volume is constant for distances smaller than size and zero for distances larger than the cutoff distance.

Property value | Description
--- | ---
Logarithmic | Volume decreases logarithmically with distance.
Linear | Volume decreases linearly with distance.
ManualAttenuation | Attenuation is defined manually using the manualAttenuation property.

loops : int

Determines how often the sound is played before the player stops. Set to SpatialSound::Infinite to loop the current sound forever.

The default value is `1`.

manualAttenuation : real

Defines a manual attenuation factor if distanceModel is set to SpatialSound.ManualAttenuation.

nearFieldGain : real

Defines the near field gain for the sound source. Valid values are between 0 and 1. A near field gain of 1 will raise the volume of the sound signal by approx 20 dB for distances very close to the listener.

occlusionIntensity : real

Defines how much the object is occluded. 0 implies the object is not occluded at all, while a large number implies a large occlusion.

The default is 0.

size : real

Defines the size of the sound source. If the listener is closer to the sound object than the size, volume will stay constant. The size is also used to for occlusion calculations, where large sources can be partially occluded by a wall.

source : url

The source file for the sound to be played.

volume : real

Defines an overall volume for this sound source.

Values between 0 and 1 will attenuate the sound, while values above 1 provide an additional gain boost.

## Method Documentation

pause()

Pauses sound playback at the current position. Calling play() will continue playback.

play()

Starts playing back the sound. Does nothing if the sound is already playing.

stop()

Stops sound playback and resets the current position and loop count to 0. Calling play() will begin playback at the beginning of the sound file.