1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
5 <title>javafx.scene.media</title>
6 </head>
7 <body>
8 <p>Provides the set of classes for integrating audio and video into Java FX
9 Applications. The primary use for this package is media playback. There are
10 three principal classes in the media package:
11 {@link javafx.scene.media.Media Media},
12 {@link javafx.scene.media.MediaPlayer MediaPlayer}, and
13 {@link javafx.scene.media.MediaView MediaView}.
14 </p>
15 <h2>Contents</h2>
16 <p>
17 <ol>
18 <li><a href="#SupportedMediaTypes">Supported Media Types</a></li>
19 <li><a href="#SupportedProtocols">Supported Protocols</a></li>
20 <li><a href="#SupportedMetadataTags">Supported Metadata Tags</a></li>
21 <li><a href="#PlayingMediaInJavaFX">Playing Media in Java FX</a></li>
22 </ol>
23 </p>
24
25 <a name="SupportedMediaTypes"/>
26 <h3>Supported Media Types</h3>
27
28 Java FX supports a number of different media types. A media type is considered to
29 be the combination of a container format and one or more encodings. In some
30 cases the container format might simply be an elementary stream containing the
31 encoded data.
32
33 <h4>Supported Encoding Types</h4>
34
35 An encoding type specifies how sampled audio or video data are stored. Usually
36 the encoding type implies a particular compression algorithm. The following
37 table indicates the encoding types supported by Java FX Media.
38
39 <p>
40 <table border="1" summary="encoding types">
41 <tr><th>Encoding</th><th>Type</th><th>Description</th></tr>
42 <tr><td>AAC</td><td>Audio</td><td>Advanced Audio Coding audio compression</td></tr>
43 <tr><td>MP3</td><td>Audio</td>
44 <td>Raw MPEG-1, 2, and 2.5 audio; layers I, II, and III; all supported
45 combinations of sampling frequencies and bit rates. Note: File must contain at least 3 MP3 frames.</td>
46 </tr>
47 <tr><td>PCM</td><td>Audio</td><td>Uncompressed, raw audio samples</td></tr>
48 <tr><td>H.264/AVC</td><td>Video</td><td>H.264/MPEG-4 Part 10 / AVC (Advanced Video Coding)
49 video compression</td></tr>
50 <tr><td>VP6</td><td>Video</td><td>On2 VP6 video compression</td></tr>
51 </table>
52 </p>
53
54 <h4>Supported Container Types</h4>
55
56 A container type specifies the file format used to store the encoded audio,
57 video, and other media data. Each container type is associated with one or more
58 MIME types, file extensions, and file signatures (the initial bytes in the file).
59 The following table indicates the combination of container and encoding types
60 supported by Java FX Media.
61
62 <p>
63 <table border="1" summary="container and encoding types combination">
64 <tr><th>Container</th><th>Description</th><th>Video Encoding</th>
65 <th>Audio Encoding</th><th>MIME Type</th><th>File Extension</th></tr>
66 <tr><td>AIFF</td><td>Audio Interchange File Format</td><td>N/A</td>
67 <td>PCM</td><td>audio/x-aiff</td><td>.aif, .aiff</td></tr>
68 <tr><td>FXM, FLV</td><td>FX Media, Flash Video</td><td>VP6</td>
69 <td>MP3</td><td>video/x-javafx, video/x-flv</td><td>.fxm, .flv</td></tr>
70 <tr><td>HLS (*)</td><td>MP2T HTTP Live Streaming (audiovisual)</td><td>H.264/AVC</td>
71 <td>AAC</td><td>application/vnd.apple.mpegurl, audio/mpegurl</td><td>.m3u8</td></tr>
72 <tr><td>HLS (*)</td><td>MP3 HTTP Live Streaming (audio-only)</td><td>N/A</td>
73 <td>MP3</td><td>application/vnd.apple.mpegurl, audio/mpegurl</td><td>.m3u8</td></tr>
74 <tr><td>MP3</td><td>MPEG-1, 2, 2.5 raw audio stream possibly with ID3 metadata v2.3 or v2.4</td>
75 <td>N/A</td><td>MP3</td><td>audio/mpeg</td><td>.mp3</td></tr>
76 <tr><td>MP4</td><td>MPEG-4 Part 14</td><td>H.264/AVC</td>
77 <td>AAC</td><td>video/mp4, audio/x-m4a, video/x-m4v</td><td>.mp4, .m4a, .m4v</td></tr>
78 <tr><td>WAV</td><td>Waveform Audio Format</td><td>N/A</td>
79 <td>PCM</td><td>audio/x-wav</td><td>.wav</td></tr>
80 </table>
81
82 <br/>(*) HLS is a protocol rather than a container type but is included here to
83 aggregate similar attributes.
84 </p>
85
86 <a name="SupportedProtocols"/>
87 <h3>Supported Protocols</h3>
88
89 <p>
90 <table border="1" summary="supported protocols">
91 <tr><th>Protocol</th><th>Description</th><th>Reference</th></tr>
92 <tr>
93 <td>FILE</td>
94 <td>Protocol for URI representation of local files</td>
95 <td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</a></td>
96 </tr>
97 <tr>
98 <td>HTTP</td>
99 <td>Hypertext transfer protocol for representation of remote files</td>
100 <td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</a></td>
101 </tr>
102 <tr>
103 <td>JAR</td>
104 <td>Representation of media entries in files accessible via the FILE or HTTP protocols</td>
105 <td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/JarURLConnection.html">java.net.JarURLConnection</a></td>
106 </tr>
107 <tr>
108 <td>HTTP Live Streaming (HLS)</td>
109 <td>Playlist-based media streaming via HTTP</td>
110 <td><a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming">Internet-Draft: HTTP Live Streaming</a></td>
111 </tr>
112 </table>
113 <br/>
114 </p>
115 <p>
116 <h4>MPEG-4 Playback via HTTP</h4>
117 It is recommended that MPEG-4 media to be played over HTTP be formatted such that the
118 headers required to decode the stream appear at the beginning of the file. Otherwise,
119 playback might stall until the entire file is downloaded.
120 </p>
121 <p>
122 <h4>HTTP Live Streaming (HLS)</h4>
123 HLS playback handles sources with these characteristics:
124 <ul>
125 <li>On-demand and live playlists.</li>
126 <li>Elementary MP3 audio streams (audio/mpegurl) and multiplexed MP2T streams
127 (application/vnd.apple.mpegurl) with one AAC audio and one H.264/AVC video track.</li>
128 <li>Playlists with integer or float duration.</li>
129 </ul>
130 Sources which do not conform to this basic profile are not guaranteed to be handled.
131 The playlist contains information about the streams comprising the source and is
132 downloaded at the start of playback. Switching between alternate streams, bit rates,
133 and video resolutions is handled automatically as a function of network conditions.
134 </p>
135
136 <a name="SupportedMetadataTags"/>
137 <h3>Supported Metadata Tags</h3>
138
139 A media container may also include certain metadata which describe the media in
140 the file. The Java FX Media API makes the metadata available via the
141 {@link javafx.scene.media.Media#getMetadata()} method. The keys in this mapping
142 are referred to as <i>tags</i> with the tags supported by Java FX Media listed in
143 the following table. Note that which tags are available for a given media source
144 depend on the metadata actually stored in that source, i.e., not all tags are
145 guaranteed to be available.
146
147 <p>
148 <table border="1" summary="metadata keys and tags">
149 <tr><th> Container </th><th> Tag (type String) </th><th> Type </th><th> Description </th></tr>
150 <tr><td> FXM, FLV </td><td> audio codec </td><td> java.lang.String </td><td>The encoder used for the audio track.</td></tr>
151 <tr><td> FXM, FLV </td><td> duration </td><td> javafx.util.Duration </td><td>The duration of the media.</td></tr>
152 <tr><td> FXM, FLV </td><td> video codec </td><td> java.lang.String </td><td>The encoder used for the video track.</td></tr>
153 <tr><td> FXM, FLV </td><td> width </td><td> java.lang.Integer </td><td>The width in pixels of the video track.</td></tr>
154 <tr><td> FXM, FLV </td><td> height </td><td> java.lang.Integer </td><td>The height in pixels of the video track.</td></tr>
155 <tr><td> FXM, FLV </td><td> framerate </td><td> java.lang.Double </td><td>The video frame rate in frames per second.</td></tr>
156 <tr><td> FXM, FLV </td><td> creationdate </td><td> java.lang.String </td><td>The date when the video was created.</td></tr>
157 <tr><td> FXM, FLV, MP3 </td><td> raw metadata </td><td> Map<String,ByteBuffer> </td><td>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.</td></tr>
158 <tr><td> MP3 </td><td> album artist </td><td> java.lang.String </td><td>The artist for the overall album, possibly "Various Artists" for compilations.</td></tr>
159 <tr><td> MP3 </td><td> album </td><td> java.lang.String </td><td>The name of the album.</td></tr>
160 <tr><td> MP3 </td><td> artist </td><td> java.lang.String </td><td>The artist of the track.</td></tr>
161 <tr><td> MP3 </td><td> comment-N </td><td> java.lang.String </td><td>A comment where N is a 0-relative index. Comment format: ContentDescription[lng]=Comment </td></tr>
162 <tr><td> MP3 </td><td> composer </td><td> java.lang.String </td><td>The composer of the track.</td></tr>
163 <tr><td> MP3 </td><td> year </td><td> java.lang.Integer </td><td>The year the track was recorded.</td></tr>
164 <tr><td> MP3 </td><td> disc count </td><td> java.lang.Integer </td><td>The number of discs in the album.</td></tr>
165 <tr><td> MP3 </td><td> disc number </td><td> java.lang.Integer </td><td>The 1-relative index of the disc on which this track appears.</td></tr>
166 <tr><td> MP3 </td><td> duration </td><td> javafx.util.Duration </td><td>The duration of the track.</td></tr>
167 <tr><td> MP3 </td><td> genre </td><td> java.lang.String </td><td>The genre of the track, for example, "Classical," "Darkwave," or "Jazz."</td></tr>
168 <tr><td> MP3 </td><td> image </td><td> javafx.scene.image.Image </td><td>The album cover.</td></tr>
169 <tr><td> MP3 </td><td> title </td><td> java.lang.String </td><td>The name of the track.</td></tr>
170 <tr><td> MP3 </td><td> track count </td><td> java.lang.Integer </td><td>The number of tracks on the album.</td></tr>
171 <tr><td> MP3 </td><td> track number </td><td> java.lang.Integer </td><td>The 1-relative index of this track on the disc.</td></tr>
172 </table>
173 </p>
174
175 <p>
176 <a name="PlayingMediaInJavaFX"/>
177 <h3>Playing Media in Java FX</h3>
178 <h4>Basic Playback</h4>
179 <p>
180 The basic steps required to play media in Java FX are:
181 <ol>
182 <li>Create a {@link javafx.scene.media.Media} object for the desired media source.</li>
183 <li>Create a {@link javafx.scene.media.MediaPlayer} object from the <code>Media</code> object.</li>
184 <li>Create a {@link javafx.scene.media.MediaView} object.</li>
185 <li>Add the <code>MediaPlayer</code> to the <code>MediaView</code>.</li>
186 <li>Add the <code>MediaView</code> to the scene graph.</li>
187 <li>Invoke {@link javafx.scene.media.MediaPlayer#play()}.</li>
188 </ol>
189 The foregoing steps are illustrated by the sample code in the <code>MediaView</code>
190 class documentation. Some things which should be noted are:
191 <ul>
192 <li>One <code>Media</code> object may be shared among multiple <code>MediaPlayer</code>s.
193 <li>One <code>MediaPlayer</code> may be shared amoung multiple <code>MediaView</code>s.
194 <li>Media may be played directly by a <code>MediaPlayer</code>
195 without creating a <code>MediaView</code> although a view is required for display.</li>
196 <li>Instead of <code>MediaPlayer.play()</code>,
197 {@link javafx.scene.media.MediaPlayer#setAutoPlay MediaPlayer.setAutoPlay(true)}
198 may be used to request that playing start as soon as possible.</li>
199 <li><code>MediaPlayer</code> has several operational states defined by
200 {@link javafx.scene.media.MediaPlayer.Status}.
201 <li>Audio-only media may instead be played using {@link javafx.scene.media.AudioClip}
202 (recommended for low latency playback of short clips).</li>
203 </ul>
204 </p>
205 <h4>Error Handling</h4>
206 <p>
207 Errors using Java FX Media may be either synchronous or asynchronous. In general
208 synchronous errors will manifest themselves as a Java <code>Exception</code> and
209 asynchronous errors will cause a Java FX property to be set. In the latter case
210 either the <code>error</code> property may be observed directly, an
211 <code>onError</code> callback registered, or possibly both.</p>
212
213 <p>The main sources of synchronous errors are
214 {@link javafx.scene.media.Media#Media Media()} and
215 {@link javafx.scene.media.MediaPlayer#MediaPlayer MediaPlayer()}.
216 The asynchronous error properties are
217 {@link javafx.scene.media.Media#errorProperty Media.error} and
218 {@link javafx.scene.media.MediaPlayer#errorProperty MediaPlayer.error}, and the
219 asynchronous error callbacks
220 {@link javafx.scene.media.Media#onErrorProperty Media.onError},
221 {@link javafx.scene.media.MediaPlayer#onErrorProperty MediaPlayer.onError}, and
222 {@link javafx.scene.media.MediaView#onErrorProperty MediaView.onError}.</p>
223
224 <p>
225 Some errors might be duplicated. For example, a <code>MediaPlayer</code> will
226 propagate an error that it encounters to its associated <code>Media</code>, and
227 a <code>MediaPlayer</code> to all its associated <code>MediaView</code>s. As a
228 consequence, it is possible to receive multiple notifications of the occurrence
229 of a given error, depending on which properties are monitored.
230 </p>
231
232 <p>The following code snippet illustrates error handling with media:
233 <code><pre>
234 String source;
235 Media media;
236 MediaPlayer mediaPlayer;
237 MediaView mediaView;
238 try {
239 media = new Media(source);
240 if (media.getError() == null) {
241 media.setOnError(new Runnable() {
242 public void run() {
243 // Handle asynchronous error in Media object.
244 }
245 });
246 try {
247 mediaPlayer = new MediaPlayer(media);
248 if (mediaPlayer.getError() == null) {
249 mediaPlayer.setOnError(new Runnable() {
250 public void run() {
251 // Handle asynchronous error in MediaPlayer object.
252 }
253 });
254 mediaView = new MediaView(mediaPlayer);
255 mediaView.setOnError(new EventHandler<MediaErrorEvent>() {
256 public void handle(MediaErrorEvent t) {
257 // Handle asynchronous error in MediaView.
258 }
259 });
260 } else {
261 // Handle synchronous error creating MediaPlayer.
262 }
263 } catch (Exception mediaPlayerException) {
264 // Handle exception in MediaPlayer constructor.
265 }
266 } else {
267 // Handle synchronous error creating Media.
268 }
269 } catch (Exception mediaException) {
270 // Handle exception in Media constructor.
271 }
272 </pre></code>
273 </p>
274 </p>
275
276 </body>
277 </html>