En esta página

QAudioEngine Class

QAudioEngine gestiona un campo sonoro tridimensional. Más...

Cabecera: #include <QAudioEngine>
CMake: find_package(Qt6 REQUIRED COMPONENTS SpatialAudio)
target_link_libraries(mytarget PRIVATE Qt6::SpatialAudio)
qmake: QT += spatialaudio
Hereda: 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 de sonido en tres dimensiones. Un campo sonoro está definido por varios objetos QSpatialSound que definen un sonido en una ubicación específica en el espacio 3D. También puede añadir superposiciones estéreo utilizando QAmbientSound.

Puede utilizar QAudioListener para definir la posición de la persona que escucha el campo sonoro con respecto a las fuentes de sonido. Las fuentes sonoras serán menos audibles si el oyente está más lejos de la fuente. También 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 primero 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 primero son las diferencias temporales de las ondas sonoras entre el oído izquierdo y el derecho. El segundo factor es la forma en que los sonidos procedentes de distintas direcciones crean distintos tipos de reflejos en nuestros oídos y cabezas. Para más información, consulta https://en.wikipedia.org/wiki/Sound_localization.

El motor de audio espacial emula esas diferencias de tiempo y reflexiones mediante 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 normal. Proporciona una experiencia de localización de sonido 3D buena y envolvente para la mayoría de las personas que utilizan auriculares.

El motor es bastante versátil y permite definir las propiedades de la sala y los ajustes de reverberación para emular distintos tipos de salas.

Las fuentes de sonido también pueden ocluirse para amortiguar el sonido procedente de ellas.

El motor de audio utiliza por defecto un sistema de coordenadas en centímetros. Los ejes están alineados con el típico sistema de coordenadas utilizado en 3D. La x positiva apunta hacia la derecha, la y positiva apunta hacia arriba y la z positiva apunta hacia atrás.

Documentación de 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 surround.
QAudioEngine::Stereo1Asigna los sonidos a la configuración de altavoces estéreo del dispositivo de salida. Esto ignorará cualquier altavoz adicional y sólo utilizará los canales izquierdo y derecho para crear una representación estereoscópica del campo sonoro.
QAudioEngine::Headphone2Utilice la espacialización de auriculares para crear un efecto de audio 3D cuando escuche el campo sonoro a través de auriculares.

Documentación de propiedades

distanceScale : float

Define la escala del sistema de coordenadas utilizado por el motor de audio espacial. Por defecto, todas las unidades están en centímetros, en línea con las unidades por defecto utilizadas por Qt Quick 3D.

Establece la escala de distancia a QAudioEngine::DistanceScaleMeter para obtener unidades en metros.

Funciones de acceso:

float distanceScale() const
void setDistanceScale(float scale)

Señal del notificador:

void distanceScaleChanged()

masterVolume : float

Establece o devuelve el volumen utilizado para representar el campo sonoro.

Funciones de acceso:

float masterVolume() const
void setMasterVolume(float volume)

Señal del notificador:

void masterVolumeChanged()

outputDevice : QAudioDevice

Establece o devuelve el dispositivo que se está utilizando para reproducir el campo sonoro.

Funciones de acceso:

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

Señal del avisador:

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 del notificador:

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)

Notificador de señal:

void pausedChanged()

Documentación de la función miembro

QAudioEngine::QAudioEngine()

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

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

Construye un motor de audio espacial con parent, si existe.

El motor funcionará con una frecuencia de muestreo dada por sampleRate. La frecuencia de muestreo predeterminada, si no se indica 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 cuando sea procesado por el motor. La frecuencia de muestreo por defecto está bien 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 con una frecuencia diferente, y evitar algunos gastos de CPU para el 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 efectos de sala como ecos y reverberación.

Activa los efectos de sala si enabled es verdadero. Los efectos de sala sólo se aplicarán si crea uno o más objetos QAudioRoom y el oyente está dentro de al menos una de las salas. Si el oyente se encuentra en varias salas, se utilizará la sala con menor volumen.

Véase también roomEffectsEnabled().

[slot] void QAudioEngine::start()

Arranca el motor.

[slot] void QAudioEngine::stop()

Para 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.