Provides the set of classes for integrating audio and video into Java FX Applications. The primary use for this package is media playback. There are three principal classes in the media package: {@link javafx.scene.media.Media Media}, {@link javafx.scene.media.MediaPlayer MediaPlayer}, and {@link javafx.scene.media.MediaView MediaView}.
An encoding type specifies how sampled audio or video data are stored. Usually the encoding type implies a particular compression algorithm. The following table indicates the encoding types supported by Java FX Media.
Encoding | Type | Description |
---|---|---|
AAC | Audio | Advanced Audio Coding audio compression |
MP3 | Audio | Raw MPEG-1, 2, and 2.5 audio; layers I, II, and III; all supported combinations of sampling frequencies and bit rates. Note: File must contain at least 3 MP3 frames. |
PCM | Audio | Uncompressed, raw audio samples |
H.264/AVC | Video | H.264/MPEG-4 Part 10 / AVC (Advanced Video Coding) video compression |
A container type specifies the file format used to store the encoded audio, video, and other media data. Each container type is associated with one or more MIME types, file extensions, and file signatures (the initial bytes in the file). The following table indicates the combination of container and encoding types supported by Java FX Media.
Container | Description | Video Encoding | Audio Encoding | MIME Type | File Extension |
---|---|---|---|---|---|
AIFF | Audio Interchange File Format | N/A | PCM | audio/x-aiff | .aif, .aiff |
HLS (*) | MP2T HTTP Live Streaming (audiovisual) | H.264/AVC | AAC | application/vnd.apple.mpegurl, audio/mpegurl | .m3u8 |
HLS (*) | MP3 HTTP Live Streaming (audio-only) | N/A | MP3 | application/vnd.apple.mpegurl, audio/mpegurl | .m3u8 |
MP3 | MPEG-1, 2, 2.5 raw audio stream possibly with ID3 metadata v2.3 or v2.4 | N/A | MP3 | audio/mpeg | .mp3 |
MP4 | MPEG-4 Part 14 | H.264/AVC | AAC | video/mp4, audio/x-m4a, video/x-m4v | .mp4, .m4a, .m4v |
WAV | Waveform Audio Format | N/A | PCM | audio/x-wav | .wav |
Protocol | Description | Reference |
---|---|---|
FILE | Protocol for URI representation of local files | java.net.URI |
HTTP | Hypertext transfer protocol for representation of remote files | java.net.URI |
HTTPS | Hypertext transfer protocol secure for representation of remote files | java.net.URI |
JAR | Representation of media entries in files accessible via the FILE, HTTP or HTTPS protocols | java.net.JarURLConnection |
HTTP Live Streaming (HLS) | Playlist-based media streaming via HTTP or HTTPS | Internet-Draft: HTTP Live Streaming |
It is recommended that MPEG-4 media to be played over HTTP or HTTPS be formatted such that the headers required to decode the stream appear at the beginning of the file. Otherwise, playback might stall until the entire file is downloaded.
HLS playback handles sources with these characteristics:
Sources which do not conform to this basic profile are not guaranteed to be handled. The playlist contains information about the streams comprising the source and is downloaded at the start of playback. Switching between alternate streams, bit rates, and video resolutions is handled automatically as a function of network conditions.
Container | Tag (type String) | Type | Description |
---|---|---|---|
MP3 | raw metadata | Map<String,ByteBuffer> | The raw metadata according to the appropriate media specification. The key "ID3" maps to MP3 ID3v2 metadata. |
MP3 | album artist | java.lang.String | The artist for the overall album, possibly "Various Artists" for compilations. |
MP3 | album | java.lang.String | The name of the album. |
MP3 | artist | java.lang.String | The artist of the track. |
MP3 | comment-N | java.lang.String | A comment where N is a 0-relative index. Comment format: ContentDescription[lng]=Comment |
MP3 | composer | java.lang.String | The composer of the track. |
MP3 | year | java.lang.Integer | The year the track was recorded. |
MP3 | disc count | java.lang.Integer | The number of discs in the album. |
MP3 | disc number | java.lang.Integer | The 1-relative index of the disc on which this track appears. |
MP3 | duration | javafx.util.Duration | The duration of the track. |
MP3 | genre | java.lang.String | The genre of the track, for example, "Classical," "Darkwave," or "Jazz." |
MP3 | image | javafx.scene.image.Image | The album cover. |
MP3 | title | java.lang.String | The name of the track. |
MP3 | track count | java.lang.Integer | The number of tracks on the album. |
MP3 | track number | java.lang.Integer | The 1-relative index of this track on the disc. |
The basic steps required to play media in Java FX are:
Media
object.MediaPlayer
to the MediaView
.MediaView
to the scene graph.MediaView
class documentation. Some things which should be noted are:
Media
object may be shared among multiple MediaPlayer
s.
MediaPlayer
may be shared amoung multiple MediaView
s.
MediaPlayer
without creating a MediaView
although a view is required for display.MediaPlayer.play()
,
{@link javafx.scene.media.MediaPlayer#setAutoPlay MediaPlayer.setAutoPlay(true)}
may be used to request that playing start as soon as possible.MediaPlayer
has several operational states defined by
{@link javafx.scene.media.MediaPlayer.Status}.
Errors using Java FX Media may be either synchronous or asynchronous. In general
synchronous errors will manifest themselves as a Java Exception
and
asynchronous errors will cause a Java FX property to be set. In the latter case
either the error
property may be observed directly, an
onError
callback registered, or possibly both.
The main sources of synchronous errors are {@link javafx.scene.media.Media#Media Media()} and {@link javafx.scene.media.MediaPlayer#MediaPlayer MediaPlayer()}. The asynchronous error properties are {@link javafx.scene.media.Media#errorProperty Media.error} and {@link javafx.scene.media.MediaPlayer#errorProperty MediaPlayer.error}, and the asynchronous error callbacks {@link javafx.scene.media.Media#onErrorProperty Media.onError}, {@link javafx.scene.media.MediaPlayer#onErrorProperty MediaPlayer.onError}, and {@link javafx.scene.media.MediaView#onErrorProperty MediaView.onError}.
Some errors might be duplicated. For example, a MediaPlayer
will
propagate an error that it encounters to its associated Media
, and
a MediaPlayer
to all its associated MediaView
s. As a
consequence, it is possible to receive multiple notifications of the occurrence
of a given error, depending on which properties are monitored.
The following code snippet illustrates error handling with media:
{@code String source; Media media; MediaPlayer mediaPlayer; MediaView mediaView; try { media = new Media(source); if (media.getError() == null) { media.setOnError(new Runnable() { public void run() { // Handle asynchronous error in Media object. } }); try { mediaPlayer = new MediaPlayer(media); if (mediaPlayer.getError() == null) { mediaPlayer.setOnError(new Runnable() { public void run() { // Handle asynchronous error in MediaPlayer object. } }); mediaView = new MediaView(mediaPlayer); mediaView.setOnError(new EventHandler() { public void handle(MediaErrorEvent t) { // Handle asynchronous error in MediaView. } }); } else { // Handle synchronous error creating MediaPlayer. } } catch (Exception mediaPlayerException) { // Handle exception in MediaPlayer constructor. } } else { // Handle synchronous error creating Media. } } catch (Exception mediaException) { // Handle exception in Media constructor. } }