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