Unit 5 : Miscellaneous

Mobile Media API

The Mobile Media API(MMAPI) is an
API specification for the java ME
platform CDC and CLDC devices such as
mobile phones.
This API allows applications to play and
record sounds and video, and to capture
images.
MMAPI was developed under the java
community process as JSR 135.
Small computing devices has many
limitations.
They also don’t have much hardware
support. Then thinking of multimedia
functionality on such devices will not be
acceptable.
One will never think of playing sounds,
watching videos or capturing an image
and then modifying the captured image.
But if you have knowledge of today’s
mobile and applications of mobile then
you will be already aware that these
features are already available on today’s
cell phones.
The MMAPI extends the functionality of the
J2ME platform by providing audio, video and
other time-based multimedia support to the small
devices.
MIDP 2.0 along with the optional Mobile Media
API 1.1 offers a range of multimedia capabilities
for mobile devices, including playback and
recording of audio and video data from a variety
of sources.
MIDP 2.0 comes with a subset of the MMAPI
which ensures that if a device does not support
MMAPI, you can still use a scaled down version.
This scaled down version only supports audio and
excludes anything to do with video or images.
The subset of MMAPI is Audio Building
Blocks(ABB).
Itincludes the capability to play simple
tones and sampled audios.
The ABB is implemented in the
javax.microedition.media and
javax.microedition.media.control
packages.
The MMAPI is a java technology and as
we know, each java technology has an
API specification, a reference
implementation (RI) and a technology
compatibility kit (TCK).
Classes and Interfaces
 Classes
◦ Manager
 Manager is the access point for obtaining system dependent resources
such as Players for multimedia processing.
 Interfaces
◦ Control
◦ Controllable
◦ Player
◦ PlayerListener
 Exception
◦ MediaException
 The proposed audio building block system constists of three main
parts.
◦ Manager
◦ Player
◦ Control
 The Manager is the top level controller of audio resources.
 Applications use Manager to request Players and to query
properties, supported content types and supported protocols.
 The manager also includes a method to play simple tones. The
Player plays the multimedia content. The application obtains a
Player by giving the locator string to Manager.
 A Control is an interface that is used to implement all different
controls a Player might have. An application can query a Player of
controls it supports and then ask for a specific Control e.g.
VolumeControl to control volume.
Manager
Manager is the access point for obtaining
system dependent resources such as
Players for multimedia processing.
Creating Players

Manager provides two methods to create

a Player for playing back media:
◦ Create from a media locator.
◦ Create from an InputStream.
The Player returned can be used to
control the presentation of the media.
Content Types
 Content types identify the type of media data.
 They are defined to be the registered MIME types (
http://www.iana.org/assignments/media-types/); plus
some user-defined types that generally follow the MIME
syntax (RFC 2045, RFC 2046).
 For example, here are a few common content types:

◦ Wave audio files: audio/x-wav

◦ AU audio files: audio/basic
◦ MP3 audio files: audio/mpeg
◦ MIDI files: audio/midi
◦ Tone sequences: audio/x-tone-seq
Media Locator

Media locators are specified in

URI syntax which is defined in the form:
    
◦ <scheme>:<scheme-specific-part>
The "scheme" part of the locator string
identifies the name of the protocol being
used to deliver the data.
Field Summary
TONE_DEVICE_LOCATOR
◦ public static final String
TONE_DEVICE_LOCATOR
Player
p=
Manager.createPlayer(Manager.TONE_D
EVICE_LOCATOR);
Method Detail
 createPlayer
public static Player createPlayer(
InputStream stream, String type) throws
IOException, MediaException
Create a Player to play back media from an
InputStream.
Parameters:
◦ stream - The InputStream that delivers the input
media.
◦ type - The ContentType of the media.
Returns:A new Player.
createPlayer

public static Player createPlayer(String

 locator) throws IOException,
MediaException
Create a Player from an input locator.
Parameters:
◦ locator - A locator string in URI syntax that
describes the media content.
Returns:A new Player.
getSupportedContentTypes
public static String[]
getSupportedContentTypes(String
 protocol)
Return the list of supported content types
for the given protocol.
Parameters:
◦ protocol - The input protocol for the supported
content types.
Returns:The list of supported content
types for the given protocol.
getSupportedProtocols
public static String[] getSupportedProtocols(
String content_type)
Return the list of supported protocols given the
content type.
The protocols are returned as strings which
identify what locators can be used for creating
Player's.
Parameters:content_type - The content type for
the supported protocols.
Returns:The list of supported protocols for the
given content type.
playTone
public static void playTone(int note, int duration,
int volume) throws MediaException
Play back a tone as specified by a note and its
duration.
 A note is given in the range of 0 to 127 inclusive.
The frequency of the note can be calculated from
the following formula: SEMITONE_CONST =
17.31234049066755 = 1/(ln(2^(1/12))) note =
ln(freq/8.176)*SEMITONE_CONST The musical
note A = MIDI note 69 (0x45) = 440 Hz.
Parameters:
◦ note - Defines the tone of the note as specified by
the above formula.
◦ duration - The duration of the tone in milli-
seconds. Duration must be positive.
◦ volume - Audio volume range from 0 to 100. 100
represents the maximum volume at the current
hardware level. Setting the volume to a value less
than 0 will set the volume to 0. Setting the
volume to greater than 100 will set the volume to
100.
Interfaces
Player
Player controls the rendering of time
based media data. It provides the methods
to manage the Player's life cycle, controls
the playback progress and obtains the
presentation components.
Simple Playback

A Player can be created from one of the

Manager's createPlayer methods. After the
Player is created, calling start will start the
playback as soon as possible. The method
will return when the playback is started.
The playback will continue in the
background and will stop automatically
when the end of media is reached.
try
{
Player p =
Manager.createPlayer("http://abc.wav");
p.start();
} catch (MediaException pe) { }
catch (IOException ioe) { }
Player Life Cycle

A Player has five states:

◦ UNREALIZED,
◦ REALIZED,
◦ PREFETCHED,
◦ STARTED,
◦ CLOSED.
 The purpose of these life-cycle states is to provide programmatic
control over potentially time-consuming operations. For example,
when a Player is first constructed, it's in the UNREALIZED state.
Transitioned from UNREALIZED to REALIZED, the Player performs
the communication necessary to locate all of the resources it needs to
function (such as communicating with a server or a file system). The
realize method allows an application to initiate this potentially time-
consuming process at an appropriate time.
 Typically, a Player moves from the UNREALIZED state to the
REALIZED state, then to the PREFETCHED state, and finally on to the
STARTED state.
 A Player stops when it reaches the end of media; or when the stop
method is invoked. When that happens, the Player moves from the
STARTED state back to the PREFETCHED state. It is then ready to
repeat the cycle.
 To use a Player, you must set up parameters to manage its movement
through these life-cycle states and then move it through the states using
the Player's state transition methods.
Player States : UNREALIZED
State
A Player starts in the UNREALIZED state. An unrealized
Player does not have enough information to acquire all
the resources it needs to function. The following methods
must not be used when the Player is in the UNREALIZED
state.
 getContentType
 setMediaTime
 getControls
 getControl
 An IllegalStateException will be thrown. The realize
method transitions the Player from the UNREALIZED
state to the REALIZED state.
 REALIZED State
 A Player is in the REALIZED state when it has obtained the
information required to acquire the media resources. Realizing a
Player can be a resource and time consuming process. The Player may
have to communicate with a server, read a file, or interact with a set of
objects. Although a realized Player does not have to acquire any
resources, it is likely to have acquired all of the resources it needs
except those that imply exclusive use of a scarce system resource,
such as an audio device.
 Normally, a Player moves from the UNREALIZED state to the
REALIZED state. After realize has been invoked on a Player, the only
way it can return to the UNREALIZED state is if deallocate is invoked
before realize is completed. Once a Player reaches the REALIZED
state, it never returns to the UNREALIZED state. It remains in one of
four states: REALIZED, PREFETCHED, STARTED or CLOSED.
PREFETCHED State
 Once realized, a Player may still need to perform a
number of time-consuming tasks before it is ready to be
started. For example, it may need to acquire scarce or
exclusive resources, fill buffers with media data, or
perform other start-up processing. Calling prefetch on
the Player carries out these tasks. Once a Player is in the
PREFETCHED state, it may be started. Prefetching
reduces the startup latency of a Player to the minimum
possible value.
 When a started Player stops, it returns to the
PREFETCHED state.
STARTED State
 Once prefetched, a Player can enter the STARTED state by calling
the start method. A STARTED Player  means the Player is running
and processing data. A Player returns to the PREFETCHED state
when it stops, because the stop method was invoked, or it has
reached the end of the media. When the Player moves from the
PREFETCHED to the STARTED state, it posts a STARTED event.
When it moves from the STARTED state to the PREFETCHED
state, it posts a STOPPED, END_OF_MEDIA event depending on
the reason it stopped.
 The following method must not be used when the Player is in the
STARTED state:
◦ setLoopCount
◦ An IllegalStateException will be thrown.
CLOSED state

Calling close on the Player puts it in the

CLOSED state. In the CLOSED state, the
Player has released most of its resources
and must not be used again.
Field Summary
CLOSED
          The state of the Player indicating that the
Player is closed.
PREFETCHED
          The state of the Player indicating that it
has acquired all the resources to begin playing.
REALIZED
          The state of the Player indicating that it
has acquired the required information but not
the resources to function.
STARTED
          The state of the Player indicating that
the Player has already started.
TIME_UNKNOWN
          The returned value indicating that the
requested time is unknown.
UNREALIZED
          The state of the Player indicating that it
has not acquired the required information and
resources to function.
Methods
close()
public void close()
          Close the Player and release its
resources.
deallocate

public void deallocate()

Release the scarce or exclusive resources
like the audio device acquired by the
Player. When deallocate returns, the
Player is in the UNREALIZED or
REALIZED state
getContentType

public String getContentType()

◦ Get the content type of the media that's being
played back by this Player.
getDuration

public long getDuration()

◦ Get the duration of the media. The value
returned is the media's duration when played
at the default rate.
If the duration cannot be determined (for
example, the Player is presenting live media)
getDuration returns TIME_UNKNOWN.
Returns:The
duration in microseconds or
TIME_UNKNOWN.
getMediaTime

public long getMediaTime() Gets this

Player's current media time. If the media
time cannot be determined, getMediaTime
returns TIME_UNKNOWN.
Returns:The current media time in
microseconds or TIME_UNKNOWN.
Throws: IllegalStateException - Thrown
if the Player is in the CLOSED state.
getState
public int getState()
Gets the current state of this Player. The
possible states are: UNREALIZED,
REALIZED, PREFETCHED, STARTED,
CLOSED.
Returns:The Player's current state.
start

public void start() throws

MediaException
Starts the Player as soon as possible. If
the Player was previously stopped by
calling stop, it will resume playback from
where it was previously stopped. If the
Player has reached the end of media,
calling start will automatically start the
playback from the start of the media.
stop

public void stop() throws

MediaException Stops the Player. It will
pause the playback at the current media
time. When stop returns, the Player is in
the PREFETCHED state. A STOPPED
event will be delivered to the registered
PlayerListeners.
If stop is called on a stopped Player, the
request is ignored.
setMediaTime

public long setMediaTime(long now)

throws MediaException
Sets the Player's media time.
getMediaTime

public long getMediaTime()

Gets this Player's current media time. If
the media time cannot be determined,
getMediaTime returns
TIME_UNKNOWN.
Returns:The current media time in
microseconds or TIME_UNKNOWN.
setLoopCount

public void setLoopCount(int count)

Set the number of times the Player will
loop and play the content.
realize

public void realize() throws MediaException

Constructs portions of the Player without
acquiring the scarce and exclusive resources.
This may include examining media data and
may take some time to complete. When realize
completes successfully, the Player is in the
REALIZED state.
If realize is called when the Player is in the
REALIZED, PREFETCHTED or STARTED
state, the request will be ignored.
addPlayerListener

public void
addPlayerListener(PlayerListener player
Listener) Add a player listener for this
player.
Parameters:playerListener - the listener
to add. If null is used, the request will be
ignored.
removePlayerListener

public void
removePlayerListener(PlayerListener pl
ayerListener) Remove a player listener for
this player.
Parameters:
◦ playerListener - the listener to remove. If null
is used or the given playerListener is not a
listener for this Player, the request will be
ignored.
PlayerInterface
The player includes methods for adding
and removing listeners that will be
notified about events in the players life.
Public void
addPlayerListener(PlayerListener pl)
Public void
addPlayerListener(PlayerListener pl)
We can listen for the player’s events by
registering playerlistener objects to a player
instance.
It has one method playerUpdate(), which is
invoked every time the registered player
receives an event.
PlayerListener is the interface for receiving
asynchronous events generated by Players.
Applications may implement this interface and
register their implementations with the
addPlayerListener method in Player.
playerUpdate

public void playerUpdate(Player player,

String event, Object eventData) This
method is called to deliver an event to a
registered listener when a Player event is
observed.
Parameters:
◦ player - The player which generated the event.
◦ event - The event generated as defined by the
enumerated types.event
◦ Data - The associated event data.
Code fragment for catching standard events
in playerUpdate()
if (eventType == PlayerListener.STARTED)
{...}

Code fragment for catching proprietary

events in playerUpdate()
if (eventType.equals("com.company.myEvent"))
{...}

PlayerListenerInterface Fields
Video Control Interface
This interface is available in the
javax.microedition.media.control package.
The purpose of the video control is to control
the video display.
This interface can be used to capture an image
as well as to play a video.
For this we need to create a player, realize it
then call start() on it to play the video.
For video only we need to change the content
type and the file extension.
For eg.. :
InputStream
is=getClass.getResource(“play1.mpg”);
Player p=Manager.createPlayer(is,”video/mpeg”);
Unlike audio that is played on speakers, video will
take up some space on the user interface.
Methods
MMAPI gives us two choices for this :
◦ Display video on custom canvas
◦ Display video on an item within a form
Display video on the canvas
 Ifwe want to display the video on a custom canvas, we need to
derive a class from canvas.
 The following code snippet can be used to position and display
the video.
Public MyVideo(VideoControl vc)
{
vc.initDisplayMode(VideoControl.USE_DIRECT_VIDEO,this);
vc.setDisplayLocation(5,5);
vc.setDisplaySize(getWidth()-50,getHeight()-50);
Vc.setVisible(true);
}
Displaying video on an item within
a form
Using an item to display the video allows
us to mix the with other items.
Eg:
(Item)mv=(Item)vc.initDisplayMode(Video
Control.USE_GUI_PRIMITIVE,null)
Form.append(mv);
Image
Once a camera video is shown on the device,
capturing an image is easy. All we need to do is
call VideoControl’s getSnapshot() method.
We need to pass an image type, or null for the
default type, PNG.
getSnapShot() returns an array of bytes, which
is the image data in the format we requested.
Byte[] raw=vc.getSnapshot(null)
Image
image=Image.captureImage(raw,0,raw.length);
Examples
ImageCaptureMidlet.java
Bluetooth/OBEX API
JSR 82
WMA API
The Wma is the Wireless Messaging API.
Nowadays we can use the internet on our mobile,
using which can transmit the text type of data.
But using internet will be quite costly in such
situation.
Another option is available which is low cost and
has become popular rapidly.
This low cost technique is SMS, which is one
type of messaging service usually for mobile
phones.
Cellular companies offer 3 types of
textual message :
◦ SMS
◦ CBS (cell broadcast services)
◦ USSD
 The Wma is the Wireless Messaging API is an optional
api that enables midp applications to send and receive
SMS.
 It can also be used to send CBS and MMS messages.
 Unlike the cell phone call, a message is not lost if the
receiving phone is not available.
 The SMS makes use of store and forward technique in
which the messages are queued until the receiving
device is available.
 The WMA makes SMS available to MIDP developers.
Javax.microedition.messaging
package
It is based on the Generic Connection
Framework (GCF) and targets the CLDC.
It is possible to take advantage of WMA,
once JSR 197 is complete.
Components of WMA
Message Connection Message

MessageListener

TextMessage BinaryMessage
The above fig shows the interface of the
WMA v1.0 which are included in the
javax.wireless.messaging package. This
can be summarized as follows :
◦ Message
◦ TextMessage
BinaryMessage
◦ MessageConnection
◦ MessageListener