Module javafx.media

Class MediaPlayer

java.lang.Object
javafx.scene.media.MediaPlayer

public final class MediaPlayer
extends Object
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 MediaPlayer.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.

Since:
JavaFX 2.0
See Also:
Media, MediaView