MMAPI JSR 135
Manager Manager is the access point for obtaining system dependent resources such as Players for multimedia processing.
TimeBase A TimeBase is a constantly ticking source of time.
PlayerListener PlayerListener is the interface for receiving asynchronous events generated by Players.
Player Player controls the rendering of time based media data.
Controllable Controllable provides an interface for obtaining the Controls from an object like a Player.
Control A Control object is used to control some media processing functions.
This package defines the specific Control types that can be used with a Player.
FramePositioningControl The FramePositioningControl is the interface to control precise positioning to a video frame for Players.
GUIControl GUIControl extends Control and is defined for controls that provide GUI functionalities.
MetaDataControl MetaDataControl is used to retrieve metadata information included within the media streams.
MIDIControl MIDIControl provides access to MIDI rendering and transmitting devices.
PitchControl PitchControl raises or lowers the playback pitch of audio without changing the playback speed.
RateControl RateControl controls the playback rate of a Player.
RecordControl RecordControl controls the recording of media from a Player.
StopTimeControl StopTimeControl allows one to specify a preset stop time for a Player.
TempoControl TempoControl controls the tempo, in musical terms, of a song.
ToneControl ToneControl is the interface to enable playback of a user-defined monotonic tone sequence.
VideoControl VideoControl controls the display of video.
VolumeControl VolumeControl is an interface for manipulating the audio volume of a Player.
SourceStream Abstracts a single stream of media data.
ContentDescriptor : A ContentDescriptor identifies media data containers.
DataSource A DataSource is an abstraction for media protocol-handlers.
DataSource for protocol handling
Player for content handling
A DataSource encapsulates protocol handling. It hides the details of how the data is read from its source, whether the data is coming from a file, streaming server, or proprietary delivery mechanism. DataSource provides a set of methods to allow a Player to read data from it for processing.
A Player reads from the DataSource, processes the data, and renders the media to the output device. It provides a set of methods to control media playback and basic synchronization. Players also provide some type-specific controls to access features for specific media types.
A factory mechanism, the Manager, creates Players from DataSources. For convenience, Manager also provides methods to create Players from locators and InputStreams.
The createPlayer method is the top-level entry point to the API:
Player Manager.createPlayer(String urlString)
The urlString fully specifies the protocol and the content of the data:
The Manager parses the URL and creates a DataSource to handle the specified data delivery protocol. The DataSource derives the content type from the data. The Manager then takes this content type and creates a Player to handle the presentation of the data. The resulting Player is returned for use by the application.
The Player provides general methods to control data flow and presentation, for example:
Fine-grained control is an important feature of the API. Therefore, each Player also provides type-specific controls with the getControls and getControl methods:
Control Player.getControl(String controlType)
Since each type of media will yield different types of controls from its corresponding Player, the getControls and getControl methods expose features that are unique to a particular media type. For example, for the MIDI type, you can receive a MIDIControl from the Player's getControl method.
MMAPI has some properties that can be queried by System.getProperty(String key). Currently, the following keys are defined:
supports.mixing Query for whether audio mixing is supported. The string returned is either "true" or "false". If mixing is supported, the following conditions are true:
At least two tones can be played with Manager.playTone simultaneously.
Manager.playTone can be used at the same time when at least one Player is playing back audio.
At least two Player's can be used to play back audio simultaneously.
supports.audio.capture Query for whether audio capture is supported. The string returned is either true or false.
supports.video.capture Query for whether video capture is supported. The string returned is either true or false.
supports.recording Query for whether recording is supported. The string returned is either true or false.
audio.encodings The string returned specifies the supported capture audio formats. Each format is specified in a special syntax. The formats are delimited by at least one space.
video.encodings The string returned specifies the supported capture video formats. Each format is specified in a special syntax. The formats are delimited by at least one space.
video.snapshot.encodings Supported video snapshot formats for the getSnapshot method in VideoControl. The string returned specifies the supported capture image formats. Each format is specified in a special syntax. The formats are delimited by at least one space.
Manager is a class with only static methods; applications cannot create an instance of it. Manager provides static methods for creating players and querying supported protocols and content types. It also provides a convenient method, playTone, for playing a single tone.
Manager's createPlayer methods create a Player with an associated DataSource to supply it with data. This DataSource can be built from an InputStream or from a URI-style locator. The DataSource instance is not visible to the application programmer. Nokia's MMAPI implementation supports, for example, the following locator forms:
capture://video (displays video from the device's built-in camera)
This document will discuss more about locators in the forthcoming chapters. Audio and video recording is discussed in section Recording Sound and Video. In addition, the technical note MIDP: Mobile Media API Support In Nokia Devices contains more information about locator support on device level.
Manager creates the correct kind of Player implementation class by checking the DataSource's content type (for example, from an HTTP response's Content-Type header) or file extension. If it cannot determine the DataSource's content type, it will throw a MediaException
Once the player has been created, you can ask it for various kinds of Control, for instance:
VolumeControl - to control a player's audio volume
StopTimeControl - to make a player stop after playing for a given length of time
VideoControl - to control how a video player's image is shown
There are many other types of Control, but not all will be supported by a given device's Mobile Media API implementation, or for a given content type. You can find out what controls are supported in a device by checking the system properties (for example, System.getProperty("supports.video.capture")). A full list of these properties is provided in the Mobile Media API specification.
Players are created in the UNREALIZED state, and are typically realized, then prefetched, and then started. When they reach the end of their media file, or stop() is called, they return to the PREFETCHED state.
You can check a player's state by calling its getState method. But be aware that players can change state dynamically or other threads can change their state, so that by the time the getState method returns, its result may no longer reflect the current state of the player.
Similarly, you can get notifications of a player's state changes by registering a PlayerListener with it and by using the listener's playerUpdate method. But note that the Mobile Media API specification gives no guarantees about how promptly the state change events will be delivered, so when you receive the "started" event, the media may already have ended (and there may be an "end of media" event already next in the queue for delivery to you).