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 Tracks 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

Constructor Summary

Constructors

Constructor and Description
Media(String source) Constructs a Media instance.

Method Summary

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

Methods inherited from class java.lang.Object

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

Constructor Detail

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 URLs 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 Detail

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()

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()

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()

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()

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()

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.