Friday, February 3, 2012

C10 Audio And Video Playback

This tutorial will show you how to play audio and video files in your application. I will show you how to use the Mobile Media API (MMAPI), also known as JSR 135 on BlackBerry SmartPhones.
I will guide you through the MMAPI, then show you on example on how to play simple tunes, how to play music from file bundled with the application, and how to play the file from your SD card.
I will also tell you which files are supported and how to implement PlayerListener to track events like when the song has finished.
Then we will cover the video playback. I will show you how to play video in full screen and non-full screen modes.

Audio Playback

To play audio on BlackBerry SmartPhones, we will use classes and interfaces from the package. This package is fully compatible with the MMAPI (JSR 135) and if you already have knowledge on how to use it, you can start using it straight away.
Let’s start with an overview of the Manager class.

Manager Class

If you did not notice already there are two classes called Manager in the BlackBerry APIs. The first class is called and the other one is net.rim.device.api.ui.Manager. The first one is the one used for media handling and the latter one is used for managing the UI components of the screen. It is worth paying attention when importing packages.
The Manager class was introduced in version 4.0.0 of BlackBerry JDE. We need the Manager to get access to system resources such as the Player for multimedia processing.
So first thing the Manager does is create a Player which we use to play our media files.
But it can also be used to query a Player, what controls it supports, i.e. volume controls as well as supported content types and protocols. It can be also used to play single tones.

Content Types and Protocols

Content types indentify the type of media. They are also registered as MIME types.
Common audio content types are:
Wave audio files: audio/x-wav, usually files with extension .wav
MP3 audio files: audio/mpeg, usually files with extension .mp3
MIDI audio files: audio/midi, usually files with extension .midi
To find our which protocols specific content types support on the device we can use:
public static String[] getSupportedProtocols(String content_type).

You can also use:
public static String[] getSupportedContentTypes(String protocol),

to find out which content types specific protocols support.

Playing Single Tones

To play a single tone you can use:
public static void playTone(int note, int duration, int volume)
throws MediaException
• SEMITONE_CONST = 17.31234049066755 = 1/(ln(2^(1/12)))
• note = ln(freq/8.176)*SEMITONE_CONST
• The musical note A = MIDI note 69 (0x45) = 440 Hz
• duration is note duration in milliseconds, and
• volume is in range from 0 to 100.
We can use ToneControl constants to play a single note to make our life a little bit easier:
try {
Manager.playTone(ToneControl.C4, 1000, 100);
} catch (MediaException e) { }
This will play middle C note for 1 second at full volume.

Creating a Player

To create a player which will play our audio files we use the following:
Player Manager.createPlayer(String url);
Where url is the location of the audio file. It can be bundled with the application or located on the
device’s memory or SD card.

Player Class

Player has a life cycle. It has 5 states: unrealized, realized, prefetched, started and closed.
Once you create a player it is in the unrealized state. Once it is created it tries to connect to the source of the audio. When the system finds the source (which can be time consuming – especially when using the network) it moves the player in realized state.
The Prefetched state is when the player is ready to play audio. From start the player and it enters the end it will move back to the prefetched state. It is important to know you cannot call some methods in some states. It makes no sense for example to call method start(); to start playback unrealized, realized or closed state. 
methods which we can call to get from one state into another.

Playing Audio

To play audio in your application you might first want to choose which format to use. For background instrumental music, MIDI is the best format as the file sizes are very small, typically 10 - 20 kb, and the sound quality is very good. However if you want to have vocals, or just voice, or any other sound effects, such as thunder or explosions, you will probably choose Mp3.
Mp3 files are bigger, but you can reduce sample rates, to create smaller files, at cost of quality.
Here is a code sample which opens a midi file called test.mid:
public Player myPlayer;
public VolumeControl vc;.

No comments:

Post a Comment