Package javafx.scene.media

Provides the set of classes for integrating audio and video into Java FX Applications.

See: Description

Interface Summary

Interface	Description
AudioSpectrumListener	Audio spectrum callback interface.

Class Summary

Class	Description
AudioClip	An AudioClip represents a segment of audio that can be played with minimal latency.
AudioClipBuilder	Builder class for javafx.scene.media.AudioClip
AudioEqualizer	The AudioEqualizer class provides audio equalization control for a media player.
AudioTrack	A Track that describes an audio track.
EqualizerBand	The EqualizerBand class provides control for each band in the AudioEqualizer.
Media	The Media class represents a media resource.
MediaBuilder	Builder class for javafx.scene.media.Media
MediaErrorEvent	An Event representing the occurrence of an error in handling media.
MediaMarkerEvent	An ActionEvent representing a media marker.
MediaPlayer	The MediaPlayer class provides the controls for playing media.
MediaPlayerBuilder	Builder class for javafx.scene.media.MediaPlayer
MediaView	A Node that provides a view of Media being played by a MediaPlayer.
MediaViewBuilder<B extends MediaViewBuilder<B>>	Builder class for javafx.scene.media.MediaView
Track	A class representing a track contained in a media resource.
VideoTrack	A Track that describes a video track.

Enum Summary

Enum	Description
MediaException.Type	Enumeration describing categories of errors.
MediaPlayer.Status	Enumeration describing the different status values of a MediaPlayer.

Exception Summary

Exception	Description
MediaException	A MediaException describes a runtime error condition in a Media, MediaPlayer or MediaView.

Package javafx.scene.media Description

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: Media, MediaPlayer, and MediaView.

Contents

1. Supported Media Types
2. Supported Protocols
3. Supported Metadata Tags
4. Playing Media in Java FX

Supported Media Types

Java FX supports a number of different media types. A media type is considered to be the combination of a container format and one or more encodings. In some cases the container format might simply be an elementary stream containing the encoded data.

Supported Encoding Types

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.
PCM	Audio	Uncompressed, raw audio samples
H.264/AVC	Video	H.264/MPEG-4 Part 10 / AVC (Advanced Video Coding) video compression
VP6	Video	On2 VP6 video compression

Supported Container Types

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
FXM, FLV	FX Media, Flash Video	VP6	MP3	video/x-javafx, video/x-flv	.fxm, .flv
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

(*) HLS is a protocol rather than a container type but is included here to aggregate similar attributes.

Supported Protocols

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
JAR	Representation of media entries in files accessible via the FILE or HTTP protocols	java.net.JarURLConnection
HTTP Live Streaming (HLS)	Playlist-based media streaming via HTTP	Internet-Draft: HTTP Live Streaming

MPEG-4 Playback via HTTP

It is recommended that MPEG-4 media to be played over HTTP 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.

HTTP Live Streaming (HLS)

HLS playback handles sources with these characteristics:

• On-demand and live playlists.
• Elementary MP3 audio streams (audio/mpegurl) and multiplexed MP2T streams (application/vnd.apple.mpegurl) with one AAC audio and one H.264/AVC video track.
• Playlists with integer or float duration.

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.

Supported Metadata Tags

A media container may also include certain metadata which describe the media in the file. The Java FX Media API makes the metadata available via the Media.getMetadata() method. The keys in this mapping are referred to as tags with the tags supported by Java FX Media listed in the following table. Note that which tags are available for a given media source depend on the metadata actually stored in that source, i.e., not all tags are guaranteed to be available.

Container	Tag (type String)	Type	Description
FXM, FLV	audio codec	java.lang.String	The encoder used for the audio track.
FXM, FLV	duration	javafx.util.Duration	The duration of the media.
FXM, FLV	video codec	java.lang.String	The encoder used for the video track.
FXM, FLV	width	java.lang.Integer	The width in pixels of the video track.
FXM, FLV	height	java.lang.Integer	The height in pixels of the video track.
FXM, FLV	framerate	java.lang.Double	The video frame rate in frames per second.
FXM, FLV	creationdate	java.lang.String	The date when the video was created.
FXM, FLV, MP3	raw metadata	Map<String,ByteBuffer>	The raw metadata according to the appropriate media specification. The key "ID3" maps to MP3 ID3v2 metadata and "FLV" to the FLV onMetadata marker content.
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.

Playing Media in Java FX

Basic Playback

The basic steps required to play media in Java FX are:

1. Create a Media object for the desired media source.
2. Create a MediaPlayer object from the Media object.
3. Create a MediaView object.
4. Add the MediaPlayer to the MediaView.
5. Add the MediaView to the scene graph.
6. Invoke MediaPlayer.play().

The foregoing steps are illustrated by the sample code in the MediaView class documentation. Some things which should be noted are:

• One Media object may be shared among multiple MediaPlayers.
• One MediaPlayer may be shared amoung multiple MediaViews.
• Media may be played directly by a MediaPlayer without creating a MediaView although a view is required for display.
• Instead of MediaPlayer.play(), MediaPlayer.setAutoPlay(true) may be used to request that playing start as soon as possible.
• MediaPlayer has several operational states defined by MediaPlayer.Status.
• Audio-only media may instead be played using AudioClip (recommended for low latency playback of short clips).

Error Handling

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 Media() and MediaPlayer(). The asynchronous error properties are Media.error and MediaPlayer.error, and the asynchronous error callbacks Media.onError, MediaPlayer.onError, and 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 MediaViews. 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:

    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.
    }