Module javafx.media
Package javafx.scene.media

# Class Media

java.lang.Object
javafx.scene.media.Media

public final class Media extends Object
The `Media` class represents a media resource. It is instantiated from the string form of a source URI. Information about the media such as duration, metadata, tracks, and video resolution may be obtained from a `Media` instance. The media information is obtained asynchronously and so not necessarily available immediately after instantiation of the class. All information should however be available if the instance has been associated with a `MediaPlayer` and that player has transitioned to `MediaPlayer.Status.READY` status. To be notified when metadata or `Track`s are added, observers may be registered with the collections returned by `getMetadata()`and `getTracks()`, respectively.

The same `Media` object may be shared among multiple `MediaPlayer` objects. Such a shared instance might manage a single copy of the source media data to be used by all players, or it might require a separate copy of the data for each player. The choice of implementation will not however have any effect on player behavior at the interface level.

Since:
  JavaFX 2.0
See Also:
  - `MediaPlayer`
  - `MediaException`

- ## Property Summary

  Properties
  Type
  Property
  Description
  `ReadOnlyObjectProperty<Duration>`
  `duration`
  The duration in seconds of the source media.
  `ReadOnlyObjectProperty<MediaException>`
  `error`
  A property set to a MediaException value when an error occurs.
  `ReadOnlyIntegerProperty`
  `height`
  The height in pixels of the source media.
  `ObjectProperty<Runnable>`
  `onError`
  Event handler called when an error occurs.
  `ReadOnlyIntegerProperty`
  `width`
  The width in pixels of the source media.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Media(String source)`
  Constructs a `Media` instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ReadOnlyObjectProperty<Duration>`
  `durationProperty()`
  The duration in seconds of the source media.
  `ReadOnlyObjectProperty<MediaException>`
  `errorProperty()`
  A property set to a MediaException value when an error occurs.
  `final Duration`
  `getDuration()`
  Retrieve the duration in seconds of the media.
  `final MediaException`
  `getError()`
  Return any error encountered in the media.
  `final int`
  `getHeight()`
  Retrieve the height in pixels of the media.
  `final ObservableMap<String,Duration>`
  `getMarkers()`
  Retrieve the markers defined on this `Media` instance.
  `final ObservableMap<String,Object>`
  `getMetadata()`
  Retrieve the metadata contained in this media source.
  `final Runnable`
  `getOnError()`
  Retrieve the error handler to be called if an error occurs.
  `String`
  `getSource()`
  Retrieve the source URI of the media.
  `final ObservableList<Track>`
  `getTracks()`
  Retrieve the tracks contained in this media source.
  `final int`
  `getWidth()`
  Retrieve the width in pixels of the media.
  `ReadOnlyIntegerProperty`
  `heightProperty()`
  The height in pixels of the source media.
  `ObjectProperty<Runnable>`
  `onErrorProperty()`
  Event handler called when an error occurs.
  `final void`
  `setOnError(Runnable value)`
  Set the event handler to be called when an error occurs.
  `ReadOnlyIntegerProperty`
  `widthProperty()`
  The width in pixels of the source media.

  ### Methods declared in class java.lang.Object

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

- ## Property Details

  - ### error

    public ReadOnlyObjectProperty<MediaException> errorProperty
    A property set to a MediaException value when an error occurs. If `error` is non-`null`, then the media could not be loaded and is not usable. If `onError` is non-`null`, it will be invoked when the `error` property is set.
    See Also:
      - `getError()`
      - `errorProperty()`

  - ### onError

    public ObjectProperty<Runnable> onErrorProperty
    Event handler called when an error occurs. This will happen if a malformed or invalid URL is passed to the constructor or there is a problem accessing the URL.
    See Also:
      - `getOnError()`
      - `setOnError(Runnable)`
      - `onErrorProperty()`

  - ### width

    public ReadOnlyIntegerProperty widthProperty
    The width in pixels of the source media. This may be zero if the media has no width, e.g., when playing audio, or if the width is currently unknown which may occur with streaming media.
    See Also:
      - `getWidth()`
      - `widthProperty()`

  - ### height

    public ReadOnlyIntegerProperty heightProperty
    The height in pixels of the source media. This may be zero if the media has no height, e.g., when playing audio, or if the height is currently unknown which may occur with streaming media.
    See Also:
      - `getHeight()`
      - `heightProperty()`

  - ### duration

    public ReadOnlyObjectProperty<Duration> durationProperty
    The duration in seconds of the source media. If the media duration is unknown then this property value will be `Duration.UNKNOWN`.
    See Also:
      - `getDuration()`
      - `durationProperty()`

- ## Constructor Details

  - ### Media

    public Media(String source)
    Constructs a `Media` instance. This is the only way to specify the media source. The source must represent a valid `URI` and is immutable. Only HTTP, HTTPS, FILE, and JAR `URL`s are supported. If the provided URL is invalid then an exception will be thrown. If an asynchronous error occurs, the `error` property will be set. Listen to this property to be notified of any such errors.

    If the source uses a non-blocking protocol such as FILE, then any problems which can be detected immediately will cause a `MediaException` to be thrown. Such problems include the media being inaccessible or in an unsupported format. If however a potentially blocking protocol such as HTTP is used, then the connection will be initialized asynchronously so that these sorts of errors will be signaled by setting the `error` property.

    Constraints:

    - The supplied URI must conform to RFC-2396 as required by java.net.URI.
    - Only HTTP, HTTPS, FILE, and JAR URIs are supported.

    See java.net.URI for more information about URI formatting in general. JAR URL syntax is specified in java.net.JarURLConnection.

    Parameters:
      `source` - The URI of the source media.
    Throws:
      `NullPointerException` - if the URI string is `null`.
      `IllegalArgumentException` - if the URI string does not conform to RFC-2396 or, if appropriate, the Jar URL specification, or is in a non-compliant form which cannot be modified to a compliant form.
      `IllegalArgumentException` - if the URI string has a `null` scheme.
      `UnsupportedOperationException` - if the protocol specified for the source is not supported.
      `MediaException` - if the media source cannot be connected (type `MediaException.Type.MEDIA_INACCESSIBLE`) or is not supported (type `MediaException.Type.MEDIA_UNSUPPORTED`).

- ## Method Details

  - ### getError

    public final MediaException getError()
    Return any error encountered in the media.
    Returns:
      a `MediaException` or `null` if there is no error.

  - ### errorProperty

    public ReadOnlyObjectProperty<MediaException> errorProperty()
    A property set to a MediaException value when an error occurs. If `error` is non-`null`, then the media could not be loaded and is not usable. If `onError` is non-`null`, it will be invoked when the `error` property is set.
    Returns:
      the `error` property
    See Also:
      - `getError()`

  - ### setOnError

    public final void setOnError(Runnable value)
    Set the event handler to be called when an error occurs.
    Parameters:
      `value` - the error event handler.

  - ### getOnError

    public final Runnable getOnError()
    Retrieve the error handler to be called if an error occurs.
    Returns:
      the error handler or `null` if none is defined.

  - ### onErrorProperty

    public ObjectProperty<Runnable> onErrorProperty()
    Event handler called when an error occurs. This will happen if a malformed or invalid URL is passed to the constructor or there is a problem accessing the URL.
    Returns:
      the `onError` property
    See Also:
      - `getOnError()`
      - `setOnError(Runnable)`

  - ### getMetadata

    public final ObservableMap<String,Object> getMetadata()
    Retrieve the metadata contained in this media source. If there are no metadata, the returned `ObservableMap` will be empty.
    Returns:
      the metadata contained in this media source.

  - ### getWidth

    public final int getWidth()
    Retrieve the width in pixels of the media.
    Returns:
      the media width or zero if the width is undefined or unknown.

  - ### widthProperty

    public ReadOnlyIntegerProperty widthProperty()
    The width in pixels of the source media. This may be zero if the media has no width, e.g., when playing audio, or if the width is currently unknown which may occur with streaming media.
    Returns:
      the `width` property
    See Also:
      - `getWidth()`

  - ### getHeight

    public final int getHeight()
    Retrieve the height in pixels of the media.
    Returns:
      the media height or zero if the height is undefined or unknown.

  - ### heightProperty

    public ReadOnlyIntegerProperty heightProperty()
    The height in pixels of the source media. This may be zero if the media has no height, e.g., when playing audio, or if the height is currently unknown which may occur with streaming media.
    Returns:
      the `height` property
    See Also:
      - `getHeight()`

  - ### getDuration

    public final Duration getDuration()
    Retrieve the duration in seconds of the media.
    Returns:
      the duration of the media, `Duration.UNKNOWN` if unknown or `Duration.INDEFINITE` for live streams

  - ### durationProperty

    public ReadOnlyObjectProperty<Duration> durationProperty()
    The duration in seconds of the source media. If the media duration is unknown then this property value will be `Duration.UNKNOWN`.
    Returns:
      the `duration` property
    See Also:
      - `getDuration()`

  - ### getTracks

    public final ObservableList<Track> getTracks()
    Retrieve the tracks contained in this media source. If there are no tracks, the returned `ObservableList` will be empty.
    Returns:
      the tracks contained in this media source.

  - ### getMarkers

    public final ObservableMap<String,Duration> getMarkers()
    Retrieve the markers defined on this `Media` instance. If there are no markers the returned `ObservableMap` will be empty. Programmatic markers may be added by inserting entries in the returned `Map`.
    Returns:
      the markers defined on this media source.

  - ### getSource

    public String getSource()
    Retrieve the source URI of the media.
    Returns:
      the media source URI as a `String`.