Module javafx.media
Package javafx.scene.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 `MediaView`s. 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`

## Property Summary

Properties
Type
Property
Description
`DoubleProperty`
`audioSpectrumInterval`
The interval between spectrum updates in seconds.
`ObjectProperty<AudioSpectrumListener>`
`audioSpectrumListener`
A listener for audio spectrum updates.
`IntegerProperty`
`audioSpectrumNumBands`
The number of bands in the audio spectrum.
`IntegerProperty`
`audioSpectrumThreshold`
The sensitivity threshold in decibels; must be non-positive.
`BooleanProperty`
`autoPlay`
Whether playing should start as soon as possible.
`DoubleProperty`
`balance`
The balance, or left-right setting, of the audio output.
`ReadOnlyObjectProperty<Duration>`
`bufferProgressTime`
The current buffer position indicating how much media can be played without stalling the `MediaPlayer`.
`ReadOnlyIntegerProperty`
`currentCount`
The number of completed playback cycles.
`ReadOnlyDoubleProperty`
`currentRate`
The current rate of playback regardless of settings.
`ReadOnlyObjectProperty<Duration>`
`currentTime`
The current media playback time.
`IntegerProperty`
`cycleCount`
The number of times the media will be played.
`ReadOnlyObjectProperty<Duration>`
`cycleDuration`
The amount of time between the `startTime` and `stopTime` of this player.
`ReadOnlyObjectProperty<MediaException>`
`error`
Observable property set to a `MediaException` if an error occurs.
`BooleanProperty`
`mute`
Whether the player audio is muted.
`ObjectProperty<Runnable>`
`onEndOfMedia`
Event handler invoked when the player `currentTime` reaches `stopTime`.
`ObjectProperty<Runnable>`
`onError`
Event handler invoked when an error occurs.
`ObjectProperty<Runnable>`
`onHalted`
Event handler invoked when the status changes to `HALTED`.
`ObjectProperty<EventHandler<MediaMarkerEvent>>`
`onMarker`
Event handler invoked when the player `currentTime` reaches a media marker.
`ObjectProperty<Runnable>`
`onPaused`
Event handler invoked when the status changes to `PAUSED`.
`ObjectProperty<Runnable>`
`onPlaying`
Event handler invoked when the status changes to `PLAYING`.
`ObjectProperty<Runnable>`
`onReady`
Event handler invoked when the status changes to `READY`.
`ObjectProperty<Runnable>`
`onRepeat`
Event handler invoked when the player `currentTime` reaches `stopTime` and will be repeating.
`ObjectProperty<Runnable>`
`onStalled`
Event handler invoked when the status changes to `STALLED`.
`ObjectProperty<Runnable>`
`onStopped`
Event handler invoked when the status changes to `STOPPED`.
`DoubleProperty`
`rate`
The rate at which the media should be played.
`ObjectProperty<Duration>`
`startTime`
The time offset where media should start playing, or restart from when repeating.
`ReadOnlyObjectProperty<MediaPlayer.Status>`
`status`
The current state of the MediaPlayer.
`ObjectProperty<Duration>`
`stopTime`
The time offset where media should stop playing or restart when repeating.
`ReadOnlyObjectProperty<Duration>`
`totalDuration`
The total amount of play time if allowed to play until finished.
`DoubleProperty`
`volume`
The volume at which the media should be played.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`MediaPlayer.Status`
Enumeration describing the different status values of a `MediaPlayer`.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`INDEFINITE`
A value representing an effectively infinite number of playback cycles.

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`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()`
Whether playing should start as soon as possible.
`DoubleProperty`
`balanceProperty()`
The balance, or left-right setting, of the audio output.
`ReadOnlyObjectProperty<Duration>`
`bufferProgressTimeProperty()`
The current buffer position indicating how much media can be played without stalling the `MediaPlayer`.
`ReadOnlyIntegerProperty`
`currentCountProperty()`
The number of completed playback cycles.
`ReadOnlyDoubleProperty`
`currentRateProperty()`
The current rate of playback regardless of settings.
`ReadOnlyObjectProperty<Duration>`
`currentTimeProperty()`
The current media playback time.
`IntegerProperty`
`cycleCountProperty()`
The number of times the media will be played.
`ReadOnlyObjectProperty<Duration>`
`cycleDurationProperty()`
The amount of time between the `startTime` and `stopTime` of this player.
`void`
`dispose()`
Free all resources associated with player.
`ReadOnlyObjectProperty<MediaException>`
`errorProperty()`
Observable property set to a `MediaException` if an error occurs.
`final AudioEqualizer`
`getAudioEqualizer()`
Retrieve the `AudioEqualizer` associated with this player.
`final double`
`getAudioSpectrumInterval()`
Retrieves the value of the audio spectrum notification interval in seconds.
`final AudioSpectrumListener`
`getAudioSpectrumListener()`
Retrieves the listener of the audio spectrum.
`final int`
`getAudioSpectrumNumBands()`
Retrieves the number of bands in the audio spectrum.
`final int`
`getAudioSpectrumThreshold()`
Retrieves the audio spectrum threshold in decibels.
`final double`
`getBalance()`
Retrieves the audio balance.
`final Duration`
`getBufferProgressTime()`
Retrieves the `bufferProgressTime` value.
`final int`
`getCurrentCount()`
Retrieves the index of the current cycle.
`final double`
`getCurrentRate()`
Retrieves the current playback rate.
`final Duration`
`getCurrentTime()`
Retrieves the current media time.
`final int`
`getCycleCount()`
Retrieves the cycle count.
`final Duration`
`getCycleDuration()`
Retrieves the cycle duration in seconds.
`final MediaException`
`getError()`
Retrieve the value of the `error` property or `null` if there is no error.
`final Media`
`getMedia()`
Retrieves the `Media` instance being played.
`final Runnable`
`getOnEndOfMedia()`
Retrieves the end of media event handler.
`final Runnable`
`getOnError()`
Retrieves the event handler for errors.
`final Runnable`
`getOnHalted()`
Retrieves the `MediaPlayer.Status.HALTED` event handler.
`final EventHandler<MediaMarkerEvent>`
`getOnMarker()`
Retrieves the marker event handler.
`final Runnable`
`getOnPaused()`
Retrieves the `MediaPlayer.Status.PAUSED` event handler.
`final Runnable`
`getOnPlaying()`
Retrieves the `MediaPlayer.Status.PLAYING` event handler.
`final Runnable`
`getOnReady()`
Retrieves the `MediaPlayer.Status.READY` event handler.
`final Runnable`
`getOnRepeat()`
Retrieves the repeat event handler.
`final Runnable`
`getOnStalled()`
Retrieves the `MediaPlayer.Status.STALLED` event handler.
`final Runnable`
`getOnStopped()`
Retrieves the `MediaPlayer.Status.STOPPED` event handler.
`final double`
`getRate()`
Retrieves the playback rate.
`final Duration`
`getStartTime()`
Retrieves the start time.
`final MediaPlayer.Status`
`getStatus()`
Retrieves the current player status.
`final Duration`
`getStopTime()`
Retrieves the stop time.
`final Duration`
`getTotalDuration()`
Retrieves the total playback duration including all cycles (repetitions).
`final double`
`getVolume()`
Retrieves the audio playback volume.
`final boolean`
`isAutoPlay()`
Retrieves the `autoPlay` property value.
`final boolean`
`isMute()`
Retrieves the `muteProperty()` value.
`BooleanProperty`
`muteProperty()`
Whether the player audio is muted.
`ObjectProperty<Runnable>`
`onEndOfMediaProperty()`
Event handler invoked when the player `currentTime` reaches `stopTime`.
`ObjectProperty<Runnable>`
`onErrorProperty()`
Event handler invoked when an error occurs.
`ObjectProperty<Runnable>`
`onHaltedProperty()`
Event handler invoked when the status changes to `HALTED`.
`ObjectProperty<EventHandler<MediaMarkerEvent>>`
`onMarkerProperty()`
Event handler invoked when the player `currentTime` reaches a media marker.
`ObjectProperty<Runnable>`
`onPausedProperty()`
Event handler invoked when the status changes to `PAUSED`.
`ObjectProperty<Runnable>`
`onPlayingProperty()`
Event handler invoked when the status changes to `PLAYING`.
`ObjectProperty<Runnable>`
`onReadyProperty()`
Event handler invoked when the status changes to `READY`.
`ObjectProperty<Runnable>`
`onRepeatProperty()`
Event handler invoked when the player `currentTime` reaches `stopTime` and will be repeating.
`ObjectProperty<Runnable>`
`onStalledProperty()`
Event handler invoked when the status changes to `STALLED`.
`ObjectProperty<Runnable>`
`onStoppedProperty()`
Event handler invoked when the status changes to `STOPPED`.
`void`
`pause()`
Pauses the player.
`void`
`play()`
Starts playing the media.
`DoubleProperty`
`rateProperty()`
The rate at which the media should be played.
`void`
`seek(Duration seekTime)`
Seeks the player to a new playback time.
`final void`
`setAudioSpectrumInterval(double value)`
Sets the value of the audio spectrum notification interval in seconds.
`final void`
`setAudioSpectrumListener(AudioSpectrumListener listener)`
Sets the listener of the audio spectrum.
`final void`
`setAudioSpectrumNumBands(int value)`
Sets the number of bands in the audio spectrum.
`final void`
`setAudioSpectrumThreshold(int value)`
Sets the audio spectrum threshold in decibels.
`final void`
`setAutoPlay(boolean value)`
Sets the `autoPlay` property value.
`final void`
`setBalance(double value)`
Sets the audio balance.
`final void`
`setCycleCount(int value)`
Sets the cycle count.
`final void`
`setMute(boolean value)`
Sets the value of `muteProperty()`.
`final void`
`setOnEndOfMedia(Runnable value)`
Sets the end of media event handler.
`final void`
`setOnError(Runnable value)`
Sets the event handler to be called when an error occurs.
`final void`
`setOnHalted(Runnable value)`
Sets the `MediaPlayer.Status.HALTED` event handler.
`final void`
`setOnMarker(EventHandler<MediaMarkerEvent> onMarker)`
Sets the marker event handler.
`final void`
`setOnPaused(Runnable value)`
Sets the `MediaPlayer.Status.PAUSED` event handler.
`final void`
`setOnPlaying(Runnable value)`
Sets the `MediaPlayer.Status.PLAYING` event handler.
`final void`
`setOnReady(Runnable value)`
Sets the `MediaPlayer.Status.READY` event handler.
`final void`
`setOnRepeat(Runnable value)`
Sets the repeat event handler.
`final void`
`setOnStalled(Runnable value)`
Sets the `MediaPlayer.Status.STALLED` event handler.
`final void`
`setOnStopped(Runnable value)`
Sets the `MediaPlayer.Status.STOPPED` event handler.
`final void`
`setRate(double value)`
Sets the playback rate to the supplied value.
`final void`
`setStartTime(Duration value)`
Sets the start time.
`final void`
`setStopTime(Duration value)`
Sets the stop time.
`final void`
`setVolume(double value)`
Sets the audio playback volume.
`ObjectProperty<Duration>`
`startTimeProperty()`
The time offset where media should start playing, or restart from when repeating.
`ReadOnlyObjectProperty<MediaPlayer.Status>`
`statusProperty()`
The current state of the MediaPlayer.
`void`
`stop()`
Stops playing the media.
`ObjectProperty<Duration>`
`stopTimeProperty()`
The time offset where media should stop playing or restart when repeating.
`ReadOnlyObjectProperty<Duration>`
`totalDurationProperty()`
The total amount of play time if allowed to play until finished.
`DoubleProperty`
`volumeProperty()`
The volume at which the media should be played.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Property Details

### error

public ReadOnlyObjectProperty<MediaException> errorProperty
Observable property set to a `MediaException` if an error occurs.

See Also:
  - `getError()`
  - `errorProperty()`

### onError

public ObjectProperty<Runnable> onErrorProperty
Event handler invoked when an error occurs.

See Also:
  - `getOnError()`
  - `setOnError(Runnable)`
  - `onErrorProperty()`

### autoPlay

public BooleanProperty autoPlayProperty
Whether playing should start as soon as possible. For a new player this will occur once the player has reached the READY state. The default value is `false`.

See Also:
  - `isAutoPlay()`
  - `setAutoPlay(boolean)`
  - `autoPlayProperty()`

### rate

public DoubleProperty rateProperty
The rate at which the media should be played. For example, a rate of `1.0` plays the media at its normal (encoded) playback rate, `2.0` plays back at twice the normal rate, etc. The currently supported range of rates is `[0.0, 8.0]`. The default value is `1.0`.

See Also:
  - `getRate()`
  - `setRate(double)`
  - `rateProperty()`

### currentRate

public ReadOnlyDoubleProperty 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, then `currentRate` will be zero.

See Also:
  - `getCurrentRate()`
  - `currentRateProperty()`

### volume

public DoubleProperty volumeProperty
The volume at which the media should be played. The range of effective values is `[0.0 1.0]` where `0.0` is inaudible and `1.0` is full volume, which is the default.

See Also:
  - `getVolume()`
  - `setVolume(double)`
  - `volumeProperty()`

### balance

public DoubleProperty balanceProperty
The balance, or left-right setting, of the audio output. The range of effective values is `[-1.0, 1.0]` with `-1.0` being full left, `0.0` center, and `1.0` full right. The default value is `0.0`.

See Also:
  - `getBalance()`
  - `setBalance(double)`
  - `balanceProperty()`

### startTime

public ObjectProperty<Duration> startTimeProperty
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. If this value is positive, then the first time the media is played there might be a delay before playing begins unless the play position can be set to an arbitrary time within the media. This could occur for example for a video which does not contain a lookup table of the offsets of intra-frames in the video stream. In such a case the video frames would need to be skipped over until the position of the first intra-frame before the start time was reached. The default value is `Duration.ZERO`.

Constraints: `0 ≤ startTime < `stopTime``

See Also:
  - `getStartTime()`
  - `setStartTime(Duration)`
  - `startTimeProperty()`

### stopTime

public ObjectProperty<Duration> stopTimeProperty
The time offset where media should stop playing or restart when repeating. The default value is ``getMedia()`.getDuration()`.

Constraints: ``startTime` < stopTime ≤ `Media.duration``

See Also:
  - `getStopTime()`
  - `setStopTime(Duration)`
  - `stopTimeProperty()`

### cycleDuration

public ReadOnlyObjectProperty<Duration> cycleDurationProperty
The amount of time between the `startTime` and `stopTime` of this player. For the total duration of the Media use the `Media.duration` property.

See Also:
  - `getCycleDuration()`
  - `cycleDurationProperty()`

### totalDuration

public ReadOnlyObjectProperty<Duration> totalDurationProperty
The total amount of play time if allowed to play until finished. If `cycleCount` is set to `INDEFINITE` then this will also be INDEFINITE. If the Media duration is UNKNOWN, then this will likewise be UNKNOWN. Otherwise, total duration will be the product of cycleDuration and cycleCount.

See Also:
  - `getTotalDuration()`
  - `totalDurationProperty()`

### currentTime

public ReadOnlyObjectProperty<Duration> currentTimeProperty
The current media playback time. This property is read-only: use `seek(javafx.util.Duration)` to change playback to a different stream position.

See Also:
  - `getCurrentTime()`
  - `currentTimeProperty()`

### status

public ReadOnlyObjectProperty<MediaPlayer.Status> statusProperty
The current state of the MediaPlayer.

See Also:
  - `getStatus()`
  - `statusProperty()`

### bufferProgressTime

public ReadOnlyObjectProperty<Duration> bufferProgressTimeProperty
The current buffer position indicating how much media can be played without stalling the `MediaPlayer`. This is applicable to buffered streams such as those reading from network connections as opposed for example to local files.

Seeking to a position beyond `bufferProgressTime` might cause a slight pause in playback until an amount of data sufficient to permit playback resumption has been buffered.

See Also:
  - `getBufferProgressTime()`
  - `bufferProgressTimeProperty()`

### cycleCount

public IntegerProperty cycleCountProperty
The number of times the media will be played. By default, `cycleCount` is set to `1` meaning the media will only be played once. Setting `cycleCount` to a value greater 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)`
  - `cycleCountProperty()`

### currentCount

public ReadOnlyIntegerProperty currentCountProperty
The number of completed playback 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`, i.e., when `stopTime` or the end of media has been reached.

See Also:
  - `getCurrentCount()`
  - `currentCountProperty()`

### mute

public BooleanProperty muteProperty
Whether the player audio is muted. A value of `true` indicates that audio is not being produced. The value of this property has no effect on `volume`, i.e., if the audio is muted and then un-muted, audio playback will resume at the same audible level provided of course that the `volume` property has not been modified meanwhile. The default value is `false`.

See Also:
  - `isMute()`
  - `setMute(boolean)`
  - `muteProperty()`

### onMarker

public ObjectProperty<EventHandler<MediaMarkerEvent>> onMarkerProperty
Event handler invoked when the player `currentTime` reaches a media marker.

See Also:
  - `getOnMarker()`
  - `setOnMarker(EventHandler)`
  - `onMarkerProperty()`

### onEndOfMedia

public ObjectProperty<Runnable> onEndOfMediaProperty
Event handler invoked when the player `currentTime` reaches `stopTime`.

See Also:
  - `getOnEndOfMedia()`
  - `setOnEndOfMedia(Runnable)`
  - `onEndOfMediaProperty()`

### onReady

public ObjectProperty<Runnable> onReadyProperty
Event handler invoked when the status changes to `READY`.

See Also:
  - `getOnReady()`
  - `setOnReady(Runnable)`
  - `onReadyProperty()`

### onPlaying

public ObjectProperty<Runnable> onPlayingProperty
Event handler invoked when the status changes to `PLAYING`.

See Also:
  - `getOnPlaying()`
  - `setOnPlaying(Runnable)`
  - `onPlayingProperty()`

### onPaused

public ObjectProperty<Runnable> onPausedProperty
Event handler invoked when the status changes to `PAUSED`.

See Also:
  - `getOnPaused()`
  - `setOnPaused(Runnable)`
  - `onPausedProperty()`

### onStopped

public ObjectProperty<Runnable> onStoppedProperty
Event handler invoked when the status changes to `STOPPED`.

See Also:
  - `getOnStopped()`
  - `setOnStopped(Runnable)`
  - `onStoppedProperty()`

### onHalted

public ObjectProperty<Runnable> onHaltedProperty
Event handler invoked when the status changes to `HALTED`.

See Also:
  - `getOnHalted()`
  - `setOnHalted(Runnable)`
  - `onHaltedProperty()`

### onRepeat

public ObjectProperty<Runnable> onRepeatProperty
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)`
  - `onRepeatProperty()`

### onStalled

public ObjectProperty<Runnable> onStalledProperty
Event handler invoked when the status changes to `STALLED`.

See Also:
  - `getOnStalled()`
  - `setOnStalled(Runnable)`
  - `onStalledProperty()`

### audioSpectrumNumBands

public IntegerProperty audioSpectrumNumBandsProperty
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)`
  - `audioSpectrumNumBandsProperty()`

### audioSpectrumInterval

public DoubleProperty audioSpectrumIntervalProperty
The interval between spectrum updates in seconds. The default is `0.1` seconds.

See Also:
  - `getAudioSpectrumInterval()`
  - `setAudioSpectrumInterval(double)`
  - `audioSpectrumIntervalProperty()`

### audioSpectrumThreshold

public IntegerProperty audioSpectrumThresholdProperty
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. The default value is -60 dB.

See Also:
  - `getAudioSpectrumThreshold()`
  - `setAudioSpectrumThreshold(int)`
  - `audioSpectrumThresholdProperty()`

### audioSpectrumListener

public ObjectProperty<AudioSpectrumListener> audioSpectrumListenerProperty
A listener for audio spectrum updates. When the listener is registered, audio spectrum computation is enabled; upon removing the listener, computation 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 waveforms for a music visualizer.

See Also:
  - `getAudioSpectrumListener()`
  - `setAudioSpectrumListener(AudioSpectrumListener)`
  - `audioSpectrumListenerProperty()`

## Field Details

### INDEFINITE

public static final int INDEFINITE
A value representing an effectively infinite number of playback cycles. When `cycleCount` is set to this value, the player will replay the `Media` until stopped or paused.

See Also:
  - Constant Field Values

## Constructor Details

### MediaPlayer

public MediaPlayer(Media media)
Create a player for a specific media. This is the only way to associate a `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.

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

## Method Details

### getAudioEqualizer

public final AudioEqualizer getAudioEqualizer()
Retrieve the `AudioEqualizer` associated with this player.

Returns:
  the `AudioEqualizer` or `null` if player is disposed.

### 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 ReadOnlyObjectProperty<MediaException> errorProperty()
Observable property set to a `MediaException` if an error occurs.

Returns:
  the `error` property
See Also:
  - `getError()`

### setOnError

public final void setOnError(Runnable value)
Sets the event handler to be called when an error occurs.

Parameters:
  `value` - the event handler or `null`.

### getOnError

public final Runnable getOnError()
Retrieves the event handler for errors.

Returns:
  the event handler.

### onErrorProperty

public ObjectProperty<Runnable> onErrorProperty()
Event handler invoked when an error occurs.

Returns:
  the `onError` property
See Also:
  - `getOnError()`
  - `setOnError(Runnable)`

### getMedia

public final Media getMedia()
Retrieves the `Media` instance being played.

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()
Whether playing should start as soon as possible. For a new player this will occur once the player has reached the READY state. The default value is `false`.

Returns:
  the `autoPlay` property
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`. 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)`.

### 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]`. Invoking this method will have no effect if media duration is `Duration.INDEFINITE`.

Parameters:
  `value` - the playback rate

### getRate

public final double getRate()
Retrieves the playback rate.

Returns:
  the playback rate

### rateProperty

public DoubleProperty rateProperty()
The rate at which the media should be played. For example, a rate of `1.0` plays the media at its normal (encoded) playback rate, `2.0` plays back at twice the normal rate, etc. The currently supported range of rates is `[0.0, 8.0]`. The default value is `1.0`.

Returns:
  the `rate` property
See Also:
  - `getRate()`
  - `setRate(double)`

### getCurrentRate

public final double getCurrentRate()
Retrieves the current playback rate.

Returns:
  the current rate

### currentRateProperty

public ReadOnlyDoubleProperty 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, then `currentRate` will be zero.

Returns:
  the `currentRate` property
See Also:
  - `getCurrentRate()`

### 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()
The volume at which the media should be played. The range of effective values is `[0.0 1.0]` where `0.0` is inaudible and `1.0` is full volume, which is the default.

Returns:
  the `volume` property
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()
The balance, or left-right setting, of the audio output. The range of effective values is `[-1.0, 1.0]` with `-1.0` being full left, `0.0` center, and `1.0` full right. The default value is `0.0`.

Returns:
  the `balance` property
See Also:
  - `getBalance()`
  - `setBalance(double)`

### setStartTime

public final void setStartTime(Duration value)
Sets the start time. Its effect will be clamped to the range `[`Duration.ZERO`, `stopTime`)`. Invoking this method will have no effect if media duration is `Duration.INDEFINITE`.

Parameters:
  `value` - the start time

### getStartTime

public final Duration getStartTime()
Retrieves the start time. The default value is `Duration.ZERO`.

Returns:
  the start time

### startTimeProperty

public ObjectProperty<Duration> startTimeProperty()
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. If this value is positive, then the first time the media is played there might be a delay before playing begins unless the play position can be set to an arbitrary time within the media. This could occur for example for a video which does not contain a lookup table of the offsets of intra-frames in the video stream. In such a case the video frames would need to be skipped over until the position of the first intra-frame before the start time was reached. The default value is `Duration.ZERO`.

Constraints: `0 ≤ startTime < `stopTime``

Returns:
  the `startTime` property
See Also:
  - `getStartTime()`
  - `setStartTime(Duration)`

### setStopTime

public final void setStopTime(Duration value)
Sets the stop time. Its effect will be clamped to the range `(`startTime`, `Media.duration`]`. Invoking this method will have no effect if media duration is `Duration.INDEFINITE`.

Parameters:
  `value` - the stop time

### getStopTime

public final Duration getStopTime()
Retrieves the stop time. The default value is ``getMedia()`.getDuration()`. Note that ``Media.duration`` may have the value `Duration.UNKNOWN` if media initialization is not complete.

Returns:
  the stop time

### stopTimeProperty

public ObjectProperty<Duration> stopTimeProperty()
The time offset where media should stop playing or restart when repeating. The default value is ``getMedia()`.getDuration()`.

Constraints: ``startTime` < stopTime ≤ `Media.duration``

Returns:
  the `stopTime` property
See Also:
  - `getStopTime()`
  - `setStopTime(Duration)`

### getCycleDuration

public final Duration getCycleDuration()
Retrieves the cycle duration in seconds.

Returns:
  the cycle duration

### cycleDurationProperty

public ReadOnlyObjectProperty<Duration> cycleDurationProperty()
The amount of time between the `startTime` and `stopTime` of this player. For the total duration of the Media use the `Media.duration` property.

Returns:
  the `cycleDuration` property
See Also:
  - `getCycleDuration()`

### getTotalDuration

public final Duration getTotalDuration()
Retrieves the total playback duration including all cycles (repetitions).

Returns:
  the total playback duration

### totalDurationProperty

public ReadOnlyObjectProperty<Duration> totalDurationProperty()
The total amount of play time if allowed to play until finished. If `cycleCount` is set to `INDEFINITE` then this will also be INDEFINITE. If the Media duration is UNKNOWN, then this will likewise be UNKNOWN. Otherwise, total duration will be the product of cycleDuration and cycleCount.

Returns:
  the `totalDuration` property
See Also:
  - `getTotalDuration()`

### getCurrentTime

public final Duration getCurrentTime()
Retrieves the current media time.

Returns:
  the current media time

### currentTimeProperty

public ReadOnlyObjectProperty<Duration> currentTimeProperty()
The current media playback time. This property is read-only: use `seek(javafx.util.Duration)` to change playback to a different stream position.

Returns:
  the `currentTime` property
See Also:
  - `getCurrentTime()`

### seek

public void seek(Duration seekTime)
Seeks the player to a new playback time. Invoking this method will have no effect while the player status is `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:

MediaPlayer Seek Table
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

Parameters:
  `seekTime` - the requested playback time

### getStatus

public final MediaPlayer.Status getStatus()
Retrieves the current player status.

Returns:
  the playback status

### statusProperty

public ReadOnlyObjectProperty<MediaPlayer.Status> statusProperty()
The current state of the MediaPlayer.

Returns:
  the `status` property
See Also:
  - `getStatus()`

### getBufferProgressTime

public final Duration getBufferProgressTime()
Retrieves the `bufferProgressTime` value.

Returns:
  the buffer progress time

### bufferProgressTimeProperty

public ReadOnlyObjectProperty<Duration> bufferProgressTimeProperty()
The current buffer position indicating how much media can be played without stalling the `MediaPlayer`. This is applicable to buffered streams such as those reading from network connections as opposed for example to local files.

Seeking to a position beyond `bufferProgressTime` might cause a slight pause in playback until an amount of data sufficient to permit playback resumption has been buffered.

Returns:
  the `bufferProgressTime` property
See Also:
  - `getBufferProgressTime()`

### setCycleCount

public final void setCycleCount(int value)
Sets the cycle count. Its effect will be constrained to `[1,`Integer.MAX_VALUE`]`. Invoking this method will have no effect if media duration is `Duration.INDEFINITE`.

Parameters:
  `value` - the cycle count

### getCycleCount

public final int getCycleCount()
Retrieves the cycle count.

Returns:
  the cycle count.

### cycleCountProperty

public IntegerProperty cycleCountProperty()
The number of times the media will be played. By default, `cycleCount` is set to `1` meaning the media will only be played once. Setting `cycleCount` to a value greater 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`

Returns:
  the `cycleCount` property
See Also:
  - `getCycleCount()`
  - `setCycleCount(int)`

### getCurrentCount

public final int getCurrentCount()
Retrieves the index of the current cycle.

Returns:
  the current cycle index

### currentCountProperty

public ReadOnlyIntegerProperty currentCountProperty()
The number of completed playback 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`, i.e., when `stopTime` or the end of media has been reached.

Returns:
  the `currentCount` property
See Also:
  - `getCurrentCount()`

### setMute

public final void setMute(boolean value)
Sets the value of `muteProperty()`.

Parameters:
  `value` - the `mute` setting

### isMute

public final boolean isMute()
Retrieves the `muteProperty()` value.

Returns:
  the mute setting

### muteProperty

public BooleanProperty muteProperty()
Whether the player audio is muted. A value of `true` indicates that audio is not being produced. The value of this property has no effect on `volume`, i.e., if the audio is muted and then un-muted, audio playback will resume at the same audible level provided of course that the `volume` property has not been modified meanwhile. The default value is `false`.

Returns:
  the `mute` property
See Also:
  - `isMute()`
  - `setMute(boolean)`

### setOnMarker

public final void setOnMarker(EventHandler<MediaMarkerEvent> onMarker)
Sets the marker event handler.

Parameters:
  `onMarker` - the marker event handler.

### getOnMarker

public final EventHandler<MediaMarkerEvent> getOnMarker()
Retrieves the marker event handler.

Returns:
  the marker event handler.

### onMarkerProperty

public ObjectProperty<EventHandler<MediaMarkerEvent>> onMarkerProperty()
Event handler invoked when the player `currentTime` reaches a media marker.

Returns:
  the `onMarker` property
See Also:
  - `getOnMarker()`
  - `setOnMarker(EventHandler)`

### setOnEndOfMedia

public final void setOnEndOfMedia(Runnable value)
Sets the end of media event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnEndOfMedia

public final Runnable getOnEndOfMedia()
Retrieves the end of media event handler.

Returns:
  the event handler or `null`.

### onEndOfMediaProperty

public ObjectProperty<Runnable> onEndOfMediaProperty()
Event handler invoked when the player `currentTime` reaches `stopTime`.

Returns:
  the `onEndOfMedia` property
See Also:
  - `getOnEndOfMedia()`
  - `setOnEndOfMedia(Runnable)`

### setOnReady

public final void setOnReady(Runnable value)
Sets the `MediaPlayer.Status.READY` event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnReady

public final Runnable getOnReady()
Retrieves the `MediaPlayer.Status.READY` event handler.

Returns:
  the event handler or `null`.

### onReadyProperty

public ObjectProperty<Runnable> onReadyProperty()
Event handler invoked when the status changes to `READY`.

Returns:
  the `onReady` property
See Also:
  - `getOnReady()`
  - `setOnReady(Runnable)`

### setOnPlaying

public final void setOnPlaying(Runnable value)
Sets the `MediaPlayer.Status.PLAYING` event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnPlaying

public final Runnable getOnPlaying()
Retrieves the `MediaPlayer.Status.PLAYING` event handler.

Returns:
  the event handler or `null`.

### onPlayingProperty

public ObjectProperty<Runnable> onPlayingProperty()
Event handler invoked when the status changes to `PLAYING`.

Returns:
  the `onPlaying` property
See Also:
  - `getOnPlaying()`
  - `setOnPlaying(Runnable)`

### setOnPaused

public final void setOnPaused(Runnable value)
Sets the `MediaPlayer.Status.PAUSED` event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnPaused

public final Runnable getOnPaused()
Retrieves the `MediaPlayer.Status.PAUSED` event handler.

Returns:
  the event handler or `null`.

### onPausedProperty

public ObjectProperty<Runnable> onPausedProperty()
Event handler invoked when the status changes to `PAUSED`.

Returns:
  the `onPaused` property
See Also:
  - `getOnPaused()`
  - `setOnPaused(Runnable)`

### setOnStopped

public final void setOnStopped(Runnable value)
Sets the `MediaPlayer.Status.STOPPED` event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnStopped

public final Runnable getOnStopped()
Retrieves the `MediaPlayer.Status.STOPPED` event handler.

Returns:
  the event handler or `null`.

### onStoppedProperty

public ObjectProperty<Runnable> onStoppedProperty()
Event handler invoked when the status changes to `STOPPED`.

Returns:
  the `onStopped` property
See Also:
  - `getOnStopped()`
  - `setOnStopped(Runnable)`

### setOnHalted

public final void setOnHalted(Runnable value)
Sets the `MediaPlayer.Status.HALTED` event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnHalted

public final Runnable getOnHalted()
Retrieves the `MediaPlayer.Status.HALTED` event handler.

Returns:
  the event handler or `null`.

### onHaltedProperty

public ObjectProperty<Runnable> onHaltedProperty()
Event handler invoked when the status changes to `HALTED`.

Returns:
  the `onHalted` property
See Also:
  - `getOnHalted()`
  - `setOnHalted(Runnable)`

### setOnRepeat

public final void setOnRepeat(Runnable value)
Sets the repeat event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnRepeat

public final Runnable getOnRepeat()
Retrieves the repeat event handler.

Returns:
  the event handler or `null`.

### onRepeatProperty

public ObjectProperty<Runnable> onRepeatProperty()
Event handler invoked when the player `currentTime` reaches `stopTime` and will be repeating. This callback is made prior to seeking back to `startTime`.

Returns:
  the `onRepeat` property
See Also:
  - `getOnRepeat()`
  - `setOnRepeat(Runnable)`

### setOnStalled

public final void setOnStalled(Runnable value)
Sets the `MediaPlayer.Status.STALLED` event handler.

Parameters:
  `value` - the event handler or `null`.

### getOnStalled

public final Runnable getOnStalled()
Retrieves the `MediaPlayer.Status.STALLED` event handler.

Returns:
  the event handler or `null`.

### onStalledProperty

public ObjectProperty<Runnable> onStalledProperty()
Event handler invoked when the status changes to `STALLED`.

Returns:
  the `onStalled` property
See Also:
  - `getOnStalled()`
  - `setOnStalled(Runnable)`

### setAudioSpectrumNumBands

public final void setAudioSpectrumNumBands(int value)
Sets the number of bands in the audio spectrum.

Parameters:
  `value` - the number of spectral bands; `value`must be ≥ 2

### getAudioSpectrumNumBands

public final int getAudioSpectrumNumBands()
Retrieves the number of bands in the audio spectrum.

Returns:
  the number of spectral bands.

### audioSpectrumNumBandsProperty

public IntegerProperty audioSpectrumNumBandsProperty()
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`.

Returns:
  the `audioSpectrumNumBands` property
See Also:
  - `getAudioSpectrumNumBands()`
  - `setAudioSpectrumNumBands(int)`

### setAudioSpectrumInterval

public final void setAudioSpectrumInterval(double value)
Sets the value of the audio spectrum notification interval in seconds.

Parameters:
  `value` - a positive value specifying the spectral update interval

### getAudioSpectrumInterval

public final double getAudioSpectrumInterval()
Retrieves the value of the audio spectrum notification interval in seconds.

Returns:
  the spectral update interval

### audioSpectrumIntervalProperty

public DoubleProperty audioSpectrumIntervalProperty()
The interval between spectrum updates in seconds. The default is `0.1` seconds.

Returns:
  the `audioSpectrumInterval` property
See Also:
  - `getAudioSpectrumInterval()`
  - `setAudioSpectrumInterval(double)`

### setAudioSpectrumThreshold

public final void setAudioSpectrumThreshold(int value)
Sets the audio spectrum threshold in decibels.

Parameters:
  `value` - the spectral threshold in dB; must be ≤ `0`.

### getAudioSpectrumThreshold

public final int getAudioSpectrumThreshold()
Retrieves the audio spectrum threshold in decibels.

Returns:
  the spectral threshold in dB

### audioSpectrumThresholdProperty

public IntegerProperty audioSpectrumThresholdProperty()
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. The default value is -60 dB.

Returns:
  the `audioSpectrumThreshold` property
See Also:
  - `getAudioSpectrumThreshold()`
  - `setAudioSpectrumThreshold(int)`

### setAudioSpectrumListener

public final void setAudioSpectrumListener(AudioSpectrumListener listener)
Sets the listener of the audio spectrum.

Parameters:
  `listener` - the spectral listener or `null`.

### getAudioSpectrumListener

public final AudioSpectrumListener getAudioSpectrumListener()
Retrieves the listener of the audio spectrum.

Returns:
  the spectral listener or `null`

### audioSpectrumListenerProperty

public ObjectProperty<AudioSpectrumListener> audioSpectrumListenerProperty()
A listener for audio spectrum updates. When the listener is registered, audio spectrum computation is enabled; upon removing the listener, computation 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 waveforms for a music visualizer.

Returns:
  the `audioSpectrumListener` property
See Also:
  - `getAudioSpectrumListener()`
  - `setAudioSpectrumListener(AudioSpectrumListener)`

### dispose

public void dispose()
Free all resources associated with player. Player SHOULD NOT be used after this function is called. Player will transition to `MediaPlayer.Status.DISPOSED` after this method is done. This method can be called anytime regardless of current player status.

Since:
  JavaFX 8.0