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 <td>HTTPS</td>
103 <td>Hypertext transfer protocol secure for representation of remote files</td>
104 <td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html">java.net.URI</a></td>
105 </tr>
106 <tr>
107 <tr>
108 <td>JAR</td>
109 <td>Representation of media entries in files accessible via the FILE, HTTP or HTTPS protocols</td>
110 <td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/JarURLConnection.html">java.net.JarURLConnection</a></td>
111 </tr>
112 <tr>
113 <td>HTTP Live Streaming (HLS)</td>
114 <td>Playlist-based media streaming via HTTP or HTTPS</td>
115 <td><a href="http://tools.ietf.org/html/draft-pantos-http-live-streaming">Internet-Draft: HTTP Live Streaming</a></td>
116 </tr>
117 </table>
118 <br/>
119 </p>
120 <p>
121 <h4>MPEG-4 Playback via HTTP</h4>
122 It is recommended that MPEG-4 media to be played over HTTP or HTTPS be formatted such that the
123 headers required to decode the stream appear at the beginning of the file. Otherwise,
124 playback might stall until the entire file is downloaded.
125 </p>
126 <p>
127 <h4>HTTP Live Streaming (HLS)</h4>
128 HLS playback handles sources with these characteristics:
129 <ul>
130 <li>On-demand and live playlists.</li>
131 <li>Elementary MP3 audio streams (audio/mpegurl) and multiplexed MP2T streams
132 (application/vnd.apple.mpegurl) with one AAC audio and one H.264/AVC video track.</li>
133 <li>Playlists with integer or float duration.</li>
134 </ul>
135 Sources which do not conform to this basic profile are not guaranteed to be handled.
136 The playlist contains information about the streams comprising the source and is
137 downloaded at the start of playback. Switching between alternate streams, bit rates,
138 and video resolutions is handled automatically as a function of network conditions.
139 </p>
140
141 <a name="SupportedMetadataTags"/>
142 <h3>Supported Metadata Tags</h3>
143
144 A media container may also include certain metadata which describe the media in
145 the file. The Java FX Media API makes the metadata available via the
146 {@link javafx.scene.media.Media#getMetadata()} method. The keys in this mapping
147 are referred to as <i>tags</i> with the tags supported by Java FX Media listed in
148 the following table. Note that which tags are available for a given media source
149 depend on the metadata actually stored in that source, i.e., not all tags are
150 guaranteed to be available.
151
152 <p>
153 <table border="1" summary="metadata keys and tags">
154 <tr><th> Container </th><th> Tag (type String) </th><th> Type </th><th> Description </th></tr>
155 <tr><td> FXM, FLV </td><td> audio codec </td><td> java.lang.String </td><td>The encoder used for the audio track.</td></tr>
156 <tr><td> FXM, FLV </td><td> duration </td><td> javafx.util.Duration </td><td>The duration of the media.</td></tr>
157 <tr><td> FXM, FLV </td><td> video codec </td><td> java.lang.String </td><td>The encoder used for the video track.</td></tr>
158 <tr><td> FXM, FLV </td><td> width </td><td> java.lang.Integer </td><td>The width in pixels of the video track.</td></tr>
159 <tr><td> FXM, FLV </td><td> height </td><td> java.lang.Integer </td><td>The height in pixels of the video track.</td></tr>
160 <tr><td> FXM, FLV </td><td> framerate </td><td> java.lang.Double </td><td>The video frame rate in frames per second.</td></tr>
161 <tr><td> FXM, FLV </td><td> creationdate </td><td> java.lang.String </td><td>The date when the video was created.</td></tr>
162 <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>
163 <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>
164 <tr><td> MP3 </td><td> album </td><td> java.lang.String </td><td>The name of the album.</td></tr>
165 <tr><td> MP3 </td><td> artist </td><td> java.lang.String </td><td>The artist of the track.</td></tr>
166 <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>
167 <tr><td> MP3 </td><td> composer </td><td> java.lang.String </td><td>The composer of the track.</td></tr>
168 <tr><td> MP3 </td><td> year </td><td> java.lang.Integer </td><td>The year the track was recorded.</td></tr>
169 <tr><td> MP3 </td><td> disc count </td><td> java.lang.Integer </td><td>The number of discs in the album.</td></tr>
170 <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>
171 <tr><td> MP3 </td><td> duration </td><td> javafx.util.Duration </td><td>The duration of the track.</td></tr>
172 <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>
173 <tr><td> MP3 </td><td> image </td><td> javafx.scene.image.Image </td><td>The album cover.</td></tr>
174 <tr><td> MP3 </td><td> title </td><td> java.lang.String </td><td>The name of the track.</td></tr>
175 <tr><td> MP3 </td><td> track count </td><td> java.lang.Integer </td><td>The number of tracks on the album.</td></tr>
176 <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>
177 </table>
178 </p>
179
180 <p>
181 <a name="PlayingMediaInJavaFX"/>
182 <h3>Playing Media in Java FX</h3>
183 <h4>Basic Playback</h4>
184 <p>
185 The basic steps required to play media in Java FX are:
186 <ol>
187 <li>Create a {@link javafx.scene.media.Media} object for the desired media source.</li>
188 <li>Create a {@link javafx.scene.media.MediaPlayer} object from the <code>Media</code> object.</li>
189 <li>Create a {@link javafx.scene.media.MediaView} object.</li>
190 <li>Add the <code>MediaPlayer</code> to the <code>MediaView</code>.</li>
191 <li>Add the <code>MediaView</code> to the scene graph.</li>
192 <li>Invoke {@link javafx.scene.media.MediaPlayer#play()}.</li>
193 </ol>
194 The foregoing steps are illustrated by the sample code in the <code>MediaView</code>
195 class documentation. Some things which should be noted are:
196 <ul>
197 <li>One <code>Media</code> object may be shared among multiple <code>MediaPlayer</code>s.
198 <li>One <code>MediaPlayer</code> may be shared amoung multiple <code>MediaView</code>s.
199 <li>Media may be played directly by a <code>MediaPlayer</code>
200 without creating a <code>MediaView</code> although a view is required for display.</li>
201 <li>Instead of <code>MediaPlayer.play()</code>,
202 {@link javafx.scene.media.MediaPlayer#setAutoPlay MediaPlayer.setAutoPlay(true)}
203 may be used to request that playing start as soon as possible.</li>
204 <li><code>MediaPlayer</code> has several operational states defined by
205 {@link javafx.scene.media.MediaPlayer.Status}.
206 <li>Audio-only media may instead be played using {@link javafx.scene.media.AudioClip}
207 (recommended for low latency playback of short clips).</li>
208 </ul>
209 </p>
210 <h4>Error Handling</h4>
211 <p>
212 Errors using Java FX Media may be either synchronous or asynchronous. In general
213 synchronous errors will manifest themselves as a Java <code>Exception</code> and
214 asynchronous errors will cause a Java FX property to be set. In the latter case
215 either the <code>error</code> property may be observed directly, an
216 <code>onError</code> callback registered, or possibly both.</p>
217
218 <p>The main sources of synchronous errors are
219 {@link javafx.scene.media.Media#Media Media()} and
220 {@link javafx.scene.media.MediaPlayer#MediaPlayer MediaPlayer()}.
221 The asynchronous error properties are
222 {@link javafx.scene.media.Media#errorProperty Media.error} and
223 {@link javafx.scene.media.MediaPlayer#errorProperty MediaPlayer.error}, and the
224 asynchronous error callbacks
225 {@link javafx.scene.media.Media#onErrorProperty Media.onError},
226 {@link javafx.scene.media.MediaPlayer#onErrorProperty MediaPlayer.onError}, and
227 {@link javafx.scene.media.MediaView#onErrorProperty MediaView.onError}.</p>
228
229 <p>
230 Some errors might be duplicated. For example, a <code>MediaPlayer</code> will
231 propagate an error that it encounters to its associated <code>Media</code>, and
232 a <code>MediaPlayer</code> to all its associated <code>MediaView</code>s. As a
233 consequence, it is possible to receive multiple notifications of the occurrence
234 of a given error, depending on which properties are monitored.
235 </p>
236
237 <p>The following code snippet illustrates error handling with media:
238 <code><pre>
239 String source;
240 Media media;
241 MediaPlayer mediaPlayer;
242 MediaView mediaView;
243 try {
244 media = new Media(source);
245 if (media.getError() == null) {
246 media.setOnError(new Runnable() {
247 public void run() {
248 // Handle asynchronous error in Media object.
249 }
250 });
251 try {
252 mediaPlayer = new MediaPlayer(media);
253 if (mediaPlayer.getError() == null) {
254 mediaPlayer.setOnError(new Runnable() {
255 public void run() {
256 // Handle asynchronous error in MediaPlayer object.
257 }
258 });
259 mediaView = new MediaView(mediaPlayer);
260 mediaView.setOnError(new EventHandler<MediaErrorEvent>() {
261 public void handle(MediaErrorEvent t) {
262 // Handle asynchronous error in MediaView.
263 }
264 });
265 } else {
266 // Handle synchronous error creating MediaPlayer.
267 }
268 } catch (Exception mediaPlayerException) {
269 // Handle exception in MediaPlayer constructor.
270 }
271 } else {
272 // Handle synchronous error creating Media.
273 }
274 } catch (Exception mediaException) {
275 // Handle exception in Media constructor.
276 }
277 </pre></code>
278 </p>
279 </p>
280
281 </body>
282 </html>