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

Sources of sounds

With Cascades, playing sounds in an app requires a little bit of setup and a few lines of code. In addition to audio files such as music, movie, web, or voice sound files, there are also BlackBerry 10 OS system sounds, and custom sounds. Cascades makes playing sounds fairly straight forward.

If you're developing an app with C, you can use the drivers and libraries of the QNX Sound Architecture (QSA) to control many aspects of the sounds your apps use.

BlackBerry 10 OS system sounds

Every device comes preloaded with BlackBerry 10 OS system sounds. The operating system uses these sounds 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 system sounds in your apps, and they're 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 sound file formats including .mp3, .wav, and .wma to name a few.

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

QNX Sound Architecture

For more information about using the QSA in your apps, see QNX Sound Architecture.

Last modified: 2015-03-31



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

comments powered by Disqus