
The BackgroundMusic element allows playing long-lasting and looping background sound in wav, mp3 or ogg file format. More...
Import Statement: | import Felgo 3.0 |
Inherits: |
This component allows to play looping audio files, mostly used as background music in games. Background musics are usually longer-lasting tracks in encoded and compressed audio formats like ogg or MP3. However, the BackgroundMusic component can also play wav files. See Supported Audio Formats for more details.
Note: If you have multiple BackgroundMusic objects in your game, set the autoPlay property to false except for the first one you would like to play, to avoid automatically playing all of them when they get loaded.
For short notifications sounds with low latency, use SoundEffect. For videos use the Video component.
Note: The Qt 5 Audio element currently (as of Qt release 5.3.0) can not play sound files from qrc on iOS, Mac and some Android devices. However, bundling your assets into a qrc file is the suggested deployment option, because you can then compile your assets into the binary and they are protected. Due to this Qt issue, we recommend using SoundEffect for your background sounds, or deploy your audio assets with the DEPLOYMENTFOLDERS option in your pro file instead of bundling them with qrc. If you need help with this topic, please use our support forums.
BackgroundMusic enhances the Qt 5 component Audio in the Qt Multimedia 5.0 module with the following additions:
onStopped
handler.
settings.musicEnbaled
to true or false.This type allows you to play compressed audio files (typically ogg or MP3 files but also others like AAC or WAV are supported). Compared to SoundEffect, it takes less resources as it does not provide such a low latency to play a sound after calling play(). Thus use it to play longer-lasting tracks.
For free sounds, we recommend the following websites:
These sites have a great search feature, as you can search by categories or tags. Most of the sounds are available for free if you add the license to your game. There also are low-price premium version of the sounds, which allows you to use them without any license note.
The different supported platforms use different APIs for playing background music, therefore not all file formats are supported over all platforms. It's recommended to use the following file formats:
Platforms | Supported Audio Formats |
---|---|
Windows | wav, mp3 |
All other platforms | wav, mp3, ogg |
The music is preloaded (the autoLoad property is true by default) and is started automatically by default after loading it. You can change that auto-play behavior by
setting autoPlay to false
.
For manual playback control, start the music with play().
Try setting the bitrate and the sampling rate as low as possible, so it still sounds reasonable. That helps in saving precious memory and runtime performance. Also mono channel sounds are preferred for performance reasons. The background musics used in the demo projects have a bitrate of 48kb/s and a 22kHz sampling rate.
Here is an example of a background music that is played when the qml file is loaded:
BackgroundMusic { id: backgroundMusic source: "../assets/snd/backgroundMusic.mp3" // autoPlay: true - this is set by default }
autoLoad : bool |
This property indicates if loading of media should begin immediately.
Defaults to true, if false media will not be loaded until playback is started.
Note that only the loading of the media is set here, the music will not start to play when it is loaded automatically, but only after calling play().
autoPauseInBackground : bool |
Set this property to automatically pause this BackgroundMusic when the app is moved to background.
On mobile that happens if the user presses the home button and leaves the app. On desktop that happens when the app loses its focus or gets minimized.
By default, this value is true on mobile platforms and false on desktop platforms.
autoPlay : bool |
Set this property to play the background music automatically when this item is loaded, e.g. at application start.
By default, it is set to true. So when the settings.musicEnabled property is also set to true, the music is played after initialization of the Settings object.
See also GameWindowApplicationWindow::settings.
availability : enumeration |
Returns the availability state of the media player.
This is one of:
Value | Description |
---|---|
Available | The media player is available to use. |
Busy | The media player is usually available, but some other process is utilizing the hardware necessary to play media. |
Unavailable | There are no supported media playback facilities. |
ResourceMissing | There is one or more resources missing, so the media player cannot be used. It may be possible to try again at a later time. |
Note: For accessing one of the enum values like Audio.Available
, add this import to your QML file: import QtMultimedia 5.0
.
bufferProgress : real |
This property holds how much of the data buffer is currently filled, from 0.0 (empty) to 1.0 (full).
duration : int |
This property holds the duration of the media in milliseconds.
If the media doesn't have a fixed duration (a live stream for example) this will be 0.
error : enumeration |
This property holds the error state of the audio. It can be one of:
Value | Description |
---|---|
NoError | There is no current error. |
ResourceError | The audio cannot be played due to a problem allocating resources. |
FormatError | The audio format is not supported. |
NetworkError | The audio cannot be played due to network issues. |
AccessDenied | The audio cannot be played due to insufficient permissions. |
ServiceMissing | The audio cannot be played because the media service could not be instantiated. |
Note: For accessing the enum values like Audio.NoError
, add this import to your QML file: import QtMultimedia 5.0
.
errorString : string |
This property holds a string describing the current error condition in more detail.
hasAudio : bool |
This property holds whether the media contains audio.
hasVideo : bool |
This property holds whether the media contains video.
This property provides a way to control the number of times to repeat the sound on each play().
By default, loops is set to Audio.Infinite
and therefore plays the sound infinitely until it gets stopped by calling stop().
Note: To have access to the Audio.Infinite
enum, make sure to call import QtMultimedia 5.0
in the header of your QML file.
See the Audio documentation which metaData properties are available.
See also QMediaMetaData.
muted : bool |
This property holds whether the background music is muted.
Defaults to false, and can be set to true or by setting the volume to 0.
playbackRate : real |
This property holds the rate at which audio is played at as a multiple of the normal rate.
Defaults to 1.0.
playbackState : enumeration |
This property holds the state of media playback. It can be one of:
Note: For accessing the enum values like Audio.PlayingState
, add this import to your QML file: import QtMultimedia 5.0
.
playing : bool |
This property holds whether the background music is currently playing.
This property is read-only.
See also play().
position : int |
seekable : bool |
This property holds whether position of the audio can be changed.
If true, calling the seek() method will cause playback to seek to the new position.
source : url |
This property holds the source URL of the media.
The default is an empty url, so this is a required property.
status : int |
This property indicates the current status of the BackgroundMusic. Possible statuses are listed below.
Value | Description |
---|---|
Audio.Null | No source has been set or the source is null. |
Audio.Loading | The Audio is trying to load the source. |
Audio.Ready | The source is loaded and ready for play. |
Audio.Error | An error occurred during operation, such as failure of loading the source. |
This property is read-only.
Note: For accessing one of the enum values like Audio.Available
, add this import to your QML file: import QtMultimedia 5.0
.
volume : real |
This property holds the volume of the music output, from 0.0 (silent) to 1.0 (maximum volume).
Note: The volume property affects ALL Sounds and the BackgroundMusic instances on Windows, but not on mobile platforms. So the last volume setting that is defined is used for all sounds in the application.
The default value is 1.
See also muted.
Pauses playback of the media.
Sets the playing property to false. It also sets the playbackState property to
Audio.PausedState
.
See also play().
Starts playback of the media if the settings.musicEnabled property is true (which is the default).
Sets the playing property to true. It also sets the playbackState property to
Audio.PlayingState
.
Stops playback of the media.
Sets the playing property to false. It also sets the playbackState property to
Audio.StoppedState
.
See also play().