QAudioEngine Class
QAudioEngine gestiona un campo sonoro tridimensional. Más información...
| Encabezado: | #include <QAudioEngine> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS SpatialAudio) target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio) |
| qmake: | QT += spatialaudio |
| Heredado de: | QObject |
Tipos públicos
| enum | OutputMode { Surround, Stereo, Headphone } |
Propiedades
|
|
Funciones públicas
| 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) |
Ranuras públicas
Señales
| void | distanceScaleChanged() |
| void | masterVolumeChanged() |
| void | outputDeviceChanged() |
| void | outputModeChanged() |
| void | pausedChanged() |
Descripción detallada
Puedes utilizar una instancia de QAudioEngine para gestionar un campo sonoro en tres dimensiones. Un campo sonoro viene definido por varios objetos ` QSpatialSound `, que definen un sonido en una ubicación específica del espacio 3D. También puedes añadir superposiciones estéreo utilizando ` QAmbientSound`.
Se puede utilizar QAudioListener para definir la posición de la persona que escucha el campo sonoro en relación con las fuentes de sonido. Las fuentes de sonido serán menos audibles cuanto más lejos se encuentre el oyente de la fuente. Además, se asignarán a los altavoces correspondientes en función de la dirección entre el oyente y la fuente.
QAudioEngine ofrece dos modos de salida. El primer modo reproduce el campo sonoro en un conjunto de altavoces, ya sea un par de altavoces estéreo o una configuración envolvente. El segundo modo proporciona una experiencia de sonido 3D envolvente cuando se utilizan auriculares.
La percepción de la localización del sonido depende principalmente de dos factores. El primer factor son las diferencias de sincronización de las ondas sonoras entre el oído izquierdo y el derecho. El segundo factor se debe a las diversas formas en que los sonidos procedentes de diferentes direcciones crean distintos tipos de reflejos en nuestros oídos y cabezas. Consulta https://en.wikipedia.org/wiki/Sound_localization para obtener más detalles.
El motor de audio espacial emula esas diferencias de tiempo y esos reflejos mediante las funciones de transferencia relacionadas con la cabeza (HRTF; véase https://en.wikipedia.org/wiki/Head-related_transfer_function). Las funciones utilizadas emulan esos efectos para los oídos y la cabeza de una persona media. Proporcionan una experiencia de localización sonora en 3D envolvente y de calidad para la mayoría de las personas cuando utilizan auriculares.
El motor es bastante versátil y permite definir las propiedades de la sala y los ajustes de reverberación para emular diferentes tipos de salas.
Las fuentes de sonido también pueden ocultarse, lo que atenúa el sonido procedente de dichas fuentes.
El motor de audio utiliza un sistema de coordenadas que, por defecto, está en centímetros. Los ejes están alineados con el sistema de coordenadas típico utilizado en 3D. El eje x positivo apunta hacia la derecha, el eje y positivo apunta hacia arriba y el eje z positivo apunta hacia atrás.
Documentación sobre los tipos de miembros
enum QAudioEngine::OutputMode
| Constante | Valor | Descripción |
|---|---|---|
QAudioEngine::Surround | 0 | Asigna los sonidos a la configuración de altavoces del dispositivo de salida. Normalmente se trata de una configuración de altavoces estéreo o envolvente. Nota: OutputMode ::Surround desactivará la reproducción de QAmbientSound |
QAudioEngine::Stereo | 1 | Asigna los sonidos a la configuración de altavoces estéreo del dispositivo de salida. Esto ignorará cualquier altavoz adicional y utilizará únicamente los canales izquierdo y derecho para crear una representación estéreo del campo sonoro. |
QAudioEngine::Headphone | 2 | Utiliza la espacialización de auriculares para crear un efecto de audio 3D al escuchar el campo sonoro a través de los auriculares |
Documentación de propiedades
distanceScale : float
Define la escala del sistema de coordenadas que utiliza el motor de audio espacial. Por defecto, todas las unidades están expresadas en centímetros, en consonancia con las unidades predeterminadas que utiliza Qt Quick 3D.
Establece la escala de distancia en QAudioEngine::DistanceScaleMeter para obtener unidades en metros.
Funciones de acceso:
| float | distanceScale() const |
| void | setDistanceScale(float scale) |
Señal de notificación:
| void | distanceScaleChanged() |
masterVolume : float
Establece o devuelve el volumen que se utiliza para reproducir el campo sonoro.
Funciones de acceso:
| float | masterVolume() const |
| void | setMasterVolume(float volume) |
Señal de notificación:
| void | masterVolumeChanged() |
outputDevice : QAudioDevice
Establece o devuelve el dispositivo que se está utilizando para reproducir el campo de sonido.
Funciones de acceso:
| QAudioDevice | outputDevice() const |
| void | setOutputDevice(const QAudioDevice &device) |
Señal de notificación:
| void | outputDeviceChanged() |
outputMode : OutputMode
Establece o recupera el modo de salida actual del motor.
Funciones de acceso:
| QAudioEngine::OutputMode | outputMode() const |
| void | setOutputMode(QAudioEngine::OutputMode mode) |
Señal de notificación:
| void | outputModeChanged() |
Véase también « QAudioEngine::OutputMode ».
paused : bool
Pone en pausa el motor de audio espacial.
Funciones de acceso:
| bool | paused() const |
| void | setPaused(bool paused) |
Señal de notificación:
| void | pausedChanged() |
Documentación de funciones de miembro
QAudioEngine::QAudioEngine()
[explicit] QAudioEngine::QAudioEngine(QObject *parent)
[explicit] QAudioEngine::QAudioEngine(int sampleRate, QObject *parent = nullptr)
Crea un motor de audio espacial con parent, si existe.
El motor funcionará con una frecuencia de muestreo determinada por sampleRate. La frecuencia de muestreo por defecto, si no se especifica ninguna, es 44100 (44,1 kHz).
El contenido de sonido que no se proporcione a esa frecuencia de muestreo se remuestreará automáticamente a sampleRate al ser procesado por el motor. La frecuencia de muestreo por defecto es adecuada en la mayoría de los casos, pero puedes definir una frecuencia diferente si la mayoría de tus archivos de sonido están muestreados a una frecuencia distinta, y así evitar cierta sobrecarga de la CPU debida al remuestreo.
[override virtual noexcept] QAudioEngine::~QAudioEngine()
Destruye el motor de audio espacial.
[slot] void QAudioEngine::pause()
Detiene la reproducción.
[slot] void QAudioEngine::resume()
Reanuda la reproducción.
bool QAudioEngine::roomEffectsEnabled() const
Devuelve «true» si los efectos de sala están activados.
Véase también ` setRoomEffectsEnabled()`.
int QAudioEngine::sampleRate() const
Devuelve la frecuencia de muestreo con la que se ha configurado el motor.
void QAudioEngine::setRoomEffectsEnabled(bool enabled)
Activa los efectos de sala, como los ecos y la reverberación.
Activa los efectos de sala si « enabled » es «true». Los efectos de sala solo se aplicarán si se crean uno o más objetos « QAudioRoom » y el oyente se encuentra dentro de al menos una de las salas. Si el oyente se encuentra dentro de varias salas, se utilizará la sala con el volumen más bajo.
Véase también roomEffectsEnabled().
[slot] void QAudioEngine::start()
Arranca el motor.
[slot] void QAudioEngine::stop()
Apaga el motor.
© 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.