public final class Media extends Object
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
-
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.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 thisMedia
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()
The height in pixels of the source media.ObjectProperty<Runnable>
onErrorProperty()
Event handler called when an error occurs.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.
-
Property Details
-
error
A property set to a MediaException value when an error occurs. Iferror
is non-null
, then the media could not be loaded and is not usable. IfonError
is non-null
, it will be invoked when theerror
property is set.- See Also:
getError()
-
onError
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)
-
width
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()
-
height
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()
-
duration
The duration in seconds of the source media. If the media duration is unknown then this property value will beDuration.UNKNOWN
.- See Also:
getDuration()
-
-
Constructor Details
-
Media
Constructs aMedia
instance. This is the only way to specify the media source. The source must represent a validURI
and is immutable. Only HTTP, HTTPS, FILE, and JARURL
s are supported. If the provided URL is invalid then an exception will be thrown. If an asynchronous error occurs, theerror
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 theerror
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 isnull
.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 anull
scheme.UnsupportedOperationException
- if the protocol specified for the source is not supported.MediaException
- if the media source cannot be connected (typeMediaException.Type.MEDIA_INACCESSIBLE
) or is not supported (typeMediaException.Type.MEDIA_UNSUPPORTED
).
-
-
Method Details
-
getError
Return any error encountered in the media.- Returns:
- a
MediaException
ornull
if there is no error.
-
errorProperty
A property set to a MediaException value when an error occurs. Iferror
is non-null
, then the media could not be loaded and is not usable. IfonError
is non-null
, it will be invoked when theerror
property is set.- See Also:
getError()
-
setOnError
Set the event handler to be called when an error occurs.- Parameters:
value
- the error event handler.
-
getOnError
Retrieve the error handler to be called if an error occurs.- Returns:
- the error handler or
null
if none is defined.
-
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)
-
getMetadata
Retrieve the metadata contained in this media source. If there are no metadata, the returnedObservableMap
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
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()
-
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
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()
-
getDuration
Retrieve the duration in seconds of the media.- Returns:
- the duration of the media,
Duration.UNKNOWN
if unknown orDuration.INDEFINITE
for live streams
-
durationProperty
The duration in seconds of the source media. If the media duration is unknown then this property value will beDuration.UNKNOWN
.- See Also:
getDuration()
-
getTracks
Retrieve the tracks contained in this media source. If there are no tracks, the returnedObservableList
will be empty.- Returns:
- the tracks contained in this media source.
-
getMarkers
Retrieve the markers defined on thisMedia
instance. If there are no markers the returnedObservableMap
will be empty. Programmatic markers may be added by inserting entries in the returnedMap
.- Returns:
- the markers defined on this media source.
-
getSource
Retrieve the source URI of the media.- Returns:
- the media source URI as a
String
.
-