javax.microedition.amms.control
Interface FormatControl

All Superinterfaces:

javax.microedition.media.Control

All Known Subinterfaces:

AudioFormatControl, ContainerFormatControl, ImageFormatControl, VideoFormatControl

public interface FormatControl
extends javax.microedition.media.Control

FormatControl controls the format used for storing media.

Formats are specified when media is captured from a Player or if the format is changed when media is processed by a MediaProcessor. FormatControl is a super interface for ContainerFormatControl, ImageFormatControl, AudioFormatControl and VideoFormatControl. FormatControl specifies the methods to set and get various parameters to specify the media format.

The purpose of the the different format Controls is as follows:

• FormatControl - an abstract superinterface of all format controls to specify the methods to manage parameters and settings affecting formats.
• ContainerFormatControl - specifies the file format of the audio-video container format. For example, 3GPP video is a container format that can contain audio and video in various formats.
• VideoFormatControl - specifies the video format. For example, if the container format is 3GPP video, VideoFormatControl specifies if the video is in MPEG4 video or H.263 format.
• AudioFormatControl - specifies the audio format. AudioFormatControl also specifies the container formats for audio only file formats.
• ImageFormatControl - specifies the image format. ImageFormatControl also specifies the container formats for imaging. For example, PNG is a container image format which is managed by ImageFormatControl, not by ContainerFormatControl.

Formats

The format is set by the setFormat(String format) method which takes one of the formats returned by the getSupportedFormats() as a parameter. Formats are represented as MIME types. MIME type alone does not provide enough information to specify the format exactly. Once the format has been set by setFormat(String format) PARAM_VERSION_TYPE parameter can be used with setParameter(String parameter, String value) (see the next section for details) to set the format exactly to the one that is wanted.

PARAM_VERSION_TYPE definitions are not part of this specification. Instead, a list of definitions can be downloaded from Forum Nokia. The list will be constantly updated and new types will be added as needed.

Parameters

The parameter interface allows various content type specific parameters to be accessed. Supported integer parameters are queried by getSupportedIntParameters() and supported String parameters by getSupportedStrParameters(), respectively. The range of integer values to be set by setParameter(String parameter, int value) can be queried by getSupportedIntParameterRange(String parameter). Different values for String parameters to be set by setParameter(String parameter, String value) can be queried by getSupportedStrParameterValues(String parameter).

Metadata

Some formats can contain metadata that can be set by setMetadata(String key, String value). getMetadataSupportMode() tells what kind of metadata can be set to the media and getSupportedMetadataKeys() returns a list of the metadata keys or, in case any metadata keys can be used, a list of the most common ones. Some metadata might be added to the content by the implementation. For instance, images taken by the digital camera may automatically contain information about resolution, camera settings and time when the image was taken.

Occasionally, when the MediaProcessor is used it is possible that the metadata is at the end of the processed stream and it is not known before the processing is started. This could result into contradiction between the metadata set by the application and the metadata already in the media. setMetadataOverride(boolean override) can be used to tell if the new metadata should override the existing metadata or vice versa.

See MetaDataControl in JSR-135 for reading metadata.

Example

This example illustrates how to set a format and some parameters for it. Here, p is Player for camera. See Overview for the complete example.

     //Set up snapshot format:
    imageFormatControl = (ImageFormatControl)
      p.getControl("javax.microedition.amms.control.ImageFormatControl");
    if(imageFormatControl != null) {
      imageFormatControl.setFormat("image/jpeg");
      imageFormatControl.setParameter(FormatControl.PARAM_VERSION_TYPE,
                                      "JPEG");
      //JPEG quality:
      imageFormatControl.setParameter(FormatControl.PARAM_QUALITY, 80);
    }
        

Adding metadata to the image can be done as follows:

         imageFormatControl.setMetadata("Title", "Swimming in summer 2006");
         imageFormatControl.setMetadata("Keywords", "swimming, beach, summer 2006");
         imageFormatControl.setMetadata("Comments", "Warmest day of the whole summer");
 

Field Summary

static int	METADATA_NOT_SUPPORTED Setting metadata is not supported.
static int	METADATA_SUPPORTED_FIXED_KEYS Setting metadata is supported and the set of metadata keys is limited.
static int	METADATA_SUPPORTED_FREE_KEYS Setting metadata is supported and any Strings can be used as metadata keys.
static java.lang.String	PARAM_BITRATE The output bit rate integer parameter.
static java.lang.String	PARAM_BITRATE_TYPE The bit rate type String parameter tells if the bit rate is constant or variable.
static java.lang.String	PARAM_FRAMERATE The output frame rate integer parameter.
static java.lang.String	PARAM_QUALITY The quality parameter for example for JPEG.
static java.lang.String	PARAM_SAMPLERATE The output sample rate integer parameter.
static java.lang.String	PARAM_VERSION_TYPE The format version type String parameter to specify what is the the type of the format.

Method Summary

int	getEstimatedBitRate() Gets the estimated bit rate of the media.
java.lang.String	getFormat() Get the format.
int	getIntParameterValue(java.lang.String parameter) Gets the current value of an integer parameter.
boolean	getMetadataOverride() Returns the metadata override mode.
int	getMetadataSupportMode() Returns the metadata support mode.
java.lang.String	getStrParameterValue(java.lang.String parameter) Gets the current value of a String parameter.
java.lang.String[]	getSupportedFormats() Gets supported formats.
int[]	getSupportedIntParameterRange(java.lang.String parameter) Gets range for the given int-valued parameter.
java.lang.String[]	getSupportedIntParameters() Gets the supported parameters for the current format.
java.lang.String[]	getSupportedMetadataKeys() Returns a list of supported metadata keys.
java.lang.String[]	getSupportedStrParameters() Gets the supported parameters for the current format.
java.lang.String[]	getSupportedStrParameterValues(java.lang.String parameter) Gets available values for the given String-valued parameter.
void	setFormat(java.lang.String format) Sets the format.
void	setMetadata(java.lang.String key, java.lang.String value) Sets metadata for the media
void	setMetadataOverride(boolean override) Sets the metadata override mode.
int	setParameter(java.lang.String parameter, int value) Sets int-valued parameter's value.
void	setParameter(java.lang.String parameter, java.lang.String value) Sets String-valued parameter's value.

Field Detail

METADATA_NOT_SUPPORTED

static final int METADATA_NOT_SUPPORTED

Setting metadata is not supported.

See Also:

Constant Field Values

METADATA_SUPPORTED_FIXED_KEYS

static final int METADATA_SUPPORTED_FIXED_KEYS

Setting metadata is supported and the set of metadata keys is limited.

See Also:

Constant Field Values

METADATA_SUPPORTED_FREE_KEYS

static final int METADATA_SUPPORTED_FREE_KEYS

Setting metadata is supported and any Strings can be used as metadata keys.

See Also:

Constant Field Values

PARAM_BITRATE

static final java.lang.String PARAM_BITRATE

The output bit rate integer parameter. The value of this parameter will be defined in bits per second.

See Also:

Constant Field Values

PARAM_BITRATE_TYPE

static final java.lang.String PARAM_BITRATE_TYPE

The bit rate type String parameter tells if the bit rate is constant or variable. Possible values are "constant" and "variable".

See Also:

Constant Field Values

PARAM_SAMPLERATE

static final java.lang.String PARAM_SAMPLERATE

The output sample rate integer parameter. The value of this parameter will be defined in samples per second.

See Also:

Constant Field Values

PARAM_FRAMERATE

static final java.lang.String PARAM_FRAMERATE

The output frame rate integer parameter. The value of this parameter will be defined in samples per second.

See Also:

Constant Field Values

PARAM_QUALITY

static final java.lang.String PARAM_QUALITY

The quality parameter for example for JPEG. This parameter can be either integer or String.

See Also:

Constant Field Values

PARAM_VERSION_TYPE

static final java.lang.String PARAM_VERSION_TYPE

The format version type String parameter to specify what is the the type of the format.

See Also:

Constant Field Values

Method Detail

getSupportedFormats

java.lang.String[] getSupportedFormats()

Gets supported formats.

Returns:

an array of supported formats

getSupportedStrParameters

java.lang.String[] getSupportedStrParameters()

Gets the supported parameters for the current format.

Returns:

an array of supported String-valued parameters

getSupportedIntParameters

java.lang.String[] getSupportedIntParameters()

Gets the supported parameters for the current format.

Returns:

an array of supported int-valued parameters

getSupportedStrParameterValues

java.lang.String[] getSupportedStrParameterValues(java.lang.String parameter)

Gets available values for the given String-valued parameter.

Parameters:

parameter - the parameter whose valid values are queried

Returns:

an array of supported values for the given parameter

Throws:

java.lang.IllegalArgumentException - if the parameter is not supported or if it is null

getSupportedIntParameterRange

int[] getSupportedIntParameterRange(java.lang.String parameter)

Gets range for the given int-valued parameter.

Parameters:

parameter - the parameter whose range is queried

Returns:

min and max value for the given parameter

Throws:

java.lang.IllegalArgumentException - if the parameter is not supported or if it is null

setFormat

void setFormat(java.lang.String format)

Sets the format.

Parameters:

format - the new format

Throws:

java.lang.IllegalArgumentException - if the format is not supported or if it is null

getFormat

java.lang.String getFormat()

Get the format.

Returns:

the current format

setParameter

int setParameter(java.lang.String parameter,
                 int value)

Sets int-valued parameter's value.

Parameters:

parameter - the parameter to be set

value - the new value to be set

Returns:

the value that was set

Throws:

java.lang.IllegalArgumentException - if the parameter is not supported or the value for the supported parameter is not supported or if the parameter is null

setParameter

void setParameter(java.lang.String parameter,
                  java.lang.String value)

Sets String-valued parameter's value.

Parameters:

parameter - the parameter to be set

value - the new value to be set

Throws:

java.lang.IllegalArgumentException - if the parameter is not supported or the value for the supported parameter is not supported or if the parameter or value is null

getStrParameterValue

java.lang.String getStrParameterValue(java.lang.String parameter)

Gets the current value of a String parameter.

Parameters:

parameter - the parameter whose value is queried

Returns:

the current value of the given parameter

Throws:

java.lang.IllegalArgumentException - if the parameter is not supported or if it is null

getIntParameterValue

int getIntParameterValue(java.lang.String parameter)

Gets the current value of an integer parameter.

Parameters:

parameter - the parameter whose value is queried

Returns:

the current value of the given parameter

Throws:

java.lang.IllegalArgumentException - if the parameter is not supported or if it is null

getEstimatedBitRate

int getEstimatedBitRate()
                        throws javax.microedition.media.MediaException

Gets the estimated bit rate of the media.

Returns:

estimated bit rate in bits/second

Throws:

javax.microedition.media.MediaException - if size estimation is not supported or if the media type is unstreamable

setMetadata

void setMetadata(java.lang.String key,
                 java.lang.String value)
                 throws javax.microedition.media.MediaException

Sets metadata for the media

Parameters:

key - metadata key

value - metadata value

Throws:

javax.microedition.media.MediaException - if setting of the metadata is not supported

java.lang.IllegalArgumentException - if the key or value contains unsupported values or if either is null

getSupportedMetadataKeys

java.lang.String[] getSupportedMetadataKeys()

Returns a list of supported metadata keys. If any String can be used as a metadata getSupportedMetadataKeys returns a list of the most common metadata keys

Returns:

supported metadata keys or a list of the most common ones

getMetadataSupportMode

int getMetadataSupportMode()

Returns the metadata support mode. The support mode is one of the following.

• METADATA_NOT_SUPPORTED
• METADATA_SUPPORTED_FIXED_KEYS
• METADATA_SUPPORTED_FREE_KEYS

Returns:

current metadata support mode

setMetadataOverride

void setMetadataOverride(boolean override)

Sets the metadata override mode. In the overried mode, the metadata set by the application overrides the metadata existing in the media when the existing metadata is found out only when the processing of the media is already going on.

By default, the metadata override mode is true.

Parameters:

override - true to make application set metadata to be written on top of the existing metadata, false to preserve the existing metadata

getMetadataOverride

boolean getMetadataOverride()

Returns the metadata override mode.

Returns:

true if the metadata set by the application overrides the existing metadata, false if the existing metadata is preserved