Mobile Media API Overview

by Jonathan Knudsen
June 2002

The Mobile Media API (MMAPI) provides a powerful, flexible, and simple interface to multimedia capabilities. It exposes a clean interface for playing and recording audio and video data. This article provides an overview of the concepts of the MMAPI and a quick tour of its classes and interfaces.

Mobile Media API Architecture

The Mobile Media API is based on four fundamental concepts:

1. A player knows how to interpret media data. One type of player, for example, might know how to produce sound based on MP3 audio data. Another type of player might be capable of showing a QuickTime movie. Players are represented by implementations of the javax.microedition.media.Player interface.
2. You can use one or more controls to modify the behavior of a player. You can get the controls from a Player instance and use them while the player is rendering data from media. For example, you can use a VolumeControl to modify the volume of a sampled audio Player. Controls are represented by implementations of the javax.microedition.media.Control interface; specific control subinterfaces are in the javax.microedition.media.control package.
3. A data source knows how to get media data from its original location to a player. Media data can be stored in a variety of locations, from remote servers to resource files or RMS databases. Media data may be transported from its original location to the player using HTTP, a streaming protocol like RTP, or some other mechanism. javax.microedition.media.protocol.DataSource is the abstract parent class for all data sources in the Mobile Media API.
4. Finally, a manager ties everything together and serves as the entry point to the API. The javax.microedition.media.Manager class contains static methods for obtaining Players or DataSources.

Using the Mobile Media API

The simplest thing you can do with Manager is play tones using the following method:

public static void playTone(int note,
int duration, int volume) throws MediaException

The duration is specified in milliseconds and the volume ranges from 0 (silent) to 100 (loud). The note is specified as a number, as in MIDI, where 60 is middle C and 69 is a 440 Hz A. The note can range from 0 to 127. The playTone() method is appropriate for playing a single tone or a very short sequence. For longer monotonic sequences, you'll use the default tone player, which is capable of playing an entire sequence of tones.

The real magic of the Mobile Media API is exposed through Manager's createPlayer() method. There are three different versions of this method as follows:

public static Player createPlayer(String locator) throws IOException, MediaException public static Player createPlayer(DataSource source) throws IOException, MediaException public static Player createPlayer(InputStream stream, String type) throws IOException, MediaException

The simplest way to obtain a Player is to use the first version of createPlayer() and just pass in a string that represents media data. For instance, you might specify an audio file on a web server:

Player p = Manager.createPlayer("http://webserver/music.mp3");

The other createPlayer() methods allow you to create a Player from a DataSource or an InputStream, whatever you happen to have available. If you think about it, these three methods are really just three different ways of getting at the media data, the actual bits. An InputStream is the simplest object, just a byte stream. The DataSource is the next level up, an object that speaks a protocol to get access to media data. And passing a locator string is the ultimate shortcut: the MMAPI figures out which protocol to use and gets the media data to the Player.

Using a Player

Once you've successfully created a Player, what do you do next? The simplest action is to begin playback with the start() method. For anything beyond the rudiments, however, it helps to understand the life cycle of a Player. This consists of four states.

When a Player is first created, it is in the UNREALIZED state. After a Player has located its data, it is in the REALIZED state. If a Player is rendering an audio file from an HTTP connection to a server, for example, the Player reaches REALIZED after the HTTP request is sent to the server, the HTTP response is received, and the DataSource is ready to begin retrieving audio data. The next state is PREFETCHED, and is achieved when the Player has read enough data to begin rendering. Finally, when the data is being rendered, the Player's state is STARTED.

The Player interface provides methods for state transitions, both forwards and backwards through the cycle described above. The reason is to provide the application with control over operations that might take a long time. You might, for example, want to push a Player through the REALIZED and PREFETCHED states so that a sound can be played immediately in response to a user action.

The Mobile Media API in the Java Platform

Where exactly does the MMAPI fit in the Java 2 platform? The answer is just about anywhere. Although the MMAPI was designed with the contraints of the CLDC in mind, it will work just fine alongside either CLDC or CDC software stacks. As a matter of fact, the MMAPI can be implemented with J2SE as a lightweight alternative to the Java Media Framework.

What Media Types are Supported?

If you get a device that supports the Mobile Media API, what kinds of data can it play? What data transfer protocols are supported? The Mobile Media API doesn't require any specific content types or protocols, but you can find out at runtime what is supported by calling Manager's getSupportedContentTypes() and getSupportedProtocols() methods.

What's the worst that can happen? If you ask Manager to give you a Player for a content type or protocol that is not supported, it will throw an exception. Your application should attempt to recover gracefully from such an exception, perhaps by using a different content type or displaying a polite message to the user.

Media in MIDP 2.0

The MIDP 2.0 specification includes a subset of the Mobile Media API. It is upwardly compatible with the full API. The MIDP 2.0 subset has the following characteristics:

• Only audio playback (and possibly recording) is supported. No video-specific control interfaces are included.
• Multiple players cannot be synchronized.
• The DataSource class and the rest of the javax.microedition.media.protocol package are excluded; applications cannot provide their own protocol implementations.
• The Manager class is simplified.

MIDP 2.0 requires support for tone generation and sampled .wav audio playback.

Summary

The Mobile Media API provides a compact, flexible, and clean API for using multimedia capabilities from a Java application running on a mobile device. At the time of this writing, the Mobile Media API is finished with its public review in the Java Community Process; expect a reference implementation release in the summer of 2002.