JSR 234 Advanced Media Supplements API, controls overview & examples

How to use JSR 234 to control the camera or radio and transform images, with code snippets and a MIDlet example.

The Advanced Multimedia Supplements API (JSR 234) extends the Mobile Media API (JSR 135) with several controls simplifying usage of multimedia files and streams. JSR 234 consists of a set of controls that can be used for operating on different media.

This article shows examples of how this API can be used for controlling the camera, radio and transforming images and focuses on the Image Post-Processing Capability, Camera Capability and Tuner Capability. Attached is a MIDlet example using selected parts of the Advanced Multimedia Supplements API.

Download example MIDlet>>

The Advanced Multimedia Supplements API (JSR 234) basically consists of a set of controls that can be used to enhance the usage of the Mobile Media API (JSR 135). The set of functionality provided by JSR 234 can be summarized by the following (some are mandatory and some are optional according to the specification):
Music Capability: Equalizer and volume controls
3D Audio Capability: Support for 3D sound
Image Encoding Capability: Support for encoding images
Image Post-Processing Capability: Effects and transformations for images
Camera Capability: Flash, focus, zoom functionality
Tuner Capability: Tuner functions for the radio

There has been a limited support for JSR 234 since JP-7 but is since JP-8 fully implemented for TCK compliance. On JP-7 phones only the Camera Capability is included. To test for support there is a set of system properties that can be queries as described below:
"supports.mediacapabilities"
"tuner.modulations"
"audio.samplerates"
"audio3d.simultaneouslocations"
"camera.orientations"
"camera.resolutions"

For a more thorough listing of supported functionality please have a look at the document Developers' Guidelines Java ME CLDC (MIDP 2) - download here>>

Image post-processing and encoding capability
The image post-processing and encoding functionality is implemented so that the image transformations are performed by a media processor. A media processor for jpeg can be retrieved by the call:

MediaProcessor mediaProc = GlobalManager.createMediaProcessor("image/jpeg");

The media processor operates in a series of states and processing an image is done by the following steps:
Create a media processor
Configure the media processor using available controls
Instruct the media processor to start processing the image

The media processor must also be configured to read and write from and to a media stream, reading and writing image data. This can be done like the following example:

InputStream is = this.getClass().getResourceAsStream(INPUT_IMAGE);
mediaProc.setInput(is, is.available());
mediaProc.setOutput(os);

The full documentation can be found in the Java Community Process (JCP) JSR 234 information. When having an instance of the media processor, you can retrieve the following controls to perform image processing and encoding using:

ImageEffectControl imageEffect = (ImageEffectControl) mediaProc.getControl("javax.microedition.amms.control.imageeffect.ImageEffectControl");

ImageTonalityControl imageTonality = (ImageTonalityControl) mediaProc.getControl("javax.microedition.amms.control.imageeffect.ImageTonalityControl");

ImageTransformControl imageTransform = (ImageTransformControl) mediaProc.getControl("javax.microedition.amms.control.imageeffect.ImageTransformControl");

OverlayControl overlay = (OverlayControl) mediaProc.getControl("javax.microedition.amms.control.imageeffect.OverlayControl");

WhiteBalanceControl whiteBalance = (WhiteBalanceControl) mediaProc.getControl("javax.microedition.amms.control.imageeffect.WhiteBalanceControl");

ImageFormatControl imageFormat = (ImageFormatControl) mediaProc.getControl("javax.microedition.amms.control.ImageFormatControl");

All the different controls have different methods for querying and setting possible values. For a complete list of functions please have a look in the JCP JSR 234 documentation. Common for all the controls is that they must be enabled by the call "setEnabled(true)" to be executed.

An example using the ImageEffectControl could look like this:

String[] preset_names = imageEffect.getPresetNames();
//…//
imageEffect.setPreset(choice);
imageEffect.setEnabled(true);

The same type of configuration can be performed using ImageTransformControl:

int source_width = imageTransform.getSourceWidth();
int source_height = imageTransform.getSourceHeight();
//…//
imageTransform.setSourceRect(x, y, new_width, new_height);
imageTransform.setTargetSize(w, h, rotation);
imageTransform.setEnabled(true);

Once the media processor has been configured properly you can trigger the media processing either synchronously or asynchronously using a framework with callbacks. To trigger synchronous processing one can do the following:

mediaProc.complete();

Camera capability
The camera capability for JSR 234 is implemented as controls operating on the Player object available from JSR 135. The controls provide a set of functionality for taking snapshots, photography and recording video. The player can be retrieved using the following call:

player = Manager.createPlayer(playerStr);
player.realize();

Once the player is created, the following controls can be retrieved for the extended camera functionality:

CameraControl camContr = (CameraControl) player.getControl("javax.microedition.amms.control.camera.CameraControl");

FlashControl flashContr = (FlashControl) player.getControl("javax.microedition.amms.control.camera.FlashControl");

ZoomControl zoomContr = (ZoomControl) player.getControl("javax.microedition.amms.control.camera.ZoomControl");

FocusControl focusContr = (FocusControl) player.getControl("javax.microedition.amms.control.camera.FocusControl");

SnapshotControl snapshotContr = (SnapshotControl) player.getControl("javax.microedition.amms.control.camera.SnapshotControl");

All the different controls have different methods for querying and setting possible values. For a complete list of functions please check the JCP JSR 234 documentation.

An example using the SnapshotControl to take 10 snapshots could look like this:

snapshotContr.setDirectory("/c:/pictures");
snapshotContr.setFilePrefix(picName);
snapshotContr.setFileSuffix(".jpg");
int bursts = 10;
snapshotContr.start(bursts);

Tuner capability
The tuner capability for JSR 234 is also implemented as controls operating on the Player object available from JSR 135. The controls provide a set of functionality for easily tuning to different radio channels. Once the player is created, the following controls can be retrieved for the extended tuning functionality:

TunerControl tunerControl = (TunerControl) player.getControl("javax.microedition.amms.control.tuner.TunerControl");

RDSControl rdsControl = (RDSControl) player.getControl("javax.microedition.amms.control.tuner.RDSControl");

Once the tuner control has been retrieved, you can use this for easy tuning of the radio frequency as the example below:

boolean forward = true;
int freq = tunerControl.seek(tunerControl.getFrequency(), tunerControl.MODULATION_FM, forward);
tunerControl.setFrequency(freq, TunerControl.MODULATION_FM);

In a similar way the RDS control can be used for querying for RDS data:

if(rdsControl.isRDSSignal()){
String channel = rdsControl.getPS();
String text = rdsControl.getRT();
}