public final class MediaPlayer extends Object
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.
| Modifier and Type | Class and Description |
|---|---|
static class |
MediaPlayer.Status
Enumeration describing the different status values of a
MediaPlayer. |
| Modifier and Type | Field and Description |
|---|---|
static int |
INDEFINITE
A value representing an effectively infinite number of playback cycles.
|
| Constructor and Description |
|---|
MediaPlayer(Media media)
Create a player for a specific media.
|
| Modifier and Type | Method and Description |
|---|---|
DoubleProperty |
audioSpectrumIntervalProperty() |
ObjectProperty<AudioSpectrumListener> |
audioSpectrumListenerProperty() |
IntegerProperty |
audioSpectrumNumBandsProperty() |
IntegerProperty |
audioSpectrumThresholdProperty() |
BooleanProperty |
autoPlayProperty() |
DoubleProperty |
balanceProperty() |
ReadOnlyObjectProperty<Duration> |
bufferProgressTimeProperty() |
ReadOnlyIntegerProperty |
currentCountProperty() |
ReadOnlyDoubleProperty |
currentRateProperty() |
ReadOnlyObjectProperty<Duration> |
currentTimeProperty() |
IntegerProperty |
cycleCountProperty() |
ReadOnlyObjectProperty<Duration> |
cycleDurationProperty() |
void |
dispose()
Free all resources associated with player.
|
ReadOnlyObjectProperty<MediaException> |
errorProperty() |
AudioEqualizer |
getAudioEqualizer()
Retrieve the
AudioEqualizer associated with this player. |
double |
getAudioSpectrumInterval()
Retrieves the value of the audio spectrum notification interval in seconds.
|
AudioSpectrumListener |
getAudioSpectrumListener()
Retrieves the listener of the audio spectrum.
|
int |
getAudioSpectrumNumBands()
Retrieves the number of bands in the audio spectrum.
|
int |
getAudioSpectrumThreshold()
Retrieves the audio spectrum threshold in decibels.
|
double |
getBalance()
Retrieves the audio balance.
|
Duration |
getBufferProgressTime()
Retrieves the
bufferProgressTime value. |
int |
getCurrentCount()
Retrieves the index of the current cycle.
|
double |
getCurrentRate()
Retrieves the current playback rate.
|
Duration |
getCurrentTime()
Retrieves the current media time.
|
int |
getCycleCount()
Retrieves the cycle count.
|
Duration |
getCycleDuration()
Retrieves the cycle duration in seconds.
|
MediaException |
getError()
Retrieve the value of the
error property or null
if there is no error. |
Media |
getMedia()
Retrieves the
Media instance being played. |
Runnable |
getOnEndOfMedia()
Retrieves the end of media event handler.
|
Runnable |
getOnError()
Retrieves the event handler for errors.
|
Runnable |
getOnHalted()
Retrieves the
MediaPlayer.Status.HALTED event handler. |
EventHandler<MediaMarkerEvent> |
getOnMarker()
Retrieves the marker event handler.
|
Runnable |
getOnPaused()
Retrieves the
MediaPlayer.Status.PAUSED event handler. |
Runnable |
getOnPlaying()
Retrieves the
MediaPlayer.Status.PLAYING event handler. |
Runnable |
getOnReady()
Retrieves the
MediaPlayer.Status.READY event handler. |
Runnable |
getOnRepeat()
Retrieves the repeat event handler.
|
Runnable |
getOnStalled()
Retrieves the
MediaPlayer.Status.STALLED event handler. |
Runnable |
getOnStopped()
Retrieves the
MediaPlayer.Status.STOPPED event handler. |
double |
getRate()
Retrieves the playback rate.
|
Duration |
getStartTime()
Retrieves the start time.
|
MediaPlayer.Status |
getStatus()
Retrieves the current player status.
|
Duration |
getStopTime()
Retrieves the stop time.
|
Duration |
getTotalDuration()
Retrieves the total playback duration including all cycles (repetitions).
|
double |
getVolume()
Retrieves the audio playback volume.
|
VideoDataBuffer |
impl_getLatestFrame()
Deprecated.
This is an internal API that is not intended for use and will be removed in the next version
|
boolean |
isAutoPlay()
Retrieves the
autoPlay property value. |
boolean |
isMute()
Retrieves the
muteProperty() value. |
BooleanProperty |
muteProperty() |
ObjectProperty<Runnable> |
onEndOfMediaProperty() |
ObjectProperty<Runnable> |
onErrorProperty() |
ObjectProperty<Runnable> |
onHaltedProperty() |
ObjectProperty<EventHandler<MediaMarkerEvent>> |
onMarkerProperty() |
ObjectProperty<Runnable> |
onPausedProperty() |
ObjectProperty<Runnable> |
onPlayingProperty() |
ObjectProperty<Runnable> |
onReadyProperty() |
ObjectProperty<Runnable> |
onRepeatProperty() |
ObjectProperty<Runnable> |
onStalledProperty() |
ObjectProperty<Runnable> |
onStoppedProperty() |
void |
pause()
Pauses the player.
|
void |
play()
Starts playing the media.
|
DoubleProperty |
rateProperty() |
void |
seek(Duration seekTime)
Seeks the player to a new playback time.
|
void |
setAudioSpectrumInterval(double value)
Sets the value of the audio spectrum notification interval in seconds.
|
void |
setAudioSpectrumListener(AudioSpectrumListener listener)
Sets the listener of the audio spectrum.
|
void |
setAudioSpectrumNumBands(int value)
Sets the number of bands in the audio spectrum.
|
void |
setAudioSpectrumThreshold(int value)
Sets the audio spectrum threshold in decibels.
|
void |
setAutoPlay(boolean value)
Sets the
autoPlay property value. |
void |
setBalance(double value)
Sets the audio balance.
|
void |
setCycleCount(int value)
Sets the cycle count.
|
void |
setMute(boolean value)
Sets the value of
muteProperty(). |
void |
setOnEndOfMedia(Runnable value)
Sets the end of media event handler.
|
void |
setOnError(Runnable value)
Sets the event handler to be called when an error occurs.
|
void |
setOnHalted(Runnable value)
Sets the
MediaPlayer.Status.HALTED event handler. |
void |
setOnMarker(EventHandler<MediaMarkerEvent> onMarker)
Sets the marker event handler.
|
void |
setOnPaused(Runnable value)
Sets the
MediaPlayer.Status.PAUSED event handler. |
void |
setOnPlaying(Runnable value)
Sets the
MediaPlayer.Status.PLAYING event handler. |
void |
setOnReady(Runnable value)
Sets the
MediaPlayer.Status.READY event handler. |
void |
setOnRepeat(Runnable value)
Sets the repeat event handler.
|
void |
setOnStalled(Runnable value)
Sets the
MediaPlayer.Status.STALLED event handler. |
void |
setOnStopped(Runnable value)
Sets the
MediaPlayer.Status.STOPPED event handler. |
void |
setRate(double value)
Sets the playback rate to the supplied value.
|
void |
setStartTime(Duration value)
Sets the start time.
|
void |
setStopTime(Duration value)
Sets the stop time.
|
void |
setVolume(double value)
Sets the audio playback volume.
|
ObjectProperty<Duration> |
startTimeProperty() |
ReadOnlyObjectProperty<MediaPlayer.Status> |
statusProperty() |
void |
stop()
Stops playing the media.
|
ObjectProperty<Duration> |
stopTimeProperty() |
ReadOnlyObjectProperty<Duration> |
totalDurationProperty() |
DoubleProperty |
volumeProperty() |
public static final int INDEFINITE
cycleCount is set to this value, the player
will replay the Media until stopped or paused.public MediaPlayer(Media media)
Media object with a MediaPlayer: once the
player is created it cannot be changed. Errors which occur synchronously
within the constructor will cause exceptions to be thrown. Errors which
occur asynchronously will cause the error property to be set and
consequently any onError callback to be invoked.
When created, the status of the player will be MediaPlayer.Status.UNKNOWN.
Once the status has transitioned to MediaPlayer.Status.READY the
player will be in a usable condition. The amount of time between player
creation and its entering READY status may vary depending,
for example, on whether the media is being read over a network connection
or from a local file system.
media - The media to play.NullPointerException - if media is null.MediaException - if any synchronous errors occur within the
constructor.public final AudioEqualizer getAudioEqualizer()
AudioEqualizer associated with this player.AudioEqualizer or null if player is disposed.public final MediaException getError()
error property or null
if there is no error.MediaException or null.public ReadOnlyObjectProperty<MediaException> errorProperty()
public final void setOnError(Runnable value)
value - the event handler or null.public final Runnable getOnError()
public ObjectProperty<Runnable> onErrorProperty()
public final Media getMedia()
Media instance being played.Media object.public final void setAutoPlay(boolean value)
autoPlay property value.value - whether to enable auto-playbackpublic final boolean isAutoPlay()
autoPlay property value.public BooleanProperty autoPlayProperty()
public void play()
startTime. When playing actually starts the
status will be set to MediaPlayer.Status.PLAYING.public void pause()
status
will be set to MediaPlayer.Status.PAUSED.public void stop()
startTime, and resets
currentCount to zero. Once the player is actually
stopped, the status will be set to MediaPlayer.Status.STOPPED. The
only transitions out of STOPPED status are to
MediaPlayer.Status.PAUSED and MediaPlayer.Status.PLAYING which occur after
invoking pause() or play(), respectively.
While stopped, the player will not respond to playback position changes
requested by seek(javafx.util.Duration).public final void setRate(double value)
[0.0, 8.0].
Invoking this method will have no effect if media duration is Duration.INDEFINITE.value - the playback ratepublic final double getRate()
public DoubleProperty rateProperty()
public final double getCurrentRate()
public ReadOnlyDoubleProperty currentRateProperty()
public final void setVolume(double value)
[0.0, 1.0].value - the volumepublic final double getVolume()
1.0.public DoubleProperty volumeProperty()
public final void setBalance(double value)
[-1.0, 1.0].value - the balancepublic final double getBalance()
public DoubleProperty balanceProperty()
public final void setStartTime(Duration value)
[Duration.ZERO, stopTime).
Invoking this method will have no effect if media duration is Duration.INDEFINITE.value - the start timepublic final Duration getStartTime()
Duration.ZERO.public ObjectProperty<Duration> startTimeProperty()
public final void setStopTime(Duration value)
(startTime, Media.duration].
Invoking this method will have no effect if media duration is Duration.INDEFINITE.value - the stop timepublic final Duration getStopTime()
getMedia().getDuration()Media.durationDuration.UNKNOWN if media initialization is not complete.public ObjectProperty<Duration> stopTimeProperty()
public final Duration getCycleDuration()
public ReadOnlyObjectProperty<Duration> cycleDurationProperty()
public final Duration getTotalDuration()
public ReadOnlyObjectProperty<Duration> totalDurationProperty()
public final Duration getCurrentTime()
public ReadOnlyObjectProperty<Duration> currentTimeProperty()
public void seek(Duration seekTime)
MediaPlayer.Status.STOPPED or media duration is Duration.INDEFINITE.
The behavior of seek() is constrained as follows where
start time and stop time indicate the effective lower and
upper bounds, respectively, of media playback:
| seekTime | seek position |
|---|---|
null | no change |
Duration.UNKNOWN | no change |
Duration.INDEFINITE | stop time |
| seekTime < start time | start time |
| seekTime > stop time | stop time |
| start time ≤ seekTime ≤ stop time | seekTime |
seekTime - the requested playback timepublic final MediaPlayer.Status getStatus()
public ReadOnlyObjectProperty<MediaPlayer.Status> statusProperty()
public final Duration getBufferProgressTime()
bufferProgressTime value.public ReadOnlyObjectProperty<Duration> bufferProgressTimeProperty()
public final void setCycleCount(int value)
[1,Integer.MAX_VALUE].
Invoking this method will have no effect if media duration is Duration.INDEFINITE.value - the cycle countpublic final int getCycleCount()
public IntegerProperty cycleCountProperty()
public final int getCurrentCount()
public ReadOnlyIntegerProperty currentCountProperty()
public final void setMute(boolean value)
muteProperty().value - the mute settingpublic final boolean isMute()
muteProperty() value.public BooleanProperty muteProperty()
public final void setOnMarker(EventHandler<MediaMarkerEvent> onMarker)
onMarker - the marker event handler.public final EventHandler<MediaMarkerEvent> getOnMarker()
public ObjectProperty<EventHandler<MediaMarkerEvent>> onMarkerProperty()
public final void setOnEndOfMedia(Runnable value)
value - the event handler or null.public final Runnable getOnEndOfMedia()
null.public ObjectProperty<Runnable> onEndOfMediaProperty()
public final void setOnReady(Runnable value)
MediaPlayer.Status.READY event handler.value - the event handler or null.public final Runnable getOnReady()
MediaPlayer.Status.READY event handler.null.public ObjectProperty<Runnable> onReadyProperty()
public final void setOnPlaying(Runnable value)
MediaPlayer.Status.PLAYING event handler.value - the event handler or null.public final Runnable getOnPlaying()
MediaPlayer.Status.PLAYING event handler.null.public ObjectProperty<Runnable> onPlayingProperty()
public final void setOnPaused(Runnable value)
MediaPlayer.Status.PAUSED event handler.value - the event handler or null.public final Runnable getOnPaused()
MediaPlayer.Status.PAUSED event handler.null.public ObjectProperty<Runnable> onPausedProperty()
public final void setOnStopped(Runnable value)
MediaPlayer.Status.STOPPED event handler.value - the event handler or null.public final Runnable getOnStopped()
MediaPlayer.Status.STOPPED event handler.null.public ObjectProperty<Runnable> onStoppedProperty()
public final void setOnHalted(Runnable value)
MediaPlayer.Status.HALTED event handler.value - the event handler or null.public final Runnable getOnHalted()
MediaPlayer.Status.HALTED event handler.null.public ObjectProperty<Runnable> onHaltedProperty()
public final void setOnRepeat(Runnable value)
value - the event handler or null.public final Runnable getOnRepeat()
null.public ObjectProperty<Runnable> onRepeatProperty()
public final void setOnStalled(Runnable value)
MediaPlayer.Status.STALLED event handler.value - the event handler or null.public final Runnable getOnStalled()
MediaPlayer.Status.STALLED event handler.null.public ObjectProperty<Runnable> onStalledProperty()
public final void setAudioSpectrumNumBands(int value)
value - the number of spectral bands; valuemust be ≥ 2public final int getAudioSpectrumNumBands()
public IntegerProperty audioSpectrumNumBandsProperty()
public final void setAudioSpectrumInterval(double value)
value - a positive value specifying the spectral update intervalpublic final double getAudioSpectrumInterval()
public DoubleProperty audioSpectrumIntervalProperty()
public final void setAudioSpectrumThreshold(int value)
value - the spectral threshold in dB; must be ≤ 0.public final int getAudioSpectrumThreshold()
public IntegerProperty audioSpectrumThresholdProperty()
public final void setAudioSpectrumListener(AudioSpectrumListener listener)
listener - the spectral listener or null.public final AudioSpectrumListener getAudioSpectrumListener()
nullpublic ObjectProperty<AudioSpectrumListener> audioSpectrumListenerProperty()
public void dispose()
MediaPlayer.Status.DISPOSED after this method is done. This method can be
called anytime regardless of current player status.@Deprecated public VideoDataBuffer impl_getLatestFrame()
Copyright © 2025. All rights reserved.