MediaPlayer (Java FX 2.0)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javafx.scene.media
Class MediaPlayer

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

public final class MediaPlayer
extends java.lang.Object
extends java.lang.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. Note that MediaPlayer does not contain any visual elements so must be used with the MediaView class to view the media.

The operation of a MediaPlayer is inherently asynchronous and 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.

See Also:: Media, MediaView

Property Summary
`audioSpectrumInterval` The interval between spectrum updates in seconds.
`audioSpectrumListener` A listener for audio spectrum updates.
`audioSpectrumNumBands` The number of bands in the audio spectrum.
`audioSpectrumThreshold` The sensitivity threshold in decibels; must be non-positive.
`autoPlay` If `autoPlay` is `true`, playing will start as soon as possible, which occurs once the player has reached the READY state.
`balance` Defines the balance, or left-right setting, of the audio output.
`bufferProgressTime` For a bufferred stream, the current buffer position which indicating how much media can be played without stalling the `MediaPlayer`.
`currentCount` This property indicates the number of completed cycles.
`currentRate` The current rate of playback regardless of settings.
`currentTime` The current media playback time; read-only.
`cycleCount` Property indicating how many times the media will be played.
`cycleDuration` Read-only property indicating the amount of time between this player's
`error` Observable property set to a `MediaException` if an error occurs.
`mute` `true` when the player audio is muted, `false` otherwise.
`onEndOfMedia` Event handler invoked when the player `currentTime` reaches `stopTime` and is not repeating..
`onError` Event handler that is invoked when an error occurs.
`onHalted` Event handler invoked when the status changes to `HALTED`.
`onMarker` Event handler invoked when a marker is encountered.
`onPaused` Event handler invoked when the status changes to `PAUSED`.
`onPlaying` Event handler invoked when the status changes to `PLAYING`.
`onReady` Event handler invoked when the status changes to `READY`.
`onRepeat` Event handler invoked when the player `currentTime` reaches `stopTime` and will be repeating.
`onStalled` Event handler invoked when the status changes to `STALLED`.
`onStopped` Event handler invoked when the status changes to `STOPPED`
`rate` Defines the rate at which the media is being played.
`startTime` Defines the time offset where media should start playing, or restart from when repeating.
`status` Reflects the current state of the MediaPlayer.
`stopTime` Defines the time offset where media should stop playing or restart when repeating.
`totalDuration` Read-only property indicating the total amount of play time if allowed to play until finished.
`volume` Defines the volume at which the media is being played.

Nested Class Summary
`static class`	`MediaPlayer.Status` Enumeration describing different states of a `MediaPlayer`.

Field Summary
`static int`	`INDEFINITE` When `cycleCount` is set to this value, the player will repeat playback of the `Media` until stopped or paused.

Constructor Summary
`MediaPlayer(Media media)` Create a player for a specific media.

Method Summary
`DoubleProperty`	`audioSpectrumIntervalProperty()` The interval between spectrum updates in seconds.
`ObjectProperty<AudioSpectrumListener>`	`audioSpectrumListenerProperty()` A listener for audio spectrum updates.
`IntegerProperty`	`audioSpectrumNumBandsProperty()` The number of bands in the audio spectrum.
`IntegerProperty`	`audioSpectrumThresholdProperty()` The sensitivity threshold in decibels; must be non-positive.
`BooleanProperty`	`autoPlayProperty()` If `autoPlay` is `true`, playing will start as soon as possible, which occurs once the player has reached the READY state.
`DoubleProperty`	`balanceProperty()` Defines the balance, or left-right setting, of the audio output.
`ObjectProperty<Duration>`	`bufferProgressTimeProperty()` For a bufferred stream, the current buffer position which indicating how much media can be played without stalling the `MediaPlayer`.
`IntegerProperty`	`currentCountProperty()` This property indicates the number of completed cycles.
`DoubleProperty`	`currentRateProperty()` The current rate of playback regardless of settings.
`ObjectProperty<Duration>`	`currentTimeProperty()` The current media playback time; read-only.
`IntegerProperty`	`cycleCountProperty()` Property indicating how many times the media will be played.
`ObjectProperty<Duration>`	`cycleDurationProperty()` Read-only property indicating the amount of time between this player's
`ObjectProperty<MediaException>`	`errorProperty()` Observable property set to a `MediaException` if an error occurs.
`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 parent `Media` instance.
`java.lang.Runnable`	`getOnEndOfMedia()` Retrieves the end of media event handler.
`java.lang.Runnable`	`getOnError()` Retrieves the event handler for errors.
`java.lang.Runnable`	`getOnHalted()` Retrieves the `MediaPlayer.Status.HALTED` event handler.
`MarkerListener`	`getOnMarker()` Retrieves the marker event handler.
`java.lang.Runnable`	`getOnPaused()` Retrieves the `MediaPlayer.Status.PAUSED` event handler.
`java.lang.Runnable`	`getOnPlay()` Retrieves the `MediaPlayer.Status.PLAYING` event handler.
`java.lang.Runnable`	`getOnReady()` Retrieves the `MediaPlayer.Status.READY` event handler.
`java.lang.Runnable`	`getOnRepeat()` Retrieves the repeat event handler.
`java.lang.Runnable`	`getOnStalled()` Retrieves the `MediaPlayer.Status.STALLED` event handler.
`java.lang.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 start time.
`Duration`	`getTotalDuration()` Retrieves the total playback duration including all cycles (repetitions).
`double`	`getVolume()` Retrieves the audio playback volume.
`boolean`	`isAutoPlay()` Retrieves the `autoPlay` property value.
`boolean`	`isMute()` Retrieves the `mute` value.
`BooleanProperty`	`muteProperty()` `true` when the player audio is muted, `false` otherwise.
`ObjectProperty<java.lang.Runnable>`	`onEndOfMediaProperty()` Event handler invoked when the player `currentTime` reaches `stopTime` and is not repeating..
`ObjectProperty<java.lang.Runnable>`	`onErrorProperty()` Event handler that is invoked when an error occurs.
`ObjectProperty<java.lang.Runnable>`	`onHaltedProperty()` Event handler invoked when the status changes to `HALTED`.
`ObjectProperty<MarkerListener>`	`onMarkerProperty()` Event handler invoked when a marker is encountered.
`ObjectProperty<java.lang.Runnable>`	`onPausedProperty()` Event handler invoked when the status changes to `PAUSED`.
`ObjectProperty<java.lang.Runnable>`	`onPlayingProperty()` Event handler invoked when the status changes to `PLAYING`.
`ObjectProperty<java.lang.Runnable>`	`onReadyProperty()` Event handler invoked when the status changes to `READY`.
`ObjectProperty<java.lang.Runnable>`	`onRepeatProperty()` Event handler invoked when the player `currentTime` reaches `stopTime` and will be repeating.
`ObjectProperty<java.lang.Runnable>`	`onStalledProperty()` Event handler invoked when the status changes to `STALLED`.
`ObjectProperty<java.lang.Runnable>`	`onStoppedProperty()` Event handler invoked when the status changes to `STOPPED`
`void`	`pause()` Pauses the player.
`void`	`play()` Starts playing the media.
`DoubleProperty`	`rateProperty()` Defines the rate at which the media is being played.
`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 `mute`.
`void`	`setOnEndOfMedia(java.lang.Runnable value)` Sets the end of media event handler.
`void`	`setOnError(java.lang.Runnable value)` Sets the event handler to be called when an error occurs.
`void`	`setOnHalted(java.lang.Runnable value)` Sets the `MediaPlayer.Status.HALTED` event handler.
`void`	`setOnMarker(MarkerListener value)` Sets the marker event handler.
`void`	`setOnPaused(java.lang.Runnable value)` Sets the `MediaPlayer.Status.PAUSED` event handler.
`void`	`setOnPlay(java.lang.Runnable value)` Sets the `MediaPlayer.Status.PLAYING` event handler.
`void`	`setOnReady(java.lang.Runnable value)` Sets the `MediaPlayer.Status.READY` event handler.
`void`	`setOnRepeat(java.lang.Runnable value)` Sets the repeat event handler.
`void`	`setOnStalled(java.lang.Runnable value)` Sets the `MediaPlayer.Status.STALLED` event handler.
`void`	`setOnStopped(java.lang.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 `startTime`.
`void`	`setStopTime(Duration value)` Sets the stop time `stopTime`.
`void`	`setVolume(double value)` Sets the audio playback volume.
`ObjectProperty<Duration>`	`startTimeProperty()` Defines the time offset where media should start playing, or restart from when repeating.
`ObjectProperty<MediaPlayer.Status>`	`statusProperty()` Reflects the current state of the MediaPlayer.
`void`	`stop()` Stops playing the media.
`ObjectProperty<Duration>`	`stopTimeProperty()` Defines the time offset where media should stop playing or restart when repeating.
`ObjectProperty<Duration>`	`totalDurationProperty()` Read-only property indicating the total amount of play time if allowed to play until finished.
`DoubleProperty`	`volumeProperty()` Defines the volume at which the media is being played.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Property Detail

error

Observable property set to a MediaException if an error occurs.

See Also:: getError(), setError(MediaException)

onError

Event handler that is invoked when an error occurs.

See Also:: getOnError(), setOnError(Runnable)

autoPlay

If autoPlay is true, playing will start as soon as possible, which occurs once the player has reached the READY state.

See Also:: isAutoPlay(), setAutoPlay(boolean)

rate

Defines the rate at which the media is being played. For example, a rate of 1.0 plays the media at its normal playback rate, 2.0 plays back at twice the normal rate, etc. The currently supported range of rates is [0.0, 8.0].

See Also:: getRate(), setRate(double)

currentRate

The current rate of playback regardless of settings. For example, if rate is set to 1.0 and the player is paused or stalled, the currentRate will be zero.

See Also:: getCurrentRate(), setCurrentRate(double)

volume

Defines the volume at which the media is being played. 1.0 is full volume, which is the default. A value of 0.0 effectively mutes the audio.

See Also:: getVolume(), setVolume(double)

balance

Defines the balance, or left-right setting, of the audio output. Value ranges continuously from -1.0 being full left, 0.0 center, and 1.0 full right.

See Also:: getBalance(), setBalance(double)

startTime

Defines the time offset where media should start playing, or restart from when repeating. When playback is stopped, the current time is reset to this value.

Constraints: 0 ≤ startTime < stopTime

See Also:: getStartTime(), setStartTime(Duration)

stopTime

Defines the time offset where media should stop playing or restart when repeating.

Constraints: startTime < stopTime ≤ Media.duration

See Also:: getStopTime(), setStopTime(Duration)

cycleDuration

Read-only property indicating the amount of time between this player's

See Also:: getCycleDuration(), setCycleDuration(Duration)

totalDuration

Read-only property indicating the total amount of play time if allowed to play until finished. If cycleCount is set to INDEFINITE then this will be also INDEFINITE. If the Media duration is UNKNOWN, then this will likewise be UNKNOWN. Otherwise, total duration will be the multiplicative product of cycleDuration and cycleCount.

See Also:: getTotalDuration(), setTotalDuration(Duration)

currentTime

The current media playback time; read-only.

See Also:: getCurrentTime(), setCurrentTime(Duration)

status

Reflects the current state of the MediaPlayer.

See Also:: getStatus(), setStatus(MediaPlayer.Status)

bufferProgressTime

For a bufferred stream, the current buffer position which indicating how much media can be played without stalling the MediaPlayer. Seeking to a value beyond bufferProgressTime will may cause a slight pause in playback until buffering reaches the desired position in the stream.

See Also:: getBufferProgressTime(), setBufferProgressTime(Duration)

cycleCount

Property indicating how many times the media will be played. By default, cycleCount is set to 1 meaning the media will only be played once. Setting cycleCount to more than 1 will cause the media to play the given number of times or until stopped. If set to INDEFINITE, playback will repeat until stop() or pause() is called.

constraints: cycleCount ≥ 1

See Also:: getCycleCount(), setCycleCount(int)

currentCount

This property indicates the number of completed cycles. On the first pass, the value should be 0. On the second pass, the value should be 1 and so on. It is incremented at the end of each cycle just prior to seeking back to startTime.

See Also:: getCurrentCount(), setCurrentCount(int)

mute

true when the player audio is muted, false otherwise.

See Also:: isMute(), setMute(boolean)

onEndOfMedia

Event handler invoked when the player currentTime reaches stopTime and is not repeating..

See Also:: getOnEndOfMedia(), setOnEndOfMedia(Runnable)

onReady

Event handler invoked when the status changes to READY.

See Also:: getOnReady(), setOnReady(Runnable)

onPlaying

Event handler invoked when the status changes to PLAYING.

onPaused

Event handler invoked when the status changes to PAUSED.

See Also:: getOnPaused(), setOnPaused(Runnable)

onStopped

Event handler invoked when the status changes to STOPPED

See Also:: getOnStopped(), setOnStopped(Runnable)

onHalted

Event handler invoked when the status changes to HALTED.

See Also:: getOnHalted(), setOnHalted(Runnable)

onRepeat

Event handler invoked when the player currentTime reaches stopTime and will be repeating. This callback is made prior to seeking back to startTime.

See Also:: getOnRepeat(), setOnRepeat(Runnable)

onStalled

Event handler invoked when the status changes to STALLED.

See Also:: getOnStalled(), setOnStalled(Runnable)

onMarker

Event handler invoked when a marker is encountered.

See Also:: getOnMarker(), setOnMarker(MarkerListener)

audioSpectrumNumBands

The number of bands in the audio spectrum. The default value is 128; minimum is 2. The frequency range of the audio signal will be divided into the specified number of frequency bins. For example, a typical digital music signal has a frequency range of [0.0, 22050] Hz. If the number of spectral bands were in this case set to 10, the width of each frequency bin in the spectrum would be 2205 Hz with the lower bound of the lowest frequency bin equal to 0.0.

See Also:: getAudioSpectrumNumBands(), setAudioSpectrumNumBands(int)

audioSpectrumInterval

The interval between spectrum updates in seconds. The default is 0.1 seconds.

See Also:: getAudioSpectrumInterval(), setAudioSpectrumInterval(double)

audioSpectrumThreshold

The sensitivity threshold in decibels; must be non-positive. Values below this threshold with respect to the peak frequency in the given spectral band will be set to the value of the threshold.

See Also:: getAudioSpectrumThreshold(), setAudioSpectrumThreshold(int)

audioSpectrumListener

A listener for audio spectrum updates. When the listener is registered, audio spectrum computation is enabled; upon removing the listener, audio spectrum is disabled. Only a single listener may be registered, so if multiple observers are required, events must be forwarded.

An AudioSpectrumListener may be useful for example to plot the frequency spectrum of the audio being played or to generate the waveforms of a music visualizer.

See Also:: getAudioSpectrumListener(), setAudioSpectrumListener(AudioSpectrumListener)

Field Detail

INDEFINITE

public static final int INDEFINITE

When cycleCount is set to this value, the player will repeat playback of the Media until stopped or paused.

See Also:: Constant Field Values

Constructor Detail

MediaPlayer

public MediaPlayer(Media media)

Create a player for a specific media. Errors which occur synchronously within the constructor will causes 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 create, 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.

Parameters:: media - The media to play.
Throws:: java.lang.NullPointerException - if media is null.; MediaException - if any synchronous errors occur within the constructor.

Method Detail

getAudioEqualizer

public final AudioEqualizer getAudioEqualizer()

Retrieve the AudioEqualizer associated with this player.

Returns:: the AudioEqualizer.

getError

public final MediaException getError()

Retrieve the value of the error property or null if there is no error.

Returns:: a MediaException or null.

errorProperty

public ObjectProperty<MediaException> errorProperty()

Observable property set to a MediaException if an error occurs.

See Also:: getError(), setError(MediaException)

setOnError

public final void setOnError(java.lang.Runnable value)

Sets the event handler to be called when an error occurs.

Parameters:: value - the event handler or null.

getOnError

public final java.lang.Runnable getOnError()

Retrieves the event handler for errors.

Returns:: the event handler.

onErrorProperty

public ObjectProperty<java.lang.Runnable> onErrorProperty()

Event handler that is invoked when an error occurs.

See Also:: getOnError(), setOnError(Runnable)

getMedia

public final Media getMedia()

Retrieves the parent Media instance.

Returns:: the Media object.

setAutoPlay

public final void setAutoPlay(boolean value)

Sets the autoPlay property value.

Parameters:: value - whether to enable auto-playback

isAutoPlay

public final boolean isAutoPlay()

Retrieves the autoPlay property value.

Returns:: the value.

autoPlayProperty

public BooleanProperty autoPlayProperty()

If autoPlay is true, playing will start as soon as possible, which occurs once the player has reached the READY state.

See Also:: isAutoPlay(), setAutoPlay(boolean)

play

public void play()

Starts playing the media. If previously paused, then playback resumes where it was paused. If playback was stopped, playback starts from the startTime. When playing actually starts the status will be set to MediaPlayer.Status.PLAYING.

pause

public void pause()

Pauses the player. Once the player is actually paused the status will be set to MediaPlayer.Status.PAUSED.

stop

public void stop()

Stops playing the media. This operation resets playback to startTime, and resets currentCount to zero. Once the player is actually stopped, the status will be set to MediaPlayer.Status.STOPPED.

setRate

public final void setRate(double value)

Sets the playback rate to the supplied value. Its effect will be clamped to the range [0.0, 8.0].

Parameters:: value - the playback rate

getRate

public final double getRate()

Retrieves the playback rate.

Returns:: the playback rate

rateProperty

public DoubleProperty rateProperty()

See Also:: getRate(), setRate(double)

getCurrentRate

public final double getCurrentRate()

Retrieves the current playback rate.

Returns:: the current rate

currentRateProperty

public DoubleProperty currentRateProperty()

The current rate of playback regardless of settings. For example, if rate is set to 1.0 and the player is paused or stalled, the currentRate will be zero.

See Also:: getCurrentRate(), setCurrentRate(double)

setVolume

public final void setVolume(double value)

Sets the audio playback volume. Its effect will be clamped to the range [0.0, 1.0].

Parameters:: value - the volume

getVolume

public final double getVolume()

Retrieves the audio playback volume. The default value is 1.0.

Returns:: the audio volume

volumeProperty

public DoubleProperty volumeProperty()

Defines the volume at which the media is being played. 1.0 is full volume, which is the default. A value of 0.0 effectively mutes the audio.

See Also:: getVolume(), setVolume(double)

setBalance

public final void setBalance(double value)

Sets the audio balance. Its effect will be clamped to the range [-1.0, 1.0].

Parameters:: value - the balance

getBalance

public final double getBalance()

Retrieves the audio balance.

Returns:: the audio balance

balanceProperty

public DoubleProperty balanceProperty()