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