En esta página

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

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

Señales

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

ConstanteValorDescripción
QAudioEngine::Surround0Asigna 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::Stereo1Asigna 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::Headphone2Utiliza 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.