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 will hold 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 Working with the file system.

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 very 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.

Last modified: 2014-02-25

comments powered by Disqus