The Mobile Media API is an API specification for the Java ME platform CDC

Connected Device Configuration

The Connected Device Configuration is a specification of a framework for Java ME applications describing the basic set of libraries and virtual-machine features that must be present in an implementation. The CDC is combined with one or more profiles to give developers a platform for building...

 and CLDC devices such as mobile phones. Depending on how it's implemented, the APIs allow applications to play and record sounds and video, and to capture still images. MMAPI was developed under the Java Community Process

Java Community Process

The Java Community Process or JCP, established in 1998, is a formalized process that allows interested parties to get involved in the definition of future versions and features of the Java platform....

 as JSR 135.

Programming concepts

The Multimedia Java API is based around four main types of classes in the javax.microedition.media package

Java package

A Java package is a mechanism for organizing Java classes into namespaces similar to the modules of Modula. Java packages can be stored in compressed files called JAR files, allowing classes to download faster as a group rather than one at a time...

—the Manager, the Player, the PlayerListener and various types of Control.

Java ME programmers wishing to use JSR 135 would first make use of the static methods of the Manager class

Class (computer science)

In object-oriented programming, a class is a construct that is used as a blueprint to create instances of itself – referred to as class instances, class objects, instance objects or simply objects. A class defines constituent members which enable these class instances to have state and behavior...

. Although there are other methods such as playTone, the main method used is createPlayer. This takes either a URI or an , and a MIME type. In most cases, URIs are used. Common URI protocols used include:

• file:
• resource: (which may extract a file from within the JAR of the MIDlet, but is implementation-dependent)
• http:
• rtsp:
• capture: (used for recording audio or video)

The MIME type is optional, and is inferred from the data passed in if not supplied.

The createPlayer method returns an implementation of the Player interface

Interface (Java)

An interface in the Java programming language is an abstract type that is used to specify an interface that classes must implement. Interfaces are declared using the interface keyword, and may only contain method signature and constant declarations...

 (even if you use a capture: protocol URI). This has core methods that are applicable to all players, such as starting and stopping the media, and requesting that it loop. You can also setPlayerListener to an object implementing the PlayerListener interface, which will receive various events related to the clip (starting, stopping, media finishing, etc.)

Player classes also have a getControl method that returns an implementation of a particular Control. A Control handles any optional APIs which are not applicable to all media types. Any given Player may or may not be able to supply an implementation of any given Control.

(Typically, the Control returned is actually the Player itself, but this is not guaranteed to be the case.)

The set of controls implemented by a Player is not limited; however, some standard ones are defined in the javax.microedition.media.control package by the JSR:

Standard MMAPI Controls

Control Interface	Description
FramePositioningControl	A control for video data that allows access to individual frames.
GUIControl	A control for data that requires a display, such as video.
MetaDataControl	Used to determine the metadata information stored within amedia stream, such as title, copyright, author, and so on.
MIDIControl	A fully functional control that enables access to a device’s MIDI player.
PitchControl	Used to control the pitch (frequency) of audio data.
RateControl	Used to control the playback rate of a Player.
RecordControl	Allows you to control the recording of data from a capture device, such as video from a camera or audio from a sound recorder.
StopTimeControl	A control that allows you to set a preset time when you want the Player to stop playing.
TempoControl	Similar to RateControl, this control allows you to change the tempo (speed) of playback for an audio Player, typically, a MIDI Player.
ToneControl	A fully functional control that allows you to play monotonic tone sequences.
VideoControl	Extends GUIControl and controls the display of video.
VolumeControl	The simplest control that allows you to control the volume of audio in a Player.

(Others may be defined in JSR 234 (Advanced Multimedia Supplements

Advanced Multimedia Supplements

In computing, the Advanced Multimedia Supplements is an API specification for the Java ME platform. Practically speaking, it is an extension to JSR 135 Mobile Media API providing new features, such as positional 3D audio processing, audio and video effects processing, better controls for digital...

).

A subset of JSR 135 is defined in JSR 118 (MIDP 2.0).

Player Lifecycle

Regardless of the protocol or media type involved, the Player moves through the same discrete states during its lifecycle. These states are listed in table below

Lifecycle states of a Player instance

State	Description
Unrealized	Initial state when a Player is created. In this state the player does not have enough information to acquire the necessary resources to process the media.
Realized	The Player moves into the Realized state once it has obtained the necessary information to acquire the resources. In this state it is likely that most of the resources have already been acquired to function. However, some resources may not have been acquired at this point, especially if there are system dependencies involved such as with an audio or video driver where exclusive access must be obtained.
Prefetched	The Player moves into the Prefetched state once all resources have been acquired, including scarce and system dependent resources. Once in the Prefetched state, the Player has everything necessary to perform its tasks.
Started	A Player in the Started state indicates that the content associated with the Player is being processed.
Closed	A Player moves to the Closed state at the end of its lifecycle. A Player in the Closed state must not be used again.

Implementations

As with most Java ME specifications, implementations differ despite the best efforts of the specification authors to ensure consistency. Two obvious areas for differences are in the controls supported, and in the acceptable URI types in the first place. More obscure areas are whether mixing

Audio mixing (recorded music)

In audio recording, audio mixing is the process by which multiple recorded sounds are combined into one or more channels, most commonly two-channel stereo. In the process, the source signals' level, frequency content, dynamics, and panoramic position are manipulated and effects such as reverb may...

 is supported; many games would like to play a MIDI music track and layer PCM sound effects on top.

Another source of extreme variance is in performance. For example, if an HTTP clip is requested, at what point does the clip get downloaded? The specification recognises this by providing two Player methods that can be called in advance of actually playing: realize and prefetch. Depending on the implementation, these may do some of the work of getting the clip into a playable state, thus making it quicker to actually play the clip when it is needed. Some implementations are sophisticated enough to actually stream a clip on request whilst it is being played.

Symbian OS contains a very complete implementation of JSR 135, but even this is highly dependent on the underlying multimedia capabilities of the device, and some device manufacturers may choose not to expose the more obscure parts of Java ME such as recording.

Implementation consistency is ensured by forcing all implementations to pass the Java Technology Compatibility Kit

Technology Compatibility Kit

A Technology Compatibility Kit is a suite of tests that at least nominally checks a particular alleged implementation of a Java Specification Request for compliance...

(TCK). This ensures that each supported URI schema, MIME type and Control is tested, but does not test every permutation of these optional parts.

Code example

package org.wikipedia;

import javax.microedition.midlet.*;
import javax.microedition.media.*;

public class SimplePlayer extends MIDlet {
protected void destroyApp(boolean arg0) throws MIDletStateChangeException {}

protected void pauseApp {}

protected void startApp throws MIDletStateChangeException {
try {
String url = "http://upload.wikimedia.org/wikipedia/commons/a/a0/Bass_sample.mid";
Player player = Manager.createPlayer(url);
player.start;
} catch (Exception e) {
e.printStackTrace;
}
}
}

External links

• JSR 135
• Mobile Media API Overview