QAudioEngine#

QAudioEngine manages a three dimensional sound field. More…

Synopsis#

Properties#

distanceScale
masterVolume
outputDevice
outputMode
paused

Functions#

def distanceScale ()
def masterVolume ()
def outputDevice ()
def outputMode ()
def paused ()
def roomEffectsEnabled ()
def sampleRate ()
def setDistanceScale (scale)
def setMasterVolume (volume)
def setOutputDevice (device)
def setOutputMode (mode)
def setPaused (paused)
def setRoomEffectsEnabled (enabled)

Slots#

def pause ()
def resume ()
def start ()
def stop ()

Signals#

def distanceScaleChanged ()
def masterVolumeChanged ()
def outputDeviceChanged ()
def outputModeChanged ()
def pausedChanged ()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

You can use an instance of QAudioEngine to manage a sound field in three dimensions. A sound field is defined by several QSpatialSound objects that define a sound at a specified location in 3D space. You can also add stereo overlays using QAmbientSound .

You can use QAudioListener to define the position of the person listening to the sound field relative to the sound sources. Sound sources will be less audible if the listener is further away from source. They will also get mapped to the corresponding loudspeakers depending on the direction between listener and source.

QAudioEngine offers two output modes. The first mode renders the sound field to a set of speakers, either a stereo speaker pair or a surround configuration. The second mode provides an immersive 3D sound experience when using headphones.

Perception of sound localization is driven mainly by two factors. The first factor is timing differences of the sound waves between left and right ear. The second factor comes from various ways how sounds coming from different direcations create different types of reflections from our ears and heads. See https://en.wikipedia.org/wiki/Sound_localization for more details.

The spatial audio engine emulates those timing differences and reflections through Head related transfer functions (HRTF, see https://en.wikipedia.org/wiki/Head-related_transfer_function). The functions used emulates those effects for an average persons ears and head. It provides a good and immersive 3D sound localization experience for most persons when using headphones.

The engine is rather versatile allowing you to define room properties and reverb settings to emulate different types of rooms.

Sound sources can also be occluded dampening the sound coming from those sources.

The audio engine uses a coordinate system that is in centimeters by default. The axes are aligned with the typical coordinate system used in 3D. Positive x points to the right, positive y points up and positive z points backwards.

class PySide6.QtSpatialAudio.QAudioEngine#

PySide6.QtSpatialAudio.QAudioEngine(parent)

PySide6.QtSpatialAudio.QAudioEngine(sampleRate[, parent=None])

Parameters:

sampleRate – int
parent – PySide6.QtCore.QObject

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property PᅟySide6.QtSpatialAudio.QAudioEngine.distanceScale: float#

Defines the scale of the coordinate system being used by the spatial audio engine. By default, all units are in centimeters, in line with the default units being used by Qt Quick 3D.

Set the distance scale to QAudioEngine::DistanceScaleMeter to get units in meters.

Access functions:

distanceScale ()
setDistanceScale (scale)
Signal distanceScaleChanged ()

property PᅟySide6.QtSpatialAudio.QAudioEngine.masterVolume: float#

Sets or returns volume being used to render the sound field.

Access functions:

masterVolume ()
setMasterVolume (volume)
Signal masterVolumeChanged ()

property PᅟySide6.QtSpatialAudio.QAudioEngine.outputDevice: PySide6.QtMultimedia.QAudioDevice#

Sets or returns the device that is being used for playing the sound field.

Access functions:

outputDevice ()
setOutputDevice (device)
Signal outputDeviceChanged ()

property PᅟySide6.QtSpatialAudio.QAudioEngine.outputMode: OutputMode#

Sets or retrieves the current output mode of the engine.

See also

OutputMode

Access functions:

outputMode ()
setOutputMode (mode)
Signal outputModeChanged ()

property PᅟySide6.QtSpatialAudio.QAudioEngine.paused: bool#

Pauses the spatial audio engine.

Access functions:

paused ()
setPaused (paused)
Signal pausedChanged ()

PySide6.QtSpatialAudio.QAudioEngine.OutputMode#

Constant	Description
QAudioEngine.Surround	Map the sounds to the loudspeaker configuration of the output device. This is normally a stereo or surround speaker setup.
QAudioEngine.Stereo	Map the sounds to the stereo loudspeaker configuration of the output device. This will ignore any additional speakers and only use the left and right channels to create a stero rendering of the sound field.
QAudioEngine.Headphone	Use Headphone spatialization to create a 3D audio effect when listening to the sound field through headphones

PySide6.QtSpatialAudio.QAudioEngine.DistanceScaleCentimeter#

PySide6.QtSpatialAudio.QAudioEngine.DistanceScaleMeter#

PySide6.QtSpatialAudio.QAudioEngine.distanceScale()#

Return type:: float

See also

setDistanceScale()

Getter of property distanceScale .

PySide6.QtSpatialAudio.QAudioEngine.distanceScaleChanged()#

Notification signal of property distanceScale .

PySide6.QtSpatialAudio.QAudioEngine.masterVolume()#

Return type:: float

See also

setMasterVolume()

Getter of property masterVolume .

PySide6.QtSpatialAudio.QAudioEngine.masterVolumeChanged()#

Notification signal of property masterVolume .

PySide6.QtSpatialAudio.QAudioEngine.outputDevice()#

Return type:: PySide6.QtMultimedia.QAudioDevice

See also

setOutputDevice()

Getter of property outputDevice .

PySide6.QtSpatialAudio.QAudioEngine.outputDeviceChanged()#

Notification signal of property outputDevice .

PySide6.QtSpatialAudio.QAudioEngine.outputMode()#

Return type:: OutputMode

See also

setOutputMode()

Getter of property outputMode .

PySide6.QtSpatialAudio.QAudioEngine.outputModeChanged()#

Notification signal of property outputMode .

PySide6.QtSpatialAudio.QAudioEngine.pause()#

Pauses playback.

PySide6.QtSpatialAudio.QAudioEngine.paused()#

Return type:: bool

See also

setPaused()

Getter of property paused .

PySide6.QtSpatialAudio.QAudioEngine.pausedChanged()#

Notification signal of property paused .

PySide6.QtSpatialAudio.QAudioEngine.resume()#

Resumes playback.

PySide6.QtSpatialAudio.QAudioEngine.roomEffectsEnabled()#

Return type:: bool

Returns true if room effects are enabled.

See also

setRoomEffectsEnabled()

PySide6.QtSpatialAudio.QAudioEngine.sampleRate()#

Return type:: int

Returns the sample rate the engine has been configured with.

PySide6.QtSpatialAudio.QAudioEngine.setDistanceScale(scale)#

Parameters:: scale – float

See also

distanceScale()

Setter of property distanceScale .

PySide6.QtSpatialAudio.QAudioEngine.setMasterVolume(volume)#

Parameters:: volume – float

See also

masterVolume()

Setter of property masterVolume .

PySide6.QtSpatialAudio.QAudioEngine.setOutputDevice(device)#

Parameters:: device – PySide6.QtMultimedia.QAudioDevice

See also

outputDevice()

Setter of property outputDevice .

PySide6.QtSpatialAudio.QAudioEngine.setOutputMode(mode)#

Parameters:: mode – OutputMode

See also

outputMode()

Setter of property outputMode .

PySide6.QtSpatialAudio.QAudioEngine.setPaused(paused)#

Parameters:: paused – bool

See also

paused()

Setter of property paused .

PySide6.QtSpatialAudio.QAudioEngine.setRoomEffectsEnabled(enabled)#

Parameters:: enabled – bool

Enables room effects such as echos and reverb.

Enables room effects if enabled is true. Room effects will only apply if you create one or more QAudioRoom objects and the listener is inside at least one of the rooms. If the listener is inside multiple rooms, the room with the smallest volume will be used.

See also

roomEffectsEnabled()

PySide6.QtSpatialAudio.QAudioEngine.start()#

Starts the engine.

PySide6.QtSpatialAudio.QAudioEngine.stop()#

Stops the engine.