En esta página

QSoundEffect Class

La clase QSoundEffect permite reproducir efectos de sonido con baja latencia. Más información...

Encabezado: #include <QSoundEffect>
CMake: find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(mytarget PRIVATE Qt6::Multimedia)
qmake: QT += multimedia
En QML: SoundEffect
Heredan de: QObject

Tipos públicos

enum Loop { Infinite }
enum Status { Null, Loading, Ready, Error }

Propiedades

Funciones públicas

QSoundEffect(QObject *parent = nullptr)
QSoundEffect(const QAudioDevice &audioDevice, QObject *parent = nullptr)
virtual ~QSoundEffect() override
QAudioDevice audioDevice()
bool isLoaded() const
bool isMuted() const
bool isPlaying() const
int loopCount() const
int loopsRemaining() const
void setAudioDevice(const QAudioDevice &device)
void setLoopCount(int loopCount)
void setMuted(bool muted)
void setSource(const QUrl &url)
void setVolume(float volume)
QUrl source() const
QSoundEffect::Status status() const
float volume() const

Ranuras públicas

void play()
void stop()

Señales

Miembros públicos estáticos

QStringList supportedMimeTypes()

Descripción detallada

Esta clase permite reproducir archivos de audio sin comprimir (normalmente archivos WAV) con una latencia generalmente menor, y es adecuada para sonidos de «retroalimentación» en respuesta a las acciones del usuario (por ejemplo, sonidos de teclado virtual, retroalimentación positiva o negativa para cuadros de diálogo emergentes o sonidos de juegos). Si la baja latencia no es importante, plantéate utilizar en su lugar la clase ` QMediaPlayer `, ya que admite una mayor variedad de formatos multimedia y consume menos recursos.

Este ejemplo muestra cómo se puede reproducir un efecto de sonido en bucle, relativamente suave:

QSoundEffect effect;
effect.setSource(QUrl::fromLocalFile("engine.wav"));
effect.setLoopCount(QSoundEffect::Infinite);
effect.setVolume(0.25f);
effect.play();

Normalmente, el efecto de sonido debe reutilizarse, lo que permite realizar todo el análisis y la preparación con antelación, y activarlo solo cuando sea necesario. Esto contribuye a una reproducción de audio con menor latencia.

    MyGame()
        : m_explosion(this)
    {
        m_explosion.setSource(QUrl::fromLocalFile("explosion.wav"));
        m_explosion.setVolume(0.25f);

        // Set up click handling etc.
        connect(clickSource, &QPushButton::clicked, &m_explosion, &QSoundEffect::play);
    }
private:
    QSoundEffect m_explosion;

Dado que QSoundEffect requiere ligeramente más recursos para lograr una reproducción con menor latencia, la plataforma puede limitar el número de efectos de sonido que se reproducen simultáneamente.

Documentación sobre los tipos de miembros

enum QSoundEffect::Loop

ConstanteValorDescripción
QSoundEffect::Infinite-2Se utiliza como parámetro de la función ` setLoopCount()` para crear bucles infinitos

enum QSoundEffect::Status

ConstanteValorDescripción
QSoundEffect::Null0No se ha establecido ninguna fuente o la fuente es nula.
QSoundEffect::Loading1El « SoundEffect » está intentando cargar la fuente.
QSoundEffect::Ready2La fuente está cargada y lista para su reproducción.
QSoundEffect::Error3Se ha producido un error durante la operación, como por ejemplo un fallo al cargar la fuente.

Documentación de propiedades

audioDevice : QAudioDevice

Devuelve la instancia ` QAudioDevice `.

Funciones de acceso:

QAudioDevice audioDevice()
void setAudioDevice(const QAudioDevice &device)

Señal de Notifier:

void audioDeviceChanged()

loops : int

Esta propiedad indica el número de veces que se reproduce el sonido. Un valor de 0 o 1 significa que el sonido se reproducirá solo una vez; establécelo en SoundEffect.Infinite para habilitar la reproducción en bucle infinito.

El valor se puede modificar mientras se reproduce el efecto de sonido; en ese caso, se actualizará el número de reproducciones restantes con el nuevo valor.

Funciones de acceso:

int loopCount() const
void setLoopCount(int loopCount)

Señal de notificación:

[read-only] loopsRemaining : int

Esta propiedad contiene el número de repeticiones que quedan antes de que el efecto de sonido se detenga por sí solo, o « QSoundEffect::Infinite » si así se ha configurado en « loops ».

Funciones de acceso:

int loopsRemaining() const

Señal de notificación:

muted : bool

Esta propiedad permite controlar el silenciamiento. Si se establece en « true », este efecto se silenciará.

Funciones de acceso:

bool isMuted() const
void setMuted(bool muted)

Señal de notificación:

void mutedChanged()

[read-only] playing : bool

Esta propiedad indica si el efecto de sonido se está reproduciendo o no.

Funciones de acceso:

bool isPlaying() const

Señal de notificación:

source : QUrl

Esta propiedad contiene la URL del sonido que se va a reproducir. Para que el « SoundEffect » intente cargar la fuente, la URL debe existir y la aplicación debe tener permiso de lectura en el directorio especificado.

Funciones de acceso:

QUrl source() const
void setSource(const QUrl &url)

Señal del notificador:

void sourceChanged()

[read-only] status : Status

Esta propiedad indica el estado actual del efecto de sonido, según la enumeración « QSoundEffect::Status ».

Funciones de acceso:

QSoundEffect::Status status() const

Señal de notificación:

void statusChanged()

volume : float

Esta propiedad determina el volumen de reproducción del efecto de sonido, desde 0,0 (silencio) hasta 1,0 (volumen máximo).

Funciones de acceso:

float volume() const
void setVolume(float volume)

Señal de notificación:

void volumeChanged()

Documentación de funciones de miembro

[explicit] QSoundEffect::QSoundEffect(QObject *parent = nullptr)

Crea un QSoundEffect con el ` parent` indicado.

[explicit] QSoundEffect::QSoundEffect(const QAudioDevice &audioDevice, QObject *parent = nullptr)

Crea un objeto `QSoundEffect` con los valores especificados para ` audioDevice ` y ` parent`.

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

Elimina este efecto de sonido.

bool QSoundEffect::isLoaded() const

Devuelve si el efecto de sonido ha terminado de cargarse mediante la función ` source()`.

bool QSoundEffect::isMuted() const

Devuelve si este efecto de sonido está silenciado

Nota: Funcióngetter para la propiedad « muted ».

bool QSoundEffect::isPlaying() const

Devuelve «true» si el efecto de sonido se está reproduciendo en ese momento; en caso contrario, devuelve «false»

Nota: Funcióngetter para la propiedad « playing ».

[signal] void QSoundEffect::loadedChanged()

La señal « loadedChanged » se emite cuando cambia el estado de carga.

int QSoundEffect::loopCount() const

Devuelve el número total de veces que se reproducirá este efecto de sonido antes de detenerse.

Consulta el método loopsRemaining() para conocer el número de repeticiones que quedan actualmente.

Nota: Funcióngetter para la propiedad loops.

Véase también setLoopCount().

[signal] void QSoundEffect::loopCountChanged()

La señal « loopCountChanged » se emite cuando cambia el número inicial de bucles.

Nota: Señalde notificación para la propiedad « loops ».

[signal] void QSoundEffect::loopsRemainingChanged()

La señal « loopsRemainingChanged » se emite cuando cambia el número de bucles restantes.

Nota: Señalde notificación para la propiedad loopsRemaining.

[signal] void QSoundEffect::mutedChanged()

La señal « mutedChanged » se emite cuando cambia el estado de silencio.

Nota: Señalde notificación para la propiedad muted.

[slot] void QSoundEffect::play()

Inicia la reproducción del efecto de sonido, repitiéndolo tantas veces como se especifique en la propiedad «loops».

[signal] void QSoundEffect::playingChanged()

La señal « playingChanged » se emite cuando cambia la propiedad de reproducción.

Nota: Señalde Notifier para la propiedad « playing ».

void QSoundEffect::setLoopCount(int loopCount)

Establece el número total de veces que se reproducirá este efecto de sonido en loopCount.

Si se establece el número de repeticiones en 0 o 1, el efecto de sonido solo se reproducirá una vez; si se establece en QSoundEffect::Infinite, se repetirá indefinidamente. El número de repeticiones se puede modificar mientras se reproduce el efecto de sonido, en cuyo caso se actualizará el número de repeticiones restantes al nuevo valor loopCount.

Nota: Funciónde asignación para la propiedad loops.

Véase también loopCount() y loopsRemaining().

void QSoundEffect::setMuted(bool muted)

Establece si se silencia la reproducción de este efecto de sonido.

Si ` muted ` es `true`, la reproducción se silenciará; en caso contrario, se reproducirá con el ` volume()` especificado actualmente.

Nota: Funciónde asignación para la propiedad muted.

Véase también isMuted().

void QSoundEffect::setSource(const QUrl &url)

Establece la URL actual que se va a reproducir en url.

Nota: Funciónde asignación para la propiedad source.

Véase también source().

void QSoundEffect::setVolume(float volume)

Establece el volumen de los efectos de sonido en volume.

El volumen se escala linealmente desde 0.0 (silencio) hasta 1.0 (volumen máximo). Los valores fuera de este rango se limitarán.

El volumen por defecto es 1.0.

Los controles de volumen de la interfaz de usuario suelen escalarse de forma no lineal. Por ejemplo, el uso de una escala logarítmica producirá cambios lineales en el volumen percibido, que es lo que un usuario esperaría normalmente de un control de volumen. Consulta QtAudio::convertVolume() para obtener más detalles.

Nota: Funciónde configuración para la propiedad volume.

Véase también volume().

QUrl QSoundEffect::source() const

Devuelve la URL de la fuente actual que se va a reproducir

Nota: Funcióngetter para la propiedad source.

Véase también setSource().

[signal] void QSoundEffect::sourceChanged()

La señal « sourceChanged » se emite cuando se ha modificado la fuente.

Nota: Señalde notificación para la propiedad « source ».

QSoundEffect::Status QSoundEffect::status() const

Devuelve el estado actual de este efecto de sonido.

Nota: Funcióngetter para la propiedad «status».

[signal] void QSoundEffect::statusChanged()

La señal « statusChanged » se emite cuando la propiedad «status» ha cambiado.

Nota: Señalde Notifier para la propiedad « status ».

[slot] void QSoundEffect::stop()

Detener la reproducción actual.

[static] QStringList QSoundEffect::supportedMimeTypes()

Devuelve una lista de los tipos MIME compatibles con esta plataforma.

float QSoundEffect::volume() const

Devuelve el volumen actual de este efecto de sonido, desde 0,0 (silencio) hasta 1,0 (volumen máximo).

Nota: Funcióngetter para la propiedad «volume».

Véase también setVolume().

[signal] void QSoundEffect::volumeChanged()

La señal « volumeChanged » se emite cuando cambia el volumen.

Nota: Señalde notificación para la propiedad volume.

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