SoundEffect QML Type
El tipo `SoundEffect` permite reproducir efectos de sonido en QML. Más información...
| Import Statement: | import QtMultimedia |
| In C++: | QSoundEffect |
Propiedades
- loops : int
- loopsRemaining : int
- muted : bool
- playing : bool
- source : url
- status : enumeration
- volume : real
Señales
- loadedChanged()
- loopCountChanged()
- loopsRemainingChanged()
- mutedChanged()
- playingChanged()
- sourceChanged()
- statusChanged()
- volumeChanged()
Métodos
Descripción detallada
Este tipo permite reproducir archivos de audio sin comprimir (normalmente archivos WAV) con una latencia generalmente menor, y es adecuado 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 el tipo « MediaPlayer », ya que admite una mayor variedad de formatos multimedia y consume menos recursos.
Normalmente, el efecto de sonido debería reutilizarse, lo que permite que todo el análisis y la preparación se realicen con antelación, y que solo se active cuando sea necesario. Esto es fácil de conseguir con QML, ya que puedes declarar tu instancia de `SoundEffect` y hacer referencia a ella en otros lugares.
El siguiente ejemplo reproduce un archivo WAV al hacer clic con el ratón.
Text {
text: "Click Me!";
font.pointSize: 24;
width: 150; height: 50;
SoundEffect {
id: playSound
source: "soundeffect.wav"
}
MouseArea {
id: playArea
anchors.fill: parent
onPressed: { playSound.play() }
}
}Nota: ` QSoundEffect ` solo admite archivos de sonido en mono o estéreo. Se recomienda utilizar archivos de sonido con una frecuencia de muestreo de 48 000 Hz, ya que es la frecuencia de muestreo nativa habitual en la mayoría de las plataformas (QAudioDevice::preferredFormat()).
Documentación de propiedades
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, el número de reproducciones restantes se actualizará con el nuevo valor.
loopsRemaining : int [read-only]
Esta propiedad contiene el número de repeticiones que quedan antes de que el efecto de sonido se detenga por sí solo, o « SoundEffect ». «Infinite» si así se ha configurado en « loops ».
muted : bool
Esta propiedad permite controlar el silenciamiento. Si se establece el valor « true », se silenciará este efecto. En caso contrario, la reproducción se realizará con el valor especificado actualmente en « volume ».
playing : bool [read-only]
Esta propiedad indica si el efecto de sonido se está reproduciendo o no.
source : url
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. Si la fuente deseada es un archivo local, la URL puede especificarse utilizando una ruta absoluta o relativa (respecto al archivo que declaró el ` SoundEffect`).
status : enumeration [read-only]
Esta propiedad indica el estado actual de la propiedad « SoundEffect », tal y como se detalla en SoundEffect. A continuación se enumeran los estados posibles.
| Valor | Descripción |
|---|---|
| SoundEffect.Null | No se ha establecido ninguna fuente o la fuente es nula. |
| SoundEffect.Cargando | SoundEffect está intentando cargar la fuente. |
| SoundEffect.Listo | La fuente se ha cargado y está lista para la reproducción. |
| SoundEffect.Error | Se ha producido un error durante la operación, como por ejemplo un fallo al cargar la fuente. |
volume : real
Esta propiedad determina el volumen de reproducción del efecto de sonido.
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 convertVolume() para obtener más detalles.
Documentación sobre señales
loadedChanged()
La señal « loadedChanged » se emite cuando cambia el estado de carga.
Nota: El controlador correspondiente es onLoadedChanged.
loopCountChanged()
La señal « loopCountChanged » se emite cuando cambia el número inicial de repeticiones.
Nota: El controlador correspondiente es ` onLoopCountChanged`.
loopsRemainingChanged()
La señal « loopsRemainingChanged » se emite cuando cambia el número de bucles restantes.
Nota: El controlador correspondiente es onLoopsRemainingChanged.
mutedChanged()
La señal « mutedChanged » se emite cuando cambia el estado de silencio.
Nota: El controlador correspondiente es onMutedChanged.
playingChanged()
La señal « playingChanged » se emite cuando cambia la propiedad de reproducción.
Nota: El controlador correspondiente es onPlayingChanged.
sourceChanged()
La señal « sourceChanged » se emite cuando se ha cambiado la fuente.
Nota: El controlador correspondiente es onSourceChanged.
statusChanged()
La señal « statusChanged » se emite cuando cambia la propiedad «status».
Nota: El controlador correspondiente es onStatusChanged.
volumeChanged()
La señal « volumeChanged » se emite cuando cambia el volumen.
Nota: El controlador correspondiente es onVolumeChanged.
Documentación del método
bool isLoaded()
Devuelve si el efecto de sonido ha terminado de cargar el ` source`.
void play()
Inicia la reproducción del efecto de sonido, repitiéndolo tantas veces como se especifique en la propiedad «loops».
Este es el método predeterminado para ` SoundEffect`.
SoundEffect {
id: playSound
source: "soundeffect.wav"
}
MouseArea {
id: playArea
anchors.fill: parent
onPressed: { playSound.play() }
}void stop()
Detener la reproducción actual.
© 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.