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