Playing audio

You can use the MediaPlayer to play audio files and streams. The MediaPlayer allows your app to play audio files, and also provides your app with seek, rewind, and fast forward functionality.

You can create one MediaPlayer for every sound you want to play, but it's not necessary unless you intend to play more than one sound at the same time. You can use one MediaPlayer and programmatically set its sourceUrl property for each sound that you want to play, at the moment that you're ready to play that sound.

Depending on the resources that are available to the device that will run your app, you could choose to create a MediaPlayer for each sound you want to play. This allows you to call the prepare() function for each MediaPlayer in advance and acquire the resources needed to play each sound. You may want to do this if you need to play a number of sounds in rapid succession, or if you want to play many sounds at the same time. The trade-off is that your app holds a number of resources as it prepares itself to play all of the sounds, in all of the MediaPlayer objects that have been defined. This may cause the device to fail if it doesn't have a sufficient amount of resources to support the app's demands. Whether you choose to create one or many MediaPlayer objects for your app should be judged on a case-by-case basis.

Permissions

When your app is used to play media content that's stored in the shared areas of the device, you must add the access_shared permission to allow your app to access and play those media files.

For more information about adding permissions to your bar-descriptor.xml file, see The bar-descriptor.xml file.

For more information about the shared data areas of the device, see File system access.

Flow and states

The architectural flow diagram below illustrates the various states of the MediaPlayer class. The MediaPlayer must proceed through various states before going to the Started state where it can play any media content.

Unprepared state

The MediaPlayer begins in an Unprepared state, which means that it cannot play content because it doesn't have the necessary resources to do so.

Prepared and Started state

When the MediaPlayer acquires the resources it needs to play the media content, it moves into the Prepared state. The Prepared state usually moves quickly into the Started state where it can begin playing media content.

It's not unusual to have an app go from the Unprepared state directly to the Started state and begin playing content. In this case, it may appear that the Prepared state was skipped, but it's not skipped, it's just occurring briefly.

Flow diagram showing the media player states

Three categories of sounds

With Cascades, playing sounds in an app requires a little bit of setup and a few lines of code. There are three basic categories of sounds that you can play in your apps.

Audio files

These are typically entertainment sound files, such as music, movie, web or voice sound files.

BlackBerry 10 OS system sounds

Every device comes preloaded with BlackBerry 10 OS system sounds. These are the sounds that the operating system uses to indicate various events. For example, a General Notification sound alerts the user to an important system event, a Camera Shutter Event sound indicates that the device camera has been activated, and a Low Battery Event sound indicates that the battery power level is low. You can use these system sounds in your apps, and they are available using the SystemSound class and some code.

Custom sounds

You can create one or more custom sounds, save them in any one of the most popular sound file formats, and play them in your apps using the MediaPlayer class and a few lines of code. The MediaPlayer class can play many of today's most popular sound file formats such as .mp3, .wav, and .wma to name a few.

For more information on the file formats supported, see BlackBerry media support at a glance.

Playing system sounds

A static play() function is provided in the SystemSound class to asynchronously play any system-defined sound file.

The architectural flow diagram for SystemSound is shown in the image to the right.

The flow for SystemSound is straightforward. You need to set a system sound to play, then play it one or more times.

Flow diagram for SystemSound

Here's a code sample that shows you how to use the play() function to play a camera shutter sound.

import bb.cascades 1.2
import bb.multimedia 1.2

Page {
    Container {
        // ...
        
        attachedObjects: [
            SystemSound {
                id: sysSound
                sound: SystemSound.CameraShutterEvent
            }
        ]
        
        Button {
            text: "Play System Sound"
                    
            onClicked: {
                sysSound.play();
            }
        }
    }
}
// Code sample showing the single line of code
// needed to asynchronously play a system sound

SystemSound::play(SystemSound::CameraShutterEvent);

You can use the play() function to play a sound, either one time or many times in rapid succession. As you can see in the following C++ code sample, a SystemSound object called keypress is used to play a system sound (SystemSound::InputKeypress) two times in rapid succession by repeatedly calling the keypress.play() function in a for loop.

// SystemSound object created and used from C++.
// In this C++ code sample, the InputKeypress system
// sound is played two times

// Define the system sound that you want to play
SystemSound keypress(SystemSound::InputKeypress);

// Play the sound as desired by calling the
// keypress.play() method repeatedly
for(int i=0; i<2; i++) {
    keypress.play();
}

Playing custom sounds

Custom sounds are saved in audio files, and you can use MediaPlayer to play audio files by following these steps:

  • Add the multimedia library by using the import bb.multimedia 1.2 import statement.
  • Create a MediaPlayer object.
  • Set the path as the source URL to the audio file that you want to play. This source path can be any URI, and can point to either a local and remote file.
  • Call the player's play() function to play the audio file.

When using BlackBerry 10 OS version 10.1 to perform the concurrent playback of multiple media items, such as local files or remote streams, you’re only guaranteed to have a maximum of 8 items playing at the same time.

Here's a QML code sample that shows you how to play and stop a custom audio file.

import bb.cascades 1.2
import bb.multimedia 1.2

Page {
    Container {
        layout: AbsoluteLayout {
        }
        
        attachedObjects:[
            MediaPlayer {
                id: audioPlayer
                sourceUrl: "/path/to/audio.wav"
            }
        ]
        
        Button {
            text: "Play Audio"
            onClicked: {
                if(audioPlayer.play() != MediaError.None) {
                    // Your error handling code here
                }
            }
        }
        
        Button {
            text: "Stop Audio"
            onClicked: {
                if(audioPlayer.stop() != MediaError.None) {
                    // Your error handling code here
                }
            }
        }
    }
}

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus