Spatial Audio Overview

The Qt Multimedia API provides a number of classes that allow the creation of three dimensional sound scene. It is defined by objects located in 3D space that emit sound and surrounding geometry that can be modelled using one or several rooms. Finally a listener can be placed into this sound scene at a specified position and orientation.

There are both C++ and QML APIs that can be used.

Creating a sound scene

To create the sound scene, one first instantiates a QSpatialAudioEngine. This engine processes input sound data and geometries to create a realistic representation of the sound scene as it would be experienced by a person placed at a specific location inside the scene.

The QSpatialAudioEngine::OutputMode property can be used to optimize the output either for headphones using binaural (virtual 3D) rendering or for a stereo or surround speaker configuration.

The output device can be selected using QSpatialAudioEngine::outputDevice property.

Once the engine is set up, we can place various sound objects into the scene by creating QSpatialAudioSoundSource objects and specifying a url to a sound file using the QSpatialAudioSoundSource::source property.

QSpatialAudioListener can be used to define the position and orientation of a person listening to the sound scene. At max one listener per engine can be used. If no listener is specified, the engine assumes that the listener is at the origin of the coordinate system facing into a positive z direction, with positive y pointing upwards.

In addition to sound sources and a listener, you can define a geometry that influences how the sound is being experienced by the listener through a set of QSpatialAudioRoom objects. Rooms are rectangular and support a wide variety of materials for each wall giving a different experience with different sound reflections and reverb. Room effects will get applied if the listener is located inside one of the rooms. If he is inside multiple rooms, the room with the smallest geometrical volume will take precedence.

If you need some stereo overlay that is independent of the position and orientation of the listener (such as background music or a voice-over), you can use QSpatialAudioStereoSource to create the sound overlay.

Reference Documentation

C++ Classes

QSpatialAudioEngine

Manages a three dimensional sound field

QSpatialAudioListener

Defines the position and orientation of the person listening to a sound field defined by QSpatialAudioEngine

QSpatialAudioRoom

QSpatialAudioSoundSource

A sound object in 3D space

QSpatialAudioStereoSource

A stereo overlay sound

QML Types

SpatialAudioEngine

Manages sound objects inside a 3D scene

SpatialAudioListener

Defines the position and orientation of the person listening to a sound field defined by a SpatialAudioEngine

SpatialAudioRoom

SpatialAudioSoundSource

A sound object in 3D space

SpatialAudioStereoSource

A stereo overlay sound

© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.