The MediaPlayer class provides the controls for playing media.
It is used in combination with the Media and MediaView
classes to display and control media playback. MediaPlayer does
not contain any visual elements so must be used with the MediaView
class to view any video track which may be present.
MediaPlayer provides the pause(), play(),
stop() and seek() controls as
well as the rate and autoPlay
properties which apply to all types of media. It also provides the
balance, mute, and
volume properties which control audio playback
characteristics. Further control over audio quality may be attained via the
AudioEqualizer associated with the player. Frequency descriptors of
audio playback may be observed by registering an AudioSpectrumListener.
Information about playback position, rate, and buffering may be obtained from
the currentTime,
currentRate, and
bufferProgressTime
properties, respectively. Media marker notifications are received by an event
handler registered as the onMarker property.
For finite duration media, playback may be positioned at any point in time
between 0.0 and the duration of the media. MediaPlayer
refines this definition by adding the startTime and
stopTime
properties which in effect define a virtual media source with time position
constrained to [startTime,stopTime]. Media playback
commences at startTime and continues to stopTime.
The interval defined by these two endpoints is termed a cycle with
duration being the difference of the stop and start times. This cycle
may be set to repeat a specific or indefinite number of times. The total
duration of media playback is then the product of the cycle duration and the
number of times the cycle is played. If the stop time of the cycle is reached
and the cycle is to be played again, the event handler registered with the
onRepeat property is invoked. If the stop time is reached and
the cycle is not to be repeated, then the event handler registered
with the onEndOfMedia property is invoked. A zero-relative index of
which cycle is presently being played is maintained by currentCount.
The operation of a MediaPlayer is inherently asynchronous.
A player is not prepared to respond to commands quasi-immediately until
its status has transitioned to Status.READY, which in
effect generally occurs when media pre-roll completes. Some requests made of
a player prior to its status being READY will however take
effect when that status is entered. These include invoking play()
without an intervening invocation of pause() or stop()
before the READY transition, as well as setting any of the
autoPlay, balance,
mute, rate,
startTime, stopTime, and
volume properties.
The status
property may be monitored to make the application aware of player status
changes, and callback functions may be registered via properties such as
onReady if an action should be taken when a particular status is
entered. There are also error and onError properties which
respectively enable monitoring when an error occurs and taking a specified
action in response thereto.
The same MediaPlayer object may be shared among multiple
MediaViews. This will not affect the player itself. In
particular, the property settings of the view will not have any effect on
media playback.