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