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
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
Señales
| void | audioDeviceChanged() |
| void | loadedChanged() |
| void | loopCountChanged() |
| void | loopsRemainingChanged() |
| void | mutedChanged() |
| void | playingChanged() |
| void | sourceChanged() |
| void | statusChanged() |
| void | volumeChanged() |
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
| Constante | Valor | Descripción |
|---|---|---|
QSoundEffect::Infinite | -2 | Se utiliza como parámetro de la función ` setLoopCount()` para crear bucles infinitos |
enum QSoundEffect::Status
| Constante | Valor | Descripción |
|---|---|---|
QSoundEffect::Null | 0 | No se ha establecido ninguna fuente o la fuente es nula. |
QSoundEffect::Loading | 1 | El « SoundEffect » está intentando cargar la fuente. |
QSoundEffect::Ready | 2 | La fuente está cargada y lista para su reproducción. |
QSoundEffect::Error | 3 | Se 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:
| void | loopCountChanged() |
[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:
| void | loopsRemainingChanged() |
muted : bool
Esta propiedad permite controlar el silenciamiento. Si se establece en « true », este efecto se silenciará.
Funciones de acceso:
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:
| void | playingChanged() |
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:
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:
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.