/*
* Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sound.sampled;
import java.io.File;
import java.io.InputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.net.URL;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.Vector;
import java.util.ArrayList;
import javax.sound.sampled.spi.AudioFileWriter;
import javax.sound.sampled.spi.AudioFileReader;
import javax.sound.sampled.spi.FormatConversionProvider;
import javax.sound.sampled.spi.MixerProvider;
import com.sun.media.sound.JDK13Services;
/* $fb TODO:
* - consistent usage of (typed) collections
*/
/**
* The AudioSystem
class acts as the entry point to the
* sampled-audio system resources. This class lets you query and
* access the mixers that are installed on the system.
* AudioSystem
includes a number of
* methods for converting audio data between different formats, and for
* translating between audio files and streams. It also provides a method
* for obtaining a {@link Line}
directly from the
* AudioSystem
without dealing explicitly
* with mixers.
*
*
Properties can be used to specify the default mixer
* for specific line types.
* Both system properties and a properties file are considered.
* The sound.properties
properties file is read from
* an implementation-specific location (typically it is the lib
* directory in the Java installation directory).
* If a property exists both as a system property and in the
* properties file, the system property takes precedence. If none is
* specified, a suitable default is chosen among the available devices.
* The syntax of the properties file is specified in
* {@link java.util.Properties#load(InputStream) Properties.load}. The
* following table lists the available property keys and which methods
* consider them:
*
*
Property Key | *Interface | *Affected Method(s) | *
---|---|---|
javax.sound.sampled.Clip |
* {@link Clip} | *{@link #getLine}, {@link #getClip} | *
javax.sound.sampled.Port |
* {@link Port} | *{@link #getLine} | *
javax.sound.sampled.SourceDataLine |
* {@link SourceDataLine} | *{@link #getLine}, {@link #getSourceDataLine} | *
javax.sound.sampled.TargetDataLine |
* {@link TargetDataLine} | *{@link #getLine}, {@link #getTargetDataLine} | *
String
returned by the getName
* method of Mixer.Info
.
* Either the class name, or the mixer name may be omitted.
* If only the class name is specified, the trailing hash mark
* is optional.
*
* If the provider class is specified, and it can be
* successfully retrieved from the installed providers, the list of
* Mixer.Info
objects is retrieved
* from the provider. Otherwise, or when these mixers
* do not provide a subsequent match, the list is retrieved
* from {@link #getMixerInfo} to contain
* all available Mixer.Info
objects.
*
*
If a mixer name is specified, the resulting list of
* If a If system properties
* The returned clip must be opened with the
* This is a high-level method that uses If the system property
* The returned clip must be opened with the
* This is a high-level method that uses The returned line should be opened with the
* This is a high-level method that uses The returned If the system property
* The returned line should be opened with the
* This is a high-level method that uses The returned The returned line should be opened with the
* This is a high-level method that uses The returned If the system property
* {@code javax.sound.sampled.TargetDataLine}
* is defined or it is defined in the file "sound.properties",
* it is used to retrieve the default target data line.
* For details, refer to the {@link AudioSystem class description}.
*
* @param format an The returned line should be opened with the
* This is a high-level method that uses The returned Mixer.Info
objects is searched:
* the first one with a matching name, and whose
* Mixer
provides the
* respective line interface, will be returned.
* If no matching Mixer.Info
object
* is found, or the mixer name is not specified,
* the first mixer from the resulting
* list, which provides the respective line
* interface, will be returned.
*
* For example, the property javax.sound.sampled.Clip
* with a value
* "com.sun.media.sound.MixerProvider#SunClip"
* will have the following consequences when
* getLine
is called requesting a Clip
* instance:
* if the class com.sun.media.sound.MixerProvider
exists
* in the list of installed mixer providers,
* the first Clip
from the first mixer with name
* "SunClip"
will be returned. If it cannot
* be found, the first Clip
from the first mixer
* of the specified provider will be returned, regardless of name.
* If there is none, the first Clip
from the first
* Mixer
with name
* "SunClip"
in the list of all mixers
* (as returned by getMixerInfo
) will be returned,
* or, if not found, the first Clip
of the first
* Mixer
that can be found in the list of all
* mixers is returned.
* If that fails, too, an IllegalArgumentException
* is thrown.
*
* @author Kara Kytle
* @author Florian Bomers
* @author Matthias Pfisterer
* @author Kevin P. Smith
*
* @see AudioFormat
* @see AudioInputStream
* @see Mixer
* @see Line
* @see Line.Info
* @since 1.3
*/
public class AudioSystem {
/**
* An integer that stands for an unknown numeric value.
* This value is appropriate only for signed quantities that do not
* normally take negative values. Examples include file sizes, frame
* sizes, buffer sizes, and sample rates.
* A number of Java Sound constructors accept
* a value of NOT_SPECIFIED
for such parameters. Other
* methods may also accept or return this value, as documented.
*/
public static final int NOT_SPECIFIED = -1;
/**
* Private no-args constructor for ensuring against instantiation.
*/
private AudioSystem() {
}
/**
* Obtains an array of mixer info objects that represents
* the set of audio mixers that are currently installed on the system.
* @return an array of info objects for the currently installed mixers. If no mixers
* are available on the system, an array of length 0 is returned.
* @see #getMixer
*/
public static Mixer.Info[] getMixerInfo() {
ListMixer.Info
object representing the desired
* mixer, or null
for the system default mixer
* @return the requested mixer
* @throws SecurityException if the requested mixer
* is unavailable because of security restrictions
* @throws IllegalArgumentException if the info object does not represent
* a mixer installed on the system
* @see #getMixerInfo
*/
public static Mixer getMixer(Mixer.Info info) {
Mixer mixer = null;
ListLine.Info
object that specifies the kind of
* lines about which information is requested
* @return an array of Line.Info
objects describing source lines matching
* the type requested. If no matching source lines are supported, an array of length 0
* is returned.
*
* @see Mixer#getSourceLineInfo(Line.Info)
*/
public static Line.Info[] getSourceLineInfo(Line.Info info) {
VectorLine.Info
object that specifies the kind of
* lines about which information is requested
* @return an array of Line.Info
objects describing target lines matching
* the type requested. If no matching target lines are supported, an array of length 0
* is returned.
*
* @see Mixer#getTargetLineInfo(Line.Info)
*/
public static Line.Info[] getTargetLineInfo(Line.Info info) {
VectorLine.Info
object. A line is supported if
* any installed mixer supports it.
* @param info a Line.Info
object describing the line for which support is queried
* @return true
if at least one matching line is
* supported, otherwise false
*
* @see Mixer#isLineSupported(Line.Info)
*/
public static boolean isLineSupported(Line.Info info) {
Mixer mixer;
Mixer.Info[] infoArray = getMixerInfo();
for (int i = 0; i < infoArray.length; i++) {
if( infoArray[i] != null ) {
mixer = getMixer(infoArray[i]);
if (mixer.isLineSupported(info)) {
return true;
}
}
}
return false;
}
/**
* Obtains a line that matches the description in the specified
* Line.Info
object.
*
* DataLine
is requested, and info
* is an instance of DataLine.Info
specifying at least
* one fully qualified audio format, the last one
* will be used as the default format of the returned
* DataLine
.
*
* javax.sound.sampled.Clip
,
* javax.sound.sampled.Port
,
* javax.sound.sampled.SourceDataLine
and
* javax.sound.sampled.TargetDataLine
are defined
* or they are defined in the file "sound.properties",
* they are used to retrieve default lines.
* For details, refer to the {@link AudioSystem class description}.
*
* If the respective property is not set, or the mixer
* requested in the property is not installed or does not provide the
* requested line, all installed mixers are queried for the
* requested line type. A Line will be returned from the first mixer
* providing the requested line type.
*
* @param info a Line.Info
object describing the desired kind of line
* @return a line of the requested kind
*
* @throws LineUnavailableException if a matching line
* is not available due to resource restrictions
* @throws SecurityException if a matching line
* is not available due to security restrictions
* @throws IllegalArgumentException if the system does not
* support at least one line matching the specified
* Line.Info
object
* through any installed mixer
*/
public static Line getLine(Line.Info info) throws LineUnavailableException {
LineUnavailableException lue = null;
ListClip
* object.
*
* open(AudioFormat)
or
* open(AudioInputStream)
method.
*
* getMixer
* and getLine
internally.
*
* javax.sound.sampled.Clip
* is defined or it is defined in the file "sound.properties",
* it is used to retrieve the default clip.
* For details, refer to the {@link AudioSystem class description}.
*
* @return the desired clip object
*
* @throws LineUnavailableException if a clip object
* is not available due to resource restrictions
* @throws SecurityException if a clip object
* is not available due to security restrictions
* @throws IllegalArgumentException if the system does not
* support at least one clip instance through any installed mixer
*
* @see #getClip(Mixer.Info)
* @since 1.5
*/
public static Clip getClip() throws LineUnavailableException{
AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,
AudioSystem.NOT_SPECIFIED,
16, 2, 4,
AudioSystem.NOT_SPECIFIED, true);
DataLine.Info info = new DataLine.Info(Clip.class, format);
return (Clip) AudioSystem.getLine(info);
}
/**
* Obtains a clip from the specified mixer that can be
* used for playing back an audio file or an audio stream.
*
* open(AudioFormat)
or
* open(AudioInputStream)
method.
*
* getMixer
* and getLine
internally.
*
* @param mixerInfo a Mixer.Info
object representing the
* desired mixer, or null
for the system default mixer
* @return a clip object from the specified mixer
*
* @throws LineUnavailableException if a clip
* is not available from this mixer due to resource restrictions
* @throws SecurityException if a clip
* is not available from this mixer due to security restrictions
* @throws IllegalArgumentException if the system does not
* support at least one clip through the specified mixer
*
* @see #getClip()
* @since 1.5
*/
public static Clip getClip(Mixer.Info mixerInfo) throws LineUnavailableException{
AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED,
AudioSystem.NOT_SPECIFIED,
16, 2, 4,
AudioSystem.NOT_SPECIFIED, true);
DataLine.Info info = new DataLine.Info(Clip.class, format);
Mixer mixer = AudioSystem.getMixer(mixerInfo);
return (Clip) mixer.getLine(info);
}
/**
* Obtains a source data line that can be used for playing back
* audio data in the format specified by the
* AudioFormat
object. The returned line
* will be provided by the default system mixer, or,
* if not possible, by any other mixer installed in the
* system that supports a matching
* SourceDataLine
object.
*
* open(AudioFormat)
or
* open(AudioFormat, int)
method.
*
* getMixer
* and getLine
internally.
*
* SourceDataLine
's default
* audio format will be initialized with format
.
*
* javax.sound.sampled.SourceDataLine
* is defined or it is defined in the file "sound.properties",
* it is used to retrieve the default source data line.
* For details, refer to the {@link AudioSystem class description}.
*
* @param format an AudioFormat
object specifying
* the supported audio format of the returned line,
* or null
for any audio format
* @return the desired SourceDataLine
object
*
* @throws LineUnavailableException if a matching source data line
* is not available due to resource restrictions
* @throws SecurityException if a matching source data line
* is not available due to security restrictions
* @throws IllegalArgumentException if the system does not
* support at least one source data line supporting the
* specified audio format through any installed mixer
*
* @see #getSourceDataLine(AudioFormat, Mixer.Info)
* @since 1.5
*/
public static SourceDataLine getSourceDataLine(AudioFormat format)
throws LineUnavailableException{
DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
return (SourceDataLine) AudioSystem.getLine(info);
}
/**
* Obtains a source data line that can be used for playing back
* audio data in the format specified by the
* AudioFormat
object, provided by the mixer
* specified by the Mixer.Info
object.
*
* open(AudioFormat)
or
* open(AudioFormat, int)
method.
*
* getMixer
* and getLine
internally.
*
* SourceDataLine
's default
* audio format will be initialized with format
.
*
* @param format an AudioFormat
object specifying
* the supported audio format of the returned line,
* or null
for any audio format
* @param mixerinfo a Mixer.Info
object representing
* the desired mixer, or null
for the system
* default mixer
* @return the desired SourceDataLine
object
*
* @throws LineUnavailableException if a matching source data
* line is not available from the specified mixer due
* to resource restrictions
* @throws SecurityException if a matching source data line
* is not available from the specified mixer due to
* security restrictions
* @throws IllegalArgumentException if the specified mixer does
* not support at least one source data line supporting
* the specified audio format
*
* @see #getSourceDataLine(AudioFormat)
* @since 1.5
*/
public static SourceDataLine getSourceDataLine(AudioFormat format,
Mixer.Info mixerinfo)
throws LineUnavailableException{
DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
Mixer mixer = AudioSystem.getMixer(mixerinfo);
return (SourceDataLine) mixer.getLine(info);
}
/**
* Obtains a target data line that can be used for recording
* audio data in the format specified by the
* AudioFormat
object. The returned line
* will be provided by the default system mixer, or,
* if not possible, by any other mixer installed in the
* system that supports a matching
* TargetDataLine
object.
*
* open(AudioFormat)
or
* open(AudioFormat, int)
method.
*
* getMixer
* and getLine
internally.
*
* TargetDataLine
's default
* audio format will be initialized with format
.
*
* AudioFormat
object specifying
* the supported audio format of the returned line,
* or null
for any audio format
* @return the desired TargetDataLine
object
*
* @throws LineUnavailableException if a matching target data line
* is not available due to resource restrictions
* @throws SecurityException if a matching target data line
* is not available due to security restrictions
* @throws IllegalArgumentException if the system does not
* support at least one target data line supporting the
* specified audio format through any installed mixer
*
* @see #getTargetDataLine(AudioFormat, Mixer.Info)
* @see AudioPermission
* @since 1.5
*/
public static TargetDataLine getTargetDataLine(AudioFormat format)
throws LineUnavailableException{
DataLine.Info info = new DataLine.Info(TargetDataLine.class, format);
return (TargetDataLine) AudioSystem.getLine(info);
}
/**
* Obtains a target data line that can be used for recording
* audio data in the format specified by the
* AudioFormat
object, provided by the mixer
* specified by the Mixer.Info
object.
*
* open(AudioFormat)
or
* open(AudioFormat, int)
method.
*
* getMixer
* and getLine
internally.
*
* TargetDataLine
's default
* audio format will be initialized with format
.
*
* @param format an AudioFormat
object specifying
* the supported audio format of the returned line,
* or null
for any audio format
* @param mixerinfo a Mixer.Info
object representing the
* desired mixer, or null
for the system default mixer
* @return the desired TargetDataLine
object
*
* @throws LineUnavailableException if a matching target data
* line is not available from the specified mixer due
* to resource restrictions
* @throws SecurityException if a matching target data line
* is not available from the specified mixer due to
* security restrictions
* @throws IllegalArgumentException if the specified mixer does
* not support at least one target data line supporting
* the specified audio format
*
* @see #getTargetDataLine(AudioFormat)
* @see AudioPermission
* @since 1.5
*/
public static TargetDataLine getTargetDataLine(AudioFormat format,
Mixer.Info mixerinfo)
throws LineUnavailableException {
DataLine.Info info = new DataLine.Info(TargetDataLine.class, format);
Mixer mixer = AudioSystem.getMixer(mixerinfo);
return (TargetDataLine) mixer.getLine(info);
}
// $$fb 2002-04-12: fix for 4662082: behavior of AudioSystem.getTargetEncodings() methods doesn't match the spec
/**
* Obtains the encodings that the system can obtain from an
* audio input stream with the specified encoding using the set
* of installed format converters.
* @param sourceEncoding the encoding for which conversion support
* is queried
* @return array of encodings. If sourceEncoding
is not supported,
* an array of length 0 is returned. Otherwise, the array will have a length
* of at least 1, representing sourceEncoding
(no conversion).
*/
public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding) {
ListsourceFormat
(no conversion).
*/
public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat) {
Listfalse
*/
public static boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) {
Listfalse
*/
public static boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) {
ListIOException
.
* @param stream the input stream from which file format information should be
* extracted
* @return an AudioFileFormat
object describing the stream's audio file format
* @throws UnsupportedAudioFileException if the stream does not point to valid audio
* file data recognized by the system
* @throws IOException if an input/output exception occurs
* @see InputStream#markSupported
* @see InputStream#mark
*/
public static AudioFileFormat getAudioFileFormat(InputStream stream)
throws UnsupportedAudioFileException, IOException {
ListAudioFileFormat
object describing the audio file format
* @throws UnsupportedAudioFileException if the URL does not point to valid audio
* file data recognized by the system
* @throws IOException if an input/output exception occurs
*/
public static AudioFileFormat getAudioFileFormat(URL url)
throws UnsupportedAudioFileException, IOException {
ListFile
. The File
must
* point to valid audio file data.
* @param file the File
from which file format information should be
* extracted
* @return an AudioFileFormat
object describing the audio file format
* @throws UnsupportedAudioFileException if the File
does not point to valid audio
* file data recognized by the system
* @throws IOException if an I/O exception occurs
*/
public static AudioFileFormat getAudioFileFormat(File file)
throws UnsupportedAudioFileException, IOException {
ListIOExcEption
.
* @param stream the input stream from which the AudioInputStream
should be
* constructed
* @return an AudioInputStream
object based on the audio file data contained
* in the input stream.
* @throws UnsupportedAudioFileException if the stream does not point to valid audio
* file data recognized by the system
* @throws IOException if an I/O exception occurs
* @see InputStream#markSupported
* @see InputStream#mark
*/
public static AudioInputStream getAudioInputStream(InputStream stream)
throws UnsupportedAudioFileException, IOException {
ListAudioInputStream
should be
* constructed
* @return an AudioInputStream
object based on the audio file data pointed
* to by the URL
* @throws UnsupportedAudioFileException if the URL does not point to valid audio
* file data recognized by the system
* @throws IOException if an I/O exception occurs
*/
public static AudioInputStream getAudioInputStream(URL url)
throws UnsupportedAudioFileException, IOException {
ListFile
. The File
must
* point to valid audio file data.
* @param file the File
for which the AudioInputStream
should be
* constructed
* @return an AudioInputStream
object based on the audio file data pointed
* to by the File
* @throws UnsupportedAudioFileException if the File
does not point to valid audio
* file data recognized by the system
* @throws IOException if an I/O exception occurs
*/
public static AudioInputStream getAudioInputStream(File file)
throws UnsupportedAudioFileException, IOException {
Listtrue
if the file type is supported,
* otherwise false
*/
public static boolean isFileTypeSupported(AudioFileFormat.Type fileType) {
Listtrue
if the file type is supported for this audio input stream,
* otherwise false
*/
public static boolean isFileTypeSupported(AudioFileFormat.Type fileType,
AudioInputStream stream) {
ListAudioSystem.NOT_SPECIFIED
.
*
* @param stream the audio input stream containing audio data to be
* written to the file
* @param fileType the kind of audio file to write
* @param out the stream to which the file data should be written
* @return the number of bytes written to the output stream
* @throws IOException if an input/output exception occurs
* @throws IllegalArgumentException if the file type is not supported by
* the system
* @see #isFileTypeSupported
* @see #getAudioFileTypes
*/
public static int write(AudioInputStream stream, AudioFileFormat.Type fileType,
OutputStream out) throws IOException {
List