Java Mobile Media API
JSR-135 is the Multimedia Java API Java Specification Request (JSR) from the Java Community Process (JCP) intended for use on CDC and CLDC devices such as mobile phones. Depending on how it's implemented, it has APIs to play and record sounds and video, and to capture still images.
Programming concepts
JSR135 is based around four main types of classes - the Manager, the Player, the PlayerListener and various types of Control.
J2ME programmers wishing to use JSR135 would first make use of the static methods of the Manager class. Although there are other methods such as playTone, the main method used is createPlayer. This takes either a [URI] or an [InputStream], and optionally a [MIME type]. In most cases, URIs are used. Common URI schemas 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 will otherwise be inferred from the data passed in.
createPlayer will return an implementation of the Player interface (even if you use a capture: 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.)
Players also have a getControl method, which will return 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 will actually be 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 JSR:
- RateControl - for setting the speed of a clip
- MetaDataControl - for accessing metadata about a clip, for example ID3 tags
- FramePositioningControl - for setting a video clip location based on frames rather than time
- StopTimeControl - for asking a clip to stop at a given time
- RecordControl - to specify how you wish to record using a capture: URI, and for taking snapshots
- ToneControl - for note-based formats such as MIDI, specifying the tone
- PitchControl - for note-based formats, specifying the pitch
- MIDIControl - for MIDI-specific functions such as bank queries
- VideoControl - for specifying where on the screen video might play
(Others may be defined in JSR234).
A subset of JSR135 is defined in JSR118 - MIDP itself.
Implementations
As with most J2ME 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 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 JSR135, 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 osbcure parts of J2ME such as recording.
Implementation consistency is ensured by forcing all implementations to pass the Java Technology Compatibility Kit (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
import javax.microedition.media.*;
Player p = Manager.createPlayer("http://www.fishy.com/my.mp3");
p.start();