Sur cette page

QAudioEngine Class

QAudioEngine gère un champ sonore tridimensionnel. Plus d'informations...

En-tête : #include <QAudioEngine>
CMake : find_package(Qt6 REQUIRED COMPONENTS SpatialAudio)
target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio)
qmake : QT += spatialaudio
Héritages : QObject

Types publics

enum OutputMode { Surround, Stereo, Headphone }

Propriétés

Fonctions publiques

QAudioEngine()
QAudioEngine(QObject *parent)
QAudioEngine(int sampleRate, QObject *parent = nullptr)
virtual ~QAudioEngine() override
float distanceScale() const
float masterVolume() const
QAudioDevice outputDevice() const
QAudioEngine::OutputMode outputMode() const
bool paused() const
bool roomEffectsEnabled() const
int sampleRate() const
void setDistanceScale(float scale)
void setMasterVolume(float volume)
void setOutputDevice(const QAudioDevice &device)
void setOutputMode(QAudioEngine::OutputMode mode)
void setPaused(bool paused)
void setRoomEffectsEnabled(bool enabled)

Emplacements publics

void pause()
void resume()
void start()
void stop()

Signaux

Description détaillée

Vous pouvez utiliser une instance de QAudioEngine pour gérer un champ sonore en trois dimensions. Un champ sonore est défini par plusieurs objets QSpatialSound qui définissent un son à un endroit précis dans l'espace 3D. Vous pouvez également ajouter des superpositions stéréo à l'aide de QAmbientSound.

Vous pouvez utiliser QAudioListener pour définir la position de la personne qui écoute le champ sonore par rapport aux sources sonores. Les sources sonores seront moins audibles si l'auditeur est plus éloigné de la source. Elles seront également affectées aux haut-parleurs correspondants en fonction de la direction entre l'auditeur et la source.

QAudioEngine propose deux modes de sortie. Le premier mode restitue le champ sonore à un ensemble de haut-parleurs, qu'il s'agisse d'une paire de haut-parleurs stéréo ou d'une configuration surround. Le second mode offre une expérience sonore 3D immersive lors de l'utilisation d'un casque.

La perception de la localisation du son dépend principalement de deux facteurs. Le premier facteur est la différence de synchronisation des ondes sonores entre l'oreille gauche et l'oreille droite. Le second facteur provient des différentes façons dont les sons provenant de différentes directions créent différents types de réflexions sur nos oreilles et nos têtes. Voir https://en.wikipedia.org/wiki/Sound_localization pour plus de détails.

Le moteur audio spatial émule ces différences de temps et ces réflexions par le biais des fonctions de transfert liées à la tête (HRTF, voir https://en.wikipedia.org/wiki/Head-related_transfer_function). Les fonctions utilisées émulent ces effets pour les oreilles et la tête d'une personne moyenne. La plupart des personnes qui utilisent un casque peuvent ainsi bénéficier d'une expérience de localisation sonore 3D satisfaisante et immersive.

Le moteur est assez polyvalent et permet de définir les propriétés de la pièce et les paramètres de réverbération afin d'émuler différents types de pièces.

Les sources sonores peuvent également être occultées, ce qui atténue le son provenant de ces sources.

Le moteur audio utilise un système de coordonnées en centimètres par défaut. Les axes sont alignés sur le système de coordonnées typique utilisé en 3D. Les x positifs pointent vers la droite, les y positifs pointent vers le haut et les z positifs pointent vers l'arrière.

Documentation des types de membres

enum QAudioEngine::OutputMode

ConstanteValeurDescription
QAudioEngine::Surround0Correspondance des sons avec la configuration des haut-parleurs de l'appareil de sortie. Il s'agit normalement d'une configuration de haut-parleurs stéréo ou surround.
QAudioEngine::Stereo1Affecte les sons à la configuration stéréo des haut-parleurs de l'appareil de sortie. Cette configuration ignore les enceintes supplémentaires et n'utilise que les canaux gauche et droit pour créer un rendu stéréo du champ sonore.
QAudioEngine::Headphone2Utiliser la spatialisation du casque pour créer un effet audio 3D lors de l'écoute du champ sonore avec un casque.

Documentation sur les propriétés

distanceScale : float

Définit l'échelle du système de coordonnées utilisé par le moteur audio spatial. Par défaut, toutes les unités sont exprimées en centimètres, conformément aux unités par défaut utilisées par Qt Quick 3D.

Définissez l'échelle de distance à QAudioEngine::DistanceScaleMeter pour obtenir des unités en mètres.

Fonctions d'accès :

float distanceScale() const
void setDistanceScale(float scale)

Signal de notification :

void distanceScaleChanged()

masterVolume : float

Définit ou renvoie le volume utilisé pour le rendu du champ sonore.

Fonctions d'accès :

float masterVolume() const
void setMasterVolume(float volume)

Signal du notificateur :

void masterVolumeChanged()

outputDevice : QAudioDevice

Définit ou renvoie le dispositif utilisé pour la lecture du champ sonore.

Fonctions d'accès :

QAudioDevice outputDevice() const
void setOutputDevice(const QAudioDevice &device)

Signal de notification :

void outputDeviceChanged()

outputMode : OutputMode

Définit ou récupère le mode de sortie actuel du moteur.

Fonctions d'accès :

QAudioEngine::OutputMode outputMode() const
void setOutputMode(QAudioEngine::OutputMode mode)

Signal de notification :

void outputModeChanged()

Voir également QAudioEngine::OutputMode.

paused : bool

Met en pause le moteur audio spatial.

Fonctions d'accès :

bool paused() const
void setPaused(bool paused)

Signal du notificateur :

void pausedChanged()

Member Function Documentation

QAudioEngine::QAudioEngine()

[explicit] QAudioEngine::QAudioEngine(QObject *parent)

[explicit] QAudioEngine::QAudioEngine(int sampleRate, QObject *parent = nullptr)

Construit un moteur audio spatial avec parent, le cas échéant.

Le moteur fonctionnera avec une fréquence d'échantillonnage donnée par sampleRate. La fréquence d'échantillonnage par défaut, si aucune n'est fournie, est de 44100 (44,1 kHz).

Le contenu sonore qui n'est pas fourni à cette fréquence d'échantillonnage sera automatiquement rééchantillonné à sampleRate lorsqu'il sera traité par le moteur. La fréquence d'échantillonnage par défaut convient dans la plupart des cas, mais vous pouvez définir une fréquence différente si la plupart de vos fichiers sonores sont échantillonnés à une fréquence différente, et éviter ainsi une surcharge du processeur pour le rééchantillonnage.

[override virtual noexcept] QAudioEngine::~QAudioEngine()

Détruit le moteur audio spatial.

[slot] void QAudioEngine::pause()

Interrompt la lecture.

[slot] void QAudioEngine::resume()

Reprend la lecture.

bool QAudioEngine::roomEffectsEnabled() const

Renvoie un résultat positif si les effets de salle sont activés.

Voir également setRoomEffectsEnabled().

int QAudioEngine::sampleRate() const

Renvoie la fréquence d'échantillonnage avec laquelle le moteur a été configuré.

void QAudioEngine::setRoomEffectsEnabled(bool enabled)

Active les effets de salle tels que les échos et la réverbération.

Active les effets de salle si enabled est vrai. Les effets de salle ne s'appliquent que si vous créez un ou plusieurs objets QAudioRoom et que l'auditeur se trouve dans au moins une des salles. Si l'auditeur se trouve dans plusieurs pièces, la pièce dont le volume est le plus faible sera utilisée.

Voir également roomEffectsEnabled().

[slot] void QAudioEngine::start()

Démarre le moteur.

[slot] void QAudioEngine::stop()

Arrête le moteur.

© 2026 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.