1 /*
2 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sound.sampled;
27
28 import java.io.File;
29 import java.io.IOException;
30 import java.io.InputStream;
31 import java.io.OutputStream;
32 import java.net.URL;
33 import java.util.ArrayList;
34 import java.util.HashSet;
35 import java.util.List;
36 import java.util.Properties;
37 import java.util.Set;
38 import java.util.Vector;
39
40 import javax.sound.sampled.spi.AudioFileReader;
41 import javax.sound.sampled.spi.AudioFileWriter;
42 import javax.sound.sampled.spi.FormatConversionProvider;
43 import javax.sound.sampled.spi.MixerProvider;
44
45 import com.sun.media.sound.JDK13Services;
46
47 /* $fb TODO:
48 * - consistent usage of (typed) collections
49 */
50
51
52 /**
53 * The {@code AudioSystem} class acts as the entry point to the sampled-audio
54 * system resources. This class lets you query and access the mixers that are
55 * installed on the system. {@code AudioSystem} includes a number of methods for
56 * converting audio data between different formats, and for translating between
57 * audio files and streams. It also provides a method for obtaining a
58 * {@link Line} directly from the {@code AudioSystem} without dealing explicitly
59 * with mixers.
60 * <p>
61 * Properties can be used to specify the default mixer for specific line types.
62 * Both system properties and a properties file are considered. The
63 * "sound.properties" properties file is read from an implementation-specific
64 * location (typically it is the {@code conf} directory in the Java installation
65 * directory). If a property exists both as a system property and in the
66 * properties file, the system property takes precedence. If none is specified,
67 * a suitable default is chosen among the available devices. The syntax of the
68 * properties file is specified in
69 * {@link Properties#load(InputStream) Properties.load}. The following table
70 * lists the available property keys and which methods consider them:
71 *
72 * <table border=0>
73 * <caption>Audio System Property Keys</caption>
74 * <tr>
75 * <th>Property Key</th>
76 * <th>Interface</th>
77 * <th>Affected Method(s)</th>
78 * </tr>
79 * <tr>
80 * <td>{@code javax.sound.sampled.Clip}</td>
81 * <td>{@link Clip}</td>
82 * <td>{@link #getLine}, {@link #getClip}</td>
83 * </tr>
84 * <tr>
85 * <td>{@code javax.sound.sampled.Port}</td>
86 * <td>{@link Port}</td>
87 * <td>{@link #getLine}</td>
88 * </tr>
89 * <tr>
90 * <td>{@code javax.sound.sampled.SourceDataLine}</td>
91 * <td>{@link SourceDataLine}</td>
92 * <td>{@link #getLine}, {@link #getSourceDataLine}</td>
93 * </tr>
94 * <tr>
95 * <td>{@code javax.sound.sampled.TargetDataLine}</td>
96 * <td>{@link TargetDataLine}</td>
97 * <td>{@link #getLine}, {@link #getTargetDataLine}</td>
98 * </tr>
99 * </table>
100 *
101 * The property value consists of the provider class name and the mixer name,
102 * separated by the hash mark ("#"). The provider class name is the
103 * fully-qualified name of a concrete {@link MixerProvider mixer provider}
104 * class. The mixer name is matched against the {@code String} returned by the
105 * {@code getName} method of {@code Mixer.Info}. Either the class name, or the
106 * mixer name may be omitted. If only the class name is specified, the trailing
107 * hash mark is optional.
108 * <p>
109 * If the provider class is specified, and it can be successfully retrieved from
110 * the installed providers, the list of {@code Mixer.Info} objects is retrieved
111 * from the provider. Otherwise, or when these mixers do not provide a
112 * subsequent match, the list is retrieved from {@link #getMixerInfo} to contain
113 * all available {@code Mixer.Info} objects.
114 * <p>
115 * If a mixer name is specified, the resulting list of {@code Mixer.Info}
116 * objects is searched: the first one with a matching name, and whose
117 * {@code Mixer} provides the respective line interface, will be returned. If no
118 * matching {@code Mixer.Info} object is found, or the mixer name is not
119 * specified, the first mixer from the resulting list, which provides the
120 * respective line interface, will be returned.
121 *
122 * For example, the property {@code javax.sound.sampled.Clip} with a value
123 * {@code "com.sun.media.sound.MixerProvider#SunClip"}
124 * will have the following consequences when {@code getLine} is called
125 * requesting a {@code Clip} instance: if the class
126 * {@code com.sun.media.sound.MixerProvider} exists in the list of installed
127 * mixer providers, the first {@code Clip} from the first mixer with name
128 * {@code "SunClip"} will be returned. If it cannot be found, the
129 * first {@code Clip} from the first mixer of the specified provider will be
130 * returned, regardless of name. If there is none, the first {@code Clip} from
131 * the first {@code Mixer} with name {@code "SunClip"} in the list of
132 * all mixers (as returned by {@code getMixerInfo}) will be returned, or, if not
133 * found, the first {@code Clip} of the first {@code Mixer} that can be found in
134 * the list of all mixers is returned. If that fails, too, an
135 * {@code IllegalArgumentException} is thrown.
136 *
137 * @author Kara Kytle
138 * @author Florian Bomers
139 * @author Matthias Pfisterer
140 * @author Kevin P. Smith
141 * @see AudioFormat
142 * @see AudioInputStream
143 * @see Mixer
144 * @see Line
145 * @see Line.Info
146 * @since 1.3
147 */
148 public class AudioSystem {
149
150 /**
151 * An integer that stands for an unknown numeric value. This value is
152 * appropriate only for signed quantities that do not normally take negative
153 * values. Examples include file sizes, frame sizes, buffer sizes, and
154 * sample rates. A number of Java Sound constructors accept a value of
155 * {@code NOT_SPECIFIED} for such parameters. Other methods may also accept
156 * or return this value, as documented.
157 */
158 public static final int NOT_SPECIFIED = -1;
159
160 /**
161 * Private no-args constructor for ensuring against instantiation.
162 */
163 private AudioSystem() {
164 }
165
166 /**
167 * Obtains an array of mixer info objects that represents the set of audio
168 * mixers that are currently installed on the system.
169 *
170 * @return an array of info objects for the currently installed mixers. If
171 * no mixers are available on the system, an array of length 0 is
172 * returned.
173 * @see #getMixer
174 */
175 public static Mixer.Info[] getMixerInfo() {
176
177 List<Mixer.Info> infos = getMixerInfoList();
178 Mixer.Info[] allInfos = infos.toArray(new Mixer.Info[infos.size()]);
179 return allInfos;
180 }
181
182 /**
183 * Obtains the requested audio mixer.
184 *
185 * @param info a {@code Mixer.Info} object representing the desired mixer,
186 * or {@code null} for the system default mixer
187 * @return the requested mixer
188 * @throws SecurityException if the requested mixer is unavailable because
189 * of security restrictions
190 * @throws IllegalArgumentException if the info object does not represent a
191 * mixer installed on the system
192 * @see #getMixerInfo
193 */
194 public static Mixer getMixer(Mixer.Info info) {
195
196 Mixer mixer = null;
197 List<MixerProvider> providers = getMixerProviders();
198
199 for(int i = 0; i < providers.size(); i++ ) {
200
201 try {
202 return providers.get(i).getMixer(info);
203
204 } catch (IllegalArgumentException e) {
205 } catch (NullPointerException e) {
206 // $$jb 08.20.99: If the strings in the info object aren't
207 // set, then Netscape (using jdk1.1.5) tends to throw
208 // NPE's when doing some string manipulation. This is
209 // probably not the best fix, but is solves the problem
210 // of the NPE in Netscape using local classes
211 // $$jb 11.01.99: Replacing this patch.
212 }
213 }
214
215 //$$fb if looking for default mixer, and not found yet, add a round of looking
216 if (info == null) {
217 for(int i = 0; i < providers.size(); i++ ) {
218 try {
219 MixerProvider provider = providers.get(i);
220 Mixer.Info[] infos = provider.getMixerInfo();
221 // start from 0 to last device (do not reverse this order)
222 for (int ii = 0; ii < infos.length; ii++) {
223 try {
224 return provider.getMixer(infos[ii]);
225 } catch (IllegalArgumentException e) {
226 // this is not a good default device :)
227 }
228 }
229 } catch (IllegalArgumentException e) {
230 } catch (NullPointerException e) {
231 }
232 }
233 }
234
235
236 throw new IllegalArgumentException("Mixer not supported: "
237 + (info!=null?info.toString():"null"));
238 }
239
240 //$$fb 2002-11-26: fix for 4757930: DOC: AudioSystem.getTarget/SourceLineInfo() is ambiguous
241
242 /**
243 * Obtains information about all source lines of a particular type that are
244 * supported by the installed mixers.
245 *
246 * @param info a {@code Line.Info} object that specifies the kind of lines
247 * about which information is requested
248 * @return an array of {@code Line.Info} objects describing source lines
249 * matching the type requested. If no matching source lines are
250 * supported, an array of length 0 is returned.
251 * @see Mixer#getSourceLineInfo(Line.Info)
252 */
253 public static Line.Info[] getSourceLineInfo(Line.Info info) {
254
255 Vector<Line.Info> vector = new Vector<>();
256 Line.Info[] currentInfoArray;
257
258 Mixer mixer;
259 Line.Info fullInfo = null;
260 Mixer.Info[] infoArray = getMixerInfo();
261
262 for (int i = 0; i < infoArray.length; i++) {
263
264 mixer = getMixer(infoArray[i]);
265
266 currentInfoArray = mixer.getSourceLineInfo(info);
267 for (int j = 0; j < currentInfoArray.length; j++) {
268 vector.addElement(currentInfoArray[j]);
269 }
270 }
271
272 Line.Info[] returnedArray = new Line.Info[vector.size()];
273
274 for (int i = 0; i < returnedArray.length; i++) {
275 returnedArray[i] = vector.get(i);
276 }
277
278 return returnedArray;
279 }
280
281 /**
282 * Obtains information about all target lines of a particular type that are
283 * supported by the installed mixers.
284 *
285 * @param info a {@code Line.Info} object that specifies the kind of lines
286 * about which information is requested
287 * @return an array of {@code Line.Info} objects describing target lines
288 * matching the type requested. If no matching target lines are
289 * supported, an array of length 0 is returned.
290 * @see Mixer#getTargetLineInfo(Line.Info)
291 */
292 public static Line.Info[] getTargetLineInfo(Line.Info info) {
293
294 Vector<Line.Info> vector = new Vector<>();
295 Line.Info[] currentInfoArray;
296
297 Mixer mixer;
298 Line.Info fullInfo = null;
299 Mixer.Info[] infoArray = getMixerInfo();
300
301 for (int i = 0; i < infoArray.length; i++) {
302
303 mixer = getMixer(infoArray[i]);
304
305 currentInfoArray = mixer.getTargetLineInfo(info);
306 for (int j = 0; j < currentInfoArray.length; j++) {
307 vector.addElement(currentInfoArray[j]);
308 }
309 }
310
311 Line.Info[] returnedArray = new Line.Info[vector.size()];
312
313 for (int i = 0; i < returnedArray.length; i++) {
314 returnedArray[i] = vector.get(i);
315 }
316
317 return returnedArray;
318 }
319
320 /**
321 * Indicates whether the system supports any lines that match the specified
322 * {@code Line.Info} object. A line is supported if any installed mixer
323 * supports it.
324 *
325 * @param info a {@code Line.Info} object describing the line for which
326 * support is queried
327 * @return {@code true} if at least one matching line is supported,
328 * otherwise {@code false}
329 * @see Mixer#isLineSupported(Line.Info)
330 */
331 public static boolean isLineSupported(Line.Info info) {
332
333 Mixer mixer;
334 Mixer.Info[] infoArray = getMixerInfo();
335
336 for (int i = 0; i < infoArray.length; i++) {
337
338 if( infoArray[i] != null ) {
339 mixer = getMixer(infoArray[i]);
340 if (mixer.isLineSupported(info)) {
341 return true;
342 }
343 }
344 }
345
346 return false;
347 }
348
349 /**
350 * Obtains a line that matches the description in the specified
351 * {@code Line.Info} object.
352 * <p>
353 * If a {@code DataLine} is requested, and {@code info} is an instance of
354 * {@code DataLine.Info} specifying at least one fully qualified audio
355 * format, the last one will be used as the default format of the returned
356 * {@code DataLine}.
357 * <p>
358 * If system properties
359 * {@code javax.sound.sampled.Clip},
360 * {@code javax.sound.sampled.Port},
361 * {@code javax.sound.sampled.SourceDataLine} and
362 * {@code javax.sound.sampled.TargetDataLine} are defined or they are
363 * defined in the file "sound.properties", they are used to retrieve default
364 * lines. For details, refer to the {@link AudioSystem class description}.
365 *
366 * If the respective property is not set, or the mixer requested in the
367 * property is not installed or does not provide the requested line, all
368 * installed mixers are queried for the requested line type. A Line will be
369 * returned from the first mixer providing the requested line type.
370 *
371 * @param info a {@code Line.Info} object describing the desired kind of
372 * line
373 * @return a line of the requested kind
374 * @throws LineUnavailableException if a matching line is not available due
375 * to resource restrictions
376 * @throws SecurityException if a matching line is not available due to
377 * security restrictions
378 * @throws IllegalArgumentException if the system does not support at least
379 * one line matching the specified {@code Line.Info} object through
380 * any installed mixer
381 */
382 public static Line getLine(Line.Info info) throws LineUnavailableException {
383 LineUnavailableException lue = null;
384 List<MixerProvider> providers = getMixerProviders();
385
386
387 // 1: try from default mixer for this line class
388 try {
389 Mixer mixer = getDefaultMixer(providers, info);
390 if (mixer != null && mixer.isLineSupported(info)) {
391 return mixer.getLine(info);
392 }
393 } catch (LineUnavailableException e) {
394 lue = e;
395 } catch (IllegalArgumentException iae) {
396 // must not happen... but better to catch it here,
397 // if plug-ins are badly written
398 }
399
400
401 // 2: if that doesn't work, try to find any mixing mixer
402 for(int i = 0; i < providers.size(); i++) {
403 MixerProvider provider = providers.get(i);
404 Mixer.Info[] infos = provider.getMixerInfo();
405
406 for (int j = 0; j < infos.length; j++) {
407 try {
408 Mixer mixer = provider.getMixer(infos[j]);
409 // see if this is an appropriate mixer which can mix
410 if (isAppropriateMixer(mixer, info, true)) {
411 return mixer.getLine(info);
412 }
413 } catch (LineUnavailableException e) {
414 lue = e;
415 } catch (IllegalArgumentException iae) {
416 // must not happen... but better to catch it here,
417 // if plug-ins are badly written
418 }
419 }
420 }
421
422
423 // 3: if that didn't work, try to find any non-mixing mixer
424 for(int i = 0; i < providers.size(); i++) {
425 MixerProvider provider = providers.get(i);
426 Mixer.Info[] infos = provider.getMixerInfo();
427 for (int j = 0; j < infos.length; j++) {
428 try {
429 Mixer mixer = provider.getMixer(infos[j]);
430 // see if this is an appropriate mixer which can mix
431 if (isAppropriateMixer(mixer, info, false)) {
432 return mixer.getLine(info);
433 }
434 } catch (LineUnavailableException e) {
435 lue = e;
436 } catch (IllegalArgumentException iae) {
437 // must not happen... but better to catch it here,
438 // if plug-ins are badly written
439 }
440 }
441 }
442
443 // if this line was supported but was not available, throw the last
444 // LineUnavailableException we got (??).
445 if (lue != null) {
446 throw lue;
447 }
448
449 // otherwise, the requested line was not supported, so throw
450 // an Illegal argument exception
451 throw new IllegalArgumentException("No line matching " +
452 info.toString() + " is supported.");
453 }
454
455 /**
456 * Obtains a clip that can be used for playing back an audio file or an
457 * audio stream. The returned clip will be provided by the default system
458 * mixer, or, if not possible, by any other mixer installed in the system
459 * that supports a {@code Clip} object.
460 * <p>
461 * The returned clip must be opened with the {@code open(AudioFormat)} or
462 * {@code open(AudioInputStream)} method.
463 * <p>
464 * This is a high-level method that uses {@code getMixer} and
465 * {@code getLine} internally.
466 * <p>
467 * If the system property {@code javax.sound.sampled.Clip} is defined or it
468 * is defined in the file "sound.properties", it is used to retrieve the
469 * default clip. For details, refer to the
470 * {@link AudioSystem class description}.
471 *
472 * @return the desired clip object
473 * @throws LineUnavailableException if a clip object is not available due to
474 * resource restrictions
475 * @throws SecurityException if a clip object is not available due to
476 * security restrictions
477 * @throws IllegalArgumentException if the system does not support at least
478 * one clip instance through any installed mixer
479 * @see #getClip(Mixer.Info)
480 * @since 1.5
481 */
482 public static Clip getClip() throws LineUnavailableException{
483 AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,
484 AudioSystem.NOT_SPECIFIED,
485 16, 2, 4,
486 AudioSystem.NOT_SPECIFIED, true);
487 DataLine.Info info = new DataLine.Info(Clip.class, format);
488 return (Clip) AudioSystem.getLine(info);
489 }
490
491 /**
492 * Obtains a clip from the specified mixer that can be used for playing back
493 * an audio file or an audio stream.
494 * <p>
495 * The returned clip must be opened with the {@code open(AudioFormat)} or
496 * {@code open(AudioInputStream)} method.
497 * <p>
498 * This is a high-level method that uses {@code getMixer} and
499 * {@code getLine} internally.
500 *
501 * @param mixerInfo a {@code Mixer.Info} object representing the desired
502 * mixer, or {@code null} for the system default mixer
503 * @return a clip object from the specified mixer
504 *
505 * @throws LineUnavailableException if a clip is not available from this
506 * mixer due to resource restrictions
507 * @throws SecurityException if a clip is not available from this mixer due
508 * to security restrictions
509 * @throws IllegalArgumentException if the system does not support at least
510 * one clip through the specified mixer
511 * @see #getClip()
512 * @since 1.5
513 */
514 public static Clip getClip(Mixer.Info mixerInfo) throws LineUnavailableException{
515 AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,
516 AudioSystem.NOT_SPECIFIED,
517 16, 2, 4,
518 AudioSystem.NOT_SPECIFIED, true);
519 DataLine.Info info = new DataLine.Info(Clip.class, format);
520 Mixer mixer = AudioSystem.getMixer(mixerInfo);
521 return (Clip) mixer.getLine(info);
522 }
523
524 /**
525 * Obtains a source data line that can be used for playing back audio data
526 * in the format specified by the {@code AudioFormat} object. The returned
527 * line will be provided by the default system mixer, or, if not possible,
528 * by any other mixer installed in the system that supports a matching
529 * {@code SourceDataLine} object.
530 * <p>
531 * The returned line should be opened with the {@code open(AudioFormat)} or
532 * {@code open(AudioFormat, int)} method.
533 * <p>
534 * This is a high-level method that uses {@code getMixer} and
535 * {@code getLine} internally.
536 * <p>
537 * The returned {@code SourceDataLine}'s default audio format will be
538 * initialized with {@code format}.
539 * <p>
540 * If the system property {@code javax.sound.sampled.SourceDataLine} is
541 * defined or it is defined in the file "sound.properties", it is used to
542 * retrieve the default source data line. For details, refer to the
543 * {@link AudioSystem class description}.
544 *
545 * @param format an {@code AudioFormat} object specifying the supported
546 * audio format of the returned line, or {@code null} for any audio
547 * format
548 * @return the desired {@code SourceDataLine} object
549 * @throws LineUnavailableException if a matching source data line is not
550 * available due to resource restrictions
551 * @throws SecurityException if a matching source data line is not available
552 * due to security restrictions
553 * @throws IllegalArgumentException if the system does not support at least
554 * one source data line supporting the specified audio format
555 * through any installed mixer
556 * @see #getSourceDataLine(AudioFormat, Mixer.Info)
557 * @since 1.5
558 */
559 public static SourceDataLine getSourceDataLine(AudioFormat format)
560 throws LineUnavailableException{
561 DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
562 return (SourceDataLine) AudioSystem.getLine(info);
563 }
564
565 /**
566 * Obtains a source data line that can be used for playing back audio data
567 * in the format specified by the {@code AudioFormat} object, provided by
568 * the mixer specified by the {@code Mixer.Info} object.
569 * <p>
570 * The returned line should be opened with the {@code open(AudioFormat)} or
571 * {@code open(AudioFormat, int)} method.
572 * <p>
573 * This is a high-level method that uses {@code getMixer} and
574 * {@code getLine} internally.
575 * <p>
576 * The returned {@code SourceDataLine}'s default audio format will be
577 * initialized with {@code format}.
578 *
579 * @param format an {@code AudioFormat} object specifying the supported
580 * audio format of the returned line, or {@code null} for any audio
581 * format
582 * @param mixerinfo a {@code Mixer.Info} object representing the desired
583 * mixer, or {@code null} for the system default mixer
584 * @return the desired {@code SourceDataLine} object
585 * @throws LineUnavailableException if a matching source data line is not
586 * available from the specified mixer due to resource restrictions
587 * @throws SecurityException if a matching source data line is not available
588 * from the specified mixer due to security restrictions
589 * @throws IllegalArgumentException if the specified mixer does not support
590 * at least one source data line supporting the specified audio
591 * format
592 * @see #getSourceDataLine(AudioFormat)
593 * @since 1.5
594 */
595 public static SourceDataLine getSourceDataLine(AudioFormat format,
596 Mixer.Info mixerinfo)
597 throws LineUnavailableException{
598 DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
599 Mixer mixer = AudioSystem.getMixer(mixerinfo);
600 return (SourceDataLine) mixer.getLine(info);
601 }
602
603 /**
604 * Obtains a target data line that can be used for recording audio data in
605 * the format specified by the {@code AudioFormat} object. The returned line
606 * will be provided by the default system mixer, or, if not possible, by any
607 * other mixer installed in the system that supports a matching
608 * {@code TargetDataLine} object.
609 * <p>
610 * The returned line should be opened with the {@code open(AudioFormat)} or
611 * {@code open(AudioFormat, int)} method.
612 * <p>
613 * This is a high-level method that uses {@code getMixer} and
614 * {@code getLine} internally.
615 * <p>
616 * The returned {@code TargetDataLine}'s default audio format will be
617 * initialized with {@code format}.
618 * <p>
619 * If the system property {@code javax.sound.sampled.TargetDataLine} is
620 * defined or it is defined in the file "sound.properties", it is used to
621 * retrieve the default target data line. For details, refer to the
622 * {@link AudioSystem class description}.
623 *
624 * @param format an {@code AudioFormat} object specifying the supported
625 * audio format of the returned line, or {@code null} for any audio
626 * format
627 * @return the desired {@code TargetDataLine} object
628 * @throws LineUnavailableException if a matching target data line is not
629 * available due to resource restrictions
630 * @throws SecurityException if a matching target data line is not available
631 * due to security restrictions
632 * @throws IllegalArgumentException if the system does not support at least
633 * one target data line supporting the specified audio format
634 * through any installed mixer
635 * @see #getTargetDataLine(AudioFormat, Mixer.Info)
636 * @see AudioPermission
637 * @since 1.5
638 */
639 public static TargetDataLine getTargetDataLine(AudioFormat format)
640 throws LineUnavailableException{
641
642 DataLine.Info info = new DataLine.Info(TargetDataLine.class, format);
643 return (TargetDataLine) AudioSystem.getLine(info);
644 }
645
646 /**
647 * Obtains a target data line that can be used for recording audio data in
648 * the format specified by the {@code AudioFormat} object, provided by the
649 * mixer specified by the {@code Mixer.Info} object.
650 * <p>
651 * The returned line should be opened with the {@code open(AudioFormat)} or
652 * {@code open(AudioFormat, int)} method.
653 * <p>
654 * This is a high-level method that uses {@code getMixer} and
655 * {@code getLine} internally.
656 * <p>
657 * The returned {@code TargetDataLine}'s default audio format will be
658 * initialized with {@code format}.
659 *
660 * @param format an {@code AudioFormat} object specifying the supported
661 * audio format of the returned line, or {@code null} for any audio
662 * format
663 * @param mixerinfo a {@code Mixer.Info} object representing the desired
664 * mixer, or {@code null} for the system default mixer
665 * @return the desired {@code TargetDataLine} object
666 * @throws LineUnavailableException if a matching target data line is not
667 * available from the specified mixer due to resource restrictions
668 * @throws SecurityException if a matching target data line is not available
669 * from the specified mixer due to security restrictions
670 * @throws IllegalArgumentException if the specified mixer does not support
671 * at least one target data line supporting the specified audio
672 * format
673 * @see #getTargetDataLine(AudioFormat)
674 * @see AudioPermission
675 * @since 1.5
676 */
677 public static TargetDataLine getTargetDataLine(AudioFormat format,
678 Mixer.Info mixerinfo)
679 throws LineUnavailableException {
680
681 DataLine.Info info = new DataLine.Info(TargetDataLine.class, format);
682 Mixer mixer = AudioSystem.getMixer(mixerinfo);
683 return (TargetDataLine) mixer.getLine(info);
684 }
685
686 // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
687
688 /**
689 * Obtains the encodings that the system can obtain from an audio input
690 * stream with the specified encoding using the set of installed format
691 * converters.
692 *
693 * @param sourceEncoding the encoding for which conversion support is
694 * queried
695 * @return array of encodings. If {@code sourceEncoding}is not supported, an
696 * array of length 0 is returned. Otherwise, the array will have a
697 * length of at least 1, representing {@code sourceEncoding}
698 * (no conversion).
699 */
700 public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding) {
701
702 List<FormatConversionProvider> codecs = getFormatConversionProviders();
703 Vector<AudioFormat.Encoding> encodings = new Vector<>();
704
705 AudioFormat.Encoding encs[] = null;
706
707 // gather from all the codecs
708 for(int i=0; i<codecs.size(); i++ ) {
709 FormatConversionProvider codec = codecs.get(i);
710 if( codec.isSourceEncodingSupported( sourceEncoding ) ) {
711 encs = codec.getTargetEncodings();
712 for (int j = 0; j < encs.length; j++) {
713 encodings.addElement( encs[j] );
714 }
715 }
716 }
717 AudioFormat.Encoding encs2[] = encodings.toArray(new AudioFormat.Encoding[0]);
718 return encs2;
719 }
720
721 // $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
722
723 /**
724 * Obtains the encodings that the system can obtain from an audio input
725 * stream with the specified format using the set of installed format
726 * converters.
727 *
728 * @param sourceFormat the audio format for which conversion is queried
729 * @return array of encodings. If {@code sourceFormat}is not supported, an
730 * array of length 0 is returned. Otherwise, the array will have a
731 * length of at least 1, representing the encoding of
732 * {@code sourceFormat} (no conversion).
733 */
734 public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat) {
735
736
737 List<FormatConversionProvider> codecs = getFormatConversionProviders();
738 Vector<AudioFormat.Encoding[]> encodings = new Vector<>();
739
740 int size = 0;
741 int index = 0;
742 AudioFormat.Encoding encs[] = null;
743
744 // gather from all the codecs
745
746 for(int i=0; i<codecs.size(); i++ ) {
747 encs = codecs.get(i).getTargetEncodings(sourceFormat);
748 size += encs.length;
749 encodings.addElement( encs );
750 }
751
752 // now build a new array
753
754 AudioFormat.Encoding encs2[] = new AudioFormat.Encoding[size];
755 for(int i=0; i<encodings.size(); i++ ) {
756 encs = encodings.get(i);
757 for(int j=0; j<encs.length; j++ ) {
758 encs2[index++] = encs[j];
759 }
760 }
761 return encs2;
762 }
763
764 /**
765 * Indicates whether an audio input stream of the specified encoding can be
766 * obtained from an audio input stream that has the specified format.
767 *
768 * @param targetEncoding the desired encoding after conversion
769 * @param sourceFormat the audio format before conversion
770 * @return {@code true} if the conversion is supported, otherwise
771 * {@code false}
772 */
773 public static boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) {
774
775
776 List<FormatConversionProvider> codecs = getFormatConversionProviders();
777
778 for(int i=0; i<codecs.size(); i++ ) {
779 FormatConversionProvider codec = codecs.get(i);
780 if(codec.isConversionSupported(targetEncoding,sourceFormat) ) {
781 return true;
782 }
783 }
784 return false;
785 }
786
787 /**
788 * Obtains an audio input stream of the indicated encoding, by converting
789 * the provided audio input stream.
790 *
791 * @param targetEncoding the desired encoding after conversion
792 * @param sourceStream the stream to be converted
793 * @return an audio input stream of the indicated encoding
794 * @throws IllegalArgumentException if the conversion is not supported
795 * @see #getTargetEncodings(AudioFormat.Encoding)
796 * @see #getTargetEncodings(AudioFormat)
797 * @see #isConversionSupported(AudioFormat.Encoding, AudioFormat)
798 * @see #getAudioInputStream(AudioFormat, AudioInputStream)
799 */
800 public static AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding,
801 AudioInputStream sourceStream) {
802
803 List<FormatConversionProvider> codecs = getFormatConversionProviders();
804
805 for(int i = 0; i < codecs.size(); i++) {
806 FormatConversionProvider codec = codecs.get(i);
807 if( codec.isConversionSupported( targetEncoding, sourceStream.getFormat() ) ) {
808 return codec.getAudioInputStream( targetEncoding, sourceStream );
809 }
810 }
811 // we ran out of options, throw an exception
812 throw new IllegalArgumentException("Unsupported conversion: " + targetEncoding + " from " + sourceStream.getFormat());
813 }
814
815 /**
816 * Obtains the formats that have a particular encoding and that the system
817 * can obtain from a stream of the specified format using the set of
818 * installed format converters.
819 *
820 * @param targetEncoding the desired encoding after conversion
821 * @param sourceFormat the audio format before conversion
822 * @return array of formats. If no formats of the specified encoding are
823 * supported, an array of length 0 is returned.
824 */
825 public static AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) {
826
827 List<FormatConversionProvider> codecs = getFormatConversionProviders();
828 Vector<AudioFormat[]> formats = new Vector<>();
829
830 int size = 0;
831 int index = 0;
832 AudioFormat fmts[] = null;
833
834 // gather from all the codecs
835
836 for(int i=0; i<codecs.size(); i++ ) {
837 FormatConversionProvider codec = codecs.get(i);
838 fmts = codec.getTargetFormats(targetEncoding, sourceFormat);
839 size += fmts.length;
840 formats.addElement( fmts );
841 }
842
843 // now build a new array
844
845 AudioFormat fmts2[] = new AudioFormat[size];
846 for(int i=0; i<formats.size(); i++ ) {
847 fmts = formats.get(i);
848 for(int j=0; j<fmts.length; j++ ) {
849 fmts2[index++] = fmts[j];
850 }
851 }
852 return fmts2;
853 }
854
855 /**
856 * Indicates whether an audio input stream of a specified format can be
857 * obtained from an audio input stream of another specified format.
858 *
859 * @param targetFormat the desired audio format after conversion
860 * @param sourceFormat the audio format before conversion
861 * @return {@code true} if the conversion is supported, otherwise
862 * {@code false}
863 */
864 public static boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) {
865
866 List<FormatConversionProvider> codecs = getFormatConversionProviders();
867
868 for(int i=0; i<codecs.size(); i++ ) {
869 FormatConversionProvider codec = codecs.get(i);
870 if(codec.isConversionSupported(targetFormat, sourceFormat) ) {
871 return true;
872 }
873 }
874 return false;
875 }
876
877 /**
878 * Obtains an audio input stream of the indicated format, by converting the
879 * provided audio input stream.
880 *
881 * @param targetFormat the desired audio format after conversion
882 * @param sourceStream the stream to be converted
883 * @return an audio input stream of the indicated format
884 * @throws IllegalArgumentException if the conversion is not supported
885 * @see #getTargetEncodings(AudioFormat)
886 * @see #getTargetFormats(AudioFormat.Encoding, AudioFormat)
887 * @see #isConversionSupported(AudioFormat, AudioFormat)
888 * @see #getAudioInputStream(AudioFormat.Encoding, AudioInputStream)
889 */
890 public static AudioInputStream getAudioInputStream(AudioFormat targetFormat,
891 AudioInputStream sourceStream) {
892
893 if (sourceStream.getFormat().matches(targetFormat)) {
894 return sourceStream;
895 }
896
897 List<FormatConversionProvider> codecs = getFormatConversionProviders();
898
899 for(int i = 0; i < codecs.size(); i++) {
900 FormatConversionProvider codec = codecs.get(i);
901 if(codec.isConversionSupported(targetFormat,sourceStream.getFormat()) ) {
902 return codec.getAudioInputStream(targetFormat,sourceStream);
903 }
904 }
905
906 // we ran out of options...
907 throw new IllegalArgumentException("Unsupported conversion: " + targetFormat + " from " + sourceStream.getFormat());
908 }
909
910 /**
911 * Obtains the audio file format of the provided input stream. The stream
912 * must point to valid audio file data. The implementation of this method
913 * may require multiple parsers to examine the stream to determine whether
914 * they support it. These parsers must be able to mark the stream, read
915 * enough data to determine whether they support the stream, and, if not,
916 * reset the stream's read pointer to its original position. If the input
917 * stream does not support these operations, this method may fail with an
918 * {@code IOException}.
919 *
920 * @param stream the input stream from which file format information should
921 * be extracted
922 * @return an {@code AudioFileFormat} object describing the stream's audio
923 * file format
924 * @throws UnsupportedAudioFileException if the stream does not point to
925 * valid audio file data recognized by the system
926 * @throws IOException if an input/output exception occurs
927 * @see InputStream#markSupported
928 * @see InputStream#mark
929 */
930 public static AudioFileFormat getAudioFileFormat(InputStream stream)
931 throws UnsupportedAudioFileException, IOException {
932
933 List<AudioFileReader> providers = getAudioFileReaders();
934 AudioFileFormat format = null;
935
936 for(int i = 0; i < providers.size(); i++ ) {
937 AudioFileReader reader = providers.get(i);
938 try {
939 format = reader.getAudioFileFormat( stream ); // throws IOException
940 break;
941 } catch (UnsupportedAudioFileException e) {
942 continue;
943 }
944 }
945
946 if( format==null ) {
947 throw new UnsupportedAudioFileException("file is not a supported file type");
948 } else {
949 return format;
950 }
951 }
952
953 /**
954 * Obtains the audio file format of the specified URL. The URL must point to
955 * valid audio file data.
956 *
957 * @param url the URL from which file format information should be
958 * extracted
959 * @return an {@code AudioFileFormat} object describing the audio file
960 * format
961 * @throws UnsupportedAudioFileException if the URL does not point to valid
962 * audio file data recognized by the system
963 * @throws IOException if an input/output exception occurs
964 */
965 public static AudioFileFormat getAudioFileFormat(URL url)
966 throws UnsupportedAudioFileException, IOException {
967
968 List<AudioFileReader> providers = getAudioFileReaders();
969 AudioFileFormat format = null;
970
971 for(int i = 0; i < providers.size(); i++ ) {
972 AudioFileReader reader = providers.get(i);
973 try {
974 format = reader.getAudioFileFormat( url ); // throws IOException
975 break;
976 } catch (UnsupportedAudioFileException e) {
977 continue;
978 }
979 }
980
981 if( format==null ) {
982 throw new UnsupportedAudioFileException("file is not a supported file type");
983 } else {
984 return format;
985 }
986 }
987
988 /**
989 * Obtains the audio file format of the specified {@code File}. The
990 * {@code File} must point to valid audio file data.
991 *
992 * @param file the {@code File} from which file format information should
993 * be extracted
994 * @return an {@code AudioFileFormat} object describing the audio file
995 * format
996 * @throws UnsupportedAudioFileException if the {@code File} does not point
997 * to valid audio file data recognized by the system
998 * @throws IOException if an I/O exception occurs
999 */
1000 public static AudioFileFormat getAudioFileFormat(File file)
1001 throws UnsupportedAudioFileException, IOException {
1002
1003 List<AudioFileReader> providers = getAudioFileReaders();
1004 AudioFileFormat format = null;
1005
1006 for(int i = 0; i < providers.size(); i++ ) {
1007 AudioFileReader reader = providers.get(i);
1008 try {
1009 format = reader.getAudioFileFormat( file ); // throws IOException
1010 break;
1011 } catch (UnsupportedAudioFileException e) {
1012 continue;
1013 }
1014 }
1015
1016 if( format==null ) {
1017 throw new UnsupportedAudioFileException("file is not a supported file type");
1018 } else {
1019 return format;
1020 }
1021 }
1022
1023 /**
1024 * Obtains an audio input stream from the provided input stream. The stream
1025 * must point to valid audio file data. The implementation of this method
1026 * may require multiple parsers to examine the stream to determine whether
1027 * they support it. These parsers must be able to mark the stream, read
1028 * enough data to determine whether they support the stream, and, if not,
1029 * reset the stream's read pointer to its original position. If the input
1030 * stream does not support these operation, this method may fail with an
1031 * {@code IOException}.
1032 *
1033 * @param stream the input stream from which the {@code AudioInputStream}
1034 * should be constructed
1035 * @return an {@code AudioInputStream} object based on the audio file data
1036 * contained in the input stream
1037 * @throws UnsupportedAudioFileException if the stream does not point to
1038 * valid audio file data recognized by the system
1039 * @throws IOException if an I/O exception occurs
1040 * @see InputStream#markSupported
1041 * @see InputStream#mark
1042 */
1043 public static AudioInputStream getAudioInputStream(InputStream stream)
1044 throws UnsupportedAudioFileException, IOException {
1045
1046 List<AudioFileReader> providers = getAudioFileReaders();
1047 AudioInputStream audioStream = null;
1048
1049 for(int i = 0; i < providers.size(); i++ ) {
1050 AudioFileReader reader = providers.get(i);
1051 try {
1052 audioStream = reader.getAudioInputStream( stream ); // throws IOException
1053 break;
1054 } catch (UnsupportedAudioFileException e) {
1055 continue;
1056 }
1057 }
1058
1059 if( audioStream==null ) {
1060 throw new UnsupportedAudioFileException("could not get audio input stream from input stream");
1061 } else {
1062 return audioStream;
1063 }
1064 }
1065
1066 /**
1067 * Obtains an audio input stream from the URL provided. The URL must point
1068 * to valid audio file data.
1069 *
1070 * @param url the URL for which the {@code AudioInputStream} should be
1071 * constructed
1072 * @return an {@code AudioInputStream} object based on the audio file data
1073 * pointed to by the URL
1074 * @throws UnsupportedAudioFileException if the URL does not point to valid
1075 * audio file data recognized by the system
1076 * @throws IOException if an I/O exception occurs
1077 */
1078 public static AudioInputStream getAudioInputStream(URL url)
1079 throws UnsupportedAudioFileException, IOException {
1080
1081 List<AudioFileReader> providers = getAudioFileReaders();
1082 AudioInputStream audioStream = null;
1083
1084 for(int i = 0; i < providers.size(); i++ ) {
1085 AudioFileReader reader = providers.get(i);
1086 try {
1087 audioStream = reader.getAudioInputStream( url ); // throws IOException
1088 break;
1089 } catch (UnsupportedAudioFileException e) {
1090 continue;
1091 }
1092 }
1093
1094 if( audioStream==null ) {
1095 throw new UnsupportedAudioFileException("could not get audio input stream from input URL");
1096 } else {
1097 return audioStream;
1098 }
1099 }
1100
1101 /**
1102 * Obtains an audio input stream from the provided {@code File}. The
1103 * {@code File} must point to valid audio file data.
1104 *
1105 * @param file the {@code File} for which the {@code AudioInputStream}
1106 * should be constructed
1107 * @return an {@code AudioInputStream} object based on the audio file data
1108 * pointed to by the {@code File}
1109 * @throws UnsupportedAudioFileException if the {@code File} does not point
1110 * to valid audio file data recognized by the system
1111 * @throws IOException if an I/O exception occurs
1112 */
1113 public static AudioInputStream getAudioInputStream(File file)
1114 throws UnsupportedAudioFileException, IOException {
1115
1116 List<AudioFileReader> providers = getAudioFileReaders();
1117 AudioInputStream audioStream = null;
1118
1119 for(int i = 0; i < providers.size(); i++ ) {
1120 AudioFileReader reader = providers.get(i);
1121 try {
1122 audioStream = reader.getAudioInputStream( file ); // throws IOException
1123 break;
1124 } catch (UnsupportedAudioFileException e) {
1125 continue;
1126 }
1127 }
1128
1129 if( audioStream==null ) {
1130 throw new UnsupportedAudioFileException("could not get audio input stream from input file");
1131 } else {
1132 return audioStream;
1133 }
1134 }
1135
1136 /**
1137 * Obtains the file types for which file writing support is provided by the
1138 * system.
1139 *
1140 * @return array of unique file types. If no file types are supported, an
1141 * array of length 0 is returned.
1142 */
1143 public static AudioFileFormat.Type[] getAudioFileTypes() {
1144 List<AudioFileWriter> providers = getAudioFileWriters();
1145 Set<AudioFileFormat.Type> returnTypesSet = new HashSet<>();
1146
1147 for(int i=0; i < providers.size(); i++) {
1148 AudioFileWriter writer = providers.get(i);
1149 AudioFileFormat.Type[] fileTypes = writer.getAudioFileTypes();
1150 for(int j=0; j < fileTypes.length; j++) {
1151 returnTypesSet.add(fileTypes[j]);
1152 }
1153 }
1154 AudioFileFormat.Type returnTypes[] =
1155 returnTypesSet.toArray(new AudioFileFormat.Type[0]);
1156 return returnTypes;
1157 }
1158
1159 /**
1160 * Indicates whether file writing support for the specified file type is
1161 * provided by the system.
1162 *
1163 * @param fileType the file type for which write capabilities are queried
1164 * @return {@code true} if the file type is supported, otherwise
1165 * {@code false}
1166 */
1167 public static boolean isFileTypeSupported(AudioFileFormat.Type fileType) {
1168
1169 List<AudioFileWriter> providers = getAudioFileWriters();
1170
1171 for(int i=0; i < providers.size(); i++) {
1172 AudioFileWriter writer = providers.get(i);
1173 if (writer.isFileTypeSupported(fileType)) {
1174 return true;
1175 }
1176 }
1177 return false;
1178 }
1179
1180 /**
1181 * Obtains the file types that the system can write from the audio input
1182 * stream specified.
1183 *
1184 * @param stream the audio input stream for which audio file type
1185 * support is queried
1186 * @return array of file types. If no file types are supported, an array of
1187 * length 0 is returned.
1188 */
1189 public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream) {
1190 List<AudioFileWriter> providers = getAudioFileWriters();
1191 Set<AudioFileFormat.Type> returnTypesSet = new HashSet<>();
1192
1193 for(int i=0; i < providers.size(); i++) {
1194 AudioFileWriter writer = providers.get(i);
1195 AudioFileFormat.Type[] fileTypes = writer.getAudioFileTypes(stream);
1196 for(int j=0; j < fileTypes.length; j++) {
1197 returnTypesSet.add(fileTypes[j]);
1198 }
1199 }
1200 AudioFileFormat.Type returnTypes[] =
1201 returnTypesSet.toArray(new AudioFileFormat.Type[0]);
1202 return returnTypes;
1203 }
1204
1205 /**
1206 * Indicates whether an audio file of the specified file type can be written
1207 * from the indicated audio input stream.
1208 *
1209 * @param fileType the file type for which write capabilities are queried
1210 * @param stream the stream for which file-writing support is queried
1211 * @return {@code true} if the file type is supported for this audio input
1212 * stream, otherwise {@code false}
1213 */
1214 public static boolean isFileTypeSupported(AudioFileFormat.Type fileType,
1215 AudioInputStream stream) {
1216
1217 List<AudioFileWriter> providers = getAudioFileWriters();
1218
1219 for(int i=0; i < providers.size(); i++) {
1220 AudioFileWriter writer = providers.get(i);
1221 if(writer.isFileTypeSupported(fileType, stream)) {
1222 return true;
1223 }
1224 }
1225 return false;
1226 }
1227
1228 /**
1229 * Writes a stream of bytes representing an audio file of the specified file
1230 * type to the output stream provided. Some file types require that the
1231 * length be written into the file header; such files cannot be written from
1232 * start to finish unless the length is known in advance. An attempt to
1233 * write a file of such a type will fail with an IOException if the length
1234 * in the audio file type is {@code AudioSystem.NOT_SPECIFIED}.
1235 *
1236 * @param stream the audio input stream containing audio data to be written
1237 * to the file
1238 * @param fileType the kind of audio file to write
1239 * @param out the stream to which the file data should be written
1240 * @return the number of bytes written to the output stream
1241 * @throws IOException if an input/output exception occurs
1242 * @throws IllegalArgumentException if the file type is not supported by the
1243 * system
1244 * @see #isFileTypeSupported
1245 * @see #getAudioFileTypes
1246 */
1247 public static int write(AudioInputStream stream, AudioFileFormat.Type fileType,
1248 OutputStream out) throws IOException {
1249
1250 List<AudioFileWriter> providers = getAudioFileWriters();
1251 int bytesWritten = 0;
1252 boolean flag = false;
1253
1254 for(int i=0; i < providers.size(); i++) {
1255 AudioFileWriter writer = providers.get(i);
1256 try {
1257 bytesWritten = writer.write( stream, fileType, out ); // throws IOException
1258 flag = true;
1259 break;
1260 } catch (IllegalArgumentException e) {
1261 // thrown if this provider cannot write the sequence, try the next
1262 continue;
1263 }
1264 }
1265 if(!flag) {
1266 throw new IllegalArgumentException("could not write audio file: file type not supported: " + fileType);
1267 } else {
1268 return bytesWritten;
1269 }
1270 }
1271
1272 /**
1273 * Writes a stream of bytes representing an audio file of the specified file
1274 * type to the external file provided.
1275 *
1276 * @param stream the audio input stream containing audio data to be written
1277 * to the file
1278 * @param fileType the kind of audio file to write
1279 * @param out the external file to which the file data should be written
1280 * @return the number of bytes written to the file
1281 * @throws IOException if an I/O exception occurs
1282 * @throws IllegalArgumentException if the file type is not supported by the
1283 * system
1284 * @see #isFileTypeSupported
1285 * @see #getAudioFileTypes
1286 */
1287 public static int write(AudioInputStream stream, AudioFileFormat.Type fileType,
1288 File out) throws IOException {
1289
1290 List<AudioFileWriter> providers = getAudioFileWriters();
1291 int bytesWritten = 0;
1292 boolean flag = false;
1293
1294 for(int i=0; i < providers.size(); i++) {
1295 AudioFileWriter writer = providers.get(i);
1296 try {
1297 bytesWritten = writer.write( stream, fileType, out ); // throws IOException
1298 flag = true;
1299 break;
1300 } catch (IllegalArgumentException e) {
1301 // thrown if this provider cannot write the sequence, try the next
1302 continue;
1303 }
1304 }
1305 if (!flag) {
1306 throw new IllegalArgumentException("could not write audio file: file type not supported: " + fileType);
1307 } else {
1308 return bytesWritten;
1309 }
1310 }
1311
1312 // METHODS FOR INTERNAL IMPLEMENTATION USE
1313
1314 /**
1315 * Obtains the set of MixerProviders on the system.
1316 */
1317 @SuppressWarnings("unchecked")
1318 private static List<MixerProvider> getMixerProviders() {
1319 return (List<MixerProvider>) getProviders(MixerProvider.class);
1320 }
1321
1322 /**
1323 * Obtains the set of format converters (codecs, transcoders, etc.) that are
1324 * currently installed on the system.
1325 *
1326 * @return an array of {@link FormatConversionProvider} objects representing
1327 * the available format converters. If no format converters readers
1328 * are available on the system, an array of length 0 is returned.
1329 */
1330 @SuppressWarnings("unchecked")
1331 private static List<FormatConversionProvider> getFormatConversionProviders() {
1332 return (List<FormatConversionProvider>) getProviders(FormatConversionProvider.class);
1333 }
1334
1335 /**
1336 * Obtains the set of audio file readers that are currently installed on the
1337 * system.
1338 *
1339 * @return a List of {@link AudioFileReader} objects representing the
1340 * installed audio file readers. If no audio file readers are
1341 * available on the system, an empty List is returned.
1342 */
1343 @SuppressWarnings("unchecked")
1344 private static List<AudioFileReader> getAudioFileReaders() {
1345 return (List<AudioFileReader>)getProviders(AudioFileReader.class);
1346 }
1347
1348 /**
1349 * Obtains the set of audio file writers that are currently installed on the
1350 * system.
1351 *
1352 * @return a List of {@link AudioFileWriter} objects representing the
1353 * available audio file writers. If no audio file writers are
1354 * available on the system, an empty List is returned.
1355 */
1356 @SuppressWarnings("unchecked")
1357 private static List<AudioFileWriter> getAudioFileWriters() {
1358 return (List<AudioFileWriter>)getProviders(AudioFileWriter.class);
1359 }
1360
1361 /**
1362 * Attempts to locate and return a default Mixer that provides lines of the
1363 * specified type.
1364 *
1365 * @param providers the installed mixer providers
1366 * @param info The requested line type TargetDataLine.class, Clip.class or
1367 * Port.class
1368 * @return a Mixer that matches the requirements, or null if no default
1369 * mixer found
1370 */
1371 private static Mixer getDefaultMixer(List<MixerProvider> providers, Line.Info info) {
1372 Class<?> lineClass = info.getLineClass();
1373 String providerClassName = JDK13Services.getDefaultProviderClassName(lineClass);
1374 String instanceName = JDK13Services.getDefaultInstanceName(lineClass);
1375 Mixer mixer;
1376
1377 if (providerClassName != null) {
1378 MixerProvider defaultProvider = getNamedProvider(providerClassName, providers);
1379 if (defaultProvider != null) {
1380 if (instanceName != null) {
1381 mixer = getNamedMixer(instanceName, defaultProvider, info);
1382 if (mixer != null) {
1383 return mixer;
1384 }
1385 } else {
1386 mixer = getFirstMixer(defaultProvider, info,
1387 false /* mixing not required*/);
1388 if (mixer != null) {
1389 return mixer;
1390 }
1391 }
1392
1393 }
1394 }
1395
1396 /* Provider class not specified or
1397 provider class cannot be found, or
1398 provider class and instance specified and instance cannot be found or is not appropriate */
1399 if (instanceName != null) {
1400 mixer = getNamedMixer(instanceName, providers, info);
1401 if (mixer != null) {
1402 return mixer;
1403 }
1404 }
1405
1406
1407 /* No default are specified, or if something is specified, everything
1408 failed. */
1409 return null;
1410 }
1411
1412 /**
1413 * Return a MixerProvider of a given class from the list of MixerProviders.
1414 * This method never requires the returned Mixer to do mixing.
1415 *
1416 * @param providerClassName The class name of the provider to be returned
1417 * @param providers The list of MixerProviders that is searched
1418 * @return A MixerProvider of the requested class, or null if none is found
1419 */
1420 private static MixerProvider getNamedProvider(String providerClassName,
1421 List<MixerProvider> providers) {
1422 for(int i = 0; i < providers.size(); i++) {
1423 MixerProvider provider = providers.get(i);
1424 if (provider.getClass().getName().equals(providerClassName)) {
1425 return provider;
1426 }
1427 }
1428 return null;
1429 }
1430
1431 /**
1432 * Return a Mixer with a given name from a given MixerProvider. This method
1433 * never requires the returned Mixer to do mixing.
1434 *
1435 * @param mixerName The name of the Mixer to be returned
1436 * @param provider The MixerProvider to check for Mixers
1437 * @param info The type of line the returned Mixer is required to support
1438 * @return A Mixer matching the requirements, or null if none is found
1439 */
1440 private static Mixer getNamedMixer(String mixerName,
1441 MixerProvider provider,
1442 Line.Info info) {
1443 Mixer.Info[] infos = provider.getMixerInfo();
1444 for (int i = 0; i < infos.length; i++) {
1445 if (infos[i].getName().equals(mixerName)) {
1446 Mixer mixer = provider.getMixer(infos[i]);
1447 if (isAppropriateMixer(mixer, info, false)) {
1448 return mixer;
1449 }
1450 }
1451 }
1452 return null;
1453 }
1454
1455 /**
1456 * From a List of MixerProviders, return a Mixer with a given name. This
1457 * method never requires the returned Mixer to do mixing.
1458 *
1459 * @param mixerName The name of the Mixer to be returned
1460 * @param providers The List of MixerProviders to check for Mixers
1461 * @param info The type of line the returned Mixer is required to support
1462 * @return A Mixer matching the requirements, or null if none is found
1463 */
1464 private static Mixer getNamedMixer(String mixerName,
1465 List<MixerProvider> providers,
1466 Line.Info info) {
1467 for(int i = 0; i < providers.size(); i++) {
1468 MixerProvider provider = providers.get(i);
1469 Mixer mixer = getNamedMixer(mixerName, provider, info);
1470 if (mixer != null) {
1471 return mixer;
1472 }
1473 }
1474 return null;
1475 }
1476
1477 /**
1478 * From a given MixerProvider, return the first appropriate Mixer.
1479 *
1480 * @param provider The MixerProvider to check for Mixers
1481 * @param info The type of line the returned Mixer is required to support
1482 * @param isMixingRequired If true, only Mixers that support mixing are
1483 * returned for line types of SourceDataLine and Clip
1484 * @return A Mixer that is considered appropriate, or null if none is found
1485 */
1486 private static Mixer getFirstMixer(MixerProvider provider,
1487 Line.Info info,
1488 boolean isMixingRequired) {
1489 Mixer.Info[] infos = provider.getMixerInfo();
1490 for (int j = 0; j < infos.length; j++) {
1491 Mixer mixer = provider.getMixer(infos[j]);
1492 if (isAppropriateMixer(mixer, info, isMixingRequired)) {
1493 return mixer;
1494 }
1495 }
1496 return null;
1497 }
1498
1499 /**
1500 * Checks if a Mixer is appropriate. A Mixer is considered appropriate if it
1501 * support the given line type. If isMixingRequired is true and the line
1502 * type is an output one (SourceDataLine, Clip), the mixer is appropriate if
1503 * it supports at least 2 (concurrent) lines of the given type.
1504 *
1505 * @return {@code true} if the mixer is considered appropriate according to
1506 * the rules given above, {@code false} otherwise
1507 */
1508 private static boolean isAppropriateMixer(Mixer mixer,
1509 Line.Info lineInfo,
1510 boolean isMixingRequired) {
1511 if (! mixer.isLineSupported(lineInfo)) {
1512 return false;
1513 }
1514 Class<?> lineClass = lineInfo.getLineClass();
1515 if (isMixingRequired
1516 && (SourceDataLine.class.isAssignableFrom(lineClass) ||
1517 Clip.class.isAssignableFrom(lineClass))) {
1518 int maxLines = mixer.getMaxLines(lineInfo);
1519 return ((maxLines == NOT_SPECIFIED) || (maxLines > 1));
1520 }
1521 return true;
1522 }
1523
1524 /**
1525 * Like getMixerInfo, but return List.
1526 */
1527 private static List<Mixer.Info> getMixerInfoList() {
1528 List<MixerProvider> providers = getMixerProviders();
1529 return getMixerInfoList(providers);
1530 }
1531
1532 /**
1533 * Like getMixerInfo, but return List.
1534 */
1535 private static List<Mixer.Info> getMixerInfoList(List<MixerProvider> providers) {
1536 List<Mixer.Info> infos = new ArrayList<>();
1537
1538 Mixer.Info[] someInfos; // per-mixer
1539 Mixer.Info[] allInfos; // for all mixers
1540
1541 for(int i = 0; i < providers.size(); i++ ) {
1542 someInfos = providers.get(i).getMixerInfo();
1543
1544 for (int j = 0; j < someInfos.length; j++) {
1545 infos.add(someInfos[j]);
1546 }
1547 }
1548
1549 return infos;
1550 }
1551
1552 /**
1553 * Obtains the set of services currently installed on the system using the
1554 * SPI mechanism in 1.3.
1555 *
1556 * @return a List of instances of providers for the requested service. If no
1557 * providers are available, a vector of length 0 will be returned.
1558 */
1559 private static List<?> getProviders(Class<?> providerClass) {
1560 return JDK13Services.getProviders(providerClass);
1561 }
1562 }