QSpatialSound

A sound object in 3D space. More…

Synopsis

Functions

• def autoPlay ()

• def directivity ()

• def directivityOrder ()

• def distanceCutoff ()

• def distanceModel ()

• def engine ()

• def loops ()

• def manualAttenuation ()

• def nearFieldGain ()

• def occlusionIntensity ()

• def position ()

• def rotation ()

• def setAutoPlay (autoPlay)

• def setDirectivity (alpha)

• def setDirectivityOrder (alpha)

• def setDistanceCutoff (cutoff)

• def setDistanceModel (model)

• def setLoops (loops)

• def setManualAttenuation (attenuation)

• def setNearFieldGain (gain)

• def setOcclusionIntensity (occlusion)

• def setPosition (pos)

• def setRotation (q)

• def setSize (size)

• def setSource (url)

• def setVolume (volume)

• def size ()

• def source ()

• def volume ()

Slots

• def pause ()

• def play ()

• def stop ()

Signals

• def autoPlayChanged ()

• def directivityChanged ()

• def directivityOrderChanged ()

• def distanceCutoffChanged ()

• def distanceModelChanged ()

• def loopsChanged ()

• def manualAttenuationChanged ()

• def nearFieldGainChanged ()

• def occlusionIntensityChanged ()

• def positionChanged ()

• def rotationChanged ()

• def sizeChanged ()

• def sourceChanged ()

• def volumeChanged ()

Detailed Description

QSpatialSound represents an audible object in 3D space. You can define its 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.

class PySide6.QtSpatialAudio.QSpatialSound(engine)

Parameters

engine – PySide6.QtSpatialAudio.QAudioEngine

Creates a spatial sound source for engine. The object can be placed in 3D space and will be louder the closer to the listener it is.

PySide6.QtSpatialAudio.QSpatialSound.Loops

PySide6.QtSpatialAudio.QSpatialSound.DistanceModel

Defines how the volume of the sound scales with distance to the listener.

Constant	Description
QSpatialSound.DistanceModel.Logarithmic	Volume decreases logarithmically with distance.
QSpatialSound.DistanceModel.Linear	Volume decreases linearly with distance.
QSpatialSound.DistanceModel.ManualAttenuation	Attenuation is defined manually using the manualAttenuation property.

PySide6.QtSpatialAudio.QSpatialSound.autoPlay()

Return type

bool

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

The default value is true.

PySide6.QtSpatialAudio.QSpatialSound.autoPlayChanged()

PySide6.QtSpatialAudio.QSpatialSound.directivity()

Return type

float

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.

PySide6.QtSpatialAudio.QSpatialSound.directivityChanged()

PySide6.QtSpatialAudio.QSpatialSound.directivityOrder()

Return type

float

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.

PySide6.QtSpatialAudio.QSpatialSound.directivityOrderChanged()

PySide6.QtSpatialAudio.QSpatialSound.distanceCutoff()

Return type

float

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.

PySide6.QtSpatialAudio.QSpatialSound.distanceCutoffChanged()

PySide6.QtSpatialAudio.QSpatialSound.distanceModel()

Return type

DistanceModel

Defines distance model for this sound source. 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.

See also

DistanceModel

PySide6.QtSpatialAudio.QSpatialSound.distanceModelChanged()

PySide6.QtSpatialAudio.QSpatialSound.engine()

Return type

PySide6.QtSpatialAudio.QAudioEngine

Returns the engine associated with this listener.

PySide6.QtSpatialAudio.QSpatialSound.loops()

Return type

int

Determines how many times the sound is played before the player stops. Set to QSpatialSound::Infinite to play the current sound in a loop forever.

The default value is 1.

PySide6.QtSpatialAudio.QSpatialSound.loopsChanged()

PySide6.QtSpatialAudio.QSpatialSound.manualAttenuation()

Return type

float

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

PySide6.QtSpatialAudio.QSpatialSound.manualAttenuationChanged()

PySide6.QtSpatialAudio.QSpatialSound.nearFieldGain()

Return type

float

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.

PySide6.QtSpatialAudio.QSpatialSound.nearFieldGainChanged()

PySide6.QtSpatialAudio.QSpatialSound.occlusionIntensity()

Return type

float

Defines how much the object is occluded. 0 implies the object is not occluded at all, 1 implies the sound source is fully occluded by another object.

A fully occluded object will still be audible, but especially higher frequencies will be dampened. In addition, the object will still participate in generating reverb and reflections in the room.

Values larger than 1 are possible to further dampen the direct sound coming from the source.

The default is 0.

PySide6.QtSpatialAudio.QSpatialSound.occlusionIntensityChanged()

PySide6.QtSpatialAudio.QSpatialSound.pause()

Pauses sound playback. Calling play() will continue playback.

PySide6.QtSpatialAudio.QSpatialSound.play()

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

PySide6.QtSpatialAudio.QSpatialSound.position()

Return type

PySide6.QtGui.QVector3D

Defines the position of the sound source in 3D space. Units are in centimeters by default.

See also

distanceScale

PySide6.QtSpatialAudio.QSpatialSound.positionChanged()

PySide6.QtSpatialAudio.QSpatialSound.rotation()

Return type

PySide6.QtGui.QQuaternion

Defines the orientation of the sound source in 3D space.

PySide6.QtSpatialAudio.QSpatialSound.rotationChanged()

PySide6.QtSpatialAudio.QSpatialSound.setAutoPlay(autoPlay)

Parameters

autoPlay – bool

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

The default value is true.

PySide6.QtSpatialAudio.QSpatialSound.setDirectivity(alpha)

Parameters

alpha – float

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.

PySide6.QtSpatialAudio.QSpatialSound.setDirectivityOrder(alpha)

Parameters

alpha – float

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.

PySide6.QtSpatialAudio.QSpatialSound.setDistanceCutoff(cutoff)

Parameters

cutoff – float

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.

PySide6.QtSpatialAudio.QSpatialSound.setDistanceModel(model)

Parameters

model – DistanceModel

Defines distance model for this sound source. 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.

See also

DistanceModel

PySide6.QtSpatialAudio.QSpatialSound.setLoops(loops)

Parameters

loops – int

Determines how many times the sound is played before the player stops. Set to QSpatialSound::Infinite to play the current sound in a loop forever.

The default value is 1.

PySide6.QtSpatialAudio.QSpatialSound.setManualAttenuation(attenuation)

Parameters

attenuation – float

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

PySide6.QtSpatialAudio.QSpatialSound.setNearFieldGain(gain)

Parameters

gain – float

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.

PySide6.QtSpatialAudio.QSpatialSound.setOcclusionIntensity(occlusion)

Parameters

occlusion – float

Defines how much the object is occluded. 0 implies the object is not occluded at all, 1 implies the sound source is fully occluded by another object.

A fully occluded object will still be audible, but especially higher frequencies will be dampened. In addition, the object will still participate in generating reverb and reflections in the room.

Values larger than 1 are possible to further dampen the direct sound coming from the source.

The default is 0.

PySide6.QtSpatialAudio.QSpatialSound.setPosition(pos)

Parameters

pos – PySide6.QtGui.QVector3D

Defines the position of the sound source in 3D space. Units are in centimeters by default.

See also

distanceScale

PySide6.QtSpatialAudio.QSpatialSound.setRotation(q)

Parameters

q – PySide6.QtGui.QQuaternion

Defines the orientation of the sound source in 3D space.

PySide6.QtSpatialAudio.QSpatialSound.setSize(size)

Parameters

size – float

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.

PySide6.QtSpatialAudio.QSpatialSound.setSource(url)

Parameters

url – PySide6.QtCore.QUrl

The source file for the sound to be played.

PySide6.QtSpatialAudio.QSpatialSound.setVolume(volume)

Parameters

volume – float

Defines the volume of the sound.

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

PySide6.QtSpatialAudio.QSpatialSound.size()

Return type

float

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.

PySide6.QtSpatialAudio.QSpatialSound.sizeChanged()

PySide6.QtSpatialAudio.QSpatialSound.source()

Return type

PySide6.QtCore.QUrl

The source file for the sound to be played.

PySide6.QtSpatialAudio.QSpatialSound.sourceChanged()

PySide6.QtSpatialAudio.QSpatialSound.stop()

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

PySide6.QtSpatialAudio.QSpatialSound.volume()

Return type

float

Defines the volume of the sound.

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

PySide6.QtSpatialAudio.QSpatialSound.volumeChanged()