src/share/classes/javax/sound/sampled/AudioSystem.java

Print this page




   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.InputStream;
  30 import java.io.IOException;

  31 import java.io.OutputStream;
  32 import java.net.URL;
  33 
  34 import java.util.HashSet;
  35 import java.util.List;

  36 import java.util.Set;
  37 import java.util.Vector;
  38 import java.util.ArrayList;
  39 
  40 import javax.sound.sampled.spi.AudioFileWriter;
  41 import javax.sound.sampled.spi.AudioFileReader;

  42 import javax.sound.sampled.spi.FormatConversionProvider;
  43 import javax.sound.sampled.spi.MixerProvider;
  44 
  45 import com.sun.media.sound.JDK13Services;
  46 
  47 /* $fb TODO:
  48  * - consistent usage of (typed) collections
  49  */
  50 
  51 
  52 /**
  53  * The {@code AudioSystem} class acts as the entry point to the sampled-audio
  54  * system resources. This class lets you query and access the mixers that are
  55  * installed on the system. {@code AudioSystem} includes a number of methods for
  56  * converting audio data between different formats, and for translating between
  57  * audio files and streams. It also provides a method for obtaining a
  58  * {@link Line} directly from the {@code AudioSystem} without dealing explicitly
  59  * with mixers.
  60  * <p>
  61  * Properties can be used to specify the default mixer for specific line types.
  62  * Both system properties and a properties file are considered. The
  63  * {@code sound.properties} properties file is read from an
  64  * implementation-specific location (typically it is the {@code lib} directory
  65  * in the Java installation directory). If a property exists both as a system
  66  * property and in the properties file, the system property takes precedence.
  67  * If none is specified, a suitable default is chosen among the available
  68  * devices. The syntax of the properties file is specified in
  69  * {@link java.util.Properties#load(InputStream) Properties.load}. The following
  70  * table lists the available property keys and which methods consider them:
  71  *
  72  * <table border=0>
  73  *  <caption>Audio System Property Keys</caption>
  74  *  <tr>
  75  *   <th>Property Key</th>
  76  *   <th>Interface</th>
  77  *   <th>Affected Method(s)</th>
  78  *  </tr>
  79  *  <tr>
  80  *   <td>{@code javax.sound.sampled.Clip}</td>
  81  *   <td>{@link Clip}</td>
  82  *   <td>{@link #getLine}, {@link #getClip}</td>
  83  *  </tr>
  84  *  <tr>
  85  *   <td>{@code javax.sound.sampled.Port}</td>
  86  *   <td>{@link Port}</td>
  87  *   <td>{@link #getLine}</td>
  88  *  </tr>
  89  *  <tr>
  90  *   <td>{@code javax.sound.sampled.SourceDataLine}</td>
  91  *   <td>{@link SourceDataLine}</td>
  92  *   <td>{@link #getLine}, {@link #getSourceDataLine}</td>
  93  *  </tr>
  94  *  <tr>
  95  *   <td>{@code javax.sound.sampled.TargetDataLine}</td>
  96  *   <td>{@link TargetDataLine}</td>
  97  *   <td>{@link #getLine}, {@link #getTargetDataLine}</td>
  98  *  </tr>
  99  * </table>
 100  *
 101  * The property value consists of the provider class name and the mixer name,
 102  * separated by the hash mark (&quot;#&quot;). The provider class name is the
 103  * fully-qualified name of a concrete
 104  * {@link javax.sound.sampled.spi.MixerProvider mixer provider} class. The mixer
 105  * name is matched against the {@code String} returned by the {@code getName}
 106  * method of {@code Mixer.Info}. Either the class name, or the mixer name may be
 107  * omitted. If only the class name is specified, the trailing hash mark is
 108  * 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  *
 123  * For example, the property {@code javax.sound.sampled.Clip} with a value
 124  * {@code "com.sun.media.sound.MixerProvider#SunClip"}
 125  * will have the following consequences when {@code getLine} is called
 126  * requesting a {@code Clip} instance: if the class
 127  * {@code com.sun.media.sound.MixerProvider} exists in the list of installed
 128  * mixer providers, the first {@code Clip} from the first mixer with name


1307             throw new IllegalArgumentException("could not write audio file: file type not supported: " + fileType);
1308         } else {
1309             return bytesWritten;
1310         }
1311     }
1312 
1313     // METHODS FOR INTERNAL IMPLEMENTATION USE
1314 
1315     /**
1316      * Obtains the set of MixerProviders on the system.
1317      */
1318     @SuppressWarnings("unchecked")
1319     private static List<MixerProvider> getMixerProviders() {
1320         return (List<MixerProvider>) getProviders(MixerProvider.class);
1321     }
1322 
1323     /**
1324      * Obtains the set of format converters (codecs, transcoders, etc.) that are
1325      * currently installed on the system.
1326      *
1327      * @return an array of {@link javax.sound.sampled.spi.FormatConversionProvider
1328      *         FormatConversionProvider} objects representing the available
1329      *         format converters. If no format converters readers are available
1330      *         on the system, an array of length 0 is returned.
1331      */
1332     @SuppressWarnings("unchecked")
1333     private static List<FormatConversionProvider> getFormatConversionProviders() {
1334         return (List<FormatConversionProvider>) getProviders(FormatConversionProvider.class);
1335     }
1336 
1337     /**
1338      * Obtains the set of audio file readers that are currently installed on the
1339      * system.
1340      *
1341      * @return a List of {@link javax.sound.sampled.spi.AudioFileReader
1342      *         AudioFileReader} objects representing the installed audio file
1343      *         readers. If no audio file readers are available on the system, an
1344      *         empty List is returned.
1345      */
1346     @SuppressWarnings("unchecked")
1347     private static List<AudioFileReader> getAudioFileReaders() {
1348         return (List<AudioFileReader>)getProviders(AudioFileReader.class);
1349     }
1350 
1351     /**
1352      * Obtains the set of audio file writers that are currently installed on the
1353      * system.
1354      *
1355      * @return a List of {@link javax.sound.sampled.spi.AudioFileWriter
1356      *         AudioFileWriter} objects representing the available audio file
1357      *         writers. If no audio file writers are available on the system, an
1358      *         empty List is returned.
1359      */
1360     @SuppressWarnings("unchecked")
1361     private static List<AudioFileWriter> getAudioFileWriters() {
1362         return (List<AudioFileWriter>)getProviders(AudioFileWriter.class);
1363     }
1364 
1365     /**
1366      * Attempts to locate and return a default Mixer that provides lines of the
1367      * specified type.
1368      *
1369      * @param  providers the installed mixer providers
1370      * @param  info The requested line type TargetDataLine.class, Clip.class or
1371      *         Port.class
1372      * @return a Mixer that matches the requirements, or null if no default
1373      *         mixer found
1374      */
1375     private static Mixer getDefaultMixer(List<MixerProvider> providers, Line.Info info) {
1376         Class<?> lineClass = info.getLineClass();
1377         String providerClassName = JDK13Services.getDefaultProviderClassName(lineClass);
1378         String instanceName = JDK13Services.getDefaultInstanceName(lineClass);




   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.HashSet;
  35 import java.util.List;
  36 import java.util.Properties;
  37 import java.util.Set;
  38 import java.util.Vector;

  39 

  40 import javax.sound.sampled.spi.AudioFileReader;
  41 import javax.sound.sampled.spi.AudioFileWriter;
  42 import javax.sound.sampled.spi.FormatConversionProvider;
  43 import javax.sound.sampled.spi.MixerProvider;
  44 
  45 import com.sun.media.sound.JDK13Services;
  46 
  47 /* $fb TODO:
  48  * - consistent usage of (typed) collections
  49  */
  50 
  51 
  52 /**
  53  * The {@code AudioSystem} class acts as the entry point to the sampled-audio
  54  * system resources. This class lets you query and access the mixers that are
  55  * installed on the system. {@code AudioSystem} includes a number of methods for
  56  * converting audio data between different formats, and for translating between
  57  * audio files and streams. It also provides a method for obtaining a
  58  * {@link Line} directly from the {@code AudioSystem} without dealing explicitly
  59  * with mixers.
  60  * <p>
  61  * Properties can be used to specify the default mixer for specific line types.
  62  * Both system properties and a properties file are considered. The
  63  * "sound.properties" properties file is read from an implementation-specific
  64  * location (typically it is the {@code lib} directory in the Java installation
  65  * directory). If a property exists both as a system property and in the
  66  * properties file, the system property takes precedence. If none is specified,
  67  * a suitable default is chosen among the available devices. The syntax of the
  68  * properties file is specified in
  69  * {@link Properties#load(InputStream) Properties.load}. The following table
  70  * lists the available property keys and which methods consider them:
  71  *
  72  * <table border=0>
  73  *  <caption>Audio System Property Keys</caption>
  74  *  <tr>
  75  *   <th>Property Key</th>
  76  *   <th>Interface</th>
  77  *   <th>Affected Method(s)</th>
  78  *  </tr>
  79  *  <tr>
  80  *   <td>{@code javax.sound.sampled.Clip}</td>
  81  *   <td>{@link Clip}</td>
  82  *   <td>{@link #getLine}, {@link #getClip}</td>
  83  *  </tr>
  84  *  <tr>
  85  *   <td>{@code javax.sound.sampled.Port}</td>
  86  *   <td>{@link Port}</td>
  87  *   <td>{@link #getLine}</td>
  88  *  </tr>
  89  *  <tr>
  90  *   <td>{@code javax.sound.sampled.SourceDataLine}</td>
  91  *   <td>{@link SourceDataLine}</td>
  92  *   <td>{@link #getLine}, {@link #getSourceDataLine}</td>
  93  *  </tr>
  94  *  <tr>
  95  *   <td>{@code javax.sound.sampled.TargetDataLine}</td>
  96  *   <td>{@link TargetDataLine}</td>
  97  *   <td>{@link #getLine}, {@link #getTargetDataLine}</td>
  98  *  </tr>
  99  * </table>
 100  *
 101  * The property value consists of the provider class name and the mixer name,
 102  * separated by the hash mark (&quot;#&quot;). The provider class name is the
 103  * fully-qualified name of a concrete {@link MixerProvider mixer provider}
 104  * class. The mixer name is matched against the {@code String} returned by the
 105  * {@code getName} method of {@code Mixer.Info}. Either the class name, or the
 106  * mixer name may be omitted. If only the class name is specified, the trailing
 107  * hash mark is optional.

 108  * <p>
 109  * If the provider class is specified, and it can be successfully retrieved from
 110  * the installed providers, the list of {@code Mixer.Info} objects is retrieved
 111  * from the provider. Otherwise, or when these mixers do not provide a
 112  * subsequent match, the list is retrieved from {@link #getMixerInfo} to contain
 113  * all available {@code Mixer.Info} objects.
 114  * <p>
 115  * If a mixer name is specified, the resulting list of {@code Mixer.Info}
 116  * objects is searched: the first one with a matching name, and whose
 117  * {@code Mixer} provides the respective line interface, will be returned. If no
 118  * matching {@code Mixer.Info} object is found, or the mixer name is not
 119  * specified, the first mixer from the resulting list, which provides the
 120  * respective line interface, will be returned.
 121  *
 122  * For example, the property {@code javax.sound.sampled.Clip} with a value
 123  * {@code "com.sun.media.sound.MixerProvider#SunClip"}
 124  * will have the following consequences when {@code getLine} is called
 125  * requesting a {@code Clip} instance: if the class
 126  * {@code com.sun.media.sound.MixerProvider} exists in the list of installed
 127  * mixer providers, the first {@code Clip} from the first mixer with name


1306             throw new IllegalArgumentException("could not write audio file: file type not supported: " + fileType);
1307         } else {
1308             return bytesWritten;
1309         }
1310     }
1311 
1312     // METHODS FOR INTERNAL IMPLEMENTATION USE
1313 
1314     /**
1315      * Obtains the set of MixerProviders on the system.
1316      */
1317     @SuppressWarnings("unchecked")
1318     private static List<MixerProvider> getMixerProviders() {
1319         return (List<MixerProvider>) getProviders(MixerProvider.class);
1320     }
1321 
1322     /**
1323      * Obtains the set of format converters (codecs, transcoders, etc.) that are
1324      * currently installed on the system.
1325      *
1326      * @return an array of {@link FormatConversionProvider} objects representing
1327      *         the available format converters. If no format converters readers
1328      *         are available on the system, an array of length 0 is returned.

1329      */
1330     @SuppressWarnings("unchecked")
1331     private static List<FormatConversionProvider> getFormatConversionProviders() {
1332         return (List<FormatConversionProvider>) getProviders(FormatConversionProvider.class);
1333     }
1334 
1335     /**
1336      * Obtains the set of audio file readers that are currently installed on the
1337      * system.
1338      *
1339      * @return a List of {@link AudioFileReader} objects representing the
1340      *         installed audio file readers. If no audio file readers are
1341      *         available on the system, an empty List is returned.

1342      */
1343     @SuppressWarnings("unchecked")
1344     private static List<AudioFileReader> getAudioFileReaders() {
1345         return (List<AudioFileReader>)getProviders(AudioFileReader.class);
1346     }
1347 
1348     /**
1349      * Obtains the set of audio file writers that are currently installed on the
1350      * system.
1351      *
1352      * @return a List of {@link AudioFileWriter} objects representing the
1353      *         available audio file writers. If no audio file writers are
1354      *         available on the system, an empty List is returned.

1355      */
1356     @SuppressWarnings("unchecked")
1357     private static List<AudioFileWriter> getAudioFileWriters() {
1358         return (List<AudioFileWriter>)getProviders(AudioFileWriter.class);
1359     }
1360 
1361     /**
1362      * Attempts to locate and return a default Mixer that provides lines of the
1363      * specified type.
1364      *
1365      * @param  providers the installed mixer providers
1366      * @param  info The requested line type TargetDataLine.class, Clip.class or
1367      *         Port.class
1368      * @return a Mixer that matches the requirements, or null if no default
1369      *         mixer found
1370      */
1371     private static Mixer getDefaultMixer(List<MixerProvider> providers, Line.Info info) {
1372         Class<?> lineClass = info.getLineClass();
1373         String providerClassName = JDK13Services.getDefaultProviderClassName(lineClass);
1374         String instanceName = JDK13Services.getDefaultInstanceName(lineClass);