UNIT IV - Chapter 1 - Mobile Media API

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.

oMethods

·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.

oFields

·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.

oMethods

·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(TimeBasemaster)

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.

oFields

·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.

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.

oMethods

·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.

oFields

·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.

oMethods

·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.

oConstructor

·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.

oMethods

·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.

oFields

·public static final int USE_GUI_PRIMITIVE

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

oMethods

·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.

oFields

·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.

oMethods

·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.

oFields

·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.

oMethods

·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.

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

Whatis 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.

oMethods

·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".

oMethods

·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.

oMethods

·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 returnsthe 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.

oFields

·public static final long RESET

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

oMethods

·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.

oMethods

·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.

oFields

·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

oMethods

·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.

oFields

·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.

oMethods

·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.

oMethods

·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.

oFields

·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.

oMethods

·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.

oConstructor

·public ContentDescriptor(java.lang.String contentType)

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

oMethods

·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.

oConstructor

·public DataSource(String locator)

This constructor constructs
a DataSource
from a locator.

oMethods

·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.