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:
Playerinstance and use them while the player is rendering data from media. For example, you can use a
VolumeControlto modify the volume of a sampled audio
Player. Controls are represented by implementations of the
javax.microedition.media.Controlinterface; specific control subinterfaces are in the
javax.microedition.media.protocol.DataSourceis the abstract parent class for all data sources in the Mobile Media API.
javax.microedition.media.Managerclass contains static methods for obtaining
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
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");
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
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.
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
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
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
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
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:
DataSourceclass and the rest of the
javax.microedition.media.protocolpackage are excluded; applications cannot provide their own protocol implementations.
Managerclass is simplified.
MIDP 2.0 requires support for tone generation and sampled .wav audio playback.
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.
To find out more, you can download the current version of the specification.