• Home

BackgroundMusic

The BackgroundMusic element allows playing long-lasting and looping background sound in wav, mp3 or ogg file format. More...

• List of all members, including inherited members

Properties

• autoLoad : bool
• autoPauseInBackground : bool
• autoPlay : bool
• availability : enumeration
• bufferProgress : real
• duration : int
• error : enumeration
• errorString : string
• hasAudio : bool
• hasVideo : bool
• loops : alias
• metaData : alias
• muted : bool
• playbackRate : real
• playbackState : enumeration
• playing : bool
• position : int
• seekable : bool
• source : url
• status : int
• volume : real

Signals

• paused()
• started()
• stopped()

Methods

• pause()
• play()
• seek(offset)
• stop()

Detailed Description

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.

Felgo Additions to Audio

BackgroundMusic enhances the Qt 5 component Audio in the Qt Multimedia 5.0 module with the following additions:

• Set infinite looping by deafult. To add more variation with different music tracks, set the loops property to a finite number and play another BackgroundMusic in the onStopped handler.
• Allow to pause and resume all BackgroundMusic objects by setting settings.musicEnbaled to true or false.
• Proper application handling: if the app is moved to the background all instances of SoundEffect and BackgroundMusic are paused on mobile platforms. All instances are then resumed when the app gets focus again and comes into foreground. This is especially useful on mobile devices, where the default Audio component would continue playing if the app is moved to the background. On Desktop platforms, the SoundEffect and BackgroundMusic instances keep playing. You can modify this behavior with the autoPauseInBackground property.
• Use the playing property to make it easier to detect if the BackgroundMusic is currently playing.

Audio Details

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.

Finding Sounds

For free sounds, we recommend the following websites:

• http://www.playonloop.com/ - For background music
• http://www.noiseforfun.com/ - For sound effects
• http://www.audiomicro.com/free-sound-effects - Also for sound effects

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.

Supported Audio Formats

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:

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().

Performance Hints

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.

Example Usage

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
 }

Property Documentation

Signal Documentation

Method Documentation