JavaFX 24 · javafx.scene.media.MediaPlayer · APIdia, the JavaDoc alternative

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, then the event handler registered with the onEndOfMedia property is invoked regardless of whether the cycle is to be repeated or not. 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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private class	MediaPlayer._BufferListener
private class	MediaPlayer._MarkerListener Listener of marker events emitted by the implementation layer.
private class	MediaPlayer._MediaErrorListener
private class	MediaPlayer._PlayerStateListener
private class	MediaPlayer._PlayerTimeListener
private class	MediaPlayer._SpectrumListener
private class	MediaPlayer._VideoTrackSizeListener
private class	MediaPlayer.InitMediaPlayer
private class	MediaPlayer.MarkerMapChangeListener
private class	MediaPlayer.RendererListener
public static enum	MediaPlayer.Status Enumeration describing the different status values of a `MediaPlayer`.

Field Summary

Modifier and Type	Field and Description
private AudioEqualizer	audioEqualizer The read-only `AudioEqualizer` associated with this player.
private static final double	AUDIOSPECTRUM_INTERVAL_MIN
private static final int	AUDIOSPECTRUM_NUMBANDS_MIN
private static final int	AUDIOSPECTRUM_THRESHOLD_MAX
private boolean	audioSpectrumEnabledChangeRequested
private DoubleProperty	audioSpectrumInterval The interval between spectrum updates in seconds.
private boolean	audioSpectrumIntervalChangeRequested
private ObjectProperty<AudioSpectrumListener>	audioSpectrumListener A listener for audio spectrum updates.
private IntegerProperty	audioSpectrumNumBands The number of bands in the audio spectrum.
private boolean	audioSpectrumNumBandsChangeRequested
private IntegerProperty	audioSpectrumThreshold The sensitivity threshold in decibels; must be non-positive.
private boolean	audioSpectrumThresholdChangeRequested
private BooleanProperty	autoPlay Whether playing should start as soon as possible.
private DoubleProperty	balance The balance, or left-right setting, of the audio output.
private boolean	balanceChangeRequested
private BufferListener	bufferListener
private ReadOnlyObjectWrapper<Duration>	bufferProgressTime The current buffer position indicating how much media can be played without stalling the `MediaPlayer`.
private ReadOnlyIntegerWrapper	currentCount The number of completed playback cycles.
private ReadOnlyDoubleWrapper	currentRate The current rate of playback regardless of settings.
private VideoDataBuffer	currentRenderFrame
private ReadOnlyObjectWrapper<Duration>	currentTime The current media playback time.
private IntegerProperty	cycleCount The number of times the media will be played.
private ReadOnlyObjectWrapper<Duration>	cycleDuration The amount of time between the `startTime` and `stopTime` of this player.
private static final int	DEFAULT_SPECTRUM_BAND_COUNT
private static final double	DEFAULT_SPECTRUM_INTERVAL
private static final int	DEFAULT_SPECTRUM_THRESHOLD
private final Object	disposeLock
private ReadOnlyObjectWrapper<MediaException>	error Observable property set to a `MediaException` if an error occurs.
private MediaErrorListener	errorListener
public static final int	INDEFINITE A value representing an effectively infinite number of playback cycles.
private boolean	isEOS
private boolean	isUpdateTimeEnabled
private MediaPlayer	jfxPlayer
private BufferProgressEvent	lastBufferEvent
private MarkerListener	markerEventListener
private MapChangeListener<String, Duration>	markerMapListener
private Media	media The parent `Media` object; read-only.
private MediaTimerTask	mediaTimerTask
private BooleanProperty	mute Whether the player audio is muted.
private boolean	muteChangeRequested
private VideoDataBuffer	nextRenderFrame
private ObjectProperty<Runnable>	onEndOfMedia Event handler invoked when the player `currentTime` reaches `stopTime`.
private ObjectProperty<Runnable>	onError Event handler invoked when an error occurs.
private ObjectProperty<Runnable>	onHalted Event handler invoked when the status changes to `HALTED`.
private ObjectProperty<EventHandler<MediaMarkerEvent>>	onMarker Event handler invoked when the player `currentTime` reaches a media marker.
private ObjectProperty<Runnable>	onPaused Event handler invoked when the status changes to `PAUSED`.
private ObjectProperty<Runnable>	onPlaying Event handler invoked when the status changes to `PLAYING`.
private ObjectProperty<Runnable>	onReady Event handler invoked when the status changes to `READY`.
private ObjectProperty<Runnable>	onRepeat Event handler invoked when the player `currentTime` reaches `stopTime` and will be repeating.
private ObjectProperty<Runnable>	onStalled Event handler invoked when the status changes to `STALLED`.
private ObjectProperty<Runnable>	onStopped Event handler invoked when the status changes to `STOPPED`.
private boolean	playerReady
private boolean	playRequested
private double	prevTimeMs
private DoubleProperty	rate The rate at which the media should be played.
private static final double	RATE_MAX
private static final double	RATE_MIN
private boolean	rateChangeRequested
private MediaPlayer.RendererListener	rendererListener
private final Object	renderLock
private VideoTrackSizeListener	sizeListener
private AudioSpectrumListener	spectrumListener
private ObjectProperty<Duration>	startTime The time offset where media should start playing, or restart from when repeating.
private Duration	startTimeAtStop
private boolean	startTimeChangeRequested
private PlayerStateListener	stateListener
private ReadOnlyObjectWrapper<MediaPlayer.Status>	status The current state of the MediaPlayer.
private ObjectProperty<Duration>	stopTime The time offset where media should stop playing or restart when repeating.
private boolean	stopTimeChangeRequested
private PlayerTimeListener	timeListener
private ReadOnlyObjectWrapper<Duration>	totalDuration The total amount of play time if allowed to play until finished.
private final Set<WeakReference<MediaView>>	viewRefs
private DoubleProperty	volume The volume at which the media should be played.
private boolean	volumeChangeRequested

Constructor Summary

Access	Constructor and Description
public	MediaPlayer(Media The media to play. media) Create a player for a specific media.

Method Summary

Modifier and Type	Method and Description
pack-priv void	addView(MediaView view)
public DoubleProperty	audioSpectrumIntervalProperty()
public ObjectProperty<AudioSpectrumListener>	audioSpectrumListenerProperty()
public IntegerProperty	audioSpectrumNumBandsProperty()
public IntegerProperty	audioSpectrumThresholdProperty()
public BooleanProperty	autoPlayProperty()
public DoubleProperty	balanceProperty()
public ReadOnlyObjectProperty<Duration>	bufferProgressTimeProperty()
private ReadOnlyObjectWrapper<Duration>	bufferProgressTimePropertyImpl()
private void	calculateCycleDuration()
private double[]	Returns: the clamped times in seconds as `{actualStart, actualStop}`. calculateStartStopTimes(Duration the new start time. startValue, Duration the new stop time. stopValue) Behaviorally clamp the start and stop times.
private void	calculateTotalDuration()
private static double	clamp(double dvalue, double dmin, double dmax)
private static int	clamp(int ivalue, int imin, int imax)
pack-priv void	createMediaTimer()
public ReadOnlyIntegerProperty	currentCountProperty()
private ReadOnlyIntegerWrapper	currentCountPropertyImpl()
public ReadOnlyDoubleProperty	currentRateProperty()
private ReadOnlyDoubleWrapper	currentRatePropertyImpl()
public ReadOnlyObjectProperty<Duration>	currentTimeProperty()
private ReadOnlyObjectWrapper<Duration>	currentTimePropertyImpl()
public IntegerProperty	cycleCountProperty()
public ReadOnlyObjectProperty<Duration>	cycleDurationProperty()
private ReadOnlyObjectWrapper<Duration>	cycleDurationPropertyImpl()
pack-priv void	destroyMediaTimer()
public synchronized void	dispose() Free all resources associated with player.
public ReadOnlyObjectProperty<MediaException>	errorProperty()
private ReadOnlyObjectWrapper<MediaException>	errorPropertyImpl()
public final AudioEqualizer	Returns: the `AudioEqualizer` or `null` if player is disposed. getAudioEqualizer() Retrieve the `AudioEqualizer` associated with this player.
public final double	Returns: the spectral update interval getAudioSpectrumInterval() Retrieves the value of the audio spectrum notification interval in seconds.
public final AudioSpectrumListener	Returns: the spectral listener or `null` getAudioSpectrumListener() Retrieves the listener of the audio spectrum.
public final int	Returns: the number of spectral bands. getAudioSpectrumNumBands() Retrieves the number of bands in the audio spectrum.
public final int	Returns: the spectral threshold in dB getAudioSpectrumThreshold() Retrieves the audio spectrum threshold in decibels.
public final double	Returns: the audio balance getBalance() Retrieves the audio balance.
public final Duration	Returns: the buffer progress time getBufferProgressTime() Retrieves the `bufferProgressTime` value.
public final int	Returns: the current cycle index getCurrentCount() Retrieves the index of the current cycle.
public final double	Returns: the current rate getCurrentRate() Retrieves the current playback rate.
public final Duration	Returns: the current media time getCurrentTime() Retrieves the current media time.
public final int	Returns: the cycle count. getCycleCount() Retrieves the cycle count.
public final Duration	Returns: the cycle duration getCycleDuration() Retrieves the cycle duration in seconds.
public final MediaException	Returns: a `MediaException` or `null`. getError() Retrieve the value of the `error` property or `null` if there is no error.
pack-priv VideoDataBuffer	Returns: the current frame to be used for rendering, or null if not in a render cycle getLatestFrame() Warning You must call releaseFrame() on the returned frame when you are finished with it or a massive memory leak will occur.
public final Media	Returns: the `Media` object. getMedia() Retrieves the `Media` instance being played.
public final Runnable	Returns: the event handler or `null`. getOnEndOfMedia() Retrieves the end of media event handler.
public final Runnable	Returns: the event handler. getOnError() Retrieves the event handler for errors.
public final Runnable	Returns: the event handler or `null`. getOnHalted() Retrieves the `Status#HALTED` event handler.
public final EventHandler<MediaMarkerEvent>	Returns: the marker event handler. getOnMarker() Retrieves the marker event handler.
public final Runnable	Returns: the event handler or `null`. getOnPaused() Retrieves the `Status#PAUSED` event handler.
public final Runnable	Returns: the event handler or `null`. getOnPlaying() Retrieves the `Status#PLAYING` event handler.
public final Runnable	Returns: the event handler or `null`. getOnReady() Retrieves the `Status#READY` event handler.
public final Runnable	Returns: the event handler or `null`. getOnRepeat() Retrieves the repeat event handler.
public final Runnable	Returns: the event handler or `null`. getOnStalled() Retrieves the `Status#STALLED` event handler.
public final Runnable	Returns: the event handler or `null`. getOnStopped() Retrieves the `Status#STOPPED` event handler.
public final double	Returns: the playback rate getRate() Retrieves the playback rate.
public final Duration	Returns: the start time getStartTime() Retrieves the start time.
public final MediaPlayer.Status	Returns: the playback status getStatus() Retrieves the current player status.
public final Duration	Returns: the stop time getStopTime() Retrieves the stop time.
public final Duration	Returns: the total playback duration getTotalDuration() Retrieves the total playback duration including all cycles (repetitions).
public final double	Returns: the audio volume getVolume() Retrieves the audio playback volume.
pack-priv void	handleError(final MediaException error)
pack-priv void	handleRequestedChanges()
private void	init()
public final boolean	Returns: the value. isAutoPlay() Retrieves the `autoPlay` property value.
public final boolean	Returns: the mute setting isMute() Retrieves the `muteProperty` value.
pack-priv void	loopPlayback()
public BooleanProperty	muteProperty()
public ObjectProperty<Runnable>	onEndOfMediaProperty()
public ObjectProperty<Runnable>	onErrorProperty()
public ObjectProperty<Runnable>	onHaltedProperty()
public ObjectProperty<EventHandler<MediaMarkerEvent>>	onMarkerProperty()
public ObjectProperty<Runnable>	onPausedProperty()
public ObjectProperty<Runnable>	onPlayingProperty()
public ObjectProperty<Runnable>	onReadyProperty()
public ObjectProperty<Runnable>	onRepeatProperty()
public ObjectProperty<Runnable>	onStalledProperty()
public ObjectProperty<Runnable>	onStoppedProperty()
public void	pause() Pauses the player.
public void	play() Starts playing the media.
pack-priv void	preReady()
public DoubleProperty	rateProperty()
pack-priv void	registerListeners()
pack-priv void	removeView(MediaView view)
pack-priv MediaPlayer	retrieveJfxPlayer()
public void	seek(Duration the requested playback time seekTime) Seeks the player to a new playback time.
public final void	setAudioSpectrumInterval(double a positive value specifying the spectral update interval value) Sets the value of the audio spectrum notification interval in seconds.
public final void	setAudioSpectrumListener(AudioSpectrumListener the spectral listener or `null`. listener) Sets the listener of the audio spectrum.
public final void	setAudioSpectrumNumBands(int the number of spectral bands; `value`must be ≥ 2 value) Sets the number of bands in the audio spectrum.
public final void	setAudioSpectrumThreshold(int the spectral threshold in dB; must be ≤ `0`. value) Sets the audio spectrum threshold in decibels.
public final void	setAutoPlay(boolean whether to enable auto-playback value) Sets the `autoPlay` property value.
public final void	setBalance(double the balance value) Sets the audio balance.
private void	setBufferProgressTime(Duration value)
private void	setCurrentCount(int value)
private void	setCurrentRate(double value)
private void	setCurrentTime(Duration value)
public final void	setCycleCount(int the cycle count value) Sets the cycle count.
private void	setCycleDuration(Duration value)
private void	setError(MediaException value)
public final void	setMute(boolean the `mute` setting value) Sets the value of `muteProperty`.
public final void	setOnEndOfMedia(Runnable the event handler or `null`. value) Sets the end of media event handler.
public final void	setOnError(Runnable the event handler or `null`. value) Sets the event handler to be called when an error occurs.
public final void	setOnHalted(Runnable the event handler or `null`. value) Sets the `Status#HALTED` event handler.
public final void	setOnMarker(EventHandler<MediaMarkerEvent> the marker event handler. onMarker) Sets the marker event handler.
public final void	setOnPaused(Runnable the event handler or `null`. value) Sets the `Status#PAUSED` event handler.
public final void	setOnPlaying(Runnable the event handler or `null`. value) Sets the `Status#PLAYING` event handler.
public final void	setOnReady(Runnable the event handler or `null`. value) Sets the `Status#READY` event handler.
public final void	setOnRepeat(Runnable the event handler or `null`. value) Sets the repeat event handler.
public final void	setOnStalled(Runnable the event handler or `null`. value) Sets the `Status#STALLED` event handler.
public final void	setOnStopped(Runnable the event handler or `null`. value) Sets the `Status#STOPPED` event handler.
public final void	setRate(double the playback rate value) Sets the playback rate to the supplied value.
private void	setStartStopTimes(Duration the new start time. startValue, boolean isStartValueSet, Duration the new stop time. stopValue, boolean isStopValueSet) Set the effective start and stop times on the underlying player, clamping as needed.
public final void	setStartTime(Duration the start time value) Sets the start time.
private void	setStatus(MediaPlayer.Status value)
public final void	setStopTime(Duration the stop time value) Sets the stop time.
private void	setTotalDuration(Duration value)
public final void	setVolume(double the volume value) Sets the audio playback volume.
public ObjectProperty<Duration>	startTimeProperty()
public ReadOnlyObjectProperty<MediaPlayer.Status>	statusProperty()
private ReadOnlyObjectWrapper<MediaPlayer.Status>	statusPropertyImpl()
public void	stop() Stops playing the media.
public ObjectProperty<Duration>	stopTimeProperty()
public ReadOnlyObjectProperty<Duration>	totalDurationProperty()
private ReadOnlyObjectWrapper<Duration>	totalDurationPropertyImpl()
pack-priv void	updateTime()
public DoubleProperty	volumeProperty()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public final Class MediaPlayer

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary