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