Music has always been a part of human civilization. Therefore it is quite logical for the consumers to demand multimedia features in there phones. Realizing this, founders of J2ME have developed the Mobile Media API (JSR 135). They have tried to give us an easy to use yet powerful API for developing applications involving multimedia. Mobile Media API helps us in playing and recording sounds and video. In fact no good game can be complete without the use of Mobile Media API. Even businesses will over the long run be using this API in a variety of ways. In this section we will discuss the classes and interfaces of Mobile Media API in detail.

Mobile Media API consists of the following 3 packages:

·   javax.microedition.media

·   javax.microedition.media.control

·   javax.microedition.media.protocol

javax.microedition.media

public interface Control

What is it?

An object of this interface is used to control some media processing functions. The set of operations in a single Control are usually functionally related. Thus an object of this interface provides a logical grouping of media processing functions. Multiple controls can be implemented by the same Player. The Control interface has the following subinterfaces:

·   FramePositioningControl

·   GUIControl

·   MetaDataControl

·   MIDIControl

·   PitchControl

·   RateControl

·   RecordControl

·   StopTimeControl

·   TempoControl

·   ToneControl

·   VideoControl

·   VolumeControl

 

public interface Controllable

What is it?

The Controllable interface provides us the methods for obtaining the Controls from an object like a Player. It provides methods to query all the supported Controls or to obtain a particular Control.

 

o    Methods

·         public Control[] getControls()

This method returns the collection of Control objects supported by the implementing object.

·         public Control getControl(String controlType)

This method returns the object that implements the control. If the object does not implements this particular Control then it returns null.

 

public interface Player

What is it?

The Player interface defines methods and fields for controlling the rendering of time based media data. This interface provides the methods which help us in accomplishing the following:

·   Manage the Player's life cycle

·   Control the playback progress

·   Obtain the presentation components

·   Synchronization with other Players.

 

o    Fields

·         public static final int UNREALIZED

This field indicates the state of the Player. It indicates that the Player has not acquired the required information and resources to function.

·         public static final int REALIZED

This field indicates the state of the Player. It indicates that the Player has acquired the required information but not the resources to function.

·         public static final int PREFETCHED

This field indicates the state of the Player. It indicates that the Player has acquired all the resources to begin playing.

·         public static final int STARTED

This field indicates the state of the Player. It indicates that the Player has already started.

·         public static final int CLOSED

This field indicates the state of the Player. It indicates that the Player is closed.

·         public static final long TIME_UNKNOWN

This field stands for the returned value indicating that the requested time is unknown.

 

o    Methods

·         public void realize()

This method constructs portions of the Player without acquiring the scarce and exclusive resources. This method may take some time to complete.

·         public void prefetch()

This method acquires the scarce and exclusive resources and processes as much data as necessary to reduce the start latency.

·         public void start()

This method starts the Player as soon as possible.

·         public void stop()

This method Stops the Player. This method pauses the playback at the current media time.

·         public void deallocate()

This method releases the scarce or exclusive resources like the audio device acquired by the Player.

·         public void close()

This method will close the Player and release its resources.

·         public void setTimeBase(TimeBase  master)

This method sets the TimeBase for this Player.

·         public TimeBase getTimeBase()

This method returns the TimeBase that this Player is using.

·         public long setMediaTime(long now)

This method sets the Player's media time.

·         public long getMediaTime()

This method returns the current media time in microseconds or this method will return TIME_UNKNOWN.

·         public int getState()

This method returns the Player's current state.

·         public long getDuration()

This method returns the duration in microseconds or the TIME_UNKNOWN field.

·         public String getContentType()

This method returns the content type being played back by this Player.

·         public void setLoopCount(int count)

This method sets the number of times the Player will loop and play the content.

·         public void addPlayerListener(PlayerListener playerListener)

This method adds a player listener for this player.

·         public void removePlayerListener(PlayerListener playerListener)

This method removes a player listener for this player.

 

public interface PlayerListener

What is it?

This interface helps in receiving asynchronous events generated by Players. To use this interface the applications have to implement this interface. They should then register their implementations with the addPlayerListener method in Player.

 

o    Fields

·         public static final String STARTED

This field is posted when a Player is started.

·         public static final String STOPPED

This field is posted when a Player stops in response to the stop method call.

·         public static final String STOPPED_AT_TIME

This field is posted when a Player is stopped as responding to the setStopTime call using the StopTimeControl.

·         public static final String END_OF_MEDIA

This field is posted when a Player has reached the end of the media.

·         public static final String DURATION_UPDATED

This field is posted when the duration of a Player is updated.

·         public static final String DEVICE_UNAVAILABLE

This field is posted when the system or another higher priority application has temporarily taken control of an exclusive device which was previously available to the Player.

·         public static final String DEVICE_AVAILABLE

This field is posted when the system or another higher priority application has released an exclusive device which is now available to the Player.

·         public static final String VOLUME_CHANGED

This field is posted when the volume of an audio device is changed.

·         public static final String SIZE_CHANGED

This field is posted when the size of the video is changed either because the source video size or the display size has changed.

·         public static final String ERROR

This field is posted when an error occurrs.

·         public static final String CLOSED

This field is posted when a Player is closed.

·         public static final String RECORD_STARTED

This field is posted when the recording is started.

·         public static final String RECORD_STOPPED

This field is posted when the recording is stopped.

·         public static final String RECORD_ERROR

This field is posted when an error occurs during recording.

·         public static final String BUFFERING_STARTED

This field is posted when the Player enters the buffering mode.

·         public static final String BUFFERING_STARTED

This field is posted when the Player leaves the buffering mode.

 

o    Methods

·         public void playerUpdate(Player player,String event,Object eventData)   

Whenever an event occurs this method is called to deliver an event to a registered listener.  

                            

public interface TimeBase

What is it?

 

The TimeBase interface defines an interface for a constantly ticking source of time. It measures the progress of time in microseconds and provides the basic means for synchronizing media playback between different Players.

 

o    Methods

·         public long getTime()

This method returns the current TimeBase time in microseconds.

 

public final class Manager

What is it?

The Manager class is the access point for obtaining system dependent resources such as Players for multimedia processing. Manager class provides an access to the implementation specific mechanism for constructing Players. Manager class can also help us in generating simple tones directly through its playTone method.

 

o    Fields

·         public static final String TONE_DEVICE_LOCATOR

This field stands for the locator to create a Player to play back tone sequences.

·         public static final String MIDI_DEVICE_LOCATOR

This field stands for the locator to create a MIDI Player which gives access to the MIDI device by making MIDIControl available.

 

o    Methods

·         public static String[] getSupportedContentTypes(String protocol)

This method returns the list of supported content types for the given protocol.

·         public static String[] getSupportedProtocols(String content_type)

This method returns the list of supported protocols for the given content type.

·         public static Player createPlayer(String locator)

This method returns a new Player.

·         public static Player createPlayer(DataSource source)

This method returns a new Player.

·         public static Player createPlayer(InputStream stream, String type)

This method returns a new Player.

·         public static void playTone(int note, int duration, int volume)

This method plays back a tone as specified by a note, its duration and volume.

·         public static TimeBase getSystemTimeBase()

This method returns the system time base.

 

public class MediaException

What is it?

This exception indicates an unexpected error condition has occurred in a method. This exception is specifically related to the Mobile Media API and its contents.

 

o    Constructor

·         public MediaException()

This constructor constructs a MediaException with null as its error detail message.

·         public MediaException(String reason)

This constructor constructs a MediaException with the specified detail message.

javax.microedition.media.control

public interface FramePositioningControl

What is it?

This Control is the interface to control the precise positioning of a video frame for Players. Frame numbers for a bounded movie must be non-negative and should generally begin with 0. This interface provides us with seek and skip facililty.

 

o    Methods

·         public int seek(int frameNumber)

This method is to seek a particular frame. This method returns the actual frame that the Player has seeked to.

·         public int skip(int framesToSkip)

This method is used to skip the given number of frames. It returns the actual number of frames skipped.

·         public long mapFrameToTime(int frameNumber)

This method returns the converted media time in microseconds for the given frame. If the conversion fails -1 is returned by this method.

·         public int mapTimeToFrame(long mediaTime)

This method returns the converted frame number for the given media time. If the conversion fails -1 is returned by this method.

 

public interface GUIControl

What is it?

GUIControl extends Control interface and is defined for controls that provide GUI functionalities. Controls that support a GUI component should implement this interface. Currently only VideoControl extends this interface.

 

o    Fields

·         public static final int USE_GUI_PRIMITIVE

This field defines a mode on how the GUI is displayed.

 

o    Methods

·         public Object initDisplayMode(int mode,Object arg)

This method is used for initializing the mode for GUI display.

 

public interface MetaDataControl

What is it?

This Control is used to retrieve metadata information included within the media streams. An object implementing this interface recognizes and stores metadata and provides XML-like accessor methods to retrieve the metadata information.

 

o    Fields

·         public static String AUTHOR_KEY

This field stands for the Default key for AUTHOR information.

·         public static String COPYRIGHT_KEY

This field stands for the Default key for COPYRIGHT information.

·         public static String DATE_KEY

This field stands for the Default key for DATE information.

·         public static String TITLE_KEY

This field stands for the Default key for TITLE information.

 

o    Methods

·         public String[] getKeys()

This method returns the list of keys for the available metadata values.

·         public String getKeyValue(String key)

This method returns the value of the key or null if the given key is valid but the value is not yet available.

 

public interface MIDIControl

What is it?

This Control provides access to MIDI rendering and transmitting devices. Internal synthesizers or external hardware ports are some of the common devices that are controlled with MIDIControl.

 

o    Fields

·         public static final int NOTE_ON

This field stands for the Command value for Note On message.

·         public static final int CONTROL_CHANGE

This field stands for the Command value for Control Change message.

 

o    Methods

·         public boolean isBankQuerySupported()

This method returns true if this device supports querying of banks.

·         public int[] getProgram(int channel)

This method returns program assigned to channel in form of an int array.

·         public int getChannelVolume(int channel)

This method returns channel volume. The returned value ranges from 0-127. The returned value may be -1 if it is not known.

·         public void setProgram(int channel,int bank,int program)

This method sets program of a channel. This sets the current program for the channel and may be overwritten during playback by events in a MIDI sequence.

·         public void setChannelVolume(int channel,int volume)

This method sets volume for the given channel.

·         public int[] getBankList(boolean custom)

This method returns an array of all installed bank numbers. Each bank number is in the range of 0 to 16383.

·         public int[] getProgramList(int bank)

This method returns an array of programs defined in the given bank. Each program number is from 0 to 127.

·         public String getProgramName(int bank, int prog)throws MediaException

This method returns name of the specified program else it returns an empty string.

·         public String getKeyName(int bank, int prog, int key)

This method returns name of the specified key, empty string or null if the key is not mapped to a sound.

·         public void shortMidiEvent(int type,int data1,int data2)

This method sends a short MIDI event to the device.

·         public int longMidiEvent(byte[] data,int offset,int length)

This method returns the number of bytes actually sent to the device or -1 if an error has occurred.

 

public interface PitchControl

What is it? 

This Control increases or decreases the playback pitch of audio without changing the playback speed. This Control can be implemented in Players for both, MIDI media or sampled audio. It is not possible to set audible output to an absolute pitch value, it only raises or lowers pitch relative to the original.

 

o    Methods

·         public int setPitch(int millisemitones)

This method sets the relative pitch increase. This method returns the actual pitch increase in "milli-semitones".

·         public int getPitch()

This method returns the current playback pitch raise in "milli-semitones".

·         public int getMaxPitch()

This method returns the maximum pitch raise in "milli-semitones".

·         public int getMinPitch()

This method returns the minimum pitch raise in "milli-semitones".

 

public interface RateControl

What is it?

This Control controls the playback rate of a Player. The playback rate defines the relationship between the Player's media time and its TimeBase. The rates are in form of "milli- percentage".

 

o    Methods

·         public int setRate(int millirate)

This method returns the actual rate set in "milli-percentage".

·         public int getRate()

This method returns the current playback rate in "milli-percentage".

·         public int getMaxRate()

This method returns the maximum rate in "milli-percentage".

·         public int getMinRate()

This method returns the minimum rate in "milli-percentage".

 

public interface RecordControl

What is it?

This Control controls the recording of media from a Player. It records the contents that are currently being played by the Player.

 

o    Methods

·         public void setRecordStream(OutputStream stream)

This method sets the output stream where the data will be recorded.

·         public void setRecordLocation(String locator)

This method sets the output location where the data will be recorded. The locator has to be specified as a URL.

·         public String getContentType()

This method returns the content type of the media.

·         public void startRecord()

This method starts recording the media.

·         public void stopRecord()

This method stops recording the media. This method will not automatically stop the Player. This method only stops the recording.

·         public void commit()

This method completes the current recording.

·         public int setRecordSizeLimit(int size)

This method returns the actual size limit set.

·         public void reset()

This method erases the current recording.

 

public interface StopTimeControl

What is it?

This interface allows one to specify a preset stop time for a Player.

 

o    Fields

·         public static final long RESET

This field is returned by getStopTime if no stop-time is set.

 

o    Methods

·         public void setStopTime(long stopTime)

This method sets the media time at which you want the Player to stop.

·         public long getStopTime()

This method returns the current stop time in microseconds.

 

public interface TempoControl

What is it?

This Control controls the tempo in musical terms of a song. This interface is typically implemented in Players for MIDI media. It is a basic functionality for a MIDI playback application.

 

o    Methods

·         public int setTempo(int millitempo)

This method is used for setting the tempo. This method returns tempo that was actually set expressed in milli-beats per minute.

·         public int getTempo()

This method returns current tempo expressed in milli-beats per minute.

 

public interface ToneControl

What is it?

This interface enables the playback of a user-defined monotonic tone sequence. A tone sequence is can be defined as a list of tone-duration pairs and user-defined sequence blocks.

 

o    Fields

·         public static final byte VERSION

This field defines the VERSION attribute tag.

Value: -2

·         public static final byte TEMPO

This field defines the TEMPO event tag.

Value: -3

·         public static final byte RESOLUTION

This field defines the RESOLUTION event tag.

Value: -4

·         public static final byte BLOCK_START

This field defines a starting point for a block.

Value: -5

·         public static final byte BLOCK_END

This field defines an ending point for a block.

Value: -6

·         public static final byte PLAY_BLOCK

This field tells that a defined block should be played.

Value: -7

·         public static final byte SET_VOLUME

This field defines the SET_VOLUME event tag.

Value: -8

·         public static final byte REPEAT

This field defines the REPEAT event tag.

Value: -9

·         public static final byte C4

This field defines the Middle C.

Value: 60

·         public static final byte SILENCE

This field defines the Silence.

Value: -1

 

o    Methods

·         public void setSequence(byte[] sequence)

This method sets the user defined tone sequence.

 

public interface VideoControl

What is it?

This Control controls the display of video. This is the control which offers the most futuristic Control of all the VideoControl.

 

o    Fields

·         public static final int USE_DIRECT_VIDEO

This defines a mode on how the video is displayed. It can only be used on platforms which support LCDUI.

 

o    Methods

·         public Object initDisplayMode(int mode,Object arg)

This method is used for initializing the mode for video display.

·         public void setDisplayLocation(int x,int y)

This method sets the location of the video with respect to the canvas where the video is displayed.

·         public int getDisplayX()

This method returns the X-coordinate of the video.

·         public int getDisplayY()

This method returns the Y-coordinate of the video.

·         public void setVisible(boolean visible)

This method shows or hides the video.

·         public void setDisplaySize(int width, int height)

This method resizes the video image.

·         public void setDisplayFullScreen(boolean fullScreenMode)

This method sets the size of the render region for the video clip to be fullscreen.

·         public int getSourceWidth()

This method returns the width of the source video.

·         public int getSourceHeight()

This method returns the height of the source video

·         public int getDisplayWidth()

This method returns width of the display video.

·         public int getDisplayHeight()

This method returns height of the display video.

·         public byte[] getSnapshot(String imageType)

This method returns image in form of a byte array in required format of the displayed content.

 

public interface VolumeControl

What is it?

  This Control is an interface for manipulating the audio volume of a Player.

 

o    Methods

·         public void setMute(boolean mute)

This method mutes or unmutes the Player associated with this VolumeControl.

·         public boolean isMuted()

This method returns the mute state.

·         public int setLevel(int level)

This method is used for setting the volume level of the Player. The volume should be set to a value from 0 to 100 on a linear scale. This method returns the level that was actually set.

·         public int getLevel()

This method returns the current volume level or -1 in certain sittuations.

 

javax.microedition.media.protocol

// To rectify the diagram

public interface SourceStream

What is it?

This interface abstracts a single stream of media data. SourceStream is used in conjunction with DataSource to provide the input interface to a Player.

 

o    Fields

·         public static final int NOT_SEEKABLE

This field defines the value which is returned by getSeekType method to indicate that this SourceStream is not seekable.

·         public static final int SEEKABLE_TO_START

This field defines the value which is returned by getSeekType method to indicate that this SourceStream can be seeked only to the beginning of the media stream.

·         public static final int RANDOM_ACCESSIBLE

This field defines the value which is returned by getSeekType method to indicate that this SourceStream can be seeked anywhere within the media.

 

o    Methods

·         public ContentDescriptor getContentDescriptor()

This method returns the current ContentDescriptor for this stream.

·         public long getContentLength()

This method returns the content length in bytes. This method will return -1 if the length is not known.

·         public int read(byte[] b, int off, int len)

This method returns the total number of bytes read into the buffer. It may return -1 if the end of the stream has been reached.

·         public int getTransferSize()

This method returns the minimum size of the buffer needed to read a "logical" chunk of data from the source. This method return’s -1 if the size cannot be determined.

·         public long seek(long where)

This method return’s the new stream position.

·         public long tell()

This method returns the current position in the stream.

·         public int getSeekType()

This method returns an enumerated value to indicate the level of seekability.

 

public class ContentDescriptor

What is it?

This class identifies media data containers.

 

o    Constructor

·         public ContentDescriptor(java.lang.String contentType)

This constructor creates a content descriptor with the specified content type.

 

o    Methods

·         public String getContentType()

This method returns the content type.

 

public abstract class DataSource

What is it?

This class is an abstract class. This class is an abstraction for media protocol-handlers. This class hides the details of how the data is read from source, whether the data is coming from a file, streaming server or proprietary delivery mechanism. This class also provides the methods for a Player to access the input data.

 

o    Constructor

·         public DataSource(String locator)

This constructor constructs a DataSource from a locator.

 

o    Methods

·         public String getLocator()

This method returns the locator for this source.

·         public abstract String getContentType()

This method returns the name that describes the media content. This method returns null if the content is unknown.

·         public abstract void connect()

This method opens a connection to the source described by the locator and initiate communication.

·         public abstract void disconnect()

This method closes the connection to the source described by the locator and free resources used to maintain the connection.

·         public abstract void start()

This method initiates data transfer.

·         public abstract void stop()

This method stops the data transfer.

·         public abstract SourceStream [] getStreams()

This method returns the collection of streams for this source.