August 13, 2007

Using the Mobile Media API to Play Video

The Mobile Media API (JSR-135) specification enables advanced audio and video support on Java ME devices. While MIDP 2.0 supports a subset of the MMAPI, this subset does not include the video or graphics components of the specification. In this article, we will look at a simple example of how to play video on a MMAPI enabled device.

From a developer perspective, there are three major components you will need to worry about when working with the MMAPI. Player objects are used to process content and rendered it to the user. Manager objects are factories that create Player objects. Lastly, you will need an object to provide the input for the content itself. This can either be a DataSource or an InputStream object.

I’ve contructed a very simple MIDlet that demonstrates how to play a video, which I will be referring to below. The full source code for this MIDlet can be found here: MMAPI Video Demo Source Code. An example MPEG file is included in this file. If you are using NetBeans Mobility Pack, make sure you have enabled the optional package “Mobile Media API” in your project configuration.

In this example, I’ve created a class called VideoForm that encapsulates all of the required logic for initializing and playing the video. A StringItem object is used to inform the user of the current status. The block of code below is used to create the player object. Note that getMediaFileName() and getContentType() are simply accessor methods in my VideoForm class. For this simple example, the video will be a resource stored in the JAR file, and the application will aquire an InputStream for it using the getResourceAsStream() method.

// Create the Player object from an InputStream
InputStream inputStream = 
    getClass().getResourceAsStream(getMediaFileName()); 

Player player = Manager.createPlayer( 
    inputStream, 
    getContentType() 
);

Once the Player is created, the code below sets the loop count and allows the Player to initialize itself. Note that the realize() method can be particularly slow, so appropriate feedback should relayed to the user.

// Set the loop count 
player.setLoopCount(getLoopCount()); 

// Realize (contruct player) 
getStatusItem().setText("Realizing..."); 
player.realize(); 
getStatusItem().setText("Realized."); 

// Prefetch (aquire resources) 
getStatusItem().setText("Prefetching..."); 
player.prefetch(); 
getStatusItem().setText("Prefetched.");

Now we can get a VideoControl object which can be added to our form. As you may have noticed, VideoControl is not part of MIDP 2.0, therefore the device must support MMAPI in order for this to work. Alternatively, if you were using a Canvas instead of a Form as your displayable object, you could take advantage of the VideoControl.USE_DIRECT_VIDEO option to write directly to the Canvas.

// Add VideoControl to form 
VideoControl videoControl = 
    (VideoControl)player.getControl("VideoControl"); 

if(videoControl != null) { 
    Item videoItem = 
    (Item)videoControl.initDisplayMode( 
        VideoControl.USE_GUI_PRIMITIVE, 
        null); 
    append(videoItem); 
}

Lastly, in our MIDlet class, we will do something similar to the following to set up the VideoForm and start the video.

VideoForm form = new VideoForm("Video Test"); 
form.setContentType("video/mpeg"); 
form.setMediaFileName("/video.mpg"); 
... 
// Start the video 
form.play();

For more information about MMAPI, check out the following links:

MMAPI Home Page
MMAPI JavaDoc
J2ME Tutorial, Part 4: Multimedia and MIDP 2.0

Filed under Java ME Development